zidane 7.2.4 → 8.0.4

package/docs/MACHINES.md

@@ -0,0 +1,456 @@
+# Machines
+
+A **machine** lends execution (files, shell, background tasks, terminals,
+live processes) to a **host** over a WebSocket it opens itself, or, for a
+local host that can't be dialed, over the host's own client connection
+(the reverse direction). As built: the protocol, the host registry, the
+remote execution context, the machine agent and the offline semantics
+(slice 4A), then the reverse direction, `execStream`, project files read
+on the machine, the machine's own sandbox, and the TUI / desktop app
+surfaces (slice 4B). Everything here is part of remote hosts: off, nothing
+of it loads.
+
+Contents: [Roles](#roles) · [Connection](#connection) · [Protocol](#protocol) · [Reverse direction](#reverse-direction) · [Host side](#host-side) · [Folders](#folders) · [Project files](#project-files) · [Machine side](#machine-side) · [Sandbox](#sandbox) · [Offline](#offline) · [Client UI](#client-ui) · [Security model](#security-model) · [Limits](#limits) · [Not in v1](#not-in-v1)
+
+## Roles
+
+| Role | Owns | Runs |
+|---|---|---|
+| **Host** | sessions, settings, credentials, approvals, the transcript | the agent loop, the model calls, every tool's logic |
+| **Machine** | its own declared folders (*roots*) and its data dir | the tools' I/O only: `exec`, file reads/writes/listings, background tasks, PTYs |
+
+Any zidane process can play either role for another. A session whose
+environment is `local@laptop` or `worktree@laptop` runs on the host, and every
+`ExecutionContext` call its tools make goes to the machine named `laptop`.
+No credential crosses to a machine: it sees commands, paths and file contents,
+never a provider key, a token or the transcript.
+
+## Connection
+
+- **The machine dials the host** (`wss://host/…`), with a token of scope
+  `machine` created on the host (`zidane server token create --name laptop --scope machine`).
+  A laptop needs no inbound port; NAT and firewalls are irrelevant.
+- Same WebSocket transport, same JSON-RPC framing, heartbeat (`$/ping`, WS
+  pings) and `ipc.hello` handshake as a client (the machine pins the host id
+  after its first hello, like a saved host). Then the direction of the
+  execution calls is reversed: the **host sends requests to the machine** over
+  the machine's connection (`createJsonRpcEndpoint` is bidirectional).
+- A machine connection is **not a client**: it is never added to the host's
+  peer set (it receives no signal, no session data) and may call only
+  `ipc.hello`, `$/ping` and `machine.*`. Anything else is refused with
+  `MethodNotAllowed`. A client connection calling `machine.*` gets the same.
+- Reconnect: the machine agent reuses the hosts' connection loop
+  (`keepHostConnected`: backoff 1 s → 30 s; a refused token or another host
+  answering is "for good" until restarted).
+
+A zidane-server can be a machine of another zidane-server with the same
+agent (it dials). A **local** host (daemon, in-process) has no listener, so
+for `local@<server>` the roles are kept and the dialing is turned around:
+see [Reverse direction](#reverse-direction).
+
+## Protocol
+
+Wire types: `src/chat/machine-protocol.ts`, re-exported by `src/ipc/protocol.ts`.
+Versioned on its own: `MACHINE_PROTOCOL_VERSION` (currently `1`). The host
+refuses a `machine.register` with another major version
+(`MachineErrorCode.VersionSkew`), naming both versions.
+
+**Machine → host** (requests on the machine's connection):
+
+| Method | Params → result |
+|---|---|
+| `ipc.hello`, `$/ping` | as for clients |
+| `machine.register` | `{ machineId, name, roots: [{ path, label? }], capabilities, version, protocolVersion }` → `{ machineId, hostId? }` |
+
+`machineId` is stable, generated once and kept in `<dataDir>/machine-id`.
+`name` is the display name and the suffix of its environment kinds; one name
+belongs to one machine id per host (a second machine claiming it is refused).
+
+`capabilities`: `shell`, `terminals`, `background`, `worktrees`, `stream`
+(`exec.stream*`; absent on an older machine, whose context then has no
+`execStream`) and `sandboxed` (it runs every command under its own OS
+sandbox: the context reports `isolated`).
+
+**Machine → host** (notifications): `terminal.data { terminalId, data (base64) }`, `terminal.exit { terminalId, code }`, `task.exit { taskId, exit: TaskExitInfo }`, `exec.stream.data { callId, stream: 'stdout' | 'stderr', data (base64) }`, `exec.stream.exit { callId, code }`.
+
+**Host → machine** notifications: `exec.cancel { callId }` (the abort of a sent `exec.run`, or the kill of a live `exec.stream`).
+
+**Host → machine** (requests), one per `ExecutionContext` method; every call
+names its handle as `{ id, cwd }` so a machine that restarted rebuilds it:
+
+| Method | Mirrors |
+|---|---|
+| `machine.ping` | liveness |
+| `exec.spawn { handle }` | `spawn` (checks `cwd` against the roots) |
+| `exec.run { handle, callId, command, cwd?, env?, timeout? }` | `exec` (timeout in seconds, like the interface) |
+| `exec.cancel { callId }` | the `signal` of `exec`; kills an `exec.stream` |
+| `exec.stream { handle, callId, command, cwd?, env? }` → `{ pid }` | `execStream`: output as `exec.stream.data`, then one `exec.stream.exit` once stdout and stderr are drained |
+| `exec.stream.write { callId, data (base64) }` | the stream's stdin |
+| `exec.destroy { handle }` | `destroy` |
+| `fs.read { handle, path, binary? }` | `readFile` / `readFileBinary` (binary as base64) |
+| `fs.write { handle, path, content (base64) }` | `writeFile` |
+| `fs.list { handle, path, options? }` | `listFiles` |
+| `fs.size { handle, path }` | `fileSize` |
+| `bg.start { handle, command, cwd?, env?, maxOutputBytes? }` | `execBackground` (output under the machine's data dir) |
+| `bg.list` / `bg.kill { taskId }` / `bg.wait { taskId, timeoutMs? }` | `listBackground` / `killBackground` / `waitBackground` |
+| `terminal.open { handle, cols, rows, cwd? }` | `openTerminal` |
+| `terminal.attach { terminalId }` | `reconnectTerminal` (returns the buffered output and the byte total, so an automatic reattach after a reconnect replays only what the host missed) |
+| `terminal.write` / `terminal.resize` / `terminal.kill` / `terminal.detach` | `TerminalProcess` |
+| `env.checkFolder { cwd }` | the machine's verdict on a session folder |
+| `env.prepareWorktree { cwd, branch, base?, config }` / `env.teardownWorktree { ref, config }` | the worktree provider's `prepare` / `teardown`, run machine-side |
+
+`execStream` is what context-scoped MCP servers (`scope: 'context'`) run
+on: a machine session's stdio servers run on the machine. The host side
+registers a stream's queues before the call, so no early byte is lost; a
+stream whose link drops ends with exit `-1` (the machine kills it: a live
+protocol can't survive lost output). Not mirrored: `getMappedPort`;
+`reassignBackgroundTasks` is done host-side (same-handle rebinding).
+
+## Reverse direction
+
+`local@<server>` on a local host (the laptop is the host, a saved
+zidane-server the machine). The local host already has what a window has
+for that server (its saved entry in `hosts.json`, its client token under
+`hosts:<id>`), so it dials it as a client and asks it to lend itself:
+
+1. `machine.attach { hostId }` (a client method): the server answers with
+   the registration a machine would send (`MachineRegisterParams`: its id,
+   its name made machine-safe, its workspace roots as roots, its
+   capabilities). `hostId` names the asking host process, so a reconnect
+   finds its tasks and terminals again (each local host process uses its
+   own instance id: two windows' in-process hosts never take over each
+   other's executor). The server keys an executor by the client's token
+   AND that id: the id is the client's word, so another token naming it
+   gets an executor of its own, never the first one's tasks, terminals or
+   exits. A token holds at most 4 executors there and only ever evicts its
+   own idle ones.
+2. The local host registers that in its own machine registry, with a
+   connection that sends every host→machine request as
+   `machine.call { method, params }` (no client deadline: a call lasts as
+   long as its command; a dead server is the heartbeat's to catch) and
+   every notification as a `machine.call` notification.
+3. The server serves them with the same confined executor a shared
+   machine runs (`createMachineExecutor`, loaded on the first attach),
+   inside its workspace roots, its data dir at `<data dir>/machine-self`.
+   Its notifications go back to that connection only, as
+   `machine:notification` signals (sent before the attach reply too: the
+   local host buffers them until it has registered).
+4. A dropped connection is the machine going offline (same semantics as
+   below); the loop reconnects (backoff), a refused token, another server
+   at the URL, or a refused attach (`allowAsMachine` off, a name taken
+   here) stop it until the user acts. A busy server (no room for this
+   token's executor now: `MachineErrorCode.Busy`) or a dropped link is
+   retried with the backoff.
+
+The server must allow it: `allowAsMachine` (`--allow-as-machine`,
+`ZIDANE_SERVER_ALLOW_AS_MACHINE=1`, `server.json`), off by default.
+`ipc.hello` says so (`machineServe: true`) and the windows offer "use as a
+machine" only then. Security: [SERVER.md § Security model](./SERVER.md#security-model).
+
+## Host side
+
+- `src/chat/host/machines/` (engine feature, `host.machines`): the registry of
+  known machines (persisted in `<dataDir>/machines.json`: id, name, roots,
+  token id, last seen) and their live links. Made only where machines
+  exist: always on a zidane-server (remote by nature), on a local host only
+  while remote hosts are on (off: `machines.json` is never read and no
+  machine kind is registered; turned off later, the known machines read
+  as absent) (`online` / `offline`), the remote
+  context (`createMachineContext`), the offline wait, and one
+  `local@<name>` + `worktree@<name>` environment provider per known machine,
+  registered on the host's environment registry when the machine is first
+  known. A forgotten machine's providers report unavailable and refuse to run.
+- Transport-free: the engine sees a `MachineLink` (`request`, `notify`,
+  `close`, `onNotification`); `src/ipc/daemon/machine-gateway.ts` builds it
+  over the WS connection and enforces the method allowlist.
+- `environments.list` lists the machine kinds with `machine: { id, name, status }`
+  (a forgotten machine's kinds are not listed); `machines.list` /
+  `machines.forget` are client methods; `machine:status { machineId, name, status }`
+  is broadcast to clients.
+- Execution: a machine context is `sandbox`-typed (its filesystem is not the
+  host's), so the host's own workspace checks on `sessions.workspace*` leave
+  paths to the machine, and the session's cwd is not "movable" like a local one.
+- Session metadata: the environment's `ref` holds `{ machineId }` (and the
+  worktree's `path` / `repoRoot` on the machine).
+- `sessions.create` with a machine kind: the host's own workspace confinement
+  does not apply (the folder is on the machine); instead the folder must be
+  absolute and lexically inside a declared root (pre-check), then the machine
+  re-checks it on its filesystem (`env.checkFolder`, real paths) during
+  provisioning.
+
+## Folders
+
+A machine kind's folders are the machine's: every entry point taking a
+folder checks one against that machine's roots (lexically here, then on
+the machine with real paths where it touches it), never against this
+host's own workspace confinement (a confined server would refuse every
+machine path; an unconfined local host would read its own filesystem at a
+path that only means something on the machine). `ChatHost.resolveFolder`
+decides: a machine kind given (`kind` on `environments.list`,
+`commands.list` / `commands.completeArgs`, `catalog.*`, `models.list`),
+else this host's confinement, else (an older client naming no kind) the
+one known machine whose roots hold it.
+
+- `environments.list` for a machine's folder: its machine's kinds as
+  usual, this host's own kinds unavailable ("The folder is on laptop."). A
+  machine kind's availability does not depend on the folder (pickers ask
+  the kind first, then a folder there, `machines.listDirs`).
+- `commands.list`, `catalog.*`, `models.list`: this host's user scope,
+  read from a folder of its own (below), plus for skills and MCP servers
+  the project scope read on the machine.
+- `sessions.setFolder` on a machine session: checked by its machine
+  (`env.checkFolder`, never waits for an offline one); launch overrides'
+  `cwd` likewise.
+
+## Project files
+
+A machine session's folder is on the machine, so is its project. The host
+reads its **user scope** (`~/.agents`, `~/.zidane`, user extensions and
+plugins, user skills and MCP servers, `~/.zidane/SYSTEM.md`) as for any
+session, but from a folder of its own with no project
+(`<data dir>/machine-sessions`, `ActiveRun.discoveryCwd`), never the
+machine's path on this filesystem. The **project scope** is read on the
+machine, through the session's own execution (`readMachineProject`:
+`fs.size` / `fs.read` / `fs.list`, so the machine's roots and data-dir
+rules apply), at agent build:
+
+| What | Where on the machine |
+|---|---|
+| project root | `git rev-parse --show-toplevel` when inside the roots, else the session folder |
+| instructions | `AGENTS.md`, `.agents/AGENTS.md`, `.<prefix>/AGENTS.md`, `CLAUDE.md` (64 KiB each), after the user's, under `userInstructionsScope` |
+| `SYSTEM.md` | `<root>/SYSTEM.md`, beating the user's |
+| skills | `.agents/skills/*/SKILL.md`, `.<prefix>/skills/*/SKILL.md` (64 at most, 256 KiB each), ahead of the user's on a name |
+| MCP servers | `.agents/mcp(s).json`, `.<prefix>/mcp(s).json` (256 KiB each) |
+
+- **No code from a machine.** Project extensions and Agent Plugins are
+  never loaded for a machine's folder (they are code; the host never runs
+  what a machine provides), so project `/` commands, which extensions
+  contribute, are not either: a machine session has the host's built-in
+  and user-extension commands.
+- **MCP servers run on the machine.** A project stdio server is kept with
+  `scope: 'context'` (it runs over `execStream`, on the machine); every
+  `${VAR}` placeholder in it is resolved first to its `:-default` or to
+  nothing, so this host's environment (provider keys) is never expanded
+  into anything a machine named. A URL server is dropped with a notice
+  (connecting would happen from the host).
+- **Offline at build**: the run is not held. The session gets
+  "laptop is offline: its project instructions, skills and MCP servers
+  load when it is back.", the agent is built with the user scope, and is
+  rebuilt (at run end when busy) once the machine is back.
+- Not read on a machine: Ruler and foreign agents' configs (`.ruler/`,
+  `.claude/…`), skill resources besides `SKILL.md` (their paths are the
+  machine's; `skills_read` of one is not proxied).
+
+## Machine side
+
+`startMachineAgent({ hostUrl, token, name, roots, dataDir })` (`src/ipc/machine/`),
+CLI `zidane machine share --host wss://… --token-file … --name laptop --root ~/code [--root …]`.
+
+- Serves execution from one `process` context per handle, through a guard
+  (`createMachineExecutor`) that never trusts the host: every path and `cwd` is
+  resolved against the handle's cwd, then **real-path contained** in a root
+  (`createWorkspaceConfinement`, the same rule as a zidane-server's workspace
+  roots): `..`, absolute escapes and symlinks pointing out are refused; the
+  machine's data dir (its `machine-id`, token file, task logs) is unreachable
+  by file ops even when a root contains it. Exception: `<dataDir>/worktrees/`
+  (an implicit root: `worktree@<machine>` makes its worktrees there).
+- **Private folders**, unreachable by file ops whatever the roots (sharing
+  `--root ~` included; `machinePrivateDirs`): zidane's own folders as the
+  machine's process resolves them (data, config, state and cache dirs, and
+  `~/.zidane`: credentials, tokens, extensions, plugins, skills, `mcps.json`,
+  the user-scope `SYSTEM.md`, the machine's data, sync files), the zidane
+  data dir it was given (a server's `--data-dir`), and the credential
+  folders the sandbox hides (`~/.ssh`, `~/.aws`, `~/.gnupg`, …). A root
+  that is, or is inside, one of them is refused when sharing (`zidane
+  machine share`, a share link); a server's own default root
+  (`<data dir>/workspaces`) stays usable when it lends itself. A listing
+  (`fs.list`, globs) only returns entries whose real path is reachable, and
+  a pattern can't climb with `..`.
+- **Task logs** (`<dataDir>/tasks/`, owner-only): a log of a background task
+  this machine started is readable by its path, opened without following a
+  symlink, and only when it is still that regular file inside the tasks
+  folder (`./task-logs.ts`); logs are created exclusively, never through a
+  link planted at their path. A command run for the host can't make the
+  machine process read anything else through "its log".
+- A handle id named again with another folder destroys the old handle (its
+  background tasks stop); a second call under a `callId` still running is
+  refused.
+- Bounded: `exec` output by the process context's own cap, background
+  output capped per task (8 MiB), at most 64 running tasks and 16
+  terminals, terminal backlogs 256 KiB, at most 256 queued task exits.
+- Path checks and use are not atomic (a shell command racing a symlink in
+  between could redirect one file op); the shell can reach as much anyway.
+- Live processes (`exec.stream`): at most 16, output sent in chunks of at
+  most 256 KiB, stdin written 256 KiB at a time; all killed when the host
+  link drops. A kill sends TERM to the process group, and KILL after the
+  grace if its pipes are still open (a TERM landing while the shell
+  forks a child would otherwise leave that child, and the stream, alive).
+- Background tasks keep running across a disconnect (they're the machine's
+  children); their exits are queued and re-sent on reconnect, and `bg.list`
+  answers by id after a reconnect. Terminals keep running for a grace period
+  (default 5 min) after their host link drops, buffering output; `terminal.attach`
+  reattaches with the backlog; past the grace they are killed.
+
+## Sandbox
+
+The machine owner decides: a machine runs every command it is sent
+(`exec`, background tasks, streams, terminals) under **its own user's**
+`sandbox*` settings (`sandbox`, `sandboxNetwork`, `sandboxAllowWrite`:
+the same OS sandbox as local sessions, macOS Seatbelt / Linux bwrap,
+failing closed when unavailable), over every root it shares (not its task
+logs: the machine process writes them), with its user's zidane credential
+files hidden. A host can't turn
+it off, and its own `sandbox*` settings don't apply to a machine session
+(they describe the host's computer). `zidane machine share` reads its
+user's `state.json`; a share run from a local host uses that host's
+settings; a server lending itself uses its own. The register says
+`sandboxed`, the host's context reports `isolated`.
+
+## Offline
+
+A machine is `offline` from the moment its connection drops (close, or two
+missed heartbeats) until it registers again. Every host→machine call goes
+through `MachineLink.call`:
+
+| When | What happens |
+|---|---|
+| Offline before the call is sent | The call **waits** for the machine (not sent, so safe to send later). The session gets a notice "waiting for laptop…" once, and `machine:status` is broadcast. On reconnect the call is sent; notice "laptop is back". |
+| Sent, then the connection drops before the reply | **Not re-sent** (it may have run). The tool fails with `result lost: laptop disconnected during the call` and the model decides. Idempotent calls (`MACHINE_IDEMPOTENT_METHODS`: reads `fs.read` / `fs.list` / `fs.size` / `bg.list` / `bg.wait` / `env.checkFolder` / `terminal.attach` / `machine.ping`, and the handle calls `exec.spawn` / `exec.destroy` / `exec.cancel`, keyed by the host's handle id) are the exception: they are re-sent after the reconnect like an unsent call. |
+| Still offline after `machineWaitMinutes` (setting, default 15) | The waiting calls fail with `laptop is unavailable`, the session's run is interrupted and ends with the notice "laptop stayed offline for 15 min: run stopped". |
+| Aborted while waiting (user interrupt) | The call is dropped, nothing is sent. |
+| The host drains (shutdown) | Waiting calls fail at once (`MachineRegistry.close`), so a run or a provisioning waiting on an offline machine never holds the drain. |
+
+The wait is the run pausing: the tool call is simply still in flight, so the
+model never sees a broken tool. Timers are injectable (`MachineRegistryOptions.timers`) for tests.
+
+## Client UI
+
+Behind remote hosts (Settings → Remote hosts, `ZIDANE_NO_REMOTE` beats
+it): off, no surface, and This computer's host loads no machine code,
+reads no `machine-links.json`, no `machine:` token, dials nothing
+(`test/tui/app-remote-containment.test.tsx`, `test/tui/remote-lazy-graph.test.ts`,
+`gui/src/main/chat/hosts/gate.containment.test.ts`). `zidane machine share`
+refuses under `ZIDANE_NO_REMOTE=1` / `--no-remote` too.
+
+**This computer's host** (in-process or the daemon; the dispatcher's
+handlers, which the desktop app's embedded host calls directly) offers:
+
+| Method | What |
+|---|---|
+| `machines.share.start { hostId, name, roots, token? }` | share this computer with a saved server (`token`: a machine token to keep, as `machine:<hostId>` in its credentials; else the one kept) |
+| `machines.share.stop { hostId }` / `machines.useServer { hostId, enabled }` | stop sharing / use a saved server as a machine ([Reverse direction](#reverse-direction)) |
+| `machines.links.status` | both, with their state (`connecting`, `connected`, `reconnecting`, `offline`, `auth-refused`, `identity`, `refused`) and why; `machine:links` signals each change |
+| `machines.list` / `machines.forget` / `machines.listDirs { machineId, path? }` | the machines it knows, forget one, a machine's folders (absent `path`: its first root) through it |
+
+and a server `tokens.createMachineToken { name }` ([SERVER.md § Tokens](./SERVER.md#tokens)), so sharing is one step: the window
+asks the local host, which has no token for that server, so the window
+mints one there and hands it over (a server that can't asks for one to be
+pasted).
+
+The wanted links live in `<data dir>/machine-links.json` (no token in it),
+any process writes it, and they resume with the host while remote hosts
+are on. **Shares** run in one process for the computer (the holder of
+`machine-links.lock`, re-checked every 2 s: the daemon, or the first
+window's in-process host; the others show its state from
+`machine-links-status.json`): two processes sharing one machine id would
+keep replacing each other's connection. The lock is exclusive
+(`src/ipc/machine/share-lock.ts`): taken by an exclusive create; its record
+names the holder's pid and a per-process nonce; the holder touches it on
+every check, so it is stale once its pid is gone or it went untouched for
+30 s (a reused pid); a stale lock is moved aside atomically and checked
+before it is retaken. A process that finds another nonce in it stops its
+shares at once, and only the holder removes it. A share's folders are
+checked like the CLI's: absolute, existing, and not zidane's own data or a
+credentials folder (real paths). **Uses** run in every host process
+(each has its own machine registry). Turning remote hosts off stops them
+all.
+
+**TUI**: Settings → Hosts → `ctrl+b` on a saved server opens its machines
+(`src/tui/machines/`): share this computer (name, folders, start / stop),
+use it as a machine (inert unless the server lends itself), its machines
+(status, folders, last seen; `ctrl+x` forgets, asks first). New session:
+a server's machine kinds (and This computer's, when it uses a server) come
+after the host's own, grouped by machine with its status (an offline one
+listed, not pickable), then a folder on that machine. The chat title shows
+`local@laptop` / `worktree@laptop ⎇ branch`, and `waiting for laptop…`
+while a run is paused on it (from the session's notices, cleared by
+`machine:status` online).
+
+**Desktop app**: the same, in Settings › Hosts (a server card's
+*Machines*: switches, folders from the native dialog), the composer's
+environment picker and a machine folder picker, and a "Waiting for
+laptop…" banner over the composer; main relays `machine:status` /
+`machine:links` as `machines:status` / `machines:links`
+([IPC.md § Desktop app](./IPC.md)).
+
+## Security model
+
+- **Sharing a machine gives the host a shell on it**, with the machine user's
+  permissions. Root containment covers file operations and every `cwd`; a
+  shell command can still read anything the machine user can (`cat ~/.ssh/id_ed25519`),
+  exactly like a zidane-server's own shell (see `SERVER.md` § Security). Share
+  with hosts you trust, as a user that owns little.
+- What the machine enforces itself (a malicious host can't bypass it): roots
+  for paths and `cwd`, data-dir exclusion, symlink escapes, size and count
+  bounds, the method set it serves.
+- What the host enforces: machine tokens can only register (never read
+  sessions, settings or signals); client tokens can't register; a revoked
+  token drops the machine's connection (it goes offline, its sessions wait
+  then stop); environments on unknown or forgotten machines are refused.
+- **A machine id is bound to its token.** Ids are not secrets (the CLI
+  prints them, `machines.list` and `machine:status` show them), so the
+  first registration binds the id to the token it used (`principal` in
+  `machines.json`). Another machine token registering that id is refused
+  (`MachineErrorCode.IdBound`) and the machine's connection is left alone;
+  once the bound token is revoked, or the machine forgotten, a new token
+  may take the id.
+- **Forgetting sticks.** `machines.forget` records the (machine id, token)
+  pair: that token registering the id again is refused for good (the agent
+  stops retrying), across restarts, until the share uses a new machine
+  token. The token itself stays (it may serve other machines): revoke it
+  on the server when it was only that machine's.
+- A window mints at most 16 live machine tokens per client token
+  (`tokens.createMachineToken`, each recorded with `createdBy` and
+  audited, refusals included); revoke some to mint more.
+- Safe-mode approvals are unchanged: they are asked of the host's clients
+  before the call ever reaches the machine.
+- Nothing a machine provides runs on the host: no project extension,
+  plugin or URL MCP server from a machine's folder, and its stdio MCP
+  servers run on the machine without this host's environment
+  ([Project files](#project-files)).
+- Reverse direction: the server's own executor confines a client's
+  `machine.call` like a machine confines its host's (its data dir private
+  even when an operator root contains it); with `allowAsMachine` on, a
+  client token can do there what terminals already let it do.
+- A zidane-server has no machine links: `machines.share.*`,
+  `machines.useServer` and `machines.links.status` are refused there.
+- A machine token minted by a window is shown to that window only, kept by
+  its local host in its credentials store, never in `machine-links.json`,
+  never in a log or a status detail.
+
+## Limits
+
+| What | Bound |
+|---|---|
+| Reply / request size | the WS transport's (32 MiB frame); file content base64 |
+| Machine connection rate | not rate-limited per message (terminal output and task exits stream as notifications; the connection can only register) |
+| Roots per machine | 32 |
+| `exec` output | the process context's cap (combined stdout+stderr) |
+| Background tasks | 64 running per machine, output file capped at 8 MiB |
+| Live processes (`exec.stream`) | 16 per machine, 256 KiB per chunk |
+| `!` in a machine session | on any host (a local one too), streamed from the machine (`sessions.workspaceExecStream` runs the session's machine context's `execStream`, i.e. `exec.stream*`; esc kills it on the machine, `exec.cancel`); counts against the 16 live processes; 1 MiB of output per command on the host's side |
+| Project files read from a machine | 64 KiB per instruction file, 256 KiB per `SKILL.md` / MCP file, 64 skills |
+| Hosts a server lends itself to at once | 32, at most 4 per client token (a token's idle one is let go for its new one; full: `Busy`, retried) |
+| Terminals | 16 per machine, 256 KiB backlog, 5 min grace |
+| Offline wait | `machineWaitMinutes` (default 15) |
+
+## Not in v1
+
+- Durable background tasks across a machine **restart** (they die with the
+  machine agent's process).
+- Project scope from a machine for Ruler and foreign agents' configs, and
+  skill resources other than `SKILL.md` (above).
+- A machine's URL MCP servers (dropped: the host would connect).
+- Moving a share between the processes of one computer while it runs: the
+  lock holder keeps it until it exits; another process takes over within
+  2 s after (30 s if it died without releasing it).

package/docs/PANELS.md

@@ -9,6 +9,7 @@ Side-panel tabs next to the transcript, in both the TUI (docked rail) and the GU
 | Artifacts | What the session produced (PRs, branches, commits, recorded files); see [ARTIFACTS.md](./ARTIFACTS.md)                                                                                                                                                                                                        | TUI + GUI |
 | Diffs     | Two sources: **Session** (edits the agent made, from the transcript) and **Working tree** (`git diff HEAD` plus untracked files, live). Unified / split, wrap. On working-tree diffs, selecting lines opens a review-comment draft; `Mod+Enter` attaches `file + range + fenced excerpt + note` to the prompt | GUI       |
 | Files     | The session workspace as a tree with git status; opening a file shows a read-only viewer (or the editor, per the setting below)                                                                                                                                                                               | GUI       |
+| Terminal  | The session's terminals (also in the bottom drawer), running in the session's environment; see [TERMINAL.md](./TERMINAL.md)                                                                                                                                                                                   | GUI       |
 
 Diffs and Files render with [`@pierre/diffs`](https://diffs.com) and [`@pierre/trees`](https://trees.software) (Apache-2.0), themed from the `--zg-*` tokens through `gui/src/renderer/src/components/code/pierre-theme.ts`; `DiffView` / `FileView` / `FileTree` are the only places the packages are touched. Filesystem and git access is read-only, on the host at the session cwd, confined to it (`gui/src/main/chat/workspace.ts`).
 
@@ -57,6 +58,8 @@ ctx.registerPanel({
 });
 ```
 
+`load` and `onAction` get `{ sessionId?, cwd, focus? }`. `focus` (`{ kind?, uri? }`) is set when a session badge opened the panel (`badge.panel`, see [EXTENSIONS.md → Session badges](./EXTENSIONS.md#session-badges)) and stays on the panel's reloads until it is opened for something else. Both run scoped to `sessionId`: `ctx.artifacts.list()` answers that chat's artifacts (GUI main and TUI alike).
+
 ### `PanelContent`
 
 | Field        | Meaning                                                        |

package/docs/README.md

@@ -15,7 +15,10 @@ Each topic has exactly one owner doc; the others link to it. If two docs seem to
 | Chat + surfaces | [CHAT.md](./CHAT.md) | `zidane/chat`: `resolveConfig`, session store + metadata, settings, safe mode, per-edit approval, todos, built-in commands, completion providers, theme, OAuth. |
 | Chat + surfaces | [TUI.md](./TUI.md) | `zidane/tui`: screens, **keybindings table**, modals, transcript rendering, code highlighting, embedding, file layout. |
 | Chat + surfaces | [IPC.md](./IPC.md) | `zidane/ipc`: daemon lifecycle, **every RPC and signal**, multi-window convergence, TUI/GUI parity matrix, `zidane attach`. |
+| Chat + surfaces | [SERVER.md](./SERVER.md) | `zidane-server`: run the host on a remote machine. Docker, configuration, TLS / proxies, tokens, security model, operations. |
+| Chat + surfaces | [MACHINES.md](./MACHINES.md) | Machines: computers lending a host their folders and shell (`local@laptop`), and a server lending itself to a local host (`local@server`). Protocol, offline semantics, project files, sandbox, client UI, security. |
 | Chat + surfaces | [ARTIFACTS.md](./ARTIFACTS.md) | Session artifacts: model, producers, storage, extension kinds, surfaces, RPCs, lazy refresh. |
+| Chat + surfaces | [TERMINAL.md](./TERMINAL.md) | Terminals: PTYs in the session's environment (host, Docker, E2B, Daytona), host manager + pacing, IPC, agent `terminal_*` tools, background tasks in terminals, GUI drawer/tab. |
 | Chat + surfaces | [PANELS.md](./PANELS.md) | Side panels: the declarative content model, `ctx.registerPanel`, catalog + open-state rules shared by the TUI rail and the GUI side panel. |
 | Chat + surfaces | [EXTENSIONS.md](./EXTENSIONS.md) | Extensions: `defineExtension`, **the full `ctx` API**, discovery, install, collisions, settings UI, authoring patterns. |
 | Integrations | [PLUGINS.md](./PLUGINS.md) | Agent Plugins 1.0.0 loader: manifest, validation, filesystem boundary. |
@@ -33,6 +36,7 @@ Each topic has exactly one owner doc; the others link to it. If two docs seem to
 | Session persistence, `SessionStore` backends, sqlite schema | CHAT.md § Sessions |
 | Artifacts (PRs, files a session produced) | ARTIFACTS.md |
 | A side-panel tab (extension or built-in) | PANELS.md |
+| Terminals (drawer, `terminal_*` tools, `openTerminal`) | TERMINAL.md |
 | Settings keys and defaults | CHAT.md § Settings |
 | Safe mode, approvals, per-edit approval | CHAT.md § Safe mode / Per-edit approval |
 | Todos (`todowrite`) contract | CHAT.md § Todos |

package/docs/RESTATE.md

@@ -307,7 +307,7 @@ createAgent({
 
 ### Child events
 
-Hook bubbling can't cross an invocation boundary, so each child's transcript is **replayed onto the parent's bus when it merges** (`child:stream:text`, `child:tool:before/after/error`, `child:turn:after`, `child:stream:end`) — existing `child:tool:*` listeners need no changes. Every event carries `childId`, `depth`, and (tool events) `runId`/`parentRunId`/`parentCallId`; blocks stay contiguous per child in submission order. Not synthesized: `tool:gate`, `tool:transform`, `tool:dispatched`, `tool:cancelled`, `background:*` (decisions taken inside another process).
+Hook bubbling can't cross an invocation boundary, so each child's transcript is **replayed onto the parent's bus when it merges** (`child:stream:text`, `child:tool:before/after/error`, `child:turn:after`, `child:stream:end`) — existing `child:tool:*` listeners need no changes. Every event carries `childId`, `depth`, and (tool events) `runId`/`parentRunId`/`parentCallId`; blocks stay contiguous per child in submission order. Not synthesized: `tool:gate`, `tool:transform`, `tool:dispatched`, `tool:cancelled`, `background:*` (decisions taken inside another process). A child's own merged descendants are announced as `child:spawn:before` → their events → (`child:spawn:error`) → `child:spawn:complete`, with `parentChildId` set to the merged label of their spawner — the lifecycle an in-process nested spawn bubbles.
 
 They **re-fire on a parent replay** — dedupe by `callId`/`turnId`, or gate on `createReplayTracker`. Disable with `emitChildEvents: false`.
 
@@ -367,7 +367,8 @@ createAgent({
 | `disableBackgroundTasks: 'non-durable'` | Background tasks (`shell` with `run_in_background`) stay enabled only when the context declares `capabilities.detachedTasks: 'durable'` — host-local tasks aren't journaled. |
 | `cache: true` | Stable system/tool prefixes reward prompt-cache breakpoints, cutting cold-start cost on retries. |
 | `shouldRethrowToolError: shouldRethrowRestateControlError` | Restate terminal/suspension control errors escape the tool-result path instead of becoming a fake tool error. |
-| `compactStrategy: 'tail'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 8`, `elideStaleReads: 'stub'`, `mediaKeepTurns: 8`, `toolOutputBudget: 64 KiB`, `autoCompact: { threshold: 0.85 }` | Shrinks the per-turn provider payload — journal weight and latency, not just tokens. |
+| `compactStrategy: 'tail'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 8`, `elideStaleReads: 'stub'`, `toolOutputBudget: 64 KiB`, `autoCompact: { threshold: 0.85 }` | Shrinks the per-turn provider payload — journal weight and latency, not just tokens. |
+| `mediaBudget: { maxItems: 80, maxBytes: 20 MiB }`, `maxImageEdge: 2000` | Media stays inline until near the provider's caps, so a long image-heavy run isn't re-billed once per aged screenshot; oversize PNGs shrink once when they enter the session. Requests carry more media bytes than the old 8-message window; pass `mediaKeepTurns: 8` to get that window back (it takes precedence). |
 
 Add `maxCostUsd`/`maxTotalTokens` as a server-side budget breaker: throws `AgentBudgetExceededError` and finalizes the run as `aborted` — durable replay+retry otherwise turns a runaway loop into a runaway bill. See `docs/ARCHITECTURE.md` § run-level budget circuit breaker.
 

package/docs/RUN_IN_BACKGROUND.md

@@ -99,7 +99,7 @@ All optional on `ExecutionContext` (`src/contexts/types.ts`) — a context imple
 | `killBackground(handle, taskId)` | SIGTERMs the whole process group; resolves once the process has exited and its output stream is flushed+closed. Returns `null` on an unknown/already-cleaned-up id — idempotent |
 | `listBackground(handle)` | Snapshot of every task (running + terminated) owned by `handle`. Terminated entries stay until context `destroy()` |
 | `waitBackground(handle, taskId, { timeoutMs?, signal? })` | Resolves with `TaskExitInfo` on exit, or `null` on timeout/abort/unknown id. In-process contexts implement it on `onExit`; durable hosts implement it as an awakeable park |
-| `reassignBackgroundTasks(fromHandle, toHandle, newOnExit?)` | Transfers ownership of every still-running task between handles, rewriting `onExit` to the new owner's callback. Returns the reassigned entries. Optional — without it, `destroy()` kills the source handle's tasks instead |
+| `reassignBackgroundTasks(fromHandle, toHandle, newOnExit?, newOnStall?)` | Transfers ownership of every still-running task between handles, replacing the owner's `onExit` / `onStall` with the new owner's callbacks (in-flight kill/wait resolvers are kept). With `fromHandle === toHandle` only the callbacks move — how a host hands tasks to a rebuilt agent. Returns the reassigned entries. Optional — without it, `destroy()` kills the source handle's tasks instead |
 
 `TaskExitInfo`: `{ taskId, status: 'exited' | 'killed', exitCode, signal?, outputPath, durationMs, command }`. `exitCode` is `128 + signal-number` on signal-killed children (POSIX convention — `143` for SIGTERM).
 
@@ -138,7 +138,15 @@ wake   → next agent.run() drains the queue → <task-notification> prepended t
 
 Every step is bounded by `destroyTimeoutMs`; a step that doesn't settle in time is abandoned (logged under `ZIDANE_DEBUG`) rather than hanging teardown.
 
-No detach-on-destroy option: destroy always kills every background task. Tasks that should outlive the zidane process are the user's job (`tmux`, `nohup`), not this feature's.
+No detach-on-destroy option: destroying the handle always kills its background tasks. Tasks that should outlive the zidane process are the user's job (`tmux`, `nohup`), not this feature's.
+
+### Surviving agent rebuilds (chat hosts)
+
+The daemon / GUI host and the TUI rebuild a session's agent for reasons unrelated to execution: model or profile swap, settings changes (extensions, MCPs, skills, plugins), MCP login, idle eviction. They build agents on a **host-owned handle** from `src/chat/execution-cache.ts` (`AgentOptions.handle`, lazy form), so step 4 above is skipped and running tasks survive the rebuild:
+
+- The rebuilt agent `adopt`s them: exit/stall callbacks are rebound to its hooks and each task is announced as `background:adopt`, which hosts register like `background:start`. A task that exited while no agent owned it reaches the model through the next run's pull reconcile.
+- The handle is released, killing its tasks, when the **session** is done with it: deleted, idle-evicted with nothing running, host drain (process exit), or — in the TUI — switching sessions.
+- A changed context configuration (cwd, sandbox policy) replaces the context and ends its tasks: they were started under the old configuration.
 
 ## Subagents