zidane 7.2.4 → 8.0.4

package/docs/SKILL.md

@@ -419,6 +419,7 @@ Every event in `AgentHooks` (`src/agent.ts`), one row each. `child:*` bubble eve
 | `context:transform` | Before each LLM call | **yes** (`messages`) | `messages` |
 | `system:transform` | Per-request system-prompt mutation (after `context:transform`) | **yes** (`system`) | `system, messages (readonly), turn, turnId, session?` |
 | `steer:inject` | Steering/follow-up injected | — | `message` |
+| `spawn:queued` | A top-level spawn call waits for a slot (`maxConcurrent` reached) | — | `task, callId?, depth, waitingFor: { active, max }` |
 | `spawn:before`, `spawn:complete`, `spawn:error` | Sub-agent lifecycle | — | `id, task, callId?, stats?, error?` (`callId` = the spawn call's own id, i.e. the child's `parentCallId`) |
 | `mcp:connect` | Server's client is live (bootstrap, or first `tools/call` for `lazyConnect`) | — | `name, transport, tools, lazy?` |
 | `mcp:error` | Fatal MCP connection failure | — | `name, error` |
@@ -483,11 +484,15 @@ child:stream:server_tool_use / child:stream:server_tool_result / child:stream:er
 child:tool:gate / child:mcp:tool:gate    ← mutable: block/reason/result propagate to the child
 child:tool:transform                     ← mutable: parent can rewrite the child's tool_result
 child:tool:before / child:tool:dispatched / child:tool:after / child:tool:error / child:tool:cancelled
+child:validation:reject / child:repeat-guard:exceeded
 child:background:start / child:background:exit / child:background:reassign
 child:turn:after
 child:artifact:recorded
+child:spawn:before / child:spawn:complete / child:spawn:error   ← a spawn run BY a subagent
 ```
 
+`child:spawn:*` carry the spawned agent's record (`id` / `depth` / `task` / `callId`, plus `stats` / `status` or `error`) and `parentChildId` (its spawner) — no `childId`, no `tracingContext`. Deeper levels chain through verbatim.
+
 Render nested activity without listening on the child instance. The `child:*:gate` and `child:tool:transform` events share the same `ctx` reference the child's loop awaits on (`BUBBLED_MUTABLE_EVENTS` in `src/tools/spawn.ts`), so a parent gate handler can refuse / substitute / annotate a child's tool call without registering on the child agent. `child:background:reassign` fires when a grandchild's background tasks get promoted to the child's handle on the grandchild's destroy — the chain runs at each spawn boundary until the top-level parent owns every task.
 
 ### Hook recipes
@@ -612,7 +617,7 @@ definePreset({
   tools: {
     ...basicTools,
     spawn: createSpawnTool({
-      maxConcurrent: 5,
+      maxConcurrent: 5,  // a 6th top-level call waits for a slot; a subagent's is refused
       model: 'claude-haiku-4-5-20251001',
       preset: { tools: {} },  // restrict children
     }),

package/docs/TERMINAL.md

@@ -0,0 +1,75 @@
+# Terminals
+
+Each session can open terminals that run **where the session runs**: on this machine, in its Docker container, or in its E2B / Daytona sandbox. The GUI shows them in a bottom drawer under the transcript and in a **Terminal** tab of the side panel. The agent can list and read them, type into them with approval, and its background `shell` tasks run in terminals of their own.
+
+## Where they run
+
+The host (the daemon) owns every terminal, so terminals keep running while no window shows them, and every view (the drawer, the panel tab, a second window) shows the same one. The execution context opens the PTY through `ExecutionContext.openTerminal`:
+
+| Context   | How                                                                                     | Survives a daemon restart |
+| --------- | --------------------------------------------------------------------------------------- | ------------------------- |
+| `process` | `Bun.spawn(..., { terminal })`: a login shell in the session directory                  | no                        |
+| `docker`  | `docker exec -it` inside a local PTY; `kill` hangs up the in-container shell's group    | no                        |
+| `e2b`     | `sandbox.pty` (`create` / `sendInput` / `resize` / `kill`)                              | yes, `pty.connect(pid)`   |
+| `daytona` | `process.createPty` / `resizePtySession` / `killPtySession`                             | yes, `connectPty(id)`     |
+
+Local PTYs need Bun, so terminals are **daemon-only**: the GUI's in-process host runs under Node and reports terminals as unavailable. Turn on the shared daemon to use them (Settings › Terminal shows the switch and whether the daemon is connected).
+
+In a Docker or sandbox session, **New terminal on this Mac** opens a shell on the host in the project directory instead.
+
+Terminals get the environment the agent's commands get in that context, plus `TERM=xterm-256color`, `COLORTERM=truecolor`, `TERM_PROGRAM=zidane`. Host plumbing (`PORT`, `ELECTRON_*`, `ZIDANE_DAEMON_SOCKET`, …) is removed.
+
+## Settings
+
+Settings › Terminal (shared `state.json`, so every surface sees them):
+
+| Key                  | Default | Off means                                                                                                                                   |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `terminal`           | on      | No drawer, panel tab, header toggle, palette entries or shortcuts; the host refuses to open terminals and closes the ones the user opened. |
+| `terminalAgent`      | on      | The agent gets no `terminal_*` tools. Requires `terminal`.                                                                                  |
+| `terminalAgentTasks` | on      | Background `shell` tasks run on pipes, without an agent tab. Requires `terminal`.                                                          |
+
+Off is enforced by the host, not just hidden: `ChatHost.applyTerminalSettings` runs on every settings write (daemon `settings.set` and the GUI's in-process path), rebuilds agents (idle ones now, busy ones at run end, no run aborted) and, when `terminal` goes off, closes user terminals. Running agent tasks keep their terminals until they end. The page also shows the "Shared daemon runtime" switch and the daemon's connection state, since terminals only run there.
+
+## Host side (`src/chat/host/terminal/`)
+
+- **History**: the last 4 M characters of raw output per terminal, replayed to a view when it attaches.
+- **Pacing**: output is batched every 16 ms and sent as `terminal:output { offset, data }`. Views drop what they already have and `terminal.ack` what they wrote. Once the slowest view is 256 K characters behind, sending stops; when it catches up, every view gets `terminal:reset` from history. The daemon sends output only to connections that attached that terminal.
+- **Size**: a PTY has one size; the view the user last focused or typed into sets it (`terminal.resize` with `claim: true`).
+- **Labels**: the title a program sets (OSC 0/2), and for local shells the foreground program (`ps -o tpgid`).
+- **Agent text**: a second, plain-text copy (escape sequences stripped, carriage-return redraws collapsed, `src/contexts/ansi-strip.ts`), 5 000 lines, for `terminal_read`.
+- **Persistence**: remote terminals are saved in session metadata (`terminals`) and come back as `paused` after a restart; attaching reconnects. Local ones end with the daemon.
+- **Idle suspension**: terminal input or output counts as session activity, and a session with recent terminal activity (or a running agent task terminal) is not suspended. When a sandbox does pause, its terminals are let go and reconnect on next use.
+- **Limits**: 12 open terminals per session.
+
+## IPC
+
+`terminal.state | open | attach | detach | write | resize | ack | restart | close | setHidden` (`src/ipc/protocol.ts`); signals `terminal:changed` (the session's full list), `terminal:output`, `terminal:reset` (`src/chat/host/signals.ts`). Shapes live in `src/chat/terminal/protocol.ts`, re-exported from `zidane/chat/pure`.
+
+## Agent tools (`src/chat/terminal/tools.ts`)
+
+| Tool             | What                                                                                     | Safe mode                                               |
+| ---------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `terminal_list`  | The session's terminals: status, owner, program, cwd                                     | never asks                                              |
+| `terminal_read`  | Recent plain-text output, up to 16 KB, with a `since` cursor                             | never asks                                              |
+| `terminal_write` | Types `text` then `keys` (`Enter`, `C-c`, `Up`, …), waits for output to settle           | asks; on a terminal the user opened, asks every time    |
+
+A terminal marked **Hide from agent** is left out of all three.
+
+## Agent background tasks
+
+In the chat host, `shell({ run_in_background: true })` runs the command in a PTY when the context supports it (`execBackground`'s `terminal` option; the `process` context today). The task shows up as an agent tab the user can watch, scroll, type into, or close (which kills the task). The model's side stays the same: the log at `output_path` receives the output as plain text (a prompt left waiting for input is written out too), and `wait_task`, `shell_kill` and `<task-notification>` work as before. One difference: stdin is now a terminal instead of `/dev/null`, so the user can answer prompts. Pagers and git's credential prompt are turned off (`PAGER=cat`, `GIT_TERMINAL_PROMPT=0`), but other tools that check for a TTY behave as they would in a shell: `vitest` starts in watch mode, `sudo` and `ssh` ask for a password. Pass their non-interactive flag (`vitest run`, `sudo -n`). Other contexts, and the headless CLI, keep running tasks on pipes.
+
+## GUI (`gui/src/renderer/src/terminal/`)
+
+Rendered with [`@tahul/ghostty-web`](https://github.com/Tahul/ghostty-web) (our fork of `ghostty-web`: Ghostty's VT parser in WebAssembly, xterm.js-compatible API); `TerminalSurface.tsx` is the only file that imports it. Theme from the `--zg-*` tokens. Selecting output and choosing **Add to chat** attaches it to the prompt as a chip (`Terminal 1 · lines 12–18`). `Ctrl+`` toggles the drawer, `Ctrl+Shift+`` opens a new terminal.
+
+- **Links**: the library finds OSC 8 hyperlinks (`ls --hyperlink`, compilers, `gh`) and URLs with a scheme, soft-wrapped ones included, and hands every click to our `linkHandler` (`linkTarget` in `links.ts`): web pages open in the Browser tab (⌘/Ctrl-click: the system browser), `file://` links in the Files panel (with `:line:col` or `#L12`), `mailto:` in the system on ⌘/Ctrl-click only, every other scheme (`javascript:`, `data:`, `vscode:`, …) never. Our own provider adds what the library can't know: file paths with a position and scheme-less local servers (`localhost:5173`).
+- **Keys**: macOS editing keys send what Terminal.app and iTerm2 send, so shells handle them by default: ⌘⌫ / ⌘⌦ delete to the line start / end, ⌘← / ⌘→ go to the line start / end, ⌥⌫ / ⌥⌦ delete a word, ⌥← / ⌥→ move by word (`keys.ts`). ⌘C copies a selection, ⌘V pastes (bracketed when asked). ⌘K stays the app's command palette; **Clear** is in the right-click menu.
+- **Tabs and sizing**: a terminal shown in a view stays mounted while another tab is active, so switching back is instant. A view's grid always has the PTY's size, never its own, so output is always drawn in the grid it was laid out for (no reflow, no garbled prompts). Views only ask for the size their container fits; the one being looked at (shown, focused, typed into) gets it, and when it leaves, the view still showing the terminal takes over with its last request. A view narrower than the grid clips the right edge, as tmux does. Sizes carry a `sizeSeq`, so a view keeps the newest one whether it came with the attach reply or the terminals list.
+- **Opening size**: the terminal area measures the grid it fits before opening (`grid-size.ts`, the library's own fit formula), so a new PTY starts at its real size. Started at 80×24 and resized, zsh would leave its `%` partial-line mark behind and the prompt would render twice.
+- **First frame**: a view stays transparent until it has its history and the size it asked for (capped at 400 ms), so a half-drawn terminal is never on screen. A grid that already has content is never resized in place (the library's reflow overlaps lines): the view clears it, resizes the empty grid and redraws what it has shown, in the same frame.
+- **Late mouse reports**: the host follows the program's mouse modes from its output (`src/contexts/terminal-mouse.ts`) and drops mouse reports that arrive after tracking went off (a view decides from its own copy of the screen, a few ms behind), so a shell never prints `80;41;31M` after a program quits.
+- **Emulator replies**: queries in the output (cursor position `ESC[6n`, device attributes), which prompts like starship send, are answered by the view's emulator. Replies produced while replaying history are dropped, and live ones are sent tagged (`terminal.write` with `response`); the host keeps only the size owner's, so a shell never reads extra `;1R` as typed text.
+- **Mouse**: while a program tracks the mouse (vim, htop, `less --mouse`), clicks, drags and the wheel are reported to it (one report per wheel notch) and don't select text or scroll; hold **Shift** to select, scroll the scrollback, or open our right-click menu instead.
+- **Known issue**: after an OSC 8 link has been clicked, the next terminal created can loop inside the WASM (`ghostty_render_state_update`, during its first fit), freezing the window. Tracked by a `test.fixme` in `gui/test/visual/terminal.test.ts`.

package/docs/TUI.md

@@ -16,13 +16,13 @@ await runTui({ providers: { ...BUILTIN_PROVIDERS } })  // custom registry
 await runTui({ projectDb: true })                      // per-repo <git-root>/.zidane/sessions.db
 ```
 
-Contents: [Quick start](#quick-start) · [Composition](#composition) · [Public exports](#public-exports) · [Screens](#screens) · [Keyboard](#keyboard) · [Modals](#modals) · [Theme + code highlighting](#theme--code-highlighting) · [Transcript rendering](#transcript-rendering) · [Settings modal](#settings-modal) · [Completion + slash-commands](#completion--slash-commands) · [MCP servers + OAuth](#mcp-servers--oauth) · [Auth wizard](#auth-wizard-ai-providers) · [Execution runtimes](#execution-runtimes-in-process-vs-daemon) · [Embedding](#embedding) · [Auto-update](#auto-update) · [File layout](#file-layout)
+Contents: [Quick start](#quick-start) · [Composition](#composition) · [Public exports](#public-exports) · [Screens](#screens) · [Keyboard](#keyboard) · [Modals](#modals) · [Theme + code highlighting](#theme--code-highlighting) · [Transcript rendering](#transcript-rendering) · [Settings modal](#settings-modal) · [Completion + slash-commands](#completion--slash-commands) · [MCP servers + OAuth](#mcp-servers--oauth) · [Auth wizard](#auth-wizard-ai-providers) · [Execution runtimes](#execution-runtimes-in-process-vs-daemon) · [Several hosts](#several-hosts-remote-hosts) · [Embedding](#embedding) · [Auto-update](#auto-update) · [File layout](#file-layout)
 
 ## Quick start
 
 `runTui` is a one-shot launcher: boots OpenTUI, registers Tree-sitter grammars, resolves config, mounts `<App>`, then `process.exit(0)`s on dismiss (Ctrl+C, or Esc on the auth screen). Calling it twice throws.
 
-Env overrides: `ZIDANE_STORAGE_DIR`, `ZIDANE_PREFIX`, `ZIDANE_PROJECT_DB`, `ZIDANE_NO_UPDATE`, `ZIDANE_NO_DAEMON` / `--no-daemon`, `ZIDANE_DEBUG` (renderer `gatherStats`, fps/frametime to stderr on exit).
+Env overrides: `ZIDANE_STORAGE_DIR`, `ZIDANE_PREFIX`, `ZIDANE_PROJECT_DB`, `ZIDANE_NO_UPDATE`, `ZIDANE_NO_DAEMON` / `--no-daemon`, `ZIDANE_HOST_URL` + `ZIDANE_HOST_TOKEN` / `--host` + `--token` (remote host), `ZIDANE_NO_REMOTE` / `--no-remote`, `ZIDANE_DEBUG` (renderer `gatherStats`, fps/frametime to stderr on exit).
 
 Renderer fps is `Settings.targetFps` (30/60/120): seeds the renderer at boot, live flips apply via `renderer.targetFps`/`maxFps`.
 
@@ -230,7 +230,7 @@ Theme switching is real-time: every `useColors()`/`useSelectStyle()`/`useSurface
 
 Fenced code blocks highlight via Tree-sitter (`src/tui/tree-sitter.ts`). Registered grammars: `python`, `bash`(`sh`/`shell`/`zsh`), `json`, `rust`(`rs`), `go`(`golang`), `yaml`(`yml`), `html`(`htm`), `css`, `haskell`(`hs`), `c`, `cpp`(`c++`/`cxx`/`cc`), `csharp`(`cs`/`c#`), `elixir`(`ex`/`exs`), `ruby`(`rb`), `diff`(`patch`), `scala`(`sbt`/`sc`), `julia`(`jl`), `ocaml`(`ml`), `r`, `perl`(`pl`/`pm`), `swift`, `kotlin`(`kt`/`kts`), `fsharp`(`fs`/`fsx`/`fsi`), `sql`(`psql`/`mysql`/`sqlite`/`plsql` — vendored into the TUI binary via `ZIDANE_LOCAL_TREE_SITTER_SQL_WASM`), plus whatever OpenTUI ships by default (TS/JS/JSX/TSX). `registerTreeSitterParsers()` runs synchronously at boot; `initTreeSitterWorker()` warms the worker off the critical path. Wasms download lazily and cache under OpenTUI's data path; failures fall back to plain text.
 
-`Settings.toolCallDisplay` picks the `'tool'` event rendering (`'hidden'` / `'formatted'` (default) / `'full'`); `Settings.showEditDiffs` renders `edit`/`multi_edit`/`write_file` as a unified diff via `EditDiffBlock` regardless of that mode, with per-hunk applied/denied/skipped/failed badges when outcomes are present. Both are engine-shaped contracts documented in [CHAT.md § Tool call display](./CHAT.md#tool-call-display) and [§ Edit-diff rendering](./CHAT.md#edit-diff-rendering) — this doc only owns the OpenTUI rendering (`<EventLine>` dispatch in `components.tsx`, diff colors from `theme.surfaces.diff`).
+`Settings.toolCallDisplay` picks the `'tool'` event rendering (`'hidden'` / `'formatted'` (default) / `'full'`); `Settings.showEditDiffs` renders `edit`/`multi_edit`/`write_file` as a unified diff via `EditDiffBlock` regardless of that mode, with per-hunk applied/denied/skipped/failed badges when outcomes are present. Both are engine-shaped contracts documented in [CHAT.md § Tool call display](./CHAT.md#tool-call-display) and [§ Edit-diff rendering](./CHAT.md#edit-diff-rendering) — this doc only owns the OpenTUI rendering (`<EventLine>` dispatch in `transcript/event-line.tsx`, diff colors from `theme.surfaces.diff`).
 
 ## Transcript rendering
 
@@ -249,16 +249,20 @@ Fenced code blocks highlight via Tree-sitter (`src/tui/tree-sitter.ts`). Registe
 Tabbed: **Agent**, **UI** (always present) + **Keybindings**, **Authentication**, **Instructions** (present when the host wires the matching data props) + **Skills**, **MCP servers** (always) + **Extensions** (present when extensions are discoverable). One shared search input filters the active tab; `←`/`→` cycle tabs, `↑`/`↓` navigate, `↵` toggle/cycle/pick/edit.
 
 - **Agent / UI** rows are toggle/choice/action, sourced from `SETTINGS_TOGGLES`/`SETTINGS_CHOICES`/`SettingsActions` in `src/chat/settings-context.tsx` — current keys, labels, categories: [CHAT.md § Settings](./CHAT.md#settings).
+- **Agent → Environments** opens `EnvironmentsSettingsModal` (`src/tui/environments-settings.tsx`): the default environment for new sessions, each kind's on/off and options, secrets (`ctrl+x` resets / clears). Same descriptors and schema check as the GUI's Environments tab — [CHAT.md § Session environments](./CHAT.md#session-environments). A kind with a connection to check gets a **test connection** row. With more than Local enabled, `newSession` opens `EnvironmentPickerModal` first (the focused kind's note says what it will clone). The session details modal shows the session's environment and runs its commands (push branch, open pull request) with `1`–`9`.
 - **Keybindings** embeds the `KEYBINDING_DEFS` catalog (shared with the standalone `KeybindingsModal` via `groupBindings`); `↵` opens `keybindings.json`.
 - **Authentication** shows the active + detected providers; `↵` pops the full-screen `AuthScreen`.
-- **Instructions** answers "what's in my context, and where from" — one row per `ContextSegment` (base prompt, each `AGENTS.md`/`CLAUDE.md`, skills catalog, MCP instructions, subagent defs), labelled by origin (`built-in`/`file`/`generated`/`mcp server`). `tab` expands inline, `↵` opens file-backed rows in `$EDITOR`. The `SYSTEM.md` row's `↵` **creates** the override file (seeded from the doctrine-only prompt) when none exists — the one Instructions action that writes. Full contract: [CHAT.md § `SYSTEM.md`](./CHAT.md#systemmd--overriding-the-built-in-prompt) and [§ Context segments](./CHAT.md#context-segments).
+- **Instructions** answers "what's in my context, and where from" — one row per `ContextSegment` (base prompt, each `AGENTS.md`/`CLAUDE.md`, skills catalog, MCP instructions, searchable-tools catalog), labelled by origin (`built-in`/`file`/`generated`/`mcp server`). `tab` expands inline, `↵` opens file-backed rows in `$EDITOR`. The `SYSTEM.md` row's `↵` **creates** the override file (seeded from the doctrine-only prompt) when none exists — the one Instructions action that writes. Full contract: [CHAT.md § `SYSTEM.md`](./CHAT.md#systemmd--overriding-the-built-in-prompt) and [§ Context segments](./CHAT.md#context-segments).
+- **Hosts** (only with Settings → Remote hosts on, and `ZIDANE_NO_REMOTE` unset): This computer and the saved servers, each with its status (connected / reconnecting / offline / token refused / different server: another server answers at its URL, not retried) and the server's name and version. `↵` on `+ add a server` asks for the URL, then the token (typed or pasted, shown as dots), and saves nothing unless the server answers to it; a refusal says why (bad URL, token refused, unreachable, TLS, not a zidane-server, a different server at that URL). `↵`/`ctrl+t` tests the focused server, `ctrl+b` opens its machines (share this computer with it, use it as a machine, its machines: [MACHINES.md § Client UI](./MACHINES.md#client-ui)), `ctrl+e` renames it, `ctrl+x` removes it and its token (asks first). This computer and a `--host` server are not removable. See [Several hosts](#several-hosts-remote-hosts).
 - **Skills / MCP servers / Extensions** render the discovered catalogs as enable/disable checklists (`enabledSkills`/`enabledMcps` default to "everything enabled"; toggling seeds an explicit allowlist so newly-discovered entries don't silently opt in). Extension semantics: [EXTENSIONS.md](./EXTENSIONS.md).
 
-Reachable from every screen but `auth`; with no live agent yet (home/sessions/model-picker), the Instructions tab composes a preview of the *next* session (`live: false`) via the same `composeHostContext` helper `buildAgent` uses.
+**On a server's session** (remote hosts on), the modal edits that server: its title is `settings · <server>`, and the settings the server owns (safe mode, sandbox, limits, compaction, the enabled skills / MCP servers / extensions, …) are read with `settings.get` and written with `settings.set` there, never into this computer's `state.json`. This window's own settings (the UI tab, theme, fps, icons, editor and keyboard habits, `useDaemon`, `remoteHosts`: `isWindowOnlySetting` in `src/chat/host-scoped-settings.ts`, shared with the GUI) stay local. The tabs that read this computer's files change: **Authentication** lists the server's providers (`auth.status`); `↵` stores an API key there (`auth.setApiKey`, typed masked), `o` signs an OAuth provider in with the browser on this computer and the tokens on the server (`auth.oauth.*`, `src/tui/settings/server-oauth.tsx`: the URL / device code shown, `p` pastes a code or the address the browser landed on, esc cancels on the server), `ctrl+x` removes the stored ones (`auth.remove`). **Skills / MCP servers / Extensions** list the server's catalogs for the session's folder there (`catalog.skills` / `catalog.mcps` / `catalog.extensions` + `catalog.plugins`, `src/tui/settings/server-catalog-panel.tsx`), each with the server's enabled state; `↵` turns an entry off or on, written to the server's enabled list (the first toggle seeds an explicit list, like this computer's tabs). MCP secrets arrive redacted. `o` signs an HTTP MCP server in the same way (a loopback on this computer, the tokens on the server). When the server takes installs (`ipc.hello`'s `remoteInstalls`, its `allowRemoteInstalls`): `i` installs a skill / extension from a GitHub or npm spec into the server user's scope (`catalog.install`), `ctrl+x` then `y` removes a user-scope one (`catalog.remove` / `mcp.remove`), `ctrl+u` updates an extension (`catalog.update`), `a` adds an MCP server (`<name> <url>` then an optional masked Authorization header, or `<name> <command> [args]`; `mcp.upsert`); a `catalog:changed` from any window re-reads the tab. `!` in a server session streams from the server (`sessions.workspaceExecStream`; esc kills it there); so does `!` in a machine session (`local@` / `worktree@<machine>`) on any host, This computer's included: it runs on the machine, never in this window's shell. A server too old for the catalogs gets its enabled lists only (the previous panel). **Instructions** is hidden (it composes this computer's context). The rule is keyed on the active session's host being a server, saved or `--host`, remote hosts on or off (`isActiveOnServer`, `src/tui/live-settings.ts`), never on "another server than the default": a setting flipped outside the modal (the command palette, an extension, the modal of a `--host` window with remote hosts off) publishes only the server's keys (`src/tui/settings/use-settings-publish.ts`); a server's `settings:changed` is applied for its host-scoped keys only (another window's theme, `remoteHosts` or `useDaemon` never reach this one); and only window-only keys are written to this computer's `state.json` while on a server. Back on a This computer session, the window takes this computer's host-scoped values again from its `state.json`.
+
+Reachable from every screen but `auth`; with no live agent yet (home/sessions/model-picker), the Instructions tab composes a preview of the *next* session (`live: false`) via the same `composeHostContext` helper the host uses to build agents.
 
 ## Completion + slash-commands
 
-Two built-in providers: **skills** (`/`, substring match on name+description, prefix sorts first) and **files** (`@`, exact-name → prefix → substring → path-substring; `git ls-files --cached --others --exclude-standard` when in a repo, else a depth-walked scan capped at 10,000 files). Commit inserts `<trigger><value> `. On submit, `App` walks the buffer via each provider's `parseReferences(text)`; skill refs call `agent.activateSkill(name)` before `agent.run()` (slash text stays visible to the model).
+Two built-in providers: **skills** (`/`, substring match on name+description, prefix sorts first) and **files** (`@`, exact-name → prefix → substring → path-substring; `git ls-files --cached --others --exclude-standard` when in a repo, else a depth-walked scan capped at 10,000 files). Commit inserts `<trigger><value> `. `↵` and `tab` both commit (the `chats` popup's `tab` toggles scope instead). On submit, `App` walks the buffer via each provider's `parseReferences(text)`; skill refs ride the send (`activatedSkills`) and the host activates them before the run (slash text stays visible to the model).
 
 References highlight in two places: the live textarea (`useChipHighlights`) and the submitted echo (`UserPromptBlock` via `splitPromptSegments`), both keyed off `theme.surfaces.chips[providerId]` (fallback `chips.default`). Adding a third provider: implement `CompletionProvider<TItem>` in `zidane/chat`, pass it in `completionProviders` — the popup picks it up automatically.
 
@@ -280,11 +284,48 @@ Discovered servers (`mcps.json` + `mcp.json` under `.{prefix}/` or `.agents/`, p
 
 `AuthScreen`/`SetupWizard`: pick provider → pick method (API key or OAuth, gated on `supportsOAuth`) → enter key (`setProviderCredential`) or run OAuth (`runOAuthLogin`, surfaced via `<OAuthAuthBlock>` with browser-open, copy, and paste-back). A first OAuth login is stored as the `Default` account; when the provider already holds OAuth accounts, picking OAuth first asks whether to re-authenticate one of them or add another, then for the new account's name (required). Settings → Authentication lists every stored account under its provider; `↵` on one makes it active, `ctrl+e` renames it (footer editor, empty = `Default`), `ctrl+x` (twice) removes it. A pre-existing user picker (when ≥1 provider is authed) lists current credentials plus `+ add or re-configure`. Esc bails to the picker, or exits the TUI on true first launch.
 
-## Execution runtimes (in-process vs daemon)
-
-`activateSession` (`src/tui/app.tsx`) is the single fork point: **in-process** (default) builds the agent loop in this window's process; **daemon** (`Settings.useDaemon`, experimental) connects to a shared daemon (`src/tui/runtime/daemon.ts`) so multiple windows converge on the same live stream, queue, drafts, approvals, and presence. An activation populates exactly one of `agentRef`/`daemonRef` — never both — and both branches feed the same React state, so every screen/modal/keybinding works unmodified in either mode.
-
-Coexistence: the store (`sessions.db`/`state.json`) is neutral ground both runtimes read/write; a cross-process run guard (`status: 'running'`, 5-minute freshness bound) stops two runtimes stacking `agent.run()` on one session; while a controller is connected the daemon owns `state.json` settings writes. Turning it off always works: every daemon touchpoint gates on the live controller, `--no-daemon`/`ZIDANE_NO_DAEMON=1` beat the setting, and a connect failure fails soft to `buildAgent` with a visible notice. Full protocol, lifecycle, and the daemon-mode asymmetries (`/` commands needing a local agent, `!`/`/` executing in the issuing window): [IPC.md](./IPC.md).
+## Execution runtimes (in-process, daemon, remote)
+
+Sessions always run in a chat host; `activateSession` (`src/tui/host/use-session-activation.ts`) connects the window to it with `connectHostSession` (`src/tui/runtime/host-session.ts`) and only the transport differs (`src/tui/runtime/transport.ts`). **In-process** (default): a host inside this window's process, started on first use and built from the window's own config, extension registry and bridges; a run lives with its window (switching sessions mid-run is refused, leaving a session disposes it, quitting drains the host). **Daemon** (`Settings.useDaemon`, experimental): the shared daemon over its socket, so multiple windows converge on the same live stream, queue, drafts, approvals, and presence, and runs outlive their window. **Remote** (`zidane --host <wss-url> --token-file <path>`, or `ZIDANE_HOST_URL` / `ZIDANE_HOST_TOKEN`; experimental): every session of the window runs on a zidane-server over WebSocket, with daemon semantics (multi-process: runs outlive the window, switching mid-run is allowed, presence, the health dot plus `host: <name>` in the footer). Which one a window uses is decided in one place, `resolveHostTarget` (`src/tui/host-target.ts`); `isMultiProcess` and the window's transport (`src/tui/host/use-local-host.ts`) read it. `ZIDANE_NO_REMOTE=1` (`--no-remote`) refuses `--host` with a message, ignores `ZIDANE_HOST_URL` from the environment with a warning (the window runs locally), and greys out Settings → Remote hosts. Headless runs (`zidane run --json`, `--json-schema`) are local-only: they refuse `--host` and ignore the environment's host. In remote mode `!` commands run on the server, in the session's folder, through its workspace exec. The window reads and writes session data (the list, the open session, titles, artifacts, out-of-band turns) only through its host (`src/tui/runtime/session-data.ts`), holding a store-less snapshot of the open session (`src/tui/runtime/session-snapshot.ts`), so a remote window shows the server's sessions. Details: [IPC.md § TUI local mode](./IPC.md#tui-local-mode), [IPC.md § Remote server](./IPC.md#remote-server-zidane-server).
+
+### Several hosts (remote hosts)
+
+Opt-in: Settings → Remote hosts (experimental, off by default), and `ZIDANE_NO_REMOTE=1` beats it. Off, the window is exactly the single-host window above: no Hosts tab, no grouping, no host step, and the saved-hosts code (`src/tui/host/remote-hosts.ts`, the WebSocket client, the registry) is never loaded, so `hosts.json` is never read and nothing is dialed (`test/tui/remote-lazy-graph.test.ts` checks the static import graph, `test/tui/app-remote-containment.test.tsx` the running app).
+
+On, the window keeps one app-lifetime connection per host in its **host directory** (`src/tui/host/host-directory.ts`: key → transport, client, status): This computer (the in-process host or the shared daemon), each server saved on the Hosts page, and a `--host` server as an unsaved entry. The registry ↔ directory sync and the connection loop (backoff 1 s → 30 s, a refused token not retried, the statuses) are shared with the GUI (`src/ipc/hosts`, `zidane/ipc/remote`); the TUI keeps its glue (`remote-hosts.ts`: a WebSocket transport per entry; `host-signals.ts`: presence and session changes). The default host (where a new session goes) is `--host` when given, else This computer; the active host is the one of the session on screen.
+
+- **Routing by session**: every call about one session (out-of-band turns, `!` on a server, extension state, artifacts, environment actions) goes to that session's host (`src/tui/runtime/routed-session-data.ts`), not to whatever host is on screen when it finishes: a `!` or a notice that completes after a switch lands on its own session. A session's host is learned from what the hosts say: their lists, a create, an activation, a lookup the active host answered. A session is a (host, id) pair: two hosts may list the same id, so a row of the several-host list carries its host (`SessionMeta.hostKey`) into opening it and its details actions, the open session's pair is recorded at activation, and an id several hosts list is refused without its host (`AmbiguousHostIdError`). A write to a session no host named is refused (`UnknownHostIdError`), never sent to This computer; the hosts also refuse `sessions.appendTurns` for a session they don't have (no header-less ghost row).
+- **Saving a saved server again** (a new token, a new URL) reconnects it in place: an open session on it stays there.
+- **Removing the server of the open session** (Hosts page, another window, or turning Remote hosts off) closes that session in the window: its controller goes, pending questions are cancelled with the reason, and the window lands on the sessions list with `<server> was removed` (`src/tui/host/use-host-removal.ts`). Its ids answer `HostRemovedError` from then on.
+
+- **Sessions list**: grouped by host, This computer first, then each server with its status. A server that is offline shows the sessions of its last good list (in memory only), marked as such; opening one says the server is offline. The project scope applies to This computer; a server's group lists all its sessions (its folders are not this machine's). Search, the scope toggle and presence glyphs work across groups. With no saved server the list has no headers.
+- **Opening** a session uses its host. Switching follows the semantics of the host the current session runs on: an in-process run blocks the switch (as above), a daemon or server run keeps going. A row whose session another window deleted meanwhile is never recreated: opening it says `This session no longer exists on <host>.` (`SessionGoneError`, `src/tui/runtime/session-data.ts`) and the list re-reads.
+- **Notices** on the sessions list are one line, gone when you leave the screen; one about a server's status ("<server> is offline") also goes as soon as that server connects again (`src/tui/sessions/use-sessions-notice.ts`).
+- **New session** (`ctrl+n`, `+ new session`) asks the host first (default focused), then that host's environments (a server's from `environments.list`), then for a server a folder on it (`fs.roots` / `fs.listDirs`, starting at its first workspace root; `↵` on a folder opens it, on `use <path>` creates there). This computer keeps the window's folder and environment picker. A window never sends its own folder to a server: a new session on a `--host` server starts in the server's first root unless one is picked.
+- **Chat title / footer**: a server session's title bar shows `<folder> (on <server>)` and the footer `host: <server>`; This computer shows neither.
+- **Machines** (`src/tui/machines/`, [MACHINES.md](./MACHINES.md)): Settings → Hosts → `ctrl+b` on a saved server: share this computer with it (name, then folders: `+ add a folder`, `ctrl+x` removes one, `start sharing`; the machine agent runs in This computer's host and its token is minted on the server, or pasted when the server can't), use it as a machine (only when it lends itself), its machines (status, folders, last seen; `ctrl+x` forgets, asks first). New session: a host's machine kinds after its own, grouped by machine with its status (offline: listed, not pickable), then a folder on the machine (`machines.listDirs`); This computer's picker adds its own machine kinds (a server it uses). The chat title shows `local@laptop` / `worktree@laptop ⎇ <branch>`, and `waiting for laptop…` while a run is paused on that machine.
+- **Live lists**: every connected host's group re-reads when that host announces a session change (`sessions:changed`, which a host sends every connection, watching a session or not), at most every 250 ms: a session another window (or the GUI) creates, renames or deletes on a server shows up without reopening the list.
+- **Resume on launch** remembers the host: the window's `state.json` keeps `lastSessionHostKey` (a saved server's host key, its id; absent for This computer; read from the older `lastSessionHostId` too) beside `lastSessionId`. A `--host` session writes neither (the pointer stays on the last session of This computer or a saved server), and a `--host` launch resumes nothing. With remote hosts on, launch waits for that server's first connect (up to 20 s) and reopens the session there; offline, refused or no longer saved, it lands on the sessions list saying why. With remote hosts off, a server's session is not resumed (the window resumes only its own).
+- **Model picker** on a server session lists the server's credentialed providers and models (`models.list`, `src/tui/model/use-host-model-catalog.ts`): a provider only the server has is pickable, one only this window has is not. A pick there is remembered for the next launch only when this computer is signed in to its provider, without the fallbacks it can't run (`rememberableChain`, the GUI's rule too).
+- **`/` commands** on a server session are the server's (`commands.list` for the session's folder there, `src/tui/prompt/use-host-commands.ts`): completion lists them, argument completion asks the server, and sending one queues it to the server. The window's built-ins (`/help`, `/reload`, …) stay its own.
+- **Transcripts** load a page of turns per reply, from the end, only as far as the window shows (`loadDisplayedTranscript` → `loadEventsTail`, in every mode): pages stop once the display cap (`capTranscriptEvents`) is covered, behind its hidden-count marker, so a long session opens on a few pages, not all of them. No single reply carries a long session; a page refused as too large is asked again at half the turns. Each page is a slice of the host's whole replay (with `start`, its place in it), so the tail is exactly what capping the whole replay shows. An older host's pages say nothing of where they start: those load whole.
+- **Claude Code import** always imports into this computer; on a server session it says so.
+- **Settings** edits the server of the active session: see [Settings modal](#settings-modal). A write the server refuses shows one line under the tabs (`<server> refused <key>: <why>`, `SettingsStatusLine`) until the next change.
+
+Coexistence: the store (`sessions.db`/`state.json`) is neutral ground both hosts read/write; a cross-process run guard (`status: 'running'`, 5-minute freshness bound) stops two processes stacking runs on one session; while a daemon controller is connected the daemon owns `state.json` settings writes. Turning it off always works: `--no-daemon`/`ZIDANE_NO_DAEMON=1` beat the setting, and a daemon connect failure leaves the window reconnecting with a visible notice. Full protocol, lifecycle, and the asymmetries (`!`/the TUI's own `/` commands executing in the issuing window): [IPC.md](./IPC.md).
+
+**Settings sync** (Settings → Hosts → a saved server → `ctrl+s`;
+[SERVER.md § Settings sync](./SERVER.md#settings-sync)): the mode (↵
+cycles Off · Import once · Keep in sync), the categories (↵ toggles), with
+API keys one row per stored key (↵ asks first: it copies the secret), *push
+everything now*, *take over* when another device syncs there (asks first),
+and the server's overrides (↵ resets one); below, the connection, the last
+push, what waits, the last error and what the server skipped or warned
+about. While the modal edits a server synced from a computer, a synced
+setting's row reads `· synced from <device>`, an override's `· edited
+here, not synced (ctrl+r: sync from <device>)`, and `ctrl+r` on it resets
+it. `src/tui/settings/server-sync-page.tsx`, `host-settings-scope.tsx`; the
+engine (`src/chat/sync`) starts with the saved hosts (`remote-hosts.ts`).
 
 ## Embedding
 
@@ -339,9 +380,10 @@ A GUI (or any host whose `process.execPath` is not the package's bin) uses `upgr
 ```
 src/tui/
   index.tsx                     runTui + public exports
-  app.tsx                       App + AppShell + ThemedShell — provider stack + agent lifecycle
-  screens.tsx                   AuthScreen, SessionsScreen, ChatScreen, PromptBlock, ApprovalBlock, QueuedMessagesBlock
-  components.tsx                Transcript, EventLine, MarkdownBlock, SubagentBlock, Footer, Spinner, StatusSpinner, TitleOverlay, EditDiffBlock, NoticeRow, TaskNotificationBlock
+  app.tsx                       App + AppShell + ThemedShell — provider stack; AppShell composes the feature hooks (shell/, host/, …)
+  screens.tsx                   Re-exports AuthScreen, SessionsScreen, ChatScreen, PromptBlock, … from auth/, sessions/, chat/, prompt/, queue/
+  components.tsx                Footer, TitleOverlay; re-exports Transcript, Spinner, StatusSpinner, … from transcript/ and status-spinner.tsx
+  <feature>/                    shell/, host/, sessions/, prompt/, chat/, transcript/, settings/, mcp/, … — each feature's hooks and components together (see ARCHITECTURE.md)
   modal.tsx                     ModalRoot + Modal (+ rightTitle slot) + useModalAwareFocus
   model-picker.tsx              Cross-provider searchable model list modal
   model-options-picker.tsx      Reasoning-effort + feature-toggle modal (ctrl+l) — supersedes effort-picker.tsx in-app
@@ -358,6 +400,15 @@ src/tui/
   extension-hud.tsx             Extension-contributed HUD overlay
   create-extension-modal.tsx    Scaffold-a-new-extension flow
   claude-import-modal.tsx       Import sessions / MCP servers / skills from Claude Code
+  host/host-directory.ts        The window's hosts (This computer, --host, saved servers): transport, client, status; default + active host
+  host/remote-hosts.ts          Saved servers in the directory (loaded only with remote hosts on)
+  sessions/hosted-sessions.ts   The sessions list across hosts (grouping, last known rows of an offline server)
+  settings/hosts-panel.tsx      Settings → Hosts
+  machines/                     A server's machines page (share, use, list), the machine folder step, the online-machines mirror
+  settings/host-settings-scope.tsx  The Settings modal editing a server's settings
+  settings/server-catalog-panel.tsx  A server's Skills / MCP servers / Extensions tabs (catalog.*)
+  model/use-host-model-catalog.ts  The model pickers' providers: the session's server's (models.list)
+  prompt/use-host-commands.ts   A server session's `/` commands (commands.list)
   cwd-picker.tsx                Directory picker (ctrl+h)
   session-details-modal.tsx     Stats + delete / export / title / compact (ctrl+shift+x)
   turn-details-modal.tsx        Fork / delete / copy / edit (opened from select-turn mode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "7.2.4",
+  "version": "8.0.4",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,
@@ -191,6 +191,11 @@
       "import": "./dist/restate.js",
       "default": "./dist/restate.js"
     },
+    "./codemode": {
+      "types": "./dist/codemode.d.ts",
+      "import": "./dist/codemode.js",
+      "default": "./dist/codemode.js"
+    },
     "./chat": {
       "types": "./dist/chat.d.ts",
       "import": "./dist/chat.js",
@@ -221,6 +226,11 @@
       "import": "./dist/ipc.js",
       "default": "./dist/ipc.js"
     },
+    "./ipc/remote": {
+      "types": "./dist/ipc/remote.d.ts",
+      "import": "./dist/ipc/remote.js",
+      "default": "./dist/ipc/remote.js"
+    },
     "./eval": {
       "types": "./dist/eval.d.ts",
       "import": "./dist/eval.js",
@@ -242,6 +252,7 @@
   "workspaces": [
     "tui",
     "tui/npm/*",
+    "server",
     "extensions/*"
   ],
   "engines": {
@@ -257,38 +268,54 @@
     "tui:install:cross": "bun install --cpu='*' --os='*'",
     "tui:build": "bun run scripts/build-executables.ts",
     "tui:build:current": "bun run scripts/build-executables.ts --current",
+    "server": "bun run src/server/main.ts",
+    "server:build": "bun run scripts/build-server.ts",
+    "server:smoke": "bun run server/scripts/smoke-binary.ts",
+    "server:docker": "docker build -f server/Dockerfile -t zidane-server:dev .",
+    "server:smoke:image": "bun run server/scripts/smoke-image.ts",
+    "server:release:package": "bun run scripts/package-server-release.ts",
     "build": "tsdown",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "smoke:package": "bun run scripts/smoke-package-exports.ts",
     "smoke:bundle": "bun run scripts/smoke-bundle-size.ts",
-    "test": "bun test",
-    "test:extensions": "bun test ./extensions",
-    "test:all": "bun test && bun test ./extensions",
+    "test": "bun run scripts/test.ts",
+    "test:extensions": "bun run scripts/test.ts ./extensions",
+    "test:all": "bun run scripts/test.ts && bun run scripts/test.ts ./extensions",
     "typecheck:extensions": "for d in extensions/*/; do tsc --noEmit -p \"$d\" || exit 1; done",
     "test:inference": "cd test-inference && bun test",
     "test:eval": "bun run scripts/eval.ts",
     "bench:memory": "bun run benchmarks/memory/run.ts",
     "evals": "bun run scripts/eval.ts",
+    "evals:codemode": "bun run scripts/eval.ts --setups build,codemode -g vite-todolist-react --repeat 3 --timeout 600000",
     "restate:fixture:up": "docker compose -f test/fixtures/restate-docker/docker-compose.yml up --build -d",
     "restate:fixture:down": "docker compose -f test/fixtures/restate-docker/docker-compose.yml down -v",
     "restate:fixture:service": "PORT=19080 bun run test/fixtures/restate-docker/service.ts",
     "restate:fixture:smoke": "bun run test/fixtures/restate-docker/smoke.ts",
     "restate:fixture:test": "bun run test/fixtures/restate-docker/run.ts",
-    "release": "bumpp package.json tui/package.json tui/npm/*/package.json gui/package.json --execute \"bun install --cpu='*' --os='*'\" --all",
+    "release": "bumpp package.json tui/package.json tui/npm/*/package.json server/package.json gui/package.json --execute \"bun install --cpu='*' --os='*'\" --all",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-ai": "1.0.4",
     "chalk": "^5.6.2",
     "fzf": "^0.5.2",
-    "hookable": "^6.1.1",
+    "hookable": "^6.1.2",
     "marked": "18.0.9"
   },
   "overrides": {
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.3",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "@typescript-eslint/parser": "8.62.1",
+    "@typescript-eslint/scope-manager": "8.62.1",
+    "@typescript-eslint/utils": "8.62.1",
+    "@typescript-eslint/types": "8.62.1",
+    "@typescript-eslint/typescript-estree": "8.62.1",
+    "@typescript-eslint/visitor-keys": "8.62.1",
+    "@typescript-eslint/eslint-plugin": "8.62.1",
+    "@typescript-eslint/type-utils": "8.62.1",
+    "typescript-eslint": "8.62.1"
   },
   "peerDependencies": {
     "@anthropic-ai/bedrock-sdk": ">=0.32.0",
@@ -300,6 +327,7 @@
     "@restatedev/restate-sdk": "^1.11.0",
     "dockerode": "^5.0.0",
     "e2b": "^2.0.0",
+    "quickjs-wasi": "^3.6.2",
     "react": "^18.0.0 || ^19.0.0",
     "tar-stream": "^3.0.0",
     "zod": ">=4.0.0"
@@ -332,6 +360,9 @@
     "e2b": {
       "optional": true
     },
+    "quickjs-wasi": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -343,29 +374,30 @@
     }
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^8.2.0",
+    "@antfu/eslint-config": "^8.3.0",
     "@anthropic-ai/bedrock-sdk": "^0.32.4",
     "@anthropic-ai/sdk": "^0.104.2",
     "@daytona/sdk": "^0.187.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "@opentui/core": "^0.5.3",
-    "@opentui/core-darwin-x64": "^0.5.3",
-    "@opentui/core-linux-arm64": "^0.5.3",
-    "@opentui/core-linux-x64": "^0.5.3",
-    "@opentui/react": "^0.5.3",
-    "@restatedev/restate-sdk": "^1.16.5",
-    "@types/bun": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@opentui/core": "^0.5.16",
+    "@opentui/core-darwin-x64": "^0.5.16",
+    "@opentui/core-linux-arm64": "^0.5.16",
+    "@opentui/core-linux-x64": "^0.5.16",
+    "@opentui/react": "^0.5.16",
+    "@restatedev/restate-sdk": "^1.17.2",
+    "@types/bun": "^1.4.2",
     "@types/dockerode": "^4.0.1",
     "@types/react": "19.2.18",
-    "@types/tar-stream": "^3.1.4",
-    "bumpp": "^11.0.1",
-    "dockerode": "^5.0.0",
-    "e2b": "^2.39.0",
-    "eslint": "^10.8.1",
-    "jiti": "^2.6.1",
-    "react": "^19.2.8",
-    "tar-stream": "^3.2.1",
-    "tsdown": "^0.22.0",
+    "@types/tar-stream": "^3.1.5",
+    "bumpp": "^11.1.0",
+    "dockerode": "^5.0.1",
+    "e2b": "^2.53.1",
+    "eslint": "^10.12.0",
+    "jiti": "^2.7.0",
+    "quickjs-wasi": "3.6.2",
+    "react": "^19.3.0",
+    "tar-stream": "^3.2.2",
+    "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
     "unrun": "^0.3.1"
   }

package/scripts/eval.ts

@@ -9,6 +9,7 @@
  *   bun run test:eval --provider openai --model gpt-5 --filter vite --repeat 3
  *   bun run test:eval --provider all                       # every provider with an API key in env/.env
  *   bun run test:eval --provider baseten --models zai-org/GLM-5.1,moonshotai/Kimi-K2.6
+ *   bun run test:eval --setups build,codemode -g vite-todolist-react --repeat 3   # Build vs Codemode
  *
  * Flags:
  *   --provider <name>        agent provider (anthropic|openai|openrouter|cerebras|arcee|baseten|local).
@@ -26,6 +27,8 @@
  *                            (default path: benchmarks/evals/baseline.json)
  *   --extensions <names>     enable repo extensions for the run, comma-separated
  *                            (e.g. pxpipe,headroom — see benchmarks/evals/_extensions.ts)
+ *   --setups <names>         run every eval once per agent setup and compare them
+ *                            (e.g. build,codemode — see benchmarks/evals/_setups.ts)
  *   --timeout <ms>           per-test timeout (default 180000)
  */
 
@@ -52,6 +55,7 @@ const FLAG_TO_ENV: Record<string, string> = {
   'artifact-dir': 'ZIDANE_EVAL_ARTIFACT_DIR',
   'baseline': 'ZIDANE_EVAL_BASELINE',
   'extensions': 'ZIDANE_EVAL_EXTENSIONS',
+  'setups': 'ZIDANE_EVAL_SETUPS',
 }
 
 /** Flags whose value may be omitted, falling back to a default. */