zidane 7.2.4 → 8.0.4

package/docs/IPC.md

@@ -7,8 +7,8 @@ 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).
+(`connectIpcClient` / `connectOrSpawnDaemon`), `src/tui/runtime/host-session.ts`
+(`connectHostSession`, the TUI's session controller, in-process or daemon).
 
 ```
 ┌────────────┐   ┌────────────┐   ┌─────────────┐
@@ -30,9 +30,10 @@ Entry points: `src/ipc/daemon/server.ts` (`startIpcDaemon`), `src/ipc/client.ts`
 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) ·
+[Daemon lifecycle](#daemon-lifecycle) · [Remote server](#remote-server-zidane-server) ·
+[Reconnect and resume](#reconnect-and-resume) · [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) ·
+[Surface matrix](#surface-cabling-matrix-daemon-runtime) · [TUI remote mode](#tui-remote-mode) · [Removability](#removability) ·
 [Status](#status--follow-ups)
 
 ## The pieces
@@ -41,8 +42,15 @@ Contents: [Pieces](#the-pieces) · [Host environment](#host-environment) ·
 | --- | --- |
 | `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/daemon/` | `dispatcher.ts`: the transport-free method table, per-peer state, signal fan-out and `ipc.hello` handling (`createHostDispatcher`); a connection is a `HostPeer` with a `send`. `handshake.ts`: the pure version / build / release fences. `server.ts`: the unix-socket transport around it (`startIpcDaemon`: framing, socket file, idle exit, retiring, drain; write backpressure is `../transports/send-budget.ts`). Plus the disk-backed environment and 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/transports/` | Wire pieces shared across transports: `peer-rpc.ts` (the host side of one JSON-RPC connection: `ipc.signal` fan-out, requests routed to the dispatcher), `send-budget.ts` (one connection's outgoing budget, socket and WebSocket alike: a peer with more than 8 MiB of pushed signals unsent is dropped, reply bytes set aside; a reply over the message size (WebSocket 32 MiB, socket 256 MiB) goes out as an `IpcErrorCode.ResponseTooLarge` error and the connection stays), `client-core.ts` (the client side: hello with its fences, request deadlines, signals). The WebSocket transport: `ws-server.ts` (`startWsServer`, `Bun.serve`, one JSON-RPC message per text frame; Bun-only, so exported nowhere), `ws-client.ts` (`connectWsClient`, the runtime's global `WebSocket`; never drains a host on mismatch; exported from `zidane/ipc/remote` with the saved-hosts registry (`src/ipc/remote.ts`), not from the `zidane/ipc` barrel, so a client that keeps remote hosts opt-in loads it only on demand), `ws-auth.ts` (token carriers: `Authorization: Bearer`, or a `zidane.bearer.<token>` subprotocol entry next to `zidane` for clients that can't set headers; not enforced unless the server is given `authorize`). |
+| `src/ipc/daemon/signal-log.ts` | Per-session signal numbering and the bounded replay log `sessions.resume` reads; see [Reconnect and resume](#reconnect-and-resume). |
+| `src/server/` | zidane-server: `startZidaneServer` (`server.ts`: one host behind the WebSocket transport with device tokens and a unix socket), the token store (`tokens.ts`), configuration (`config.ts`), upgrade policy (`security.ts`), the checks before the token and the failure accounting (`upgrade-guard.ts`), the audit log (`audit.ts`), and `zidane server …` (`cli.ts`, standalone `main.ts`). May import `src/ipc` and `src/chat`; nothing in `src/` imports it (the `zidane` binary routes `server` to `cli.ts`). See [Remote server](#remote-server-zidane-server). |
+| `src/ipc/daemon/identity.ts` | Host identity: a UUID written once to `<userDataDir>/host-id`. The daemon and a window's in-process host share the user dir, so they share the id (one computer, one store); a remote server has its own. |
+| `src/ipc/memory.ts` | `startInProcessHost` — the same dispatcher in the caller's process, with `IpcClient`s that call it directly (no socket, no spawn). Wire-faithful: JSON copies (a top-level `undefined` result → `null`, nested `undefined` fields dropped), `JsonRpcRemoteError` codes, `JsonRpcConnectionClosedError` for closed connections (in-flight requests included), responses and signals through one queue in production order, `close()` detaches quietly, host shutdown drains runs and fires `onClose`. No request deadlines (nothing to reconnect to) and `daemon.shutdown` does not stop it: its lifetime belongs to the embedding window. |
+| `src/tui/runtime/transport.ts` | `HostTransport`: how a TUI window reaches its host. `socketTransport` (connect-or-spawn for session controllers, a passive connect for the presence watcher) or `inProcessTransport(host)`. `connectHostSession({ transport })` and the presence watcher speak only `IpcClient`. |
+| `src/chat/hosts/` | The client's saved hosts (`createHostRegistry`): entries in `<userDir>/hosts.json` (0600, atomic), tokens in `credentials.json` under `hosts:<id>`. `add` verifies a host before saving it (the entry id is the server's `hostId`); `test` says who answers, or why not (`auth`, `unreachable`, `tls`, `protocol`, `identity`, …). Connecting is injected: `src/ipc/hosts/probe.ts` (`createWsHostRegistry`, `probeWsHost`) wires the WebSocket client. The host index (`host-index.ts`: which host an id lives on, never guessed) and the presence merge (`presence.ts`) are here too. Types and URL rules are in `zidane/chat/pure`. |
 | `src/ipc/attach.ts` | `zidane attach` — a thin readline client proving the multi-window contract end-to-end. |
 
 ## Host environment
@@ -57,6 +65,15 @@ process supplies a `ChatHostEnvironment`:
   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.
+- **A host in the window's own process**: `createHostEnvironment({
+  broadcast, shared: { config, runtimeConfig, hostRuntime?, extensionBus?,
+  multiProcess? } })`, the daemon's environment reusing the window's boot
+  config (one store and one writer to `state.json` in the process), its
+  per-cwd runtime config (no second extension discovery, so no extension
+  `setup` runs twice in the process; `invalidate` / `forget` keep the
+  daemon's reload contract) and its extension bus. Single-process unless
+  `multiProcess`. `createDaemonEnvironment` is the same function without
+  `shared`: own config, discovery, multi-process.
 
 Both run the same engine — the gate flow, edit-approval pipeline,
 compaction, and hook forwarding cannot drift between surfaces.
@@ -71,28 +88,53 @@ path through the same `ChatHost` method. Source of truth: `IpcMethods` in
 | --- | --- |
 | `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.steer` | Inject a message into the live run. Resolves `false` when no run took it. |
+| `chat.followUp` | Queue a message on the agent to run after the current turn (no steer). Resolves `false` when no run took it. |
 | `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.listMeta` | The sessions list as a window renders it (`SessionMeta`: title, turn / message / run counts, project, cwd, environment, artifact count, main flag), by project root (`null` = untagged) or all. |
+| `sessions.getMeta` | One `SessionMeta` by id, or `null`. |
+| `sessions.get` | The whole session document: the live copy when an agent holds it, else the stored one (stale `running` marker demoted), or `null`. `turns: false` leaves the turns out (read them with `sessions.getTurns`) and names the snapshot's `version`. |
+| `sessions.getTurns` | `{ sessionId, from?, limit? }` → `{ turns, total, version }`: a slice of the same copy's turns (default 200, at most 1000), or `null`. Pages and the `turns: false` head come from one cached snapshot per content version (the session is read once per version, not per page), named by `version`. `loadSessionDocument(request, sessionId)` (`zidane/ipc`) reads a whole document a page at a time with it (halving a page refused as too large), starts over when the version changes mid-read (a few times, then the whole document in one reply), and reads in one reply from an older host. What the GUI exports a server session with. |
+| `sessions.getToolResult` | `{ sessionId, callId, turnId? }` → the full text of one tool result, or `null`: what a clipped tool row shows on expand, without the session crossing the wire. |
+| `sessions.getHeader` | One session's header: its `SessionMeta` row plus `metadata`, `agentId`, `status`, `createdAt`, without turns or runs (the live copy when an agent holds it; from the store's header index when it has one). What a window re-reads on `sessions:changed`. `usage: true` adds `contextTokens` (the last parent turn's context size: the footer gauge) and `costUsd` (summed run costs: the cost pill), computed host-side from the turns and runs, so a client needs no document for them. |
+| `sessions.setExtensionState` | Write (or, `value` omitted, delete) one key of an extension's per-session state in the host's copy (renderer `useSessionState`). |
+| `sessions.create` | Create a session through the shared lifecycle factory (`src/chat/session-factory.ts`): cwd, derived project root, agent, title, model + fallbacks + `effort` / `modelOptions`, `extensionEdit` / `skillEdit` markers, `pinnedSkills`, `environment` (`{ kind, branch?, base? }`; omitted = local), and an `id` (refused when taken or not a plain token). A kind that provisions returns at once with the row's `environment.state` = `provisioning`. |
+| `sessions.delete` | Delete a session: retire its live agent + pending HITL state, tear down the environment it owns, then remove the row and its on-disk artifacts (`ChatHost.deleteSession`). Resolves with `{ environment? }` — `removed: false` + `reason` when the provider kept it. Clients in daemon mode must delete through this, never behind the daemon's back. |
+| `sessions.environmentActions` | The per-session commands the session's environment offers right now (push, open PR). |
+| `sessions.runEnvironmentAction` | Run one in the session's environment (resumed when paused); `{ message, url? }`. |
+| `sessions.workspaceExec` | Run a shell command in the session's workspace: its execution context, rooted inside the environment when the files live there (resumed when paused), else at the session's cwd. Optional `cwd` (same path rules), `env`, `timeoutSeconds` (default 30): `ExecResult`. Backs `!` shell mode for sandboxed sessions and window-side `ctx.workspace` in the TUI's daemon mode. |
+| `sessions.workspaceReadFile` | Read a file from the session's workspace. Paths resolve against the workspace root the way the execution context resolves them (absolute paths as given); containment is the context's own: a sandbox confines to its workspace, the local process context doesn't, except on a confined host (a server), where a path on the host's filesystem must resolve (real path) inside the workspace roots or the session's own environment folder (a worktree), and never into the data dir (`ChatHost.workspace.checkPath`); the same holds for `workspaceWriteFile` / `ListFiles` / `FileSize` and `workspaceExec`'s `cwd`. Backs the files panel and diffs for sandboxed sessions. |
+| `sessions.workspaceWriteFile` | Write a file in the session's workspace, same path rules. |
+| `sessions.workspaceExecStream` | The same command streamed (`!` on a remote host): `{ execId }`, then `workspace:exec:data { execId, stream, chunk }` signals in arrival order and one `workspace:exec:exit { execId, code, signal, truncated?, cancelled? }`, to the requesting connection only (never fanned out or replayed; signals may beat the reply). Runs the session context's `execStream` (a machine's too: `exec.stream*`); a context without one runs the buffered exec and reports it the same way. Bounded per connection: 4 running commands, 64 KiB chunks, 1 MiB of output (then the process group is stopped and the exit says `truncated`). Same `cwd` confinement as `workspaceExec`. A dropped connection kills what it started. |
+| `sessions.workspaceExecCancel` | Kill a streamed command's process group (`SIGTERM`, `SIGKILL` after the grace): `{ cancelled }`, `false` for another connection's exec or one that ended. |
+| `sessions.workspaceListFiles` | List a directory (or, with `options.glob`, match a pattern) in the session's workspace: `ListFilesOptions` semantics, same path rules. |
+| `sessions.workspaceFileSize` | A file's byte size in the session's workspace, or `null`. |
+| `sessions.setLaunchOverrides` | A window's overrides for the session agent: `zidane run --system / --mcp / --context` (`system` replaces the base prompt, extension fragments still append; `mcp` adds servers after the discovered ones; `execution` runs the session on the launch context) and `cwd`, a folder picked mid-session (moves the live agent without a rebuild). In memory and per client: the session runs the most recent connected setter's, and a client clearing (a call with no field) or disconnecting drops only its own, so the previous setter's apply again. |
+| `sessions.retryEnvironment` | Provision a failed (or restart-stranded) environment again, in the background; progress arrives as `sessions:changed`. |
 | `sessions.setTitle` | Rename a session. |
+| `sessions.generateTitle` | Title a session on the host, with the host's providers and credentials (`{ providerKey?, model? }`: the window's pick, used when the host has that provider; else the session's own). Written as a rename; refuses Main. |
 | `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.loadEvents` | Canonical transcript replay — the re-convergence source of truth. Optional paging: `{ before?, limit? }` (turn positions; `limit` default 200, at most 1000) answers `{ events, cursor?, exact: true, start }`, whole runs before `before` (a run: a user message to the turn before the next one): the run the page ends in, and the runs before it while the page stays within `limit` turns, so scroll-back never brings part of a run. A run longer than `5 × limit` turns on its own comes in pieces of that size, each starting on a turn that keeps a tool call with its result; `cursor` is the next page's `before`, absent at the first turn. A page's events are its turns' slice of the WHOLE replay (`exact`), so pages concatenate to exactly one whole load: exchange separators, run receipts, subagent markers and command state as the whole replay has them. `start` is how many events of the whole replay come before the page (absent from older hosts). `loadAllEvents` joins them as they are, and puts the exchange separator back at the joins of an older host's (unflagged) pages; `loadEventsTail` reads from the end only until a predicate is met, returning how many events it left out. Without them, the whole transcript as a plain array (the old shape). Typed callers page through `loadEventsPage(client.request, params)` (`zidane/ipc`), which also reads an older host's whole array as one page. |
+| `sessions.resume` | Reattach without a reload: `{ sessionId, epoch, afterSeq }` → the session's numbered signals after `afterSeq`, or `{ ok: false, reason: 'epoch' \| 'gap' }` (then `loadEvents`). See [Reconnect and resume](#reconnect-and-resume). |
 | `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.fork` | Fork at a turn into a new session (`ChatHost.forkSession`); announced as a `sessions:changed` create. |
+| `sessions.deleteTurn` / `sessions.editTurnText` | History edits in the host: refused while the session runs (here or by another process's fresh run marker), one atomic rewrite when the store has `mutateTurns`, cached agent retired, `sessions:changed`. |
+| `sessions.setFolder` | Bind a session to a folder (`cwd` + derived project root), or back to a plain chat with `cwd: ''`. Refused while running and for the Main session. |
+| `sessions.appendTurns` | Turns written outside a run (`!` shell output, a window's `/` built-in output and notices), through the live session when one exists; fans out `sessions:changed`. |
+| `sessions.appendNote` | `ctx.appendNote` outside a run: a display-only note persisted as a `command` turn and broadcast under the same turn id. `false` for an unknown session or no blocks. |
+| `sessions.compact` | Compact a session now (loads its agent when no window has run it). Returns a `CompactionReport` (replaced/dropped turn counts, restored files and skills, summarizer model and usage, post-compact `effectiveTokens`), or `null` when there was nothing to compact. |
 | `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. |
@@ -102,7 +144,7 @@ path through the same `ChatHost` method. Source of truth: `IpcMethods` in
 | `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). |
+| `todos.set` | Apply a user todo edit to the live agent's `Session` (what `todowrite` reads); with `persistIdle`, to the stored session when no agent is live. |
 | `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. |
@@ -111,12 +153,18 @@ path through the same `ChatHost` method. Source of truth: `IpcMethods` in
 | `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.list` | The `/` commands the host runs for a cwd: its extensions' (the registry for that folder there) then its built-ins (`/help`). A TUI session on a server completes and sends these (`useHostCommands`). |
 | `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. |
+| `terminal.state` | A session's terminals, whether this host can run them, and its environment kind. See [TERMINAL.md](./TERMINAL.md). |
+| `terminal.open` | Open a terminal in the session's environment (or `target: 'local'`). |
+| `terminal.attach` / `terminal.detach` | Start / stop showing a terminal in one view (`clientId`): history plus the offset live output resumes at. Views are detached when their connection drops. |
+| `terminal.write` / `terminal.resize` / `terminal.ack` | Input; size (`claim: true` when the user focuses or types); acknowledge written output to keep it flowing. |
+| `terminal.restart` / `terminal.close` / `terminal.setHidden` | Restart a user terminal; close one (an agent terminal's task is killed); hide one from the agent's tools. |
+| `terminal.registerViewer` / `terminal.unregisterViewer` | This connection can show terminals (the desktop app). Agents get the terminal tools only while a viewer is attached; the registration ends with the connection. |
 | `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. |
@@ -133,15 +181,55 @@ path through the same `ChatHost` method. Source of truth: `IpcMethods` in
 | `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`. |
+| `environments.list` | Every registered environment kind described for a `cwd`: enabled, default, availability + reason, branch suggestion, option fields (secrets as `configured` / `fromEnv` only), and for a machine's kinds `machine: { id, name, status }`. |
+| `environments.verify` | "Test connection" for a kind with its current options: `{ ok, detail }` or `{ ok: false, reason }`. |
+| `environments.update` | One Settings → Environments edit (enable, default, option values, secrets), validated against the kind's schema; settings go through `settings.set`, secrets to the daemon's environment credential store. |
 | `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. |
+| `fs.roots` | Where session folders may be: a server's workspace roots (`confined: true`), or the user's home on a local host (unconfined). |
+| `fs.listDirs` | The folders in `path` (default: the first root) for a picker on the host's machine: real paths inside the roots only (`..` and symlinks out refused), no dotfiles, `isGitRepo` per entry, capped at 2000 (`truncated`). |
+| `auth.status` | The host's provider credentials: per provider, `configured`, `oauth`, `envKey`, and its sources (stored API key, OAuth accounts with labels, env var), which is active. Never a secret. |
+| `auth.setApiKey` | Store an API key as the provider's active credential in the host's `credentials.json`, re-apply the host's auth env, rebuild agents (idle now, busy at run end). OAuth sign-in: `auth.oauth.*`. |
+| `auth.remove` | Remove one stored credential (`account`, a key from `auth.status`) or all of a provider's; a removed key also leaves the host's environment (one it only has from its own environment stays). |
+| `auth.oauth.begin` | OAuth sign-in with the browser on the client and the tokens on the host: `{ provider }` or `{ mcpServer, cwd?, kind?, redirectUri }` (an MCP server of `cwd`'s catalog; `redirectUri` a `http://127.0.0.1:<port>/…` loopback the client listens on). The host runs the login (PKCE verifier, `state`, discovery and dynamic registration stay there) and answers `{ flowId, url, mode, redirectUri?, userCode?, instructions?, expiresAt }`: `loopback` (the client listens at `redirectUri`: a provider's fixed port, e.g. Anthropic's `http://localhost:53692/callback`; a busy port falls back to pasting), `browser` (open `url`, maybe paste a code), `device` (show `userCode`). zidane's providers bind no listener on the host (`callbackServer: false`); a provider that would (it ignores the flag) is refused. A question the login asks before its URL comes back as `{ mode: 'step', url: '', step }` (`HostOAuthStep`: a `select` with options, or a `prompt`): answer it with `auth.oauth.respond`. The flow is bound to this connection, at most 4 open, expires after 10 minutes (`oauthFlowTtlMs`). |
+| `auth.oauth.complete` | `{ flowId, code?, state?, input? }`: the code from the loopback (its `state` must be the flow's, else the flow ends refused) or what the user pasted (a callback URL, `code=…&state=…`, Anthropic's `code#state`; a `state` in it is checked too), delivered once; then waits for the token exchange. Without a code it only waits (device and polling flows). Another connection's flow is refused. Result: `{ provider?: HostProviderAuth }` or `{ mcpServer? }`, never a token, or `{ step }` when the login asks something after its URL (answer with `auth.oauth.respond`, then call `complete` again); tokens go to the host's `credentials.json` / `mcp-credentials.json` and agents rebuild. |
+| `auth.oauth.respond` | `{ flowId, stepId, value? }`: answer the flow's pending step (a `select`'s option id, none to cancel; a `prompt`'s text). Answers with where the flow stands (`HostOAuthBegin`: its URL, or the next step). Additive. |
+| `auth.oauth.cancel` | Abandon a flow of this connection: `{ cancelled }`. |
+| `catalog.install` / `catalog.remove` / `catalog.update` | Install a skill or an extension in the host user's scope from a GitHub (`owner/repo[#ref][:dir]`, GitHub / skills.sh URLs) or npm spec (paths refused; `scope` only `'user'`), remove a user-scope one by name, update an extension from its source. Gated by `remoteInstalls` (a zidane-server's `allowRemoteInstalls`; refused on any other host), every attempt audited with the token, bounded to 5 minutes; progress lines come back with the result. Extensions join an explicit `enabledExtensions` list; removals leave the enabled lists. Then agents rebuild and every window gets `catalog:changed`. |
+| `mcp.upsert` / `mcp.remove` | Add or replace / remove an MCP server in the host user's `mcps.json` (`{ name, created }` / `{ removed }`); validated (`command` or http(s) `url`, string `env` / `headers`), its secrets stored there and never echoed (`catalog.mcps` redacts them). Same gate, audit and signal as `catalog.install`. |
+| `catalog.skills` / `catalog.mcps` / `catalog.extensions` / `catalog.plugins` | What the host discovered for the settings tabs, with the same scans and gates its agents use, each entry with `enabled` (its settings' allowlist; unset = all) and `toggleable` (its own allowlist governs it: not a plugin's or extension's contribution, not broken). `cwd` adds that folder's project scope (inside the workspace roots on a server), else the host user's scope. Skills carry origin (`disk`, `plugin`, `extension`); MCP servers their transport, command, args, URL, file, with `<redacted>` in place of: every `env` / `headers` value; in the URL and in every URL-shaped argument, the userinfo, query values, fragment values (`#k=v`, or a token-shaped fragment) and token-shaped path segments; the value of a secret-looking flag (`--token x`, `--api-key=x`), of a header flag (`-H` / `--header` / `--header=`: `Name: <redacted>`) and of a secret-looking header anywhere (`Authorization: …`); the value of a secret-looking `KEY=VALUE` (`-e GITHUB_TOKEN=…`, `env API_KEY=…`, `--env=…`); known token shapes anywhere in an argument (`sk-`, `sk_live_`, `ghp_` / `gho_` / `ghu_` / `ghs_` / `ghr_`, `github_pat_`, `xox?-`, `AKIA` / `ASIA`, `glpat-`, `zds_`, `AIza`); and a whole argument or path segment that looks random (20+ characters: hex / UUID-like, or mixed case and digits with high entropy). File paths, package names and dash-joined words are kept. The rules are `src/ipc/daemon/redact.ts`; they are a best effort over free-form arguments, not a guarantee. Plus the config files that failed to parse; extensions their source, version, error, capabilities; plugins their origin, contributions, rejection. Toggles write the enabled lists with `settings.set`; installs, removal and MCP sign-in stay on the host's machine (`src/ipc/daemon/handlers/catalogs.ts`, `catalog-entries.ts`). |
+| `models.list` | The host's credentialed providers (`detectAuth` on its data dir) and their models (`ModelInfo`), for the model picker of a session on that host; `cwd` adds what its extensions contribute there. |
+| `machines.list` / `machines.forget` | The machines lending this host their execution (online or not), and forgetting one: it disconnects, its `local@` / `worktree@<name>` kinds stop resolving, and the token it registered with can't register it again (a new token can). `machine:status` signals each change. See `docs/MACHINES.md`. |
+| `machines.listDirs` | A machine's folders for a picker (`path`, default its first root), listed on the machine (`fs.list`, confined there); never waits for an offline machine. |
+| `machines.share.start` / `machines.share.stop` / `machines.useServer` / `machines.links.status` | This (local) host's machine links, behind remote hosts (refused while off; always refused on a zidane-server): share this computer with a saved server, use a saved server as a machine; `machine:links` signals each change. See `docs/MACHINES.md` § Client UI. |
+| `machine.attach` / `machine.call` / `machine.detach` | The reverse direction, on a server with `allowAsMachine`: a client's host asks the server to lend itself over this connection, then sends each machine request; notifications come back as `machine:notification` signals to that connection only. The server keys its executor by this connection's token and the `hostId` (another token never reaches it; 4 per token); a full one answers `MachineErrorCode.Busy` (retry). Refused while off. See `docs/MACHINES.md` § Reverse direction. |
+| `tokens.createMachineToken` | A zidane-server mints a `machine` token for the asking client (one-step "share this computer"), at most 16 live per client token, audited with it; other hosts refuse. |
+| `sync.status` / `sync.claim` / `sync.push` / `sync.reset` / `sync.release` | Settings sync from a client's computer to a zidane-server ([SERVER.md § Settings sync](./SERVER.md#settings-sync)); other hosts refuse, and `ipc.hello` says `sync: true` on a server that takes it. `status`: the record (source device, categories, opted-in keys, synced fields, overrides; no values). `claim { deviceId, deviceName, takeover?, categories?, keys? }`: `{ claimed: false, status }` when another device is the source and `takeover` is not set. `push { deviceId, category, payload }`: one category's snapshot (`SyncPayloads`), source only, applied through the host's own setters (`settings.set` for syncable host-scoped keys, never window-only ones; the user-scope `SYSTEM.md` and skills as files; `mcp.upsert` / `remove`; `catalog.install`, behind `allowRemoteInstalls`; `auth.setApiKey` for opted-in providers), skipping overrides: `{ applied, unchanged, skipped: [{ field, reason }], warnings }`. `reset { field }`: drop an override. `release { deviceId }`: the source stops (values stay). A window's `settings.set` / `mcp.*` / `catalog.remove` / `update` / `auth.setApiKey` / `remove` on a synced field marks it an override. Each changes the record → `sync:changed` to every window; each call is audited. |
 | `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
+Without a version bump (additive; an older daemon answers "method not found", which clients treat as unsupported): `catalog.*` and `models.list` (the TUI keeps its enabled-list panels and this window's providers), `sessions.loadEvents` paging and `exact`, `sessions.getHeader` `usage` (an older host ignores the fields), `sessions.getTurns`, `sessions.getToolResult` and `sessions.get` `turns: false` (a client reads the whole document from an older host), `sessions.getHeader` (the TUI falls back to `sessions.get`), `fs.roots`, `fs.listDirs`, `auth.status`, `auth.setApiKey`, `auth.remove`, `sessions.resume`, `signalEpoch` on `ipc.hello` and the `$seq` signal envelope field, the `$/ping` heartbeat request (answered outside the method table, before the handshake too), host identity (`hostId` / `hostKind` / `hostName` on `ipc.hello` and `daemon.info`, `hostId` on `SessionRow`; `hostRefOf(hello)` is `null` against an older host), `sessions.setLaunchOverrides`, `sessions.workspaceListFiles`, `sessions.workspaceFileSize`, `cwd` / `env` on `sessions.workspaceExec`, workspace calls for local sessions, the `sessions.compact` report, `sessions.appendNote`, `sessions.workspaceExecStream` / `workspaceExecCancel` and the `workspace:exec:*` signals (a client falls back to the buffered `workspaceExec`), `auth.oauth.*`, `catalog.install` / `remove` / `update` and `mcp.upsert` / `remove` (offered when `ipc.hello` says `remoteInstalls`), the `catalog:changed` signal, `cwd` / `execution` on `sessions.setLaunchOverrides`, and the `mcp:status` and `mcp:settled` signals. Version 13 added the `terminal.*` methods and the `terminal:*` signals. Version 12 added `sessions.workspaceExec`, `sessions.workspaceReadFile` and `sessions.workspaceWriteFile`. Version 11 added `environments.verify`, `sessions.environmentActions` and `sessions.runEnvironmentAction`, and `suspended` on row environments. Version 10 added `sessions.retryEnvironment`, `environments.list`, `environments.update`, `environment` on `sessions.create` / `SessionRow`, and the `sessions.delete` result. 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.
+`src/tui/runtime/host-session.ts` is the TUI's wrapper for that pattern.
+
+### Errors
+
+A failed request rejects with a `JsonRpcRemoteError` carrying one of these
+codes (`AcpErrorCode` in `src/acp/types.ts`, `IpcErrorCode` in
+`src/ipc/protocol.ts`). Clients branch only on the codes that call for a
+different action (`VersionMismatch`, `ResponseTooLarge`, method not found);
+the rest are a plain remote error with a message.
+
+| Code | Name | When |
+| --- | --- | --- |
+| -32601 | method not found | The host lacks the method (an older host: degrade). |
+| -32602 | invalid params | The params are malformed (`InvalidParamsError`: not an object, a bad session id, a wrong type); `message` names the field. |
+| -32010 | `VersionMismatch` | `ipc.hello` across protocol versions or builds. |
+| -32011 | `NotHandshaken` | A method before `ipc.hello` (`daemon.info` / `daemon.shutdown` excepted). |
+| -32012 | `RateLimited` | A network transport's per-connection request budget is spent; retry later. |
+| -32013 | `ResponseTooLarge` | The reply would exceed the transport's message size; ask for less. |
+| -32014 | `HandlerFailed` | The handler threw: the host refused or failed the call (`message` says why). Hosts before it answered -32000, ACP's `AuthenticationRequired`; clients never branched on either. |
 
 ## Signals and convergence
 
@@ -153,7 +241,7 @@ Host → every connected client, one push channel. Source of truth:
 | `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. |
+| `event` | Canonical `StreamEvent`; `echo: true` marks the sender's own send/steer echo. A failed call's `tool-result` carries `isError: true` (live and on replay); there is no separate `error` row for it. |
 | `compacting:start` | Manual or auto-compaction began. |
 | `compacting:progress` | Live summary-token estimate during an in-flight compaction. |
 | `stream:progress` | Live counters for the streaming parent turn (`outputTokens`, `estimated`, `elapsedMs`, optional `estCostUsd`), throttled ~4/s plus one final tick before the turn settles. Clients fold `estCostUsd` into the session cost until the matching `turn:end`. |
@@ -166,6 +254,10 @@ Host → every connected client, one push channel. Source of truth:
 | `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. |
+| `terminal:changed` | A session's terminal list changed (full list). |
+| `terminal:output` / `terminal:reset` | Output batch starting at `offset`, or a view reset from history; sent only to connections that attached that terminal. |
+| `workspace:exec:data` / `workspace:exec:exit` | A streamed workspace command's output and its end (`sessions.workspaceExecStream`); sent only to the connection that started it. |
+| `catalog:changed` | `{ catalog }`: a client installed, updated or removed something on the host (`catalog.install`, `mcp.upsert`, …); windows re-read that catalog. |
 | `approval:request` | A safe-mode approval is pending. |
 | `approval:resolved` | An approval left the pending queue. |
 | `sessions:changed` | Session created / updated / deleted. |
@@ -176,8 +268,10 @@ Host → every connected client, one push channel. Source of truth:
 | `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. |
+| `mcp:status` | A daemon-side MCP server connected (`status: 'connected'`) or failed to bootstrap (`status: 'failed'`, with `transport`, `error`, optional `code`). |
+| `mcp:settled` | The session agent's MCP bootstrap finished (after every server's `mcp:status` / `mcp:auth`); a window's deadline for its one-shot auto-login. |
 | `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`. |
+| `stream:retry:cleared` | A retried stream for `source` resumed streaming or reached a terminal state. |
 | `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). |
@@ -186,16 +280,19 @@ Host → every connected client, one push channel. Source of truth:
 | `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. |
 
+**Numbering.** Every signal with a `sessionId` that goes to every peer (not the origin-excluded drafts / search / suggestions, not terminal output) carries its number in its session as an extra `$seq` field on the `ipc.signal` params: from 1, gap-free within one host process (`HelloResult.signalEpoch`). Clients predating it ignore the field; `IpcClient` strips it and hands it to listeners as `onSignal((signal, meta) => ...)`, `meta.seq`.
+
 `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.
+- **Re-convergence guarantee**: at every run end, and on a reconnect that
+  cannot resume, windows replace their transcript via `sessions.loadEvents`
+  — a signal missed to a disconnect, attach gap, or daemon respawn
+  reconciles at the next run boundary. A reconnect to the same host process
+  replays exactly what was missed instead ([Reconnect and resume](#reconnect-and-resume)).
 - **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
@@ -214,12 +311,12 @@ Cross-cutting contracts worth knowing before you touch a consumer:
   (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
+> **Adding a signal.** Both `src/tui/runtime/host-session.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
+> therefore required (not optional) on `HostSessionCallbacks`: they were
 > once dispatched while the TUI silently never supplied them, quietly
 > dropping the fallback notice and the retry indicator.
 
@@ -230,9 +327,8 @@ 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
+> `status: 'running'`, so the daemon refuses a session a local-mode window's
+> in-process host is running, and the reverse — 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.
 
@@ -262,11 +358,12 @@ is `undefined`.
   (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`.
+- **`useDaemon` setting** (Settings → agent, experimental): the window's
+  own in-process host (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. Both go through
+  `connectHostSession` in `src/tui/runtime/host-session.ts`; only the transport
+  differs (`src/tui/runtime/transport.ts`).
 - Start explicitly: `zidane daemon [--socket <path>] [--verbose]` or the
   published `zidane-daemon` bin (`--idle-exit <ms>`, default 30 min, `0`
   disables). `connectOrSpawnDaemon()` / `zidane attach` spawn one
@@ -290,28 +387,200 @@ is `undefined`.
   may ignore `codeVersion`, so a recognizable `appVersion` is the fallback.
   A successful legacy hello reporting an older release is refused without
   shutting down its active runs. Unknown versions cannot establish release age.
+- **A network server** (`hostKind: 'server'`) keeps only the protocol fence:
+  a newer-release or newer-build client attaches and degrades (`optional()`)
+  like an older one, the server never retires for it, and no client ever
+  drains it (`client-core` refuses to, whatever its `drain` option). A
+  protocol mismatch is refused both ways with both versions and the side to
+  upgrade (`Protocol version mismatch: the server speaks v13, the client v14.
+  Upgrade the server.`; the client words it from its side).
+
+## Remote server (zidane-server)
+
+Running one (Docker, configuration, proxies, tokens, operations):
+[SERVER.md](./SERVER.md). This section is the internals.
+
+`startZidaneServer` (`src/server/server.ts`) serves ONE host over two
+front-ends: the WebSocket transport (`src/ipc/transports/ws-server.ts`,
+Bun only) for remote windows, and a unix socket (`startIpcDaemon`) for
+local tools on the server's machine. Both attach to the same dispatcher,
+built by `createServerHostDispatcher` (`ws-server.ts`, around
+`createHostDispatcher`) and handed to each as the `dispatcher` option of
+`startWsServer` / `startIpcDaemon` (a transport given a dispatcher serves
+it and leaves draining it to its owner), so a session created over one is
+live on the other. The host is a `server` (`hostKind`): multi-process (`env.multiProcess`
+forced on: the run guard engages, runs outlive their windows), no idle
+exit, never drained or retired by a client. The socket is unauthenticated
+like the daemon's (0600 socket in the data dir) and not audited.
+
+- **Run it**: `zidane server start` (`src/server/cli.ts`; standalone
+  `bun src/server/main.ts start`, compiled into the `zidane-server`
+  binary by `scripts/build-server.ts`). `zidane server health` asks
+  `daemon.info` over the unix socket; `health --http` GETs `/healthz` on
+  the configured port (`healthUrl`: loopback for a wildcard host; the
+  image's healthcheck). Tokens: `zidane server token create
+  --name <device>` (prints the token once, on stdout), `token list` (id,
+  name, scope, created, last used, revoked; never secrets), `token revoke
+  <id|name>`, `token generate` (a fresh token, stored nowhere). The token
+  commands edit the data dir's files directly, so they work while the
+  server runs. At start, `ZIDANE_SERVER_BOOTSTRAP_TOKEN` (or
+  `ZIDANE_SERVER_BOOTSTRAP_TOKEN_FILE`, a file holding it; both set is a
+  boot error; well-formed or a boot error) is adopted as the live client
+  token `bootstrap` (`TokenStore.adopt`: created, unchanged, rotated with
+  the old one revoked, or ignored with a warning when that value was
+  revoked); both variables are removed from the process environment
+  (children spawned later don't inherit them; the container's own
+  configuration and `/proc/1/environ` still hold an inline value). In a
+  Linux container, a data dir on no mount, an anonymous volume or a tmpfs
+  gets a start-up warning (`src/server/storage-check.ts`, from
+  `/proc/self/mountinfo`).
+- **Configuration** (`src/server/config.ts`): flags > `ZIDANE_SERVER_*` env
+  (empty values are unset; the generic `PORT` is never read)
+  > `<data dir>/server.json` > defaults, validated at boot (errors name the
+  flag, variable or file key; unknown file keys and wrongly typed JSON
+  values are errors). Keys: `host` (127.0.0.1), `port` (4280), `tlsCert` /
+  `tlsKey` (relative to the data dir in the file; with `behindProxy` a
+  boot error), `behindProxy`, `drainTimeoutMs` (8000; env
+  `ZIDANE_SERVER_DRAIN_TIMEOUT_MS`), `name`
+  (the `hostName` clients see), `heartbeatMs`, `maxMessageBytes` (32 MiB),
+  `rateLimit` `{ perSecond: 50, burst: 200 }` (env `_RATE_LIMIT` /
+  `_RATE_BURST`; 0 disables), `allowedOrigins` (none), `socket` (default
+  `<data dir>/server.sock`, `off` for none), `workspaceRoots` (default
+  `[<data dir>/workspaces]`; flag `--workspace-root`, repeatable; env
+  `ZIDANE_SERVER_WORKSPACE_ROOTS`, path-delimited, absolute; relative
+  entries in the file resolve against the data dir; missing ones are
+  created at start and handed to the host as `DaemonEnvironment.workspaceRoots`). The data dir is the zidane
+  user dir (sessions, settings, `host-id`, and the server's files);
+  `--data-dir` / `ZIDANE_SERVER_DATA_DIR` set the storage root as
+  `ZIDANE_STORAGE_DIR` does, so `--data-dir /data` keeps everything in
+  `/data/.zidane`.
+- **Exposure**: a non-loopback `host` without TLS is refused at boot
+  unless `behindProxy` (the error lists the three ways out). With
+  `tlsCert` / `tlsKey` the server speaks `wss://`. Behind a proxy, every
+  upgrade must carry `X-Forwarded-Proto` with only `https` entries, from
+  any peer, loopback included (local tools use the unix socket); with
+  `trustedProxies` (IPs / CIDRs, or `private` for every private range:
+  `PRIVATE_NETWORKS`) any other peer is a 403; without them every
+  peer's forwarded headers are believed, and the server warns at start
+  (`startupWarnings`: stderr, and `warnings` on the audit's `server.start`).
+  A 403 carries its reason in `X-Zidane-Refusal` (`origin`,
+  `insecure-transport`, `untrusted-proxy`, `scope`). An upgrade
+  carrying an `Origin` not in `allowedOrigins` is a 403 (browsers send
+  one, CLI clients don't; the default list is empty). These checks
+  (`src/server/security.ts`, `src/server/upgrade-guard.ts`) run before the
+  token. Behind a proxy the client address is the last `X-Forwarded-For`
+  entry (skipping trusted proxies from the right), never the first.
+  `GET` / `HEAD /healthz` (`SERVER_HEALTH_PATH`, the transport's
+  `healthPath` option) is answered before all of these: `200 ok`, `503`
+  while closing, no token, no rate limit, no audit, no host details.
+- **Limits**: a frame over `maxMessageBytes` closes the connection with
+  1009; a reply over it goes out as an `IpcErrorCode.ResponseTooLarge`
+  error and the connection stays (clients page what can be big:
+  `loadAllEvents`, `loadSessionDocument`). Each connection has a token bucket over its incoming messages;
+  past it a request gets JSON-RPC error `IpcErrorCode.RateLimited`
+  (-32012) and the connection lives on (notifications over budget are
+  dropped; a message over 4 KiB is not parsed, its id is read from its
+  head). Upgrades are rate-limited per client address
+  (`upgradeRateLimit`, 429), and open connections capped per token
+  (`maxConnectionsPerToken`) and per client address
+  (`maxConnectionsPerAddress`), 429. A token revoked between its upgrade
+  and the socket opening is closed with 1008.
+- **Audit log** (`src/server/audit.ts`): append-only JSONL, 0600, rotated
+  to `.1` past 5 MB, written asynchronously in order and flushed at
+  shutdown. `<data dir>/server-audit.jsonl`: `connect` (token id and
+  name, remote address, client `appVersion` from its hello), `disconnect`
+  (and why: client close, heartbeat, slow consumer, oversized frame, token
+  revoked, shutdown), `token.create` / `token.revoke` (written by the
+  CLI, and at start for the bootstrap token), `server.start` /
+  `server.stop`.
+  `server-audit.failures.jsonl`: `auth.failure` (address, `missing` |
+  `invalid` | `scope` | `origin` | `insecure-transport` |
+  `untrusted-proxy` | `rate-limited` | `too-many-connections`, the
+  forwarded client behind a proxy), the first per address and minute;
+  the rest as one `auth.failure.summary` (count by reason). Never token
+  material.
+- **Shutdown** (SIGINT / SIGTERM, or `close()`): stop accepting (upgrades
+  get 503, the socket stops listening), close every connection on both
+  front-ends (clients' `onClose` fires), drain the host within
+  `drainTimeoutMs` (8 s by default, under Docker's 10 s stop timeout),
+  exit 0. A second signal at least a second
+  after the first exits at once (one Ctrl-C delivered twice does not).
+
+- **Device tokens** (`src/server/tokens.ts`): `zds_` + 32 random bytes
+  base64url, handed out once by `create(name, scope)`. The store keeps only
+  a SHA-256 (constant-time compare) in `<userDir>/server-tokens.json`, mode
+  0600, written atomically (`writeJsonFileAtomic`): id, name, scope,
+  `createdAt`, `revokedAt`. `lastUsedAt` lives apart in
+  `server-tokens.usage.json` (written at most once a minute per token,
+  merged with what is on disk), so the server never rewrites the token
+  file and can't undo another process's revocation. `list()` never
+  returns hashes; `revoke(idOrName)`; `verify(token)` refuses revoked ones;
+  `adopt(name, token, scope)` stores a value chosen elsewhere (the
+  bootstrap token). Another process writing the file (a CLI) is picked up
+  on the next verify. An unreadable or corrupt file keeps the last good
+  tokens in force (never "no tokens").
+- **Auth on every upgrade**: no token, an unknown or a revoked one is the
+  same plain HTTP 401, before any JSON-RPC (no echo, no telling them apart).
+  `client` tokens open client connections; `machine` tokens open a machine
+  connection ([MACHINES.md](./MACHINES.md)): never a dispatcher peer (no
+  signals), only `ipc.hello`, `$/ping` and `machine.register`, then the
+  host sends it execution requests (`src/ipc/daemon/machine-gateway.ts`).
+  A client calling `machine.*` gets `MachineErrorCode.MethodNotAllowed`. Revoking a token (here, or by another process: the server watches the
+  file and re-reads it every 2 s) drops the connections it opened (close
+  1008); the server tracks connection → token id. Logs name token id and
+  name, never the token. `auth: { disabled: true }` is refused off loopback.
+- **Heartbeat** (both ends, default 20 s, `heartbeatMs`): the server sends
+  WS ping frames, which every WebSocket client answers on its own; the
+  client sends a `$/ping` JSON-RPC request (a browser's WebSocket cannot send
+  ping frames), which every host answers. Two ticks in a row without an
+  answer (a pong, or for the server any message) and the peer is dead: the
+  client aborts (its `onClose` fires, its owner reconnects), the server
+  terminates the connection and removes the peer (presence follows).
+- **Slow consumers** (`src/ipc/transports/send-budget.ts`, the socket's
+  too): a peer with more than 8 MiB (`maxBufferedBytes`) of pushed signals
+  unsent, or one Bun drops a frame for, is terminated; it reconnects and
+  resumes. Reply bytes it asked for don't count toward the bound (a big
+  page followed by a signal is not a slow consumer); the whole buffer has
+  a hard cap of `maxBufferedBytes + 2 × maxMessageBytes`.
+
+## Reconnect and resume
+
+The host numbers session signals (see [Signals](#signals-and-convergence)) and
+keeps the last ones per session (`src/ipc/daemon/signal-log.ts`: 2000
+signals or 4 MiB per session, 32 MiB across sessions, least recently written
+session evicted first; numbering survives eviction). The TUI's session
+controller (`connectHostSession`, `src/tui/runtime/host-session-resume.ts`)
+keeps a resume cursor per activation (session, epoch, last applied number).
+On reattach to the same host process it calls `sessions.resume`, holding the
+session's live signals meanwhile; it applies the replay, then the held ones
+it did not carry: no duplicate, no gap, and `onInitialTranscript` does not
+fire. Another process (`epoch`), a position the log dropped (`gap`), or an
+older host fall back to the full `sessions.loadEvents` reload.
+Transport-agnostic: it runs through the dispatcher on every transport, and
+matters for the network one.
 
 ## Turning it off (containment guarantees)
 
 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.
+- **Default off**: `useDaemon` defaults to `false`; off, no socket, no
+  spawn, no other process: the TUI runs its sessions on a host inside its
+  own process (`startInProcessHost`, see [TUI local mode](#tui-local-mode))
+  and the GUI on its embedded `ChatHost`. Toggling re-activates the open
+  session on the other host; 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 both TUI and GUI regardless of the
+  forces the in-process host 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.
+- **Fail-visible + zero footprint**: in daemon mode a spawn failure, socket
+  problem, or handshake bug leaves the window reconnecting with a visible
+  notice (sends disabled until reattached); turning the setting off or
+  `--no-daemon` runs sessions in-process. 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)
 
@@ -329,6 +598,13 @@ Moving the host out of the window process changes two things users notice:
   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/server-sync.test.ts` (a server's `sync.*`: claim and takeover,
+  each category, window-only keys, overrides and reset, path and size
+  checks, `allowRemoteInstalls`, opted-in keys, audit),
+  `test/chat-sync-engine.test.ts` (the client engine: watchers and the
+  settings stream, offline queue across restarts, import once, takeover,
+  off), `test/tui/app-settings-sync.test.tsx` (the real `<App>` with a
+  saved server, end to end).
 - `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
@@ -359,19 +635,29 @@ store at the next run-end resync; **gap** = known missing cabling.
 | Running work + ctrl+k cancel picker | synced | `work:snapshot` mirror; cancel via `chat.cancelWork` |
 | Context panel (ctrl+?) | synced | `sessions.contextBreakdown` RPC |
 | Artifacts (rail, badges, `#pr` completion) | synced | see [ARTIFACTS.md § IPC](./ARTIFACTS.md#ipc) |
-| History edits (selection modal) | synced | store refresh, `chat.rebuildAgent`, `sessions.touch` |
+| History edits (selection modal), fork, folder attach/detach | synced | host-side (`sessions.deleteTurn` / `editTurnText` / `fork` / `setFolder`); refused mid-run on every surface |
 | History search (transcript + cross-session) | synced + accelerated | `history.searchSession`/`searchAll`, daemon LRU cache |
-| Provider-retry indicator | synced | `stream:retry`; clears on resume / run end |
+| Provider-retry indicator | synced | `stream:retry`; `stream:retry:cleared` when the stream resumes, errors, or the run ends |
 | 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 |
+| MCP connect / failure status | synced | `mcp:status` |
+| Manual compaction (trigger, indicator, "compacted N turns") | synced | `sessions.compact` runs host-side and returns the report; `compacting:*` signals |
+| Repeat-guard notice | synced | host broadcasts and persists the notice row |
+| Safe-mode "allow for this session" rules | synced | host-owned per session; survive agent rebuilds, dropped on delete |
+| Auto-title after the first exchange | synced | generated host-side at run end (`sessions.generateTitle`: the host's providers and credentials, so a server session is titled with the server's); with several TUI windows on one new session each may generate one (last write wins) |
+| `zidane run --context` (non-`process`) | local | forces the in-process host (`ZIDANE_NO_DAEMON=1`), which runs the session on the launch context (`sessions.setLaunchOverrides`) |
+| `zidane run --system` / `--mcp` | synced | `sessions.setLaunchOverrides` on every activation, per window; the latest connected setter's apply |
+| Cwd picked mid-session | synced | `sessions.setLaunchOverrides({ cwd })`: the live agent moves (tools at once, prompt next turn), not persisted |
+| Extension `ctx.appendNote` outside a run | synced | `sessions.appendNote`: host persists and broadcasts the note |
+| Auto-login after adding an MCP server | synced | window arms it; `mcp:auth` starts the login, `mcp:settled` disarms |
+| Window-side extension `ctx.workspace` | synced | daemon session's `workspace` ops over `sessions.workspace*` |
 | 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 |
+| `!` shell mode | synced output | runs in the issuing window's cwd/env (on a remote server: streamed from the session's folder there, `sessions.workspaceExecStream`, esc kills it there; an older server: the buffered `sessions.workspaceExec`); `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 |
@@ -384,36 +670,461 @@ store at the next run-end resync; **gap** = known missing cabling.
 | 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 |
+| Agent-spawning `/` commands | synced | host-side spawn seam; children may pin any credentialed provider's model |
 | 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 |
 
+## TUI local mode
+
+A single-process TUI window (the default) runs its sessions on a host in
+its own process: `startInProcessHost` (`src/ipc/memory.ts`) around the same
+dispatcher a daemon serves, with `createHostEnvironment({ shared })` built
+from the window's setup (its config and state store, its live extension
+registry and agent profiles, its HUD / bus / host-runtime bridges, its Logs
+tab), so nothing is discovered or set up twice. The window reaches it
+through `lazyInProcessTransport` (started by the first connect) with the
+same `connectHostSession` code daemon mode uses, and drains it on quit
+(`closeLocalHost`, bounded). Local semantics are kept: a run lives with its
+window (opening another session mid-run is refused, and leaving a session
+disposes it in the host, background tasks included); per-session artifacts
+go to the window's cache dir. `isMultiProcess()` (another process shares
+the sessions) gates what only exists across processes: presence, the run
+guard and heartbeat, the daemon health dot.
+
+## TUI remote mode
+
+`zidane --host <wss-url> --token-file <path|->` (or `--token <t|->`, or
+`ZIDANE_HOST_URL` / `ZIDANE_HOST_TOKEN`) runs every session of the window on a zidane-server
+through `wsTransport`: a whole-window choice for its lifetime. Which host a
+window uses is one decision, `resolveHostTarget` (`src/tui/host-target.ts`):
+`remote` (a launch's or the environment's remote host), else `daemon`
+(`daemonGate`), else `local`. `isMultiProcess()` is `target !== local`, so
+remote behaves like daemon mode everywhere it is consulted (runs outlive the
+window, switching sessions mid-run is allowed, presence, the run guard, the
+health dot); `useLocalHost` picks the transport from the same target; the
+footer adds `host: <name>` (the server's `hostName` from `ipc.hello`), only
+in remote mode.
+
+- **Opt-in**: the flag (or the variable) is the explicit opt-in, as `zidane
+  attach` is for the daemon. The `remoteHosts` setting
+  (`remoteHostsGate`, default off; Settings → Sessions, "Remote hosts
+  (experimental)", inert under the kill switch) gates the several-hosts
+  window ([TUI.md § Several hosts](./TUI.md#several-hosts-remote-hosts)):
+  it connects only to the servers saved on Settings → Hosts. With several
+  hosts, `isMultiProcess()` and the footer label follow the active
+  session's host once it is not the window's default one
+  (`setActiveHostElsewhereSource` in `src/tui/live-settings.ts`). It stays in the window's `state.json`
+  even while a host owns the settings file (`WINDOW_LOCAL_SETTINGS`). `ZIDANE_NO_REMOTE=1`
+  wins over everything: the CLI refuses `--host` / `ZIDANE_HOST_URL` with a
+  message naming the switch, and `resolveHostTarget` never answers `remote`.
+- **URLs**: `wss://`, or `ws://` to loopback only (a token never crosses
+  the network in the clear). The CLI keeps the URL and token in memory
+  (`runTui({ remoteHost })`) and removes `ZIDANE_HOST_URL` and
+  `ZIDANE_HOST_TOKEN` from its environment so child processes inherit
+  neither (`remoteHostFromCli`). A literal `--token` warns on stderr (ps,
+  shell history).
+- **Connecting** (`connectWsClient`): bounded by `openTimeoutMs` (15 s),
+  abortable through `signal` up to the end of the handshake. A refused
+  upgrade is asked again over plain HTTP for its status: 401 / 403 reject
+  with `HostAuthError` (`token refused`, `forbidden`), with fixed messages:
+  the body is never read (a proxy may echo the token), and a 403's reason
+  comes only from the server's `X-Zidane-Refusal` code (`WS_REFUSAL_REASONS`
+  in `src/ipc/transports/ws-auth.ts`; unknown codes are ignored). That
+  request is `redirect: 'manual'`: a 3xx rejects with `HostRedirectError`
+  and the token never leaves the URL's origin (the TLS diagnosis probe in
+  `src/ipc/hosts/probe.ts` sends no token and follows no redirect either).
+  `expectHostId` (saved hosts: the entry id) closes a connection whose
+  hello names another host and rejects with `HostIdentityError`; the shared
+  connection loop (`src/ipc/hosts/connection-loop.ts`, `saved-hosts.ts`,
+  which checks every connection itself too) reports it as status
+  `identity` and does not retry. Messages name URLs by scheme, host and
+  path (`displayHostUrl`); `parseRemoteHostUrl` refuses userinfo, query
+  strings and fragments.
+- **`zidane attach --host <wss-url> --token-file <path|->`**: the thin client on a
+  server (`runAttach({ host })`); nothing is spawned or drained.
+- **Session data comes from the host**, in every mode
+  (`src/tui/runtime/session-data.ts`): the sessions list and the `#` chat
+  catalog (`sessions.listMeta` / `sessions.getMeta`), resume and activation
+  (`sessions.get`; header refreshes on `sessions:changed` and the model /
+  agent reflectors read `sessions.getHeader`, so opening a session moves
+  its turns once as a document and once as `sessions.loadEvents`, and later
+  header refreshes move none), creation (`sessions.create`, stamped host-side with the
+  cwd, profile, the window's whole model pick and an authoring session's
+  pinned skill), header / model / agent refreshes, titles, export, the
+  details modal, cross-session search, environment actions, artifacts,
+  out-of-band turns (`sessions.appendTurns`: command output, `!` shell,
+  notices), idle todo edits (`todos.set` with `persistIdle`) and renderer
+  state (`sessions.setExtensionState`). Requests ride the window's
+  app-lifetime host client, or a connection of their own while it is down.
+  The window keeps a `SessionSnapshot` of the open session
+  (`src/tui/runtime/session-snapshot.ts`): the host's document wrapped as a
+  `Session` with no store (mutators are memory-only mirrors, `save()`
+  throws), refreshed from the host on activation, history edits and a todos
+  signal for a run it doesn't know.
+- **Older hosts**: a host on this machine (the in-process host, the local
+  daemon) shares the window's store, so when it predates a method (or can't
+  be reached) the window falls back to that store, as before. A remote
+  server has no such fallback: one too old to serve sessions is refused
+  with a message naming it ("runs an older zidane that can't serve this
+  window's sessions").
+- **`!` shell on a server** runs on the server, in the session's folder
+  there, streamed like a local `!` (`sessions.workspaceExecStream`; esc
+  kills the process group on the server; 1 MiB of output, then it is
+  stopped). A server without the method runs it buffered
+  (`sessions.workspaceExec`, 10 min bound; esc stops waiting). On a host on
+  this machine it is the window's local shell, as before. Either way the
+  turns go to the host, in the same format.
+- **Session folders on a server** are inside its workspace roots
+  (`--workspace-root`, default `<data dir>/workspaces`): `sessions.create`
+  without a folder takes the first root, one outside is refused, as is
+  `sessions.setFolder`; a launch-override `cwd` outside them is dropped (a
+  window's own path is on its machine). The chat host enforces this itself
+  (`ChatHostEnvironment.workspaceRoots` → `ChatHost.workspace`,
+  `src/chat/workspace-confinement.ts`) at every entry point taking a
+  folder: session creation (orchestration workers included),
+  `setSessionFolder`, `setLaunchOverrides`, `listCommands` /
+  `completeCommandArgs`, `listEnvironments`, and the workspace file / exec
+  methods; `catalog.*` / `models.list` and `fs.*` use the same instance. A
+  folderless session (the orchestration main) works in the first root. `fs.roots` / `fs.listDirs` browse
+  them. Local hosts are unconfined (`fs.*` rooted at the home; clients may
+  keep their local picker there).
+- **Window-local, by design**: `state.json` (UI settings in local mode, the
+  last provider and session), keybindings, the window's credentials and MCP
+  tokens, `/` built-ins (they act on this window; their transcript turns go
+  to the host), session export files (written on
+  this machine), and in local / daemon mode the cleanup of this machine's
+  artifact blobs on delete. Still on the window's store: the Claude Code
+  import (`Settings → import`), which imports this machine's Claude data
+  into this machine's store, whatever the window's host
+  (`importFromClaudeCode` returns `target: 'this-computer'`; given the
+  window's `activeHost`, a remote one adds `claudeImportHostNote`'s "imported
+  to this computer" note). Against a remote server the imported sessions
+  don't show in its list.
+- **The host's provider keys** are managed over `auth.*`: API keys, and
+  OAuth sign-ins with the browser on this computer and the tokens on the
+  server (`auth.oauth.*`; Settings › Authentication, `o`). MCP servers sign
+  in the same way (MCP servers tab, `o`), and with the server's
+  `remoteInstalls` skills / extensions install (`i`), user-scope ones are
+  removed (ctrl+x) or updated (ctrl+u), MCP servers added (`a`). The
+  window's own credentials stay its own.
+- `test/tui/app-modes.test.tsx` remote mode gives the server its own store
+  and data dir (daemon mode keeps sharing the window's: same machine), so a
+  direct read of the window's store fails its scenarios; "sessions come from
+  the host" opens a session only the host has and checks that one only in
+  the window's store is not listed.
+
+## GUI several hosts
+
+The desktop app's counterpart of [TUI.md § Several hosts](./TUI.md#several-hosts-remote-hosts),
+behind the same gate (`remoteHosts`, Settings › General › Experimental;
+`ZIDANE_NO_REMOTE=1` wins) and the same saved hosts (`hosts.json` + tokens
+in the shared data dir).
+
+- **Off** (default, or the kill switch): the app is the single-host app.
+  `gui/src/main/chat/hosts/gate.ts` never imports `./remote-hosts` (the only
+  module importing `zidane/ipc/remote`), so `hosts.json` is not read, no
+  registry is built, no WebSocket opens; the host directory holds This
+  computer only and every request goes where it went before.
+  `hosts/gate.containment.test.ts` boots `registerChatIpc` with the setting
+  off and a saved server on disk (also with the setting on under the kill
+  switch), and checks the static graph: no main module but
+  `remote-hosts.ts` imports `zidane/ipc/remote`, none imports
+  `remote-hosts` statically, and the `zidane` entries main imports
+  statically don't reach the WebSocket chunk.
+- **Host directory** (`gui/src/main/chat/host-directory.ts`): This computer
+  (the embedded host or the daemon, through `hostRequest`, its in-process
+  fallback kept) plus one `ServerHost` per saved server (the WebSocket
+  client, reconnecting with backoff, its status: `connecting`,
+  `connected`, `reconnecting`, `offline`, `auth-refused`, `identity`: a
+  different server answers at its URL, not retried). A session is a
+  (host, id) pair: two hosts can hold the same id (a server sharing this
+  machine's data dir, a copied store). The app names a session by its
+  `SessionKey` (`gui/src/shared/session-key.ts`): the bare id for This
+  computer's (so local-only state is what it always was), `<hostId>␟<id>`
+  for a server's. Rows, the open chat, selection, the sidebar, persisted
+  view state and every signal main pushes carry keys (main keys a host's
+  signals by the host they came from); every session-scoped channel takes
+  one (branded type: a bare id doesn't type-check), and main routes with
+  `hostFor({ key })` or `hostFor({ hostId })` (list, create, environments,
+  settings, folders). A key of a server never known, or a local key This
+  computer has no session for, throws `UnknownHostIdError`: never a
+  guess. Saving a saved server again (a new token) reconnects it in place,
+  its sessions still routed to it. Removing one (Settings › Hosts, another
+  window, the gate turned off) marks its sessions and request ids removed
+  (`HostRemovedError` from then on), retracts its pending approvals and
+  questions on the renderer and sends `hosts:removed` with their keys
+  (`hosts/server-removal.ts`): a chat open on one of its sessions closes
+  with "<server> was removed", a twin on This computer stays open.
+  `sessionRequest(method, key, params)` / `sessionNotify` are the shorthands every
+  chat channel uses (send, steer, queue, approvals, interactions, todos,
+  context, model picks, history edits, terminals, workspace exec). Ids a
+  server hands out (approvals, questions, terminals) are noted and
+  answered there, and forgotten once settled (answered, withdrawn,
+  closed: `forgetOwner`); a late use of a settled id is refused
+  (`RequestSettledError`), never sent to This computer. A server that is down rejects with `HostOfflineError`:
+  never a fallback to this computer's store.
+- **Signals**: every connected server's signals go through the same
+  `broadcast()` demux (`hosts/server-signals.ts`), minus what is this
+  computer's (its settings, extension bus, the dev browser, the
+  transcript-search mirror, the shared ghost text). Drafts another client
+  of the server types on a session (`draft:changed`, `draft:attachments`)
+  and the session's active skills (`skills:snapshot`) reach the window as
+  the local daemon's do, whether or not the local daemon is connected,
+  and the server's
+  `presence:changed` is merged with every other host's
+  (`presence-merge.ts`: the last snapshot per host, a server's entries
+  dropped when it goes away); `presence:list` asks every connected host.
+  `drafts.*` go to the session's host. `sessions:changed` from any host
+  re-reads every group of the sidebar.
+- **Session data**: a server session's rows, transcript
+  (`sessions.loadEvents` pages of 200 turns, `loadEventsPage`: the last
+  page first, scrolling back passes the page's `cursor` as `before`),
+  footer numbers (`sessions.getHeader` `usage`: `contextTokens` for the
+  context gauge, `costUsd` for the cost pill; only a server too old for
+  `usage` has its document read), a clipped tool result's full text
+  (`sessions.getToolResult`), header, title, archive, turns and export
+  (`loadSessionDocument`: the document a page of turns at a time, written
+  as a copy on this computer) come from the server
+  (`hosts/server-sessions.ts`, `channels/history.ts`). No read asks a
+  current server for a whole session in one reply. Its last good list
+  stays in memory while it is offline (shown read-only, opening says the
+  server is offline). Rows carry `hostId` and a `zidane-env://<key>`
+  workspace root (the key URI-encoded), so the
+  Files / Diffs panels and `@` mentions read the server's folder through
+  `sessions.workspace*`, and `!` runs there, streamed
+  (`sessions.workspaceExecStream`, `server-shell.ts`; `shell:cancel` kills
+  it there; an older server: buffered), like the TUI.
+- **Channels**: `hosts:status` (snapshot, also pushed on `hosts:status`),
+  `hosts:list` (with the registry's dates), `hosts:add` / `hosts:test`
+  (a saved id, or an unsaved URL + token; refusals come back as
+  `{ ok: false, error, message }` with the registry's codes),
+  `hosts:rename`, `hosts:remove`, `hosts:retry`, `hosts:listDirs`
+  (`fs.listDirs`), `hosts:authStatus` / `hosts:authSetApiKey` /
+  `hosts:authRemove` (`auth.*`), `hosts:catalog` (`catalog.*`, `null`
+  from a server too old for them). `sessions:list`, `sessions:create`,
+  `environments:list`, `settings:get` / `settings:set`,
+  `sessions:listModels`, `commands:list` / `commands:completeArgs`,
+  `extensions:completionProviders` / `extensions:completionSubmit` take
+  an optional host id.
+- **Renderer**: Settings › Hosts (This computer + servers, status, server
+  name and version; add with the token masked, test before saving, a
+  message per refusal code; test, rename, remove with a confirm); the
+  sidebar grouped by host (no headers with This computer alone); a new
+  chat picks its host first, then that host's environments, then for a
+  server a folder on it; the chat header shows `on <server>` with its
+  status dot. On a server session, actions that need this machine's files
+  are not offered (reveal in Finder, open in editor, the local folder
+  picker, the dev browser tab, extension panels); there is no "download a
+  copy" of a single file yet, the session export writes a copy here. A
+  server terminal's loopback links (`localhost:5173`) are the server's:
+  they are not opened here, a tooltip says why (`serverOnlyLink`,
+  `terminal/links.ts`). A new chat that can't be created (its server went
+  offline) puts the typed prompt back with the reason above it
+  (`unsentDraft`, `ComposerNotice`).
+- **Settings sync** ([SERVER.md § Settings sync](./SERVER.md#settings-sync)):
+  a server card's *Sync* (`ServerSync.tsx`): mode (Off · Import once ·
+  Keep in sync), the categories, each API key opted in after a
+  confirmation, *Take over* when another device syncs there (confirmed),
+  the server's overrides with *Sync again*, the connection / last push /
+  what waits / errors and what can't sync. Main: `hosts:syncState`,
+  `hosts:syncConfigure` (modes, categories and provider names checked),
+  `hosts:syncPush`, `hosts:syncTakeOver`, `hosts:syncReset`, and the
+  `hosts:syncChanged` push (the engine changed, or a server's
+  `sync:changed`). A server's Settings show `synced from <device>` under a
+  synced setting, or `edited here, not synced from <device>` with *Sync
+  again* (`SyncMarker.tsx`, `hosts:syncStatus`, any window). A local
+  `settings:set` tells the engine; its watchers cover the TUI's and other
+  windows' writes. Off with remote hosts: `hosts:syncState` answers
+  `enabled: false` and nothing loads (`gate.containment.test.ts`).
+- **Settings on a server session**: `HostSettingsProvider` (renderer)
+  reads `settings:get(hostId)` (this window's settings overlaid with the
+  server's, `overlayHostSettings`) and writes `settings:set(patch,
+  hostId)` (main splits it with `splitHostSettingsPatch`: window-only keys
+  to this computer, the rest to the server, the server's part first: a
+  refused write applies nothing here and rejects with the server's error);
+  title `Settings · <server>`.
+  Authentication lists the server's providers: an API key is stored there,
+  an OAuth provider signs in (`hosts:oauth`, `ServerOAuthSignIn`: the
+  browser opens here through a loopback in the main process, a code can be
+  pasted, `hosts:oauthPaste` / `hosts:oauthCancel`, `hosts:oauthStart`
+  pushes the URL / device code), a stored credential is removed. Skills / MCPs / Extensions /
+  Plugins show the server's catalog for the session's folder there
+  (`HostCatalogPanel`, `hosts:catalog`): each entry with the server's
+  enabled state, a toggle writing the server's enabled list (the first
+  one seeds it from what the list governs; a plugin's or extension's
+  contribution or a broken entry shows its state and can't be toggled);
+  an HTTP MCP server signs in from here (`hosts:oauth`). When the server
+  takes installs (`hosts:installsAllowed`, its hello's `remoteInstalls`):
+  skills / extensions install from a spec (`hosts:install`), user-scope
+  entries are removed (two presses, `hosts:uninstall`), extensions updated
+  (`hosts:update`), MCP servers added / removed (`hosts:mcpUpsert` /
+  `hosts:mcpRemove`; an Authorization header stays on the server); a
+  `catalog:changed` from the server (`hosts:catalogChanged`) re-reads the
+  open tab. A server too old for `catalog.*` gets its enabled list. The summarizer picker
+  lists the server's models. Environments and Instructions are hidden.
+  The Claude Code import still targets this computer and says so when the
+  active chat is on a server.
+- **Models, commands, search on a server session**: the model pickers
+  list the server's credentialed providers and models (`models.list`;
+  an older server: this computer's, as before). A pick there becomes this
+  window's remembered default (`lastProvider`, `lastModelChain`) only when
+  this computer can run its provider, without the fallbacks it can't
+  (`rememberableChain` in `zidane/chat/pure`, the TUI applies the same one); a server draft that picks a
+  provider only the server has launches under it without remembering it.
+  `/` completion, the palette's commands and the submit path's command
+  check use the server's `commands.list` / `commands.completeArgs` for the
+  session's folder there. Ghost text is the server's (`suggest.resolve`:
+  its path provider over its files, its extensions' providers). This
+  window's extension popup providers (`extensions:completionProviders`)
+  are not offered on a server session: they are this window's extensions,
+  run against this computer's files, and no RPC runs a server's. `@`
+  mentions list the server's files (`sessions.workspaceListFiles`). The
+  sidebar's content search also searches each connected server's group
+  there (`history.searchAll` over that group's rows), the hits merged with
+  this computer's. The `/` popover's skills are the ones the server
+  enables (`hosts:catalog` skills for the folder there).
+- Tests: `host-directory.test.ts` (routing by key, twins),
+  `hosts/remote-hosts.server.test.ts` (the channels against a real
+  zidane-server spawned with Bun: per-code refusals, add, folders,
+  environments, create in a server folder, rename, `!` on the server,
+  transcript pages and scroll-back, the same id on this computer and the
+  server (both listed, each opened and edited on its host), a tool
+  result's text and an export without the whole document in one reply,
+  skills signals without the local daemon,
+  footer numbers from the header, the server's models, `/` commands,
+  ghost text and files, content search, drafts and presence from another
+  client, catalogs and a toggle, per-host settings and provider keys,
+  offline rows, remove; the server runs with its own HOME and no provider
+  keys of the developer's), `hosts/gate.containment.test.ts`, renderer
+  `HostsPanel.test.tsx`, `HostCatalogPanel.test.tsx`,
+  `remember-model-pick.test.ts`, `sidebar-host-rows.test.ts`,
+  `sidebar/hosts-sidebar.test.tsx`, `SessionsContext.twins.test.tsx` (two
+  rows with one id, each opened and acted on with its key).
+
+### Machines in the desktop app
+
+Behind the same gate (`docs/MACHINES.md` § Client UI). Main
+(`gui/src/main/chat/channels/machines.ts`) answers `machines:links`,
+`machines:shareStart` (minting the machine token on the server when This
+computer's host has none; `needsToken` asks the renderer for a pasted
+one, never echoed back in an error), `machines:shareStop`,
+`machines:useServer`, `machines:list`, `machines:forget`,
+`machines:listDirs`, all through This computer's host (`hostRequest`:
+the daemon, or the embedded host through the dispatcher's own handlers,
+`gui/src/main/chat/machine-links.ts`) or a saved server. It relays
+`machine:status` (any host, with its `hostId`) as `machines:status` and
+This computer's `machine:links` as `machines:links`; a server's
+`machine:notification` never reaches a window. `HostSummary.machineServe`
+says a server lends itself. Remote hosts coming on resume the embedded
+host's saved links. The renderer: Settings › Hosts › a server's
+*Machines* (`ServerMachines.tsx`), machine kinds grouped in the
+environment picker with a machine folder picker in the composer, and
+`MachineWaitingBanner` over the composer.
+
+## Several hosts: what the TUI and the GUI share
+
+One implementation of the client side, each app keeping only its glue:
+
+- `src/chat/hosts` (pure parts re-exported from `zidane/chat/pure`):
+  `LOCAL_HOST_KEY` / `LOCAL_HOST_NAME`, `HostConnectionStatus`,
+  `isMethodNotFound` (JSON-RPC -32601), the presence merge
+  (`createPresenceMerge`, `mergePresenceMaps`), the id → host index
+  (`createHostIndex`: unknown ids refused, a removed host's ids remembered
+  as removed), and the registry with `checkHostInput` /
+  `probeUnsavedHost` (the add form's unsaved test runs `add`'s checks).
+- `src/ipc/hosts` (exported from `zidane/ipc/remote`): `keepHostConnected`
+  (the transport-agnostic connection loop: backoff, statuses, auth refusal
+  not retried), `startSavedHosts` (registry ↔ directory sync through a
+  `SavedHostsDirectory` the app supplies; a re-add reconfigures the entry
+  in place), and `startWsSavedHosts` (the WebSocket registry, dial, unsaved
+  probe and refusal classification). `connection-loop.ts` imports no
+  WebSocket code, so the TUI loads it statically for This computer; the
+  rest stays behind each app's gate.
+- TUI glue: `src/tui/host/host-directory.ts` (entries with transports,
+  default/active pointers, session routing, `onRemoved`),
+  `remote-hosts.ts`, `host-signals.ts`, `use-host-removal.ts`,
+  `runtime/routed-session-data.ts`. GUI glue:
+  `gui/src/main/chat/host-directory.ts`, `hosts/remote-hosts.ts`,
+  `hosts/server-removal.ts`, `hosts/server-signals.ts`,
+  `hosts/server-sessions.ts`, `presence-merge.ts`, and the renderer's
+  `gui/src/shared/session-key.ts`.
+- Paged reads (`zidane/ipc`): `loadAllEvents` / `loadEventsPage` (the
+  transcript, both apps) and `loadSessionDocument` (the whole document a
+  page of turns at a time: the GUI's export of a server session; the TUI's
+  own reads of a document still use `sessions.get`).
+- Settings sync to a server (`src/chat/sync`, loaded with the saved
+  servers, behind the same gate): `types.ts` (pure: categories, modes,
+  field names, `syncMarkerOf`; re-exported from `zidane/chat/pure`),
+  `local.ts` (the device id in `device.json`, the per-server config and
+  offline queue in `hosts-sync.json`, both 0600), `collect.ts` (each
+  category's snapshot from this computer's files), `watchers.ts`,
+  `pusher.ts` and `engine.ts` (`createSyncEngine`, exported from
+  `zidane/ipc/remote`). Each app hands it its servers' connections and
+  `sync:changed` signals: the TUI in `src/tui/host/remote-hosts.ts`, the
+  GUI in `gui/src/main/chat/hosts/remote-hosts.ts`. UIs: the TUI's
+  `src/tui/settings/server-sync-page.tsx` (Hosts → `ctrl+s`) and markers
+  in `host-settings-scope.tsx`; the GUI's `ServerSync.tsx` (a server card's
+  Sync) and `SyncMarker.tsx` (its Settings), over the `hosts:sync*`
+  channels.
+- Settings on a server, both apps: the split is keyed on "the host is a
+  server, not This computer" (`isWindowOnlySetting`). Window-only keys
+  never go to a server and a server's never come in; the GUI's main splits
+  `settings:set` and drops a server's `settings:changed`, the TUI applies a
+  server's host-scoped keys only and persists only window-only ones while
+  on a server (`--host` included).
+
 ## 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 (`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.
+from `src/ipc`. The TUI's local mode runs on `src/ipc`'s dispatcher, host
+environment and in-process transport, so those stay. Deleting the socket
+side — the daemon server and socket client, `src/daemon-cli.ts`, the
+socket transport, and the GUI's daemon glue (`daemon-client.ts`,
+`daemonHostClient` in `host-client.ts`, and the few remaining daemon
+branches in `ipc.ts`: the `!` guard, inline autocomplete, the settings
+write) — 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 client. Migrating the full OpenTUI
-  front-end onto `connectIpcClient` is the tracked follow-up.
+- Every TUI mode is host-backed ([TUI local mode](#tui-local-mode)).
+  `test/tui/app-modes.test.tsx` drives the real `<App>` through every
+  scenario on the in-process host and against a daemon built with the
+  production environment around the window's setup, and pins the intended
+  difference (local refuses to open another session mid-run; the daemon
+  lets the run continue). `test/tui-runtime-parity.test.ts` runs every
+  runtime scenario over the in-process and socket transports, which must
+  match.
+- The daemon keeps per-session artifacts under the config dir
+  (`paths.userDir`), the in-process host under the cache dir
+  (`paths.cacheDir`, where the TUI always kept them). They coincide in the
+  default layout and differ under an XDG layout.
+- `state.json` across processes: the daemon and a local-mode window on the
+  same file both read-modify-write it without a lock (in daemon mode the
+  window leaves settings to the daemon). A host in the window's process
+  shares the window's state store, so that pair is one writer. Field-scoped
+  merges or a lock would close the cross-process case.
 - 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.
+  guest (`drainOnMismatch: false`). Every host operation goes through one
+  `HostClient` (`gui/src/main/chat/host-client.ts`), named and typed by
+  `IpcMethods`: `daemonHostClient` forwards to the socket,
+  `embeddedHostClient` is a typed table of the in-process behavior
+  (including where it differs: inert drafts / presence / search, artifacts
+  in the local store). `hostRequest(method, params, { fallback })` picks
+  the live one; with `fallback`, a dead socket (never a daemon answer)
+  retries on the in-process host. A remote host would be a third
+  implementation.
 - `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`, guarded by a `chat.isRunning` refusal on history
-  edits. Remaining optional wire additions: paginated `sessions.loadEvents`
-  and a SQL-narrowed cross-session search fast path (perf only).
+- Session edits (fork / deleteTurn / editTurnText / attach and detach a
+  folder / `!` output) run in the host on every surface: the GUI calls
+  the daemon's RPC or its in-process host, the TUI calls the RPC on its
+  host (daemon or in-process), and no client writes the store for them. History and folder edits
+  are refused while the session runs; the GUI greys the actions out, the
+  TUI explains. Remaining optional wire addition: a SQL-narrowed
+  cross-session search fast path (perf only). `sessions.loadEvents` pages
+  from the host's loaded document (the store has no turn-range read), so
+  paging saves the wire, not the host's disk read.