zidane 7.0.15 → 7.0.16

package/docs/IPC.md

@@ -1,9 +1,14 @@
 # zidane/ipc — shared chat host, daemon, and multi-window sync
 
-`zidane/ipc` is the layer that lets several zidane windows — terminal
-sessions, the GUI, `zidane attach` clients — share **one set of live agents**
-and stay converged on the same state: the same transcript stream, the same
-pending approvals, the same interaction prompts.
+`zidane/ipc` lets several zidane windows — terminal sessions, the GUI,
+`zidane attach` clients — share **one set of live agents** and stay
+converged: same transcript, same pending approvals, same interaction
+prompts. The engine (`createChatHost`) is transport-agnostic; the daemon
+is one embedding of it, reached over a unix socket with JSON-RPC.
+
+Entry points: `src/ipc/daemon/server.ts` (`startIpcDaemon`), `src/ipc/client.ts`
+(`connectIpcClient` / `connectOrSpawnDaemon`), `src/tui/runtime/daemon.ts`
+(`connectDaemonSession`, the TUI's daemon-mode controller).
 
 ```
 ┌────────────┐   ┌────────────┐   ┌─────────────┐
@@ -22,294 +27,280 @@ pending approvals, the same interaction prompts.
             └────────────┘
 ```
 
+Contents: [Pieces](#the-pieces) · [Host environment](#host-environment) ·
+[RPC methods](#rpc-methods) · [Signals](#signals-and-convergence) ·
+[Concurrent sends](#concurrent-sends) · [Extension bus](#extension-bus-ctxbus) ·
+[Daemon lifecycle](#daemon-lifecycle) · [Turning it off](#turning-it-off-containment-guarantees) ·
+[Execution semantics](#execution-semantics-read-this) · [Testing](#testing) ·
+[Surface matrix](#surface-cabling-matrix-daemon-runtime) · [Removability](#removability) ·
+[Status](#status--follow-ups)
+
 ## The pieces
 
 | Module | What it is |
 | --- | --- |
-| `protocol.ts` | Transport contract: the typed `IpcMethods` RPC map, `IPC_PROTOCOL_VERSION`, handshake shapes. Re-exports the host-domain shapes (`HostSignal` & co.) from `src/chat/host/signals.ts`. |
-| `src/chat/host/` | `createChatHost(env)` — the transport-agnostic engine. Owns live `Agent`s, forwards agent-loop hooks as signals, runs the approval + interaction hubs. Lives under `src/chat` (it's the chat engine, not an IPC feature); `zidane/ipc` re-exports it for back-compat, new code imports it from `zidane/chat`. |
-| `daemon/` | Unix-socket JSON-RPC server (`startIpcDaemon`), disk-backed environment, lifecycle helpers (socket path, liveness probe, spawn-on-demand). |
-| `client.ts` | `connectIpcClient` / `connectOrSpawnDaemon` — typed `request()`, `onSignal()`, protocol-version handshake with automatic stale-daemon drain. |
-| `attach.ts` | `zidane attach` — a thin readline client proving the multi-window contract end-to-end. |
+| `src/ipc/protocol.ts` | Transport contract: typed `IpcMethods` map, `IPC_PROTOCOL_VERSION`, handshake shapes. Re-exports `HostSignal` & co. from `src/chat/host/signals.ts`. |
+| `src/chat/host/` | `createChatHost(env)` — the transport-agnostic engine. Owns live `Agent`s, forwards loop hooks as signals, runs the approval + interaction hubs. |
+| `src/ipc/daemon/` | Unix-socket JSON-RPC server (`startIpcDaemon`), disk-backed environment, lifecycle helpers (socket path, liveness probe, spawn-on-demand). |
+| `src/ipc/client.ts` | `connectIpcClient` / `connectOrSpawnDaemon` — typed `request()`, `onSignal()`, version handshake with stale-daemon drain. |
+| `src/ipc/attach.ts` | `zidane attach` — a thin readline client proving the multi-window contract end-to-end. |
 
 ## Host environment
 
 `createChatHost` never touches disk or Electron directly — the embedding
 process supplies a `ChatHostEnvironment`:
 
-- **GUI main** (`gui/src/main/chat/host.ts`): broadcast → `webContents.send`
-  demuxed onto the legacy renderer channels; settings in `state.json`'s
-  `settings` slot (shared with the TUI and the daemon; the legacy sqlite
-  row is migrated by `initSettings`), pending approvals in sqlite; the
-  extension-aware runtime-config cache.
+- **GUI main** (`gui/src/main/chat/host.ts`): broadcast → `webContents.send`;
+  settings in `state.json`'s `settings` slot (shared with the TUI/daemon);
+  pending approvals in sqlite.
 - **Daemon** (`src/ipc/daemon/environment.ts`): broadcast → socket peers;
-  settings in `state.json`'s `settings` slot (shared with the TUI); pending
-  approvals in `pending-approvals.json`; per-cwd extension discovery with
-  the same allowlist + trust contract as every other surface.
+  same `state.json` settings slot; pending approvals in
+  `pending-approvals.json`; per-cwd extension discovery with the same
+  allowlist + trust contract as every other surface.
+
+Both run the same engine — the gate flow, edit-approval pipeline,
+compaction, and hook forwarding cannot drift between surfaces.
 
-Both run the **same engine** — the gate flow, edit-approval pipeline,
-compaction, and hook forwarding cannot drift between surfaces anymore.
+## RPC methods
+
+Client → host, daemon-dispatched. All are mirrored by the GUI's embedded
+path through the same `ChatHost` method. Source of truth: `IpcMethods` in
+`src/ipc/protocol.ts`.
+
+| Method | Purpose |
+| --- | --- |
+| `chat.send` | Send a prompt; starts a run (errors if already running elsewhere). |
+| `chat.interrupt` | Stop the session's active run. |
+| `chat.steer` | Inject a message into the live run. |
+| `chat.followUp` | Queue a message on the agent to run after the current turn (no steer). |
+| `chat.pushQueued` | Race-free send: steers a live run, sends otherwise. |
+| `chat.isRunning` | Whether the session has a run in flight. |
+| `chat.rebuildAgent` | Retire the cached agent so the next run rebuilds (fresh MCP/creds/extensions). |
+| `chat.listWork` | List cancellable tool calls / background tasks for the session. |
+| `chat.cancelWork` | Cancel one work item, or `'all'`. |
+| `sessions.list` | List sessions, filtered by project root / archive state. |
+| `sessions.create` | Create a session. |
+| `sessions.delete` | Delete a session. |
+| `sessions.setTitle` | Rename a session. |
+| `sessions.setArchived` | Archive / unarchive a session. |
+| `sessions.setAgentId` | Change a session's agent profile. |
+| `sessions.setEffort` | Change a session's thinking-effort level. |
+| `sessions.setModel` | Set provider/model; `fallbacks` patches the chain (omit = untouched, `[]` = clear). |
+| `sessions.setModelOptions` | Set per-model boolean options. |
+| `sessions.loadEvents` | Canonical transcript replay — the re-convergence source of truth. |
+| `sessions.getTurn` | Fetch one turn. |
+| `sessions.contextBreakdown` | Context-usage breakdown for the context panel. |
+| `sessions.artifacts` | One session's artifacts — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `sessions.touch` | Announce an out-of-band local `/`/`!` append; fans out `sessions:changed`. |
+| `sessions.compact` | Trigger manual compaction. |
+| `sessions.systemMd` | Attach-time backfill of the resolved `SYSTEM.md` override. |
+| `sessions.contextSegments` | Every prompt segment with provenance (Instructions tab). |
+| `sessions.createSystemOverride` | Seed a user-scope `SYSTEM.md`; throws when no override could apply. |
+| `artifacts.list` | Cross-session artifact query — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `artifacts.delete` | Remove an artifact — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `artifacts.upsert` | Refresh an artifact (lazy `resolve()` write-back) — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `history.searchSession` | Transcript search over one session, against authoritative mid-run-fresh turns. |
+| `history.searchAll` | Cross-session content search; one shared index built in the daemon. |
+| `todos.get` | Current todos snapshot for a session. |
+| `todos.set` | Apply a user todo edit to the live agent's `Session` (what `todowrite` reads). |
+| `orchestration.main` | Resolve/create the pinned "main" session id. Gated on the `orchestration` setting. |
+| `orchestration.createWorker` | Create a worker session under a main. |
+| `orchestration.list` | List a main's workers. |
+| `orchestration.read` | Read one worker's summary. |
+| `orchestration.send` | Send a prompt to a worker; `wake` (default true) wakes the main on completion. |
+| `orchestration.steer` | Steer a worker's live run. |
+| `orchestration.cancel` | Cancel a worker's run. |
+| `orchestration.transcript` | Fetch a worker's transcript text. |
+| `commands.list` | Extension-contributed `/` commands discovered for a cwd. |
+| `commands.completeArgs` | Argument suggestions for `/name <prefix>`. |
+| `interactions.list` | Pending `present_plan` / `ask_user` requests. |
+| `interactions.respond` | Answer an interaction. |
+| `interactions.cancel` | Cancel an interaction. |
+| `interactions.rehydrate` | Re-queue orphaned interactions from a reopened session. |
+| `approvals.resolve` | Resolve a safe-mode approval request. |
+| `approvals.denyAll` | Deny every pending approval (optionally scoped to a session). |
+| `approvals.listPending` | Pending approvals — backfill for a late attacher. |
+| `queue.list` | Current type-ahead queue for a session. |
+| `queue.add` | Queue a message while a run is in flight; sends immediately otherwise. |
+| `queue.remove` | Drop a queued entry. |
+| `queue.update` | Edit a queued entry's text in place; order is kept. |
+| `queue.pushNow` | Steer a queued entry into the live run now (sends if idle). |
+| `drafts.get` | Current shared draft — backfill on window attach. |
+| `drafts.set` | Replace the shared draft text (notification, fired per keystroke). |
+| `drafts.setAttachments` | Replace the shared draft's composing attachments (notification). |
+| `search.set` | Replace the shared transcript-search state (notification, per keystroke). |
+| `extension.emit` | Forward a client-side `ctx.bus` emit (`'ipc'` permission); daemon validates + re-broadcasts. |
+| `suggest.resolve` | Resolve inline ghost-text autocomplete daemon-side; latest `seq` per session wins. |
+| `settings.get` | Read host settings. |
+| `settings.set` | Patch host settings; fans out `settings:changed`. |
+| `presence.list` | Current presence snapshot — backfill for a freshly opened session list. |
+| `presence.watch` | Tag this connection as attached to a session; detach is implicit on close. |
+| `daemon.info` | Handshake / diagnostics info. |
+| `daemon.shutdown` | Graceful drain: deny pending approvals, abort live runs, close the socket. |
+
+All methods above `IPC_PROTOCOL_VERSION` 9 are additive: an older daemon
+answers "method not found" and clients degrade (local compute, or a
+store-level fallback) instead of failing. `optional()` in
+`src/tui/runtime/daemon.ts` is the TUI's wrapper for that pattern.
 
 ## Signals and convergence
 
-Every state change broadcasts a `HostSignal` to every connected client:
-
-- `run:start` / `event` / `run:end` — the live stream. A window attaching
-  mid-run starts receiving events immediately and rebuilds prior history via
-  `sessions.loadEvents` (canonical `eventsFromTurns` replay).
-- **The user message is part of the stream**: the host broadcasts a
-  `user-prompt` event for every send / steer / follow-up, BEFORE
-  `run:start`, and stamps the sender's own copy `echo: true` —
-  ORIGIN-AGNOSTICALLY (one broadcast, every peer sees the tag; the host
-  cannot know which window originated the send). Clients that render
-  purely from the broadcast (TUI, attach) ignore the flag. A client that
-  appends its own sends optimistically (the Electron GUI, for
-  refs/attachments enrichment) must dedupe CLIENT-SIDE: consume exactly
-  one pending optimistic append per matching echo and render every other
-  user prompt — echo-tagged prompts with no pending match are genuine
-  remote sends (another window, a queue drain). Never blanket-drop
-  echo-tagged prompts in an adapter: that swallows other windows'
-  messages (see `StreamStore._pendingEcho`).
-- `queue:changed` — the shared type-ahead queue. Host-owned: `queue.add`
-  queues while a run is in flight (from ANY window) and sends otherwise;
-  the host drains FIFO at run end, so queued messages run even after the
-  window that queued them closed. Every window renders the same queue box
-  and can drop (`queue.remove`) or steer (`queue.pushNow`) any entry.
-- **Re-convergence guarantee**: at every run end (and on reconnect) the
-  TUI replaces its transcript with the canonical `sessions.loadEvents`
-  replay — any signal a window missed (disconnect, attach gap, daemon
-  respawn) is reconciled at the next run boundary, so windows cannot
-  drift apart permanently. A dropped daemon connection auto-reconnects
-  (re-activation with full replay) after a short grace.
-- **Slash commands execute HOST-SIDE** (`chat.send` / `chat.pushQueued`
-  route them; full parity incl. agent-spawning commands). The TUI's own
-  `/` commands and `!` shell still execute window-locally by design
-  (UI-coupled); their persisted transcript effects converge immediately
-  via `sessions.touch`.
-- `search:changed` — the shared transcript-search state (mode + query):
-  entering/exiting search or editing the query in one window mirrors in
-  every window on the session, same origin-excluded last-writer-wins
-  contract as drafts, backfilled on attach. Draft publishing is
-  suppressed while searching (the buffer holds the QUERY; the parked
-  draft stays the shared text) and shell mode rides the draft as an
-  out-of-band `shell` flag — never encoded into the text, so a literal
-  leading `!` in a normal draft can't flip other windows into
-  shell-execution semantics.
-- `draft:changed` — the shared per-session prompt draft. The daemon
-  excludes the ORIGINATING peer from the fan-out, so a window's own
-  keystrokes never bounce back and fight its cursor (echo-safety by
-  construction, no client-side dedupe). Last-writer-wins whole-text
-  replacement; drafts are ephemeral daemon memory (`drafts.get/set`),
-  backfilled on attach, and cleared for every other window when any
-  window submits. The TUI publishes EVERY keystroke as a fire-and-forget
-  JSON-RPC notification (no id, no response, FIFO on the socket — the
-  last keystroke always wins), so other windows mirror the draft at
-  keystroke latency; remote drafts apply through the same imperative
-  `setText` path the external-editor reload uses.
-- `settings:changed` — settings written through the host fan out so every
-  window's settings UI converges live. The TUI publishes its local
-  settings changes through the daemon when in daemon mode; behavioral
-  reads (safe-mode gates, etc.) were already convergent because the
-  daemon re-reads `state.json` per call.
-- `approval:request` / `approval:resolved` — the safe-mode queue. Any window
-  may answer; `approval:resolved` clears the surface everywhere else. Pending
-  rows survive daemon restarts (persisted before broadcast) and are listable
-  via `approvals.listPending` for late attachers.
-- `interaction:request` / `interaction:resolved` — `present_plan` /
-  `ask_user`, same fan-out semantics.
-- `sessions:changed` — create/update/delete, keeps session lists in sync.
-- `artifact:recorded` / `artifact:changed` — the session recorded an artifact
-  (PR / branch / commit / file / extension kind; see EXTENSIONS.md → Session
-  artifacts) or one was deleted / refreshed through the host. Both are
-  wake-ups: windows re-query `sessions.artifacts` (one session) or
-  `artifacts.list` (project-wide / reverse lookup by `kind` + `uri`); writes go
-  through `artifacts.delete` / `artifacts.upsert` (the lazy `resolve()`
-  write-back). All additive — a pre-artifact daemon rejects the methods and
-  clients treat that as empty.
-- `work:snapshot`, `todos:snapshot`, `compacting:start` / `compacting:progress`
-  / `compacting:end`, `model:fallback`, `stream:retry` / `stream:retry:cleared`,
-  `cache:break` — auxiliary indicators. `compacting:progress` carries the live
-  summary-token estimate; `stream:retry:cleared` is a distinct kind (not a
-  nullable `attempt`) so a subagent stream dying mid-run clears only its own
-  chip.
-- `prompt-turns` — prompt turns that just persisted, reduced to
-  `PromptTurnRef` (`id` + texts + attachment-only) so a window can bind its
-  live `user-prompt` echo to a turn id during the run. Deliberately not the
-  full `SessionTurn`: those carry base64 attachment payloads.
-- `event { kind: 'session-event' }` — a worker's outcome delivered to its main
-  session (rides the existing `event` signal; no new kind). Clickable in both
-  clients: activation opens the worker.
-- `system-md` — which `SYSTEM.md` override (if any) the host folded into the
-  session's prompt, emitted at agent-build time, plus the precedence losers.
-  Windows cannot derive this locally: the daemon owns the cwd and the
-  `userInstructionsScope` setting.
-
-RPCs added alongside (all daemon-dispatched, all mirrored by the GUI's
-embedded path through the same `ChatHost` method):
-
-- `todos.set` — apply a user todo edit to the `Session` the MODEL reads
-  (`ChatHost.setTodos`, validated + capped host-side). Returns the resulting
-  snapshot, or `null` when no agent is live so the caller falls back to a
-  store-level write. This is what makes the todos modal's edits survive the
-  model's next `todowrite`.
-- `sessions.systemMd` — attach-time backfill of the resolved `SYSTEM.md`
-  (windows cannot probe the daemon's filesystem).
-- `sessions.contextSegments` — the Instructions tab: every prompt segment with
-  provenance, from the live agent's assembly.
-- `sessions.createSystemOverride` — seed a user-scope `SYSTEM.md` from the
-  doctrine in effect; throws when an override could never apply (host-supplied
-  profile, or a scope that excludes user files) rather than writing a file
-  that would never be read.
-
-> **Adding a signal.** The consuming ends fail CLOSED on purpose: both
-> `src/tui/runtime/daemon.ts` and `gui/src/main/chat/host.ts` end their
-> dispatch with `signal satisfies never`, so a new `HostSignal` kind does not
-> compile until it is routed explicitly. Note that this catches an unrouted
-> KIND, not an unconsumed CALLBACK — `onRetry` and `onModelFallback` were once
-> declared, decoded, and dispatched while the TUI never supplied them, which
-> silently removed the retry indicator and the model-fallback notice. Callbacks
-> whose absence is a user-visible regression are therefore REQUIRED (not
-> optional) in `DaemonSessionCallbacks`.
-
-### Concurrent sends
+Host → every connected client, one push channel. Source of truth:
+`HostSignal` in `src/chat/host/signals.ts`.
+
+| Signal | Purpose |
+| --- | --- |
+| `run:start` | A run began. |
+| `run:end` | A run ended (`ok`, optional `error`). |
+| `turn:end` | A turn finished; carries `TurnUsage` (footer context gauge + live cost). |
+| `event` | Canonical `StreamEvent`; `echo: true` marks the sender's own send/steer echo. |
+| `compacting:start` | Manual or auto-compaction began. |
+| `compacting:progress` | Live summary-token estimate during an in-flight compaction. |
+| `compacting:end` | Compaction finished; `effectiveTokens` (success only) is the post-compact estimate. |
+| `prompt-turns` | Persisted prompt turns, reduced to `PromptTurnRef` (id + texts) for echo binding. |
+| `model:fallback` | The run fell back off its primary model. |
+| `work:snapshot` | Cancellable tool calls / background tasks changed. |
+| `todos:snapshot` | Todos state recomputed by the daemon-side agent. |
+| `artifact:recorded` | An artifact was recorded — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `artifact:changed` | An artifact was deleted / refreshed — see [ARTIFACTS.md](./ARTIFACTS.md). |
+| `interaction:request` | A `present_plan` / `ask_user` call is pending. |
+| `interaction:resolved` | An interaction left the pending queue. |
+| `approval:request` | A safe-mode approval is pending. |
+| `approval:resolved` | An approval left the pending queue. |
+| `sessions:changed` | Session created / updated / deleted. |
+| `settings:changed` | Settings were written through the host. |
+| `draft:changed` | The shared prompt draft changed (origin excluded from fan-out). |
+| `draft:attachments` | The draft's composing attachments changed (origin excluded). |
+| `search:changed` | The shared transcript-search state changed (origin excluded). |
+| `suggest:changed` | Another window's ghost-text autocomplete resolved (origin excluded). |
+| `skills:snapshot` | The daemon-side agent's active-skill set changed. |
+| `mcp:auth` | A daemon-side MCP server needs (re-)authentication. |
+| `stream:retry` | Provider retry in progress; `source` is `'parent'` or a retrying child's id. |
+| `stream:retry:cleared` | A retried stream reached a terminal state for `source`. |
+| `system-md` | Which `SYSTEM.md` override (if any) composed this session's prompt. |
+| `cache:break` | A cache-prefix break was detected for the session's last request. |
+| `presence:changed` | Full presence snapshot (attached windows, running, attention). |
+| `hud:state` | Daemon-side extension HUD (status lines + banners); windows overlay their local HUD. |
+| `hud:notify` | Daemon-side extension `ctx.tui.notify` — one-shot transcript line. |
+| `queue:changed` | The shared type-ahead queue changed — broadcast to every peer, origin included. |
+| `extension:signal` | Extension-bus message (`ctx.bus.emit`), private per `extensionId`, 64 KiB cap. |
+
+`event { kind: 'session-event' }` is not a separate signal: a worker's
+outcome to its main session rides the existing `event` kind as a
+`StreamEvent` variant, clickable in both clients.
+
+Cross-cutting contracts worth knowing before you touch a consumer:
+
+- **Re-convergence guarantee**: at every run end and on reconnect, windows
+  replace their transcript via `sessions.loadEvents` — a signal missed to
+  a disconnect, attach gap, or daemon respawn reconciles at the next run
+  boundary.
+- **User messages are part of the stream**: the host broadcasts
+  `user-prompt` (inside `event`) for every send/steer, before `run:start`,
+  tagging the sender's own copy `echo: true`. A client that appends its
+  own sends optimistically (the GUI) must consume exactly one pending
+  append per matching echo — never blanket-drop echo-tagged prompts, since
+  other windows' genuine sends carry the same tag (`StreamStore._pendingEcho`).
+- **Drafts and search** are last-writer-wins, origin-excluded, backfilled
+  on attach. Shell mode rides `drafts.set`'s `shell` flag out-of-band —
+  never encoded into the text — so a literal leading `!` can't flip other
+  windows into shell-execution semantics.
+- **Slash commands execute host-side** (`chat.send` / `chat.pushQueued`,
+  full parity incl. agent-spawning commands). The TUI's own `/` and `!`
+  shell still execute window-locally by design; effects converge via
+  `sessions.touch`.
+- **Queue is host-owned**: `queue.add` queues while a run is in flight
+  (any window) and sends otherwise; the host drains FIFO at run end, so a
+  queued message still runs after the queuing window closes.
+
+> **Adding a signal.** Both `src/tui/runtime/daemon.ts` and
+> `gui/src/main/chat/host.ts` end their dispatch with
+> `signal satisfies never`, so a new `HostSignal` kind fails to compile
+> until routed explicitly. That catches an unrouted *kind*, not an
+> unconsumed *callback* — `onModelFallback`/`onRetry`/`onRetryCleared` are
+> therefore required (not optional) on `DaemonSessionCallbacks`: they were
+> once dispatched while the TUI silently never supplied them, quietly
+> dropping the fallback notice and the retry indicator.
+
+## Concurrent sends
 
 Two windows racing `chat.send` on one session is refused host-side: the
-loser gets an explicit error. `chat.pushQueued` is the race-free spelling —
-it **steers** the live run when one is active and sends otherwise.
-
-> **Cross-process run guard.** Both directions are now guarded through the
-> store: the canonical loop persists session-level `status: 'running'`, so
-> the daemon's `sendPrompt` refuses a session a local in-process window is
-> running, and the local TUI refuses a session the daemon is running —
-> each with an explicit, actionable error. A freshness bound (5 min against
-> `updatedAt`) means a crashed process's leftover marker never blocks new
-> runs; live runs keep the marker fresh through a 60s heartbeat (targeted
-> single-column status UPDATE — safe against concurrent turn appends), so
-> long quiet tool calls never make a live run look stale.
+loser gets an explicit error. `chat.pushQueued` is the race-free
+spelling — it steers the live run when one is active and sends otherwise.
+
+> **Cross-process run guard.** The canonical loop persists session-level
+> `status: 'running'`, so the daemon refuses a session a local in-process
+> window is running, and the local TUI refuses a session the daemon is
+> running — each with an explicit error. A 5-minute freshness bound
+> against `updatedAt` means a crashed process's leftover marker never
+> blocks new runs; a live run refreshes the marker every 60s.
 
 ## Extension bus (`ctx.bus`)
 
 A private, permission-gated, per-extension cross-window message channel.
 An extension declaring the `'ipc'` permission gets `ctx.bus` —
-`emit(payload, { sessionId? })` plus `onMessage(fn)`; without the
-permission `ctx.bus` is `undefined` and no emit path exists.
-
-**Privacy model.** Channels are private per extension id: a subscriber
-only ever receives its own extension's messages. The id on every wire
-envelope is stamped by the host from the registration identity (the
-`buildExtensionRegistry` entry name) — the emit surface has no field a
-caller could use to impersonate another extension, and the daemon
-re-validates inbound `extension.emit` ids against the session cwd's
-registry (id must be loaded AND `'ipc'`-permitted) before fanning out.
-
-**Delivery.** `emit` delivers to local subscribers synchronously
-(`origin: 'local'`) — in-process mode is fully functional with zero IPC —
-and forwards the envelope (`extension:signal`, additive v6) to peers when
-a transport exists. Receivers re-inject with `origin: 'remote'`, dropping
-ids without a local registration and deduping by `(extensionId, seq)`
-(bounded last-seen window) so a self-echo through a second connection of
-the same process, or the same signal arriving on several session
-connections, lands at most once. Payloads are JSON values capped at
-64 KiB serialized — enforced at emit (dropped with a logger warning) and
-again at the daemon trust boundary.
-
-Per embedding:
-
-- **daemon** — shared bus across the per-cwd registries; emits broadcast
-  to every peer; client `extension.emit` notifications are validated,
-  delivered daemon-side, and re-broadcast to every peer except the origin.
-- **TUI** — process-global bus (`tui-bus.ts`); local mode is loopback-only.
-  In daemon mode extensions still run in the TUI process: emits ride the
-  active session connection's `extension.emit` notification, and every
-  connection routes inbound `extension:signal`s back into the one bus.
-- **GUI** — extensions run in the main process; loopback covers all
-  main-side subscribers and the renderer (no extension runtime) never
-  sees these signals. In daemon mode inbound signals re-inject via the
-  main demux, and main-side emits ride the daemon connection's
-  `extension.emit` notification (same shape as the TUI's outbound hook).
+`emit(payload, { sessionId? })` plus `onMessage(fn)`; otherwise `ctx.bus`
+is `undefined`.
+
+- **Privacy**: channels are private per extension id, stamped by the host
+  from the registration identity. The daemon re-validates inbound
+  `extension.emit` ids against the session cwd's registry before fanning out.
+- **Delivery**: `emit` delivers to local subscribers synchronously and
+  forwards the envelope to peers. Receivers dedupe by `(extensionId, seq)`
+  (or `(extensionId, nonce, seq)` on newer peers) so a self-echo or a
+  multi-connection message lands at most once. Payloads cap at 64 KiB,
+  enforced at emit and again at the daemon boundary.
+- **Per embedding**: the daemon shares one bus per cwd registry across
+  peers; the TUI runs a process-global bus (`tui-bus.ts`) riding the
+  active session connection in daemon mode; the GUI's bus lives in the
+  main process (the renderer has no extension runtime).
 
 ## Daemon lifecycle
 
-- Socket: `~/.zidane/daemon/daemon.sock` — a dedicated 0700 subdir so the socket
-  never inherits the shared state dir's permissions (honors `ZIDANE_STORAGE_DIR` /
-  `ZIDANE_PREFIX`), override with `ZIDANE_DAEMON_SOCKET`.
-- Dev builds (`ZIDANE_DEV=1`, set by every `dev` script) use `dev.sock` in the
-  same dir: a checkout's TUI, GUI and `zidane daemon` pair up among themselves
-  and never attach to, drain, or get refused by the installed daemon. Sessions
-  and settings are still shared; use `ZIDANE_PREFIX` for a fully separate
-  instance.
-- **`useDaemon` setting** (Settings → agent, experimental): selects the
-  TUI's execution runtime — in-process agent (default) vs the shared
-  daemon. Plain `zidane` always opens the full TUI either way; the flag
-  only decides where the agent loop runs. With it on, two terminals
-  opening the same session converge on the same live stream: both see
-  the run, either can steer / interrupt / answer approvals, and closing
-  a window leaves the run executing. Window-local by design in daemon mode:
-  the TUI's own `/` command execution and `!` shell (both converge via
-  `sessions.touch`); slash commands sent over the wire execute host-side,
-  and attachments sync end-to-end. Implementation:
-  `src/tui/runtime/daemon.ts` (`connectDaemonSession`).
+- Socket: `~/.zidane/daemon/daemon.sock` — a dedicated 0700 subdir
+  (honors `ZIDANE_STORAGE_DIR` / `ZIDANE_PREFIX`), override with
+  `ZIDANE_DAEMON_SOCKET`. Dev builds (`ZIDANE_DEV=1`) use `dev.sock` in the
+  same dir so a checkout never attaches to or drains the installed daemon.
+- **`useDaemon` setting** (Settings → agent, experimental): in-process
+  (default) vs. the shared daemon. On, two terminals on one session share
+  the live stream — either can steer/interrupt/answer approvals, and
+  closing a window leaves the run executing. Implementation:
+  `connectDaemonSession` in `src/tui/runtime/daemon.ts`.
 - Start explicitly: `zidane daemon [--socket <path>] [--verbose]` or the
-  published `zidane-daemon` bin (`--idle-exit <ms>` exits after a period
-  with zero peers; default 30 min).
-- Spawn-on-demand: `connectOrSpawnDaemon()` / `zidane attach` probe the
-  socket and spawn a detached daemon when nothing is listening.
-- Stale sockets: a leftover socket file from a crashed daemon is probed
-  before unlink — a live daemon is never yanked from under its peers; a
-  second daemon on the same socket refuses to start.
+  published `zidane-daemon` bin (`--idle-exit <ms>`, default 30 min, `0`
+  disables). `connectOrSpawnDaemon()` / `zidane attach` spawn one
+  on-demand when nothing is listening; a leftover socket from a crashed
+  daemon is probed before unlink, so a live daemon is never yanked.
 - Version skew: the first request must be `ipc.hello` carrying
   `IPC_PROTOCOL_VERSION`. On mismatch the daemon replies with a structured
-  error (its own version attached), the client asks it to drain
-  (`daemon.shutdown`) and respawns a fresh one.
+  error, the client asks it to drain (`daemon.shutdown`), and respawns.
 - **Build skew (dev)**: the handshake also carries a build fingerprint
-  (`IPC_BUILD_ID`, the ipc module's file mtime at import). A daemon
-  started from an older build of the SAME protocol version is rejected,
-  drained, and respawned — so during development a rebuild or source edit
-  automatically retires running daemons instead of leaving them serving
-  stale code. Compiled binaries report `'unknown'` and skip the check
-  (releases are governed by the protocol version alone).
+  (`IPC_BUILD_ID`, the ipc module's file mtime); an older build of the
+  same protocol version is rejected, drained, and respawned, so a rebuild
+  retires stale daemons automatically. Compiled binaries report
+  `'unknown'` and skip the check.
 
 ## Turning it off (containment guarantees)
 
-The daemon runtime is opt-in and designed to be inert when disabled:
-
-- **Default off**: `useDaemon` defaults to `false`. Every daemon touchpoint
-  in the TUI is gated on the live controller (`daemonRef`) — with the
-  setting off, no daemon code runs beyond one boot-time module import: no
-  socket, no spawn, no signals, and the in-process path is byte-identical
-  to pre-IPC behavior (send/queue/drain, settings persistence, gates).
-- **Cross-process run guard + heartbeat gated too**: the pre-send
-  'running'-marker guard and the 60s marker heartbeat (TUI local runtime
-  AND the shared host) only engage when `useDaemon` is on. With IPC
-  disabled there is exactly one writer per session, so the only marker a
-  fresh process can meet is a crashed one's — ungated, that meant up to a
-  5-minute send lockout after an ungraceful exit mid-run. `loadSession`
-  additionally heals stale (>5 min) on-disk 'running' headers with a
-  targeted write, bounded so a reader can never clobber a live run's
-  marker.
-- **Setting toggle**: flipping `useDaemon` off takes effect at the next
-  session activation; teardown disposes the controller and the local
-  runtime takes over. Detached daemons idle-exit on their own.
-- **GUI, same gate**: the Electron main process gates on the SAME shared
-  `useDaemon` flag (settings live in the one `state.json`). Disabled, the
-  GUI never probes the socket; its daemon-mode handlers all carry
-  `if (daemon) wire / else local` branches where the local side is the
-  embedded-host path the whole GUI test suite exercises (the suites run
-  daemon-less), and the renderer sync surfaces are inert without signals
-  (the shared-queue latch only engages on a first `queue:changed` and
-  releases on `daemon:state` disconnect).
+The daemon runtime is opt-in and inert when disabled:
+
+- **Default off**: `useDaemon` defaults to `false`; every daemon touchpoint
+  (TUI and, on the same shared flag, GUI main) is gated on the live
+  controller — off, no socket, no spawn, no signals, byte-identical to
+  pre-IPC behavior. Toggling takes effect at the next session activation;
+  detached daemons idle-exit on their own.
+- **Run guard + heartbeat gated too**: the pre-send running-marker guard
+  and its 60s heartbeat only engage when `useDaemon` is on, since with it
+  off there is exactly one writer per session. `loadSession` heals stale
+  (>5 min) on-disk `running` headers with a bounded targeted write.
 - **Emergency kill-switch**: `zidane --no-daemon` (or `ZIDANE_NO_DAEMON=1`)
-  forces the in-process runtime for that launch regardless of the setting —
-  usable even if the settings UI itself is unreachable. The same env var
-  gates the GUI above its setting.
-- **Fail-soft activation**: if the daemon can't be reached (spawn failure,
-  socket problem, handshake bug), session activation catches the error and
-  falls back to the in-process runtime with a visible notice — a broken
-  daemon path can never brick a session.
-- **Shared-state footprint when disabled**: none. The daemon's extra state
-  (socket, pidfile, `pending-approvals.json`, in-memory drafts/queues)
-  is only created by a running daemon; `sessions.db` / `state.json` access
-  from the local TUI is unchanged.
+  forces the in-process runtime for both TUI and GUI regardless of the
+  setting.
+- **Fail-soft + zero footprint**: a spawn failure, socket problem, or
+  handshake bug falls back to the in-process runtime with a visible
+  notice; the daemon's extra state (socket, pidfile,
+  `pending-approvals.json`, in-memory drafts/queues) exists only while a
+  daemon is running.
 
 ## Execution semantics (read this)
 
@@ -317,118 +308,101 @@ Moving the host out of the window process changes two things users notice:
 
 1. **Tools run in the daemon's environment.** cwd comes from the session
    (`metadata.cwd`), but env vars are the daemon's, not the terminal's.
-   Terminal-specific env (`AWS_PROFILE` exported in one shell) does not
-   reach daemon-hosted tools.
-2. **Runs survive window close.** Detaching (`/exit`, closing the terminal)
-   leaves the run executing in the daemon — that's the feature. Interrupt
-   explicitly (`/interrupt`, Ctrl+C while running) to stop it.
+2. **Runs survive window close.** Detaching (`/exit`, closing the
+   terminal) leaves the run executing in the daemon — that's the feature.
+   Interrupt explicitly (`/interrupt`, Ctrl+C while running) to stop it.
 
 ## Testing
 
 - `test/ipc-host.test.ts` — host engine against a mock provider + fake
-  broadcast: run lifecycle, gate decisions (accept/deny/denyAll/off),
-  interaction flow, dispose/shutdown.
+  broadcast: run lifecycle, gate decisions, interaction flow, dispose/shutdown.
+- `test/ipc-host-commands.test.ts` — host-side `/` command execution and
+  parity with the local runtime.
 - `test/ipc-daemon.test.ts` — real unix-socket round-trips: handshake,
   version mismatch, stale socket, multi-peer fan-out, late-attach replay,
-  cross-window approval convergence, the concurrent-send guard, and a full
+  cross-window approval convergence, the concurrent-send guard, and a
   scripted `zidane attach` session.
 
 ## Surface cabling matrix (daemon runtime)
 
-Audited feature-by-feature. **Synced** = converges across every window via
-host signals; **local** = executes in the issuing window by design, effects
-converge through the shared store at the next run-end resync; **gap** =
-known missing cabling, listed with its path forward.
+**Synced** = converges across every window via host signals; **local** =
+executes in the issuing window by design, converges through the shared
+store at the next run-end resync; **gap** = known missing cabling.
 
 | Surface | Status | How |
 | --- | --- | --- |
 | Prompt send / stream / interrupt / steer | synced | `chat.*` + `event` signals |
-| User messages (incl. steered/queued) | synced | host-broadcast `user-prompt` before `run:start` |
-| Attachments (paste/drag images + docs) | synced | `queue.add`/`chat.send` carry base64 payloads; `user-prompt` carries chip metadata (name/type/exact size) |
-| Type-ahead queue (queue box, push/drop) | synced | host-owned queue, `queue:*` RPC + `queue:changed` |
-| Prompt draft (input box content) | synced | per-keystroke `drafts.set` notifications, origin-excluded |
+| User messages (incl. steered/queued) | synced | `user-prompt` broadcast before `run:start` |
+| Attachments (images + docs) | synced | `queue.add`/`chat.send` carry base64; `user-prompt` carries chip metadata |
+| Type-ahead queue | synced | host-owned; `queue:*` RPC + `queue:changed` |
+| Prompt draft | synced | per-keystroke `drafts.set`, origin-excluded |
 | Safe-mode approvals | synced | `approval:*` signals, cross-window resolve + retraction |
 | `present_plan` / `ask_user` | synced | `interaction:*` signals, resumed orphans included |
-| Settings (UI + behavior) | synced | `settings:changed`; daemon is the sole `state.json` writer in daemon mode |
+| Settings (UI + behavior) | synced | `settings:changed`; daemon is sole `state.json` writer in daemon mode |
 | Session list / titles / archive | synced | `sessions:changed` + store reads |
-| Session list "active" scope + status icons | synced | `presence.watch`/`presence.list` + `presence:changed`; each window ALSO runs an app-lifetime presence watcher (probe-only, never spawns, never counted as a window) so the list shows status before activation and across the session-switch teardown gap |
-| Model fallback chains (multi-model picker) | synced | `metadata.modelChain` (TUI byte format) restored host-side into multi-provider agents + `buildRunModel` pinned targets with per-target context windows; `sessions.setModel` carries `fallbacks`, `SessionRow.modelFallbacks` feeds pickers |
-| Compaction summarizer (`compactionModel`) + skill-edit sessions + folderless cwd (HOME anchor) | synced | ported from the GUI engine into the shared host |
-| Model / effort / model-options picker | synced | pick → `sessions.setModel/setEffort/setModelOptions`; session metadata is authoritative, absent metadata seeded from the window's pick |
-| Todos indicator + editing modal | synced | reads: `todos:snapshot` is MIRRORED into the window's session (`applyTodosSnapshot`) after a store reload for `runs` — the bag itself is never persisted, so a reload alone was always empty; `todos.get` backfills on attach. Writes: `todos.set` lands on the live agent's `Session`, and the host fans the result out. Same `chat/todo-edits` mutators on both surfaces |
-| Running work + ctrl+k cancel picker | synced | `work:snapshot` mirror; cancels via `chat.cancelWork` |
+| Session list "active" scope + status icons | synced | `presence.*` RPC + `presence:changed` |
+| Model fallback chains | synced | `metadata.modelChain`; `sessions.setModel` carries `fallbacks` |
+| Compaction summarizer, skill-edit, folderless cwd | synced | ported from the GUI engine into the shared host |
+| Model / effort / model-options picker | synced | `sessions.setModel/setEffort/setModelOptions` |
+| Todos indicator + editing modal | synced | `todos:snapshot` mirror; `todos.set` writes the live `Session` |
+| Running work + ctrl+k cancel picker | synced | `work:snapshot` mirror; cancel via `chat.cancelWork` |
 | Context panel (ctrl+?) | synced | `sessions.contextBreakdown` RPC |
-| Artifacts (`/artifacts`, ctrl+shift+a, sessions-list badge, `#pr` completion) | synced | reads are daemon-authoritative (`sessions.artifacts` / `artifacts.list`, falling back to the window's own store handle only on a pre-artifact daemon); `artifacts.delete` / `artifacts.upsert` fan out `artifact:changed`; the loop's `artifact:recorded` hook broadcasts the same-named signal, so an open modal refreshes the moment the agent opens a PR |
-| History edits (edit / delete turns via the selection modal) | synced | mutations refresh the wrapper from the store first (refused mid-run), retire the daemon's cached agent (`chat.rebuildAgent` — the next run uses the edited history), and announce via `sessions.touch` for immediate re-convergence |
-| History search (transcript + cross-session) | synced + accelerated | `history.searchSession`/`history.searchAll` run in the daemon over authoritative turns (fresh mid-run) with one LRU index cache shared by every window; local worker path remains the fallback |
-| Provider-retry indicator ("retrying n/m", parent + subagents) | synced | `stream:retry` signal; clears on resumed streaming / run end |
-| Run ceilings (max turns / cost / tokens / wall clock / retry budget) | synced | host reads the same settings-driven caps per run the local TUI applies |
-| Native server tools (e.g. Anthropic web_search) | synced | host forwards `stream:server_tool_use/result` as the same synthetic tool events replay produces |
-| Footer context gauge + live session cost | synced | `turn:end` signals carry `TurnUsage` (parent turns drive the gauge; parent + child turns accrue cost) |
-| Subagent spawn banners (start/end/error markers) | synced | host forwards `spawn:before/complete/error` as the same `spawn-start`/`spawn-end` events replay produces |
-| Active-skill chips | synced | `skills:snapshot` on every activation change |
-| MCP "needs login" badge | synced | `mcp:auth` signal; the interactive login flow runs window-local (shared credential store; daemon reconnects on next rebuild) |
+| Artifacts (`/artifacts`, badges, `#pr` completion) | synced | see [ARTIFACTS.md § IPC](./ARTIFACTS.md#ipc) |
+| History edits (selection modal) | synced | store refresh, `chat.rebuildAgent`, `sessions.touch` |
+| History search (transcript + cross-session) | synced + accelerated | `history.searchSession`/`searchAll`, daemon LRU cache |
+| Provider-retry indicator | synced | `stream:retry`; clears on resume / run end |
+| Run ceilings (turns/cost/tokens/wall clock/retry) | synced | host reads the same settings-driven caps as local |
+| Native server tools (e.g. web_search) | synced | host forwards `stream:server_tool_use/result` |
+| Footer context gauge + live session cost | synced | `turn:end` carries `TurnUsage` |
+| Subagent spawn banners | synced | host forwards `spawn:before/complete/error` |
+| Active-skill chips | synced | `skills:snapshot` on activation change |
+| MCP "needs login" badge | synced | `mcp:auth`; login flow itself runs window-local |
 | Manual compaction indicator | synced | `compacting:*` signals |
-| Transcript convergence after any miss | synced | authoritative `loadEvents` replace at every run end + reconnect |
-| `/` commands (incl. extension commands) | synced | HOST-SIDE execution (`src/chat/host/commands.ts`): `chat.send`/`chat.pushQueued` route slash commands in the host — full parity incl. `spawnAgents`/`runAgent` (the command spawn seam lives on the host's ActiveRun), output events fan out live to every window, command turns persist via the live Session. `commands.list`/`commands.completeArgs` serve catalogs over the wire. The TUI's daemon mode still executes its own `/` commands locally by design (UI-coupled) with `sessions.touch` convergence |
-| `!` shell mode | synced output | runs in the issuing window's cwd/env; the persisted call + result turns trigger `sessions.touch` → immediate convergence |
-| Extension tools / hooks / MCPs | synced | the daemon discovers + loads the same extension registry (same allowlist, trust, `state.json`) — extension tools run daemon-side for every window |
-| Agent Plugins (skills + MCP servers, `enabledPlugins` gate) | synced | the host discovers disk plugins per cwd (cached) and folds contributions into the agent it builds, and applies the SECOND plugin gate (`filterRegistryPlugins`) to the registry before composing the preset — so a plugin toggled off contributes nothing daemon-side either. Windows keep their own catalog for the settings list |
-| `SYSTEM.md` prompt override | synced | the host discovers it where it composes the prompt (`systemFor`), under the same `userInstructionsScope` as AGENTS.md; the winning file + shadowed candidates ride the `system-md` signal so a window can tell "none on disk" from "in force" without probing a filesystem that may not be the daemon's |
-| Cache-break chip (`cache:break`) + predictive `cache:drift` | synced | detection is per-agent closure state, so it is installed on the daemon's agent and forwarded as `cache:break`; cost pricing stays window-side (it needs only the provider key + token count) |
-| Main session (orchestration) | synced | opt-in (`orchestration`, default off). The host owns the main (`metadata.role='main'`) and its workers (`metadata.orchestratedBy`); `orchestration.main/createWorker/list/read/send/steer/cancel` RPCs, verbs scoped to the caller's own workers. A worker's `run:end` / pending approval reaches the main on two channels: a `session-event` transcript row broadcast immediately (display, safe mid-stream), and a `<session-event>` user turn + empty wake run when the main is idle (context, at the next turn boundary — buffered while running so a user turn never lands between a `tool_call` and its `tool_result`). Requires the daemon in the TUI: the local runtime has no host |
-| Extension UI (renderers, themes, completion, HUD chrome) | local | loaded by each window's own registry, renders broadcast events |
-| Extension hook-driven HUDs (status lines / banners / notify) | synced | the daemon runs a live HUD bus for extension hooks and forwards `hud:state`/`hud:notify`; windows overlay it under their local HUD (local wins per extension) |
-| Draft attachments (pre-submit composing view) | synced | `drafts.setAttachments` notification (payloads included, 24 MiB cap), origin-excluded fan-out, backfill on attach, cleared on submit |
-| Background-task wake runs | synced | host-scheduled: an idle session with pending task notifications runs a wake pass (no `user-prompt` echo) — even with zero windows attached; user interrupts latch suppression until the next send |
-| Steer / follow-up transcript order | synced | `user-prompt` broadcasts at DELIVERY time via the `steer:inject` hook (matched against accepted texts so system injections never render as user messages) |
-| MCP login → daemon credential pickup | synced | `chat.rebuildAgent` retires the daemon-side agent after a window-local OAuth login (run-end deferred) |
-| Cross-process run guard | synced | store-status guard in both directions with a staleness bound (see above) |
-| Agent-spawning `/` commands (`spawnAgents`/`runAgent`) | **gap** | need a local spawn seam without the chat agent (or a host-side spawn RPC) — the last command-parity item |
-| GUI windows on the shared daemon | synced | GUI main is a daemon guest under the SAME strict opt-in gate as the TUI: the shared `useDaemon` setting in `state.json` (probe-first, never spawns — the daemon needs Bun, Electron main is Node; `ZIDANE_NO_DAEMON=1` is the kill-switch above the setting); execution + HITL + queue + drafts + search + presence + settings writes ride the wire, store + settings reads stay local (same `sessions.db` / `state.json`), store mutations stay local + `sessions.touch` / `chat.rebuildAgent`; fail-soft to the embedded host with a 5s background retry |
-| GUI composer draft / attachments / `?` search / queue / presence badges / settings live-apply | synced | renderer surfaces bound to the daemon-mode channels; inert in-process (no signal → local behavior unchanged) |
+| Transcript convergence after any miss | synced | `loadEvents` replace at run end + reconnect |
+| `/` commands (incl. extension) | synced | host-side (`commands.ts`); TUI's own `/` stays local, converges via `sessions.touch` |
+| `!` shell mode | synced output | runs in the issuing window's cwd/env; `sessions.touch` on persist |
+| Extension tools / hooks / MCPs | synced | daemon loads the same registry; tools run daemon-side |
+| Agent Plugins (`enabledPlugins`) | synced | host applies both plugin gates before composing the preset |
+| `SYSTEM.md` prompt override | synced | `system-md` carries the winning file + shadowed candidates |
+| Cache-break chip + predictive drift | synced | `cache:break`; cost pricing stays window-side |
+| Main session (orchestration) | synced | opt-in (`orchestration`); `orchestration.*` RPCs; requires the daemon |
+| Extension UI (renderers, themes, completion, HUD chrome) | local | loaded by each window's own registry |
+| Extension HUDs (status/banners/notify) | synced | daemon HUD bus forwards `hud:state`/`hud:notify`, local wins |
+| Draft attachments (pre-submit composing view) | synced | `drafts.setAttachments`, origin-excluded |
+| Background-task wake runs | synced | host-scheduled wake pass, no windows required |
+| Steer / follow-up transcript order | synced | `user-prompt` fires at delivery via the `steer:inject` hook |
+| MCP login → daemon credential pickup | synced | `chat.rebuildAgent` after a window-local OAuth login |
+| Cross-process run guard | synced | store-status guard both ways (see [Concurrent sends](#concurrent-sends)) |
+| Agent-spawning `/` commands | **gap** | needs a local spawn seam, or a host-side spawn RPC |
+| GUI windows on the shared daemon | synced | GUI main is a daemon guest under the same opt-in gate |
+| GUI composer draft/attachments/search/queue/presence | synced | renderer bound to daemon-mode channels; inert in-process |
 
 ## Removability
 
 The dependency direction is strictly `src/ipc` → `src/chat`: the host and
-its wire shapes (`src/chat/host/**`, incl. `signals.ts`) import nothing from
-`src/ipc`. Deleting the whole transport — `src/ipc/**`, `src/daemon-cli.ts`,
-`src/tui/runtime/daemon.ts`, and the GUI's daemon glue
-(`gui/src/main/chat/daemon-client.ts` plus the daemon branches in
-`ipc.ts`/`engine.ts`/`interactions.ts`/`safeMode.ts`) — removes multi-window
-sync and nothing else: `createChatHost` stays, because it is the chat engine
-the GUI embeds unconditionally.
+its wire shapes (`src/chat/host/**`, incl. `signals.ts`) import nothing
+from `src/ipc`. Deleting the whole transport — `src/ipc/**`,
+`src/daemon-cli.ts`, `src/tui/runtime/daemon.ts`, and the GUI's daemon
+glue (`daemon-client.ts` plus the daemon branches in
+`ipc.ts`/`engine.ts`/`interactions.ts`/`safeMode.ts`) — removes
+multi-window sync and nothing else: `createChatHost` stays, since it's
+the chat engine the GUI embeds unconditionally.
 
 ## Status / follow-ups
 
 - The default TUI (`zidane`) still runs its agent in-process; `zidane
-  attach` is the daemon-backed terminal client. Migrating the full OpenTUI
+  attach` is the daemon-backed client. Migrating the full OpenTUI
   front-end onto `connectIpcClient` is the tracked follow-up.
-- The GUI embeds the SHARED `ChatHost` in the Electron main process
-  (re-thinned; commands, model chains, summarizer, skill-edit, session-cwd,
-  spawn-markers all canonical) and ALSO speaks daemon: whenever a daemon
-  is listening AND the shared `useDaemon` setting is on,
-  `gui/src/main/chat/daemon-client.ts` connects as a guest. The gate is
-  the SAME strict opt-in as the TUI's — readable here because settings
-  live in the one canonical `state.json`; the earlier socket-as-opt-in
-  heuristic existed only for the pre-migration sqlite bootstrap gap. A
-  manually-run `zidane daemon` with `useDaemon` off is served to explicit
-  `zidane attach` clients but never adopted implicitly by the GUI. The
-  gate re-evaluates live: local `settings:set`, remote
-  `settings:changed` broadcasts, and a 5s poll all trigger
-  connect/disconnect (`ZIDANE_NO_DAEMON=1` is the kill-switch above the
-  setting, mirroring `--no-daemon`) (`drainOnMismatch: false`, never
-  spawns or retires a daemon) and routes execution, HITL, queue, drafts,
-  search, presence, and settings writes over the wire; the embedded host
-  stays as the fail-soft fallback. Settings live in the canonical
-  `state.json` (shared with the TUI): `settings:get` reads it locally in
-  both modes, `settings:set` in daemon mode is WIRE-ONLY — a local
-  pre-write would empty the daemon's before/after diff and skip its
-  agent-teardown ladder on extension/MCP toggles — with a local-write
-  fallback when the socket dies mid-write.
-  Wire-less session mutations (fork / deleteTurn / editTurnText /
+- The GUI embeds `ChatHost` in Electron main and also speaks daemon: when
+  one is listening and `useDaemon` is on, `daemon-client.ts` connects as a
+  guest (`drainOnMismatch: false`), routing execution, HITL, queue,
+  drafts, search, presence, and settings writes over the wire; the
+  embedded host is the fail-soft fallback.
+- `settings.set` in GUI daemon mode is wire-only (a local pre-write would
+  skip the daemon's agent-teardown ladder on extension/MCP toggles), with
+  a local-write fallback if the socket dies mid-write.
+- Wire-less session mutations (fork / deleteTurn / editTurnText /
   attachFolder / detachFolder) stay local-store + `sessions.touch` +
-  `chat.rebuildAgent`, with a `chat.isRunning` refusal guard on history
+  `chat.rebuildAgent`, guarded by a `chat.isRunning` refusal on history
   edits. Remaining optional wire additions: paginated `sessions.loadEvents`
-  + lazy tool-result fetch and the SQL-narrowed cross-session search fast
-  path (perf only — correctness converges through touch/replay today).
+  and a SQL-narrowed cross-session search fast path (perf only).