Background

Stage 1's qwen serve (#3889) shipped a headless daemon with HTTP+SSE for remote clients; #4113 is consolidating the "1 daemon = 1 workspace" architecture. But today only Mode B (headless) exists: with a TUI process running, you cannot also run a daemon — so while a local user has the TUI open, mobile / IDE / IM bot / web clients cannot connect.

The design proposal at qwen-code-daemon-design §04 / §06 names this work Stage 1.5b — Mode A qwen --serve flag: attach an HttpServer inside a normal TUI process; the TUI acts as a super-client over the in-process EventBus, and remote clients connect via HTTP+SSE sharing the same daemon and same session pool.

⚠️ Strongly recommended to start this issue after #4113 merges. APIs introduced by #4113 are dependencies: boundWorkspace is required, canonicalizeWorkspace and WorkspaceMismatchError are exported. Sub-task A0 (extract a workspace-validation helper) is itself a small refactor of #4113's code; sub-task A1 (extract the in-memory channel helper) has no #4113 dependency and can start immediately.

Architecture comparison

Key technical finding

createServeApp(opts, deps) (packages/cli/src/serve/server.ts:53) already supports deps.bridge?: HttpAcpBridge injection, and HttpAcpBridge (packages/cli/src/serve/httpAcpBridge.ts:87) is a transport-agnostic interface. So Mode A does not need to change the routing / SSE / EventBus layers — it only needs a createInProcessAcpBridge(agent) implementation that wraps the in-process QwenAgent as a bridge to inject. SSE / Last-Event-ID / 15s heartbeat / ring replay all reuse #3889 directly.

⚠️ Scope clarification: the design proposal's "TUI startup auto-POST /session, remote attaches to the same X" full semantics requires refactoring the TUI to flow through QwenAgent — that's a Phase D-class refactor (see Phase A detailed design §1 below). This issue's Phase A/B/C does NOT include it.

Three-phase plan overview (3 stacked PRs)

Each phase reviews and merges independently; B/C have no hard dependency between them. Phase A detailed design is in its own section below.

Phase A — Loopback-only minimal skeleton (~4.3 days, split into A0/A1/A2/A3 four stacked PRs)

qwen --serve [--workspace /path] [--serve-port N] brings up TUI + local daemon, with remote curl over loopback exercising the full prompt + SSE flow. Local debugging only — no auth, no graceful shutdown, TUI and remote sessions not shared, remote cannot call authenticate, daemon exception will kill TUI. Detailed design below.

Phase B — Remote bind + auth/CORS defaults (~1 day)

Goal: qwen --serve --serve-host 0.0.0.0 is reachable from LAN/container; bearer token required for non-loopback; loopback still no-token. Team / container alpha-quality.

Changes:

1. Add --serve-host flag (default 127.0.0.1) and --serve-token flag + QWEN_SERVER_TOKEN env fallback
2. Reuse packages/cli/src/serve/runQwenServe.ts:60-75 token trim+env logic
3. Loopback detection via isLoopbackBind() (packages/cli/src/serve/loopbackBinds.ts); non-loopback without token → boot fails with same stderr message as Mode B's "Refusing to bind X without a bearer token"
4. Auto-generate token written to ~/.qwen/serve/token, TUI banner shows the path (matches Mode B existing behavior)
5. CORS / Host allowlist fully reuses packages/cli/src/serve/auth.ts three middlewares (bearerAuth / denyBrowserOriginCors / hostAllowlist); they are transparent to the in-process bridge
6. Disallow --serve-port 0 + non-loopback host combination (OS ephemeral port + remote = operator can't tell what they exposed)
7. Tests: non-loopback no-token → boot reject; with token → accept; wrong token → 401

Phase B does NOT do: Mutual TLS / client certificates (Stage 2), token revocation API (chiga0 must-have #3)

Phase C — Lifecycle coordination (~1 day)

Goal: TUI exit (Ctrl+C / /quit / exception) drains HTTP first, then unmounts ink, then exits process; remote clients see clean close not TCP RST; remote disconnect doesn't affect TUI. Production-ready.

Changes:

1. Centralized shutdown handle: TUI startup hook returns { shutdown(): Promise<void> } wrapping bridge.shutdown() + server.close() + 5s force-close (reuses runQwenServe.ts:15 SHUTDOWN_FORCE_CLOSE_MS)
2. qwen.tsx top-level single SIGINT/SIGTERM handler, ordered: ① EventBus pushes daemon_shutting_down to all SSE → ② server.close() rejects new connections, awaits in-flight → ③ bridge.shutdown() → ④ ink unmount → ⑤ process.exit(0)
3. /quit reuses the same shutdown() function — avoid two divergent exit paths
4. Double-SIGINT force exit (matches refactor(serve): 1 daemon = 1 workspace (#3803 §02) #4113 BkUyD behavior): second Ctrl+C → skip drain, exit(130)
5. Coordinate with ink's default SIGINT handler: must remove/wrap ink's handler at TUI startup, otherwise ink unmounts first and HTTP drain doesn't run (only likely-trap point in this phase, leave 0.5d buffer)
6. E2E: a) TUI + remote SSE connected, TUI process SIGINT → remote sees close event + 200 response within 5s, TUI exit code 0; b) remote kill -9 SSE client → TUI still running, /help still responds

Phase C does NOT do: Daemon hot-reload (restart daemon without restarting TUI), Persistent SSE replay across restart (Stage 2 durable scope)

Three-phase characteristics

Phase A detailed design

0. opencode reference and trade-offs

opencode's tui command (packages/opencode/src/cli/cmd/tui/thread.ts) implements TUI + server in one process:

Core borrow: opencode proves "TUI + server in same process" is viable + 5s shutdown is a sensible constant. Key difference: opencode's TUI already abstracts data access behind fetch/events injection; qwen-code's TUI does not. So Phase A cannot simply copy "TUI as daemon client" — that's Phase D's work.

1. Honest scope statement ⚠️

Phase A actually achieves:

• ✅ qwen --serve brings up TUI with HttpServer attached
• ✅ Remote clients can curl /capabilities, POST /session to get an independent session in the same workspace, receive SSE events, send prompts
• ✅ TUI's own session continues normally without regression

Known limitations (differences from Mode B; must be documented for users):

"TUI ↔ daemon session unification" is broken out as Phase D (not in this issue's scope).

2. File-level change list

3. Key technical decisions

Decision 1: in-process bridge uses paired channel + full ACP

The TransformStream pair + ndJsonStream pattern at httpAcpBridge.test.ts:151-154 already exists; just extract to inMemoryChannel.ts.

Simplification advantage (vs #4113's httpAcpBridge.ts): in-process has no child process / spawn race / child crash race / SIGTERM grace window, so it does not need ChannelInfo.isDying state, aliveChannels set, killAllSync path, or tanzhenxin's BkUyD double-SIGINT invariant. Estimated in-process bridge ~180-220 lines, an order of magnitude smaller than #4113's httpAcpBridge.ts (~2400 lines).

Decision 2: TUI ↔ daemon session relationship — decoupled

See §1. The daemon runs an independent QwenAgent in the same process; TUI session and daemon session are mutually invisible.

Decision 3: when to listen + boot failure + log direction

• Position: gemini.tsx, after initializeApp(config, settings) (ensures settings/auth are ready), before render(<App ...>)
• Failure handling: port conflict / bind error / workspace validation failure → TUI does not start, writeStderrLine prints error, process.exit(1)
• Listen URL printing: only via writeStderrLine (stdout is occupied by ink; writing to stdout would pollute TUI rendering)
• Default port: 0 (OS-assigned), to avoid clashing with Mode B's default 4170; users must check stderr for the actual port

Decision 4: EventBus instance sharing

createServeApp instantiates an EventBus internally for SSE. Phase A: in-process QwenAgent flows via paired channel → ACP sessionUpdate notification → bridge forwards to EventBus → SSE fan-out. Does not do "TUI directly subscribes to EventBus" — that's Phase D.

Decision 5: --serve mutex with existing flags

Validation lives near gemini.tsx:417, alongside --bare / --prompt-interactive mutex checks.

Decision 6: Phase A forces loopback

--serve-host is not exposed in Phase A; hard-coded 127.0.0.1. Remote bind must come with token — that's Phase B's work.

Decision 7: boundWorkspace is boot-time snapshot + canonical

Mode A's boundWorkspace = validateAndCanonicalizeWorkspace(argv.workspace ?? process.cwd()) at --serve boot time, never changes. Even if TUI calls process.chdir() during runtime (triggered by some commands), the daemon still serves the original workspace. This matches #4113's 1-daemon-1-workspace semantics.

Critical: canonicalizeWorkspace is the idempotent helper already exported from httpAcpBridge.ts; handles symlinks + case-insensitive FS. Phase A must pre-canonicalize — otherwise /capabilities.workspaceCwd may drift from the bridge's internal canonical form (although #4113 has its own re-canonicalize fallback, aligning with runQwenServe's pattern is cleaner).

Empirical: grepping the entire codebase for process.chdir() in ui/commands/, services/, acp-integration/ — zero calls, so snapshot vs dynamic is equivalent today. But future sub-agent tools (EnterWorktree PR #4073) involve directory switching; dynamic mode would silently change boundWorkspace, causing all connected clients to receive workspace_mismatch without notification — a sliding error. Snapshot is strictly superior to dynamic.

Decision 8: reject remote authenticate request forwarding

The in-process bridge intercepts the authenticate method at the ACP request routing layer and returns ACP error directly: { code: -32601, message: "remote authenticate disabled in Mode A; use TUI /auth instead" }. Rationale per §1: QwenAgent.authenticate() clears TUI credentials.

Decision 9: share config / settings, fabricate argv

The daemon's QwenAgent uses the TUI's already-constructed config + settings instances (avoiding settings drift), but argv is freshly built as a clean CliArgs (containing only daemon-relevant fields like cwd, mode), to avoid TUI's flags like --prompt-interactive poisoning daemon behavior.

InProcessBridgeOptions TS signature (aligned with #4113's BridgeOptions):

interface InProcessBridgeOptions {
  boundWorkspace: string;           // required (matches #4113 BridgeOptions.boundWorkspace)
  sharedConfig: Config;             // required
  sharedSettings: LoadedSettings;   // required
  daemonArgv: CliArgs;              // required (fabricated)
  maxSessions?: number;             // optional, defaults to 5 (per D2 decision)
  // No maxConnections needed (in-process has no listener layer)
  // No sessionScope override needed (sticks with single default)
}

export function createInProcessAcpBridge(opts: InProcessBridgeOptions): HttpAcpBridge;
// Note: matches #4113's createHttpAcpBridge(opts: BridgeOptions), opts has no default

fabricateDaemonArgv(orig: CliArgs) field disposition (keep / drop):

Decision 10: lazy import

gemini.tsx's daemon startup logic is wrapped with await import('./serve/inProcessDaemon.js'). No --serve → no ESM cold-start cost (~50ms, matches Mode B's commands/serve.ts:106 lazy pattern).

4. Data flow diagram

┌──────────────────────────────────────────────────────────────────┐
│                     qwen --serve process                          │
│                                                                   │
│  ┌─────────────┐                                                  │
│  │  ink TUI    │ ─── existing path (no ACP / no daemon) ──→       │
│  │ (gemini.tsx)│      sendMessage / GeminiClient / ...            │
│  └─────────────┘                                                  │
│         │                                                          │
│         │ Mutually invisible to QwenAgent below (Phase A limit)    │
│         │ Shares: config / settings / OAuth / FileReadCache       │
│         ▼                                                          │
│  ┌─────────────────────────────────────────────────────┐         │
│  │  Daemon subsystem (only when --serve, lazy-imported) │         │
│  │  boundWorkspace = validateAndCanonicalizeWorkspace() │         │
│  │                                                       │         │
│  │  Express(createServeApp({ workspace: boundWorkspace }))│       │
│  │       │                                               │         │
│  │       │ deps.bridge = createInProcessAcpBridge(...)  │         │
│  │       ▼                                               │         │
│  │  HttpAcpBridge (in-process impl, ~200 lines)         │         │
│  │       │  · Rejects authenticate request               │         │
│  │       │  · try/catch around uncaughtException         │         │
│  │       │  · No console redirect / stdio wrap / sigreg  │         │
│  │       │  · No isDying / aliveChannels / killAllSync   │         │
│  │       │  paired in-memory NDJSON channel              │         │
│  │       │  (TransformStream pair + ndJsonStream)        │         │
│  │       ▼                                               │         │
│  │  ClientSideConnection ←───────→ AgentSideConnection  │         │
│  │                                       │               │         │
│  │                                       ▼               │         │
│  │                  new QwenAgent(sharedConfig,          │         │
│  │                                sharedSettings,        │         │
│  │                                fabricatedArgv,        │         │
│  │                                conn)                  │         │
│  │                  sessions: Map<id, S>                 │         │
│  └─────────────────────────────────────────────────────┘         │
│                          ▲                                         │
│                          │ HTTP + SSE on 127.0.0.1:N (N OS-assigned) │
└──────────────────────────│─────────────────────────────────────────┘
                           │
            ┌──────────────┴──────────────┐
            │                              │
       curl / SDK                    IDE / mobile / IM
       (remote client A)             (remote client B)
       gets sessionId Y              attach Y or get new Z
       (cwd may be omitted →         (cwd mismatch → 400
        falls back to boundWorkspace)  workspace_mismatch)

5. Test matrix

6. Acceptance criteria

• qwen --serve starts TUI; /help etc. work normally inside TUI
• Same machine curl http://127.0.0.1:N/capabilities returns workspaceCwd = TUI's cwd (N read from stderr)
• Same machine curl -X POST http://127.0.0.1:N/session -d '{}' returns sessionId (omitting cwd takes fallback)
• Same machine curl -X POST http://127.0.0.1:N/session -d '{"cwd":"/wrong"}' returns 400 + code: workspace_mismatch
• curl -N http://127.0.0.1:N/session/{id}/events streams ACP events
• Remote POST /session/{id}/prompt triggers agent work and SSE returns streaming tokens
• Remote ACP authenticate request → receives method-disabled error, TUI credentials untouched
• qwen --serve --workspace /no/such/path → exit 1 + friendly error
• TUI exit (Ctrl+C) exits the entire process (does not guarantee SSE clean close — that's Phase C)
• Without --serve startup → ESM load graph does NOT include serve module
• CI: vitest all green, new tests pass

7. Phase A explicit non-goals

8. PR split recommendation

A 4.3-day diff in a single PR is too much review burden; split into 4 stacked PRs:

A1 can start now (no #4113 dependency); A0/A2/A3 wait for #4113 merge before stacking, to avoid rebases.

Phase A workload estimate (revised)

Main added cost is:

• §3 decision 1 paired channel + ACP wiring: ~1.5d (in-process simplification saves back 0.5d)
• §3 decision 8 authenticate rejection forwarding + tests: ~0.5d
• §1 known limitations documentation + uncaughtException wrapping: ~0.5d
• A0 helper extraction: ~0.3d

ROI is positive: in exchange for zero invasion of server layer + ACP protocol auto-follow + no security/resource amplification problems + alignment with #4113 workflow.

Routing decision point ⚠️

#3929 / #3930 / #3931 (chiga0) are an alternative route that overlaps in functionality but uses a different protocol: qwen remote-control + qwen --remote-control, WebSocket + stream-json. Both routes do "TUI as super-client + mobile/browser thin client". Before implementing 1.5b, design alignment is needed:

• Option A: take feat(cli): add remote-control foundation #3929-3931 as 1.5b (accept the WebSocket protocol)
• Option B: follow this issue's HTTP daemon route, withdraw or merge feat(cli): add remote-control foundation #3929-3931 into the daemon protocol
• Option C: first do chiga0 finding OpenAI API Error: 401 Incorecct API Key provided #6 (converge dualOutput/remoteInput onto AcpChannel/EventBus), then have both routes connect to the same root

Out of scope for this issue

• Phase D — TUI ↔ daemon session unification (make TUI a real daemon client pre-release: fix ci #1, requires refactoring TUI to flow through QwenAgent; also unlocks remote authenticate / process-level credential mediator / telemetry span merge) — separate issue
• Phase E — Stage 2e in-process reverse refactor (process-level quarantine so daemon exceptions don't kill TUI) — separate issue
• chiga0's 6 prereq refactors (PermissionMediator extraction, EventBus elevation, MCP per-daemon shared state, etc.) — separate issue
• Stage 1.5a remaining 9 must-haves (per-request sessionScope override, loadSession HTTP, heartbeat, token revocation, etc.) — separate issue
• Stage 1.5c daemon-side state CRUD (memory/mcp/agents/tools/approval-mode/init/auth 7 routes) — separate issue

References

Daemon series upstream (@wenshao-led)

• Daemon mode (qwen serve): proposal & open decisions #3803 — Daemon mode (qwen serve): proposal & open decisions (root tracking issue; this issue is its §02 follow-up Mode A landing detail design)
• feat(cli,sdk): qwen serve daemon (Stage 1) #3889 — Stage 1 daemon qwen serve (✅ merged)
• refactor(serve): 1 daemon = 1 workspace (#3803 §02) #4113 — refactor(serve): 1 daemon = 1 workspace (Daemon mode (qwen serve): proposal & open decisions #3803 §02) (must merge first; this issue's A0 sub-task reuses its canonicalizeWorkspace / WorkspaceMismatchError / BridgeOptions.boundWorkspace, etc.)

Design docs

• Design proposal: qwen-code-daemon-design §04 / §06 (drafted by @wenshao)

Routing decision point

• chiga0 remote-control trio (pending alignment): feat(cli): add remote-control foundation #3929 / feat(cli): add remote-control worker server #3930 / feat(cli): attach remote-control to current TUI #3931 (functionally overlapping WebSocket route, needs selection first)

External reference

• opencode reference implementation: packages/opencode/src/cli/cmd/tui/thread.ts (Worker + RPC fetch)

interface InProcessBridgeOptions {
  boundWorkspace: string;           // required（与 #4113 BridgeOptions.boundWorkspace 一致）
  sharedConfig: Config;             // required
  sharedSettings: LoadedSettings;   // required
  daemonArgv: CliArgs;              // required（fabricated）
  maxSessions?: number;             // optional, 默认 5（D2 决策）
  // 不需要 maxConnections（in-process 没 listener 层）
  // 不需要 sessionScope override（沿用 single 默认）
}

export function createInProcessAcpBridge(opts: InProcessBridgeOptions): HttpAcpBridge;
// 注意：与 #4113 后的 createHttpAcpBridge(opts: BridgeOptions) 一致，opts 无默认值

┌──────────────────────────────────────────────────────────────────┐
│                      qwen --serve 进程                            │
│                                                                   │
│  ┌─────────────┐                                                  │
│  │  ink TUI    │ ─── 现有路径（不走 ACP / 不经 daemon） ──→       │
│  │ (gemini.tsx)│      sendMessage / GeminiClient / ...            │
│  └─────────────┘                                                  │
│         │                                                          │
│         │ 与下方 QwenAgent 互不可见（Phase A 限制）                │
│         │ 共享：config / settings / OAuth / FileReadCache         │
│         ▼                                                          │
│  ┌─────────────────────────────────────────────────────┐         │
│  │  Daemon 子系统（仅当 --serve 启用时，lazy imported） │         │
│  │  boundWorkspace = validateAndCanonicalizeWorkspace() │         │
│  │                                                       │         │
│  │  Express(createServeApp({ workspace: boundWorkspace }))│       │
│  │       │                                               │         │
│  │       │ deps.bridge = createInProcessAcpBridge(...)  │         │
│  │       ▼                                               │         │
│  │  HttpAcpBridge (in-process 实现, ~200 行)            │         │
│  │       │  · 拒绝 authenticate request                  │         │
│  │       │  · try/catch 捕获 uncaughtException           │         │
│  │       │  · 不重定向 console / 不包 stdio / 不注册 sig │         │
│  │       │  · 无 isDying / aliveChannels / killAllSync   │         │
│  │       │  paired in-memory NDJSON channel              │         │
│  │       │  (TransformStream pair + ndJsonStream)        │         │
│  │       ▼                                               │         │
│  │  ClientSideConnection ←───────→ AgentSideConnection  │         │
│  │                                       │               │         │
│  │                                       ▼               │         │
│  │                  new QwenAgent(sharedConfig,          │         │
│  │                                sharedSettings,        │         │
│  │                                fabricatedArgv,        │         │
│  │                                conn)                  │         │
│  │                  sessions: Map<id, S>                 │         │
│  └─────────────────────────────────────────────────────┘         │
│                          ▲                                         │
│                          │ HTTP + SSE on 127.0.0.1:N (N OS 分配)  │
└──────────────────────────│─────────────────────────────────────────┘
                           │
            ┌──────────────┴──────────────┐
            │                              │
       curl / SDK                    IDE / mobile / IM
       (远端 client A)               (远端 client B)
       拿到 sessionId Y               attach Y 或拿新的 Z
       (可省略 cwd → fallback         (cwd 不匹配 → 400
        到 boundWorkspace)             workspace_mismatch)