zidane 6.6.3 → 7.0.0

package/docs/IPC.md

@@ -0,0 +1,420 @@
+# 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 TUI │   │ zidane GUI │   │zidane attach│      clients (presentation only)
+└─────┬──────┘   └─────┬──────┘   └──────┬──────┘
+      │  JSON-RPC over │ unix socket     │            (or Electron IPC for the GUI)
+      └───────────┬────┴─────────────────┘
+            ┌─────▼──────┐
+            │  ChatHost  │   createChatHost(env) — owns live Agents,
+            │ (daemon or │   safe-mode gate, interactions, compaction,
+            │  GUI main) │   work tracking, todos
+            └─────┬──────┘
+            ┌─────▼──────┐
+            │ SessionStore│  shared ~/.zidane (sessions.db, credentials,
+            │  + settings │  safelist, state.json)
+            └────────────┘
+```
+
+## 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. |
+
+## 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.
+- **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.
+
+Both run the **same engine** — the gate flow, edit-approval pipeline,
+compaction, and hook forwarding cannot drift between surfaces anymore.
+
+## 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.
+- `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
+
+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.
+
+## 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).
+
+## 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`.
+- **`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`).
+- 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.
+- 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.
+- **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).
+
+## 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).
+- **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.
+
+## Execution semantics (read this)
+
+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.
+
+## 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.
+- `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
+  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.
+
+| 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 |
+| 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 |
+| 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` |
+| Context panel (ctrl+?) | synced | `sessions.contextBreakdown` RPC |
+| 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) |
+| 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) |
+
+## 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.
+
+## 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
+  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 /
+  attachFolder / detachFolder) stay local-store + `sessions.touch` +
+  `chat.rebuildAgent`, with a `chat.isRunning` refusal guard 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).

package/docs/TUI.md

@@ -566,6 +566,67 @@ Interactive login flow (triggered by `ctrl+L` on a needs-auth row in `SettingsMo
 
 A pre-existing user picker (when at least one provider is already authed) lists current credentials plus a `+ add or re-configure` entry that opens the wizard with a `← back` affordance. Esc on the wizard bails to the picker (or exits the TUI on a true first launch).
 
+## Execution runtimes (in-process vs daemon)
+
+The TUI is one UI over two interchangeable engines. `activateSession`
+(`src/tui/app.tsx`) is the single fork point:
+
+- **In-process (default)** — `agentRef.current = buildAgent(...)`; the agent
+  loop, hooks, gates, and MCP connections live in this window's process.
+  This is the battle-tested path and the floor everything degrades to.
+- **Daemon** (`useDaemon` setting, experimental) — `daemonRef.current =
+  connectDaemonSession(...)` (`src/tui/runtime/daemon.ts`); execution lives
+  in the shared daemon and this window is presentation. Multiple windows on
+  one session converge on the same live stream, queue, drafts, approvals,
+  and presence. Full protocol + daemon lifecycle: `docs/IPC.md`.
+
+**Mutual exclusivity is structural**: an activation populates exactly one of
+`agentRef` / `daemonRef` — no code path ever reconciles two live sources of
+truth. The ~29 daemon touchpoints are shaped `if (daemonRef.current) { RPC }
+else { agent }`, and both branches feed the **same React state** (stream
+buffer, safe-mode queue, interactions queue, queue-box mirror, todo
+indicator, HUD overlay) — the render layer cannot tell the runtimes apart,
+which is why every screen/modal/keybinding works in both modes without a
+fork.
+
+Coexistence rules (why mixing windows is safe):
+
+- **The store is the neutral ground.** Both runtimes read/write the same
+  `sessions.db` / `state.json` through canonical code; a window's live view
+  re-converges with the store at every run end and on `sessions.touch`
+  (out-of-band appends from `/` commands and `!` shell).
+- **Cross-process run guard.** The loop persists session-level
+  `status: 'running'`; both runtimes check it (with a 5-minute freshness
+  bound against `updatedAt`) before starting a run, so an in-process window
+  and the daemon can never stack `agent.run()` on one session — each side
+  gets an explicit error instead of interleaved turns.
+- **Settings single-writer.** While a controller is connected the daemon
+  owns `state.json` settings writes (`publishSettings` → `settings.set`);
+  locally only the `useDaemon` key persists. With no controller (auth
+  screens, disconnect grace, local mode) the pre-IPC local persistence is
+  byte-identical.
+
+Containment (turning it off must always work):
+
+- Every daemon touchpoint gates on the live controller — with the setting
+  off, no daemon code runs beyond a module import.
+- `zidane --no-daemon` / `ZIDANE_NO_DAEMON=1` beat the setting entirely
+  (usable even if the settings UI is unreachable).
+- Activation is **fail-soft**: a daemon connect failure falls back to
+  `buildAgent` for that session with a visible notice — a broken daemon
+  path can never brick a window.
+- Teardown order is load-bearing: dispose the controller FIRST (so local
+  `denyAll()`/`cancelAll()` can't settle shared daemon HITL state), clear
+  the connected flag, bump the activation generation (supersedes an
+  in-flight connect), then drop the remote mirrors (draft, attachments,
+  HUD overlay, presence).
+
+Known asymmetries in daemon mode (documented, not silent): agent-spawning
+`/` commands (`spawnAgents`/`runAgent`) need a local agent and degrade with
+an explicit error; `!` shell and `/` commands execute locally in the
+issuing window (their persisted output converges everywhere via
+`sessions.touch`).
+
 ## Embedding
 
 Drive `<App>` against your own renderer when you need:
@@ -701,3 +762,4 @@ src/tui/
 - `docs/INTERACTIONS.md` — `present_plan` / `ask_user` protocol.
 - `docs/SKILL.md` — skill system, lifecycle, and authoring.
 - `docs/ARCHITECTURE.md` — agent loop, hook firing order, gate precedence.
+- `docs/IPC.md` — daemon protocol, signal fan-out, sync matrix, containment guarantees.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "6.6.3",
+  "version": "7.0.0",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,
@@ -211,6 +211,11 @@
       "import": "./dist/acp.js",
       "default": "./dist/acp.js"
     },
+    "./ipc": {
+      "types": "./dist/ipc.d.ts",
+      "import": "./dist/ipc.js",
+      "default": "./dist/ipc.js"
+    },
     "./eval": {
       "types": "./dist/eval.d.ts",
       "import": "./dist/eval.js",
@@ -221,7 +226,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "zidane-acp": "./dist/acp-cli.js"
+    "zidane-acp": "./dist/acp-cli.js",
+    "zidane-daemon": "./dist/daemon-cli.js"
   },
   "files": [
     "dist",