hop2 0.11.0 → 0.11.2

package/README-MCP.md

@@ -43,7 +43,16 @@ Supported auto-detected clients:
 
 4. Restart your MCP client.
 
+Install the bundled Hop workflow instructions for Claude Code and Codex:
+
+```bash
+hop agent-skill install
+```
+
 The server auto-connects to the local Hop daemon via `~/.hop2/.tunnel-state`.
+Long-lived MCP clients refresh that file automatically when the local daemon
+restarts on a new port. Explicit `connect_server` and `HOP_API_URL` connections
+remain pinned to the configured endpoint.
 
 ## Recommended Flow: One Agent Terminal
 
@@ -85,6 +94,50 @@ Safety notes:
 - Keep one subagent per terminal (no multiplexing multiple agent CLIs in one PTY).
 - For existing user sessions, verify `agentPermitted` (or set with `hop_set_agent_permission`) before writing input.
 
+## Manager Agents: Orchestrating a Fleet
+
+A manager agent (any MCP client — Claude Code, Codex, ...) can run a whole
+fleet of subagent terminals through hop. The loop:
+
+1. **Spawn** — one call per subagent:
+   `hopx_spawn_agent(name="worker-1", cwd="/repo", agent="claude", initial_task="<task>", async=true)`
+   → `{ terminal_id, sessionName, wait_id, completion_contract }`. Hop gives
+   each initial task a unique completion contract automatically.
+2. **Wait for anyone** — block on the whole fleet with one call:
+   `hopx_wait_any(wait_ids=[...], max_wait_ms=60000)` returns the first
+   completed turn(s) and the still-pending set. No round-robin polling.
+   A settled result is successful only when `ok=true` and its completion
+   contract matched; a mismatch is `contract_failed`. A watch whose window
+   merely expired is re-armed under a new wait_id and stays in `pending` (carry
+   those forward to the next call). Two distinct timers: each background job's own
+   wait window defaults to 15 minutes; `max_wait_ms` on the call is only how
+   long that one `hopx_wait_any` invocation blocks (default 30s).
+3. **Read the result** — `hop_read_trajectory(name=<sessionName>)` for the
+   full turn (digest mode is context-safe), or use the slimmed wait result
+   returned by `hopx_wait_any` directly. Follow-up turns should pass
+   `until_reply_regex`; only `reply_matched=true` counts as completion.
+4. **Redispatch** — next task via
+   `hopx_agent_turn(terminal_id=..., data="<task>", async=true)`; collect the
+   new `wait_id` and go back to step 2.
+5. **Check the room** — `hopx_agents_overview()` any time you lose track:
+   who is busy (a live wait job), who is idle, turn counts, and bell counters.
+   Diff `bellSeq`/`turnCount` against your previous call to spot a subagent
+   asking for attention or finishing turns you didn't drive.
+6. **Interrupt / tear down** — `hopx_agent_turn(wait_id=..., control="interrupt")`
+   for a stuck turn; `hop_close_terminal(terminal_id=..., killSession=true)`
+   when a worker is done. Never leave orphaned sessions.
+7. **Survive your own restart** — every async dispatch is recorded in the
+   durable task ledger. If the manager process dies, start fresh and call
+   `hopx_task_ledger`: turns that finished unwatched are reconciled (contract
+   verdicts included), still-pending ones can be re-armed with
+   `hopx_wait_any(terminal_ids=[...])`. Workers commit to their own fleet/
+   branch when using worktree isolation, so no work is ever trapped in a dead
+   manager's memory.
+
+Guardrails (see MULTI-AGENT-CHECKLIST.md): one subagent per terminal, explicit
+deadlines on every wait, never write into a terminal whose overview state is
+`busy`, and gate destructive commands behind user confirmation.
+
 ## Shell Commands: `hopx_exec`
 
 For plain shell work (not interactive TUIs), `hopx_exec` behaves like a Bash
@@ -130,8 +183,15 @@ connect_server(base_url="https://hop2.example.com", token="<token>", verify=true
 
 ## Tools
 
-Core tools (`hop_`): stable atomic operations.
+Naming convention: `hop_` tools are atomic operations — one stable primitive
+each. `hopx_` tools are the convenience/specialized layer composed from those
+atomic operations; anything that orchestrates, joins, or wraps multiple
+primitives lives under `hopx_`.
+
+Connection (the one un-prefixed tool):
 - `connect_server` — connect to a Hop API base_url (optional token); use for remote hop instances
+
+Core tools (`hop_`): stable atomic operations.
 - `hop_server_info` — hop-mcp runtime diagnostics (version, script path, read-mode capabilities)
 - `hop_list_sessions` — list Hop sessions and metadata
 - `hop_list_terminals` — list terminal API sessions (created via `hop_create_terminal` / `hop_attach_terminal`)
@@ -139,11 +199,11 @@ Core tools (`hop_`): stable atomic operations.
 - `hop_attach_terminal` — attach to an existing terminal session by name or internalName
 - `hop_write_terminal` — write raw input to a terminal session
 - `hop_send_key` — send a named keypress (enter, esc, tab, shift_tab, arrows, f1-f12, ctrl+[a-z], ...)
-- `hop_wait_terminal` — wait for output conditions (regex, prompt, idle, agent_done); `async=true` returns a `wait_id`
-- `hop_wait_start` — deprecated legacy alias for `hop_wait_terminal(async=true)`
+- `hop_wait_terminal` — wait for output conditions (regex, prompt, idle, agent_done); `async=true` returns a `wait_id` (`hop_wait_start` was removed; use `hop_wait_terminal(async=true)`)
 - `hop_wait_poll` — poll or await completion of a background wait job
 - `hop_resize_terminal` — resize the terminal PTY
 - `hop_read_terminal` — read terminal output events (default `mode="readable_raw"`); returns a cursor for incremental reads
+- `hop_read_trajectory` — read a Claude Code session's real conversation history from its on-disk transcript (resolved from the hop session name via the SessionStart hook record); context-safe reduced `digest` mode by default, plus `summary`/`list`/`get`/`tail` modes; gated by the per-session agent permission (`hop_set_agent_permission`) and requires the transcript on the same host as the MCP
 - `hop_close_terminal` — detach the terminal API session; optionally kill the underlying hop session
 - `hop_set_agent_permission` — allow or block agent access for a session
 - `hop_list_workspaces` — list available workspaces
@@ -156,7 +216,21 @@ Core tools (`hop_`): stable atomic operations.
 Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 - `hopx_send_and_wait` — single-call send + wait wrapper
 - `hopx_exec` — Bash-tool-style shell execution: command in, clean stdout + `exit_code` out (see section above)
-- `hopx_agent_turn` — single-turn send + wait + mode-aware output, default `mode="auto"`
+- `hopx_agent_turn` — single-turn send + wait + mode-aware output, default `mode="auto"`; optional `until_reply_regex` is a completion contract, and a mismatch returns `contract_failed`
+- `hopx_capture_scrollback` — capture an alternate-screen TUI's scrollback the way a user would: scroll up page-by-page, snapshot each frame, and stitch newly-revealed rows together (live view restored afterward by default); best-effort and lossy for wrapped/redrawn content; requires agent permission on the session
+- `hopx_agents_overview` — fleet status in one call: every agent-created/agent-permitted session with state (running/busy/idle), cwd, foreground program, Claude turn count, bell counters, last activity, and pending wait jobs; `include_user_sessions=false` narrows to agent-created only, `include_ports=true` adds proxy sessions
+- `hopx_wait_any` — race several background waits (wait_ids and/or terminal_ids, auto-starting `until_agent_done` waits); returns the first real completion(s) plus the still-pending set; expired watches are re-armed automatically (new wait_id in `pending`) rather than reported as completions
+- `hopx_spawn_agent` — one-call subagent bring-up: create terminal + launch agent CLI (claude/codex/gemini/custom) + wait until ready + optionally run a first task with an automatic completion contract; `isolation="worktree"` gives the worker its own git worktree + fleet/ branch for overlapping-file fleets
+  - the Claude preset uses the `sonnet` model alias and `bypassPermissions` mode by default, and removes inherited Claude Code process credentials before launch, so a delegated worker uses the host's durable `claude auth login` without parking on approval prompts; pass `permission_mode="manual"` for a restricted worker, `args="--model ..."` to choose another model, or an explicit `command` when inherited credentials are intentional
+  - the Codex preset runs autonomously and bypasses workspace-trust, approval, and self-update startup gates; Hop rejects detected login, trust, or update screens instead of dispatching a task into them
+  - MCP and `hopa spawn --task` wait by default and return the transcript-backed `assistant_reply`; `async=true` is for fleet dispatch through a long-lived MCP connection, while the short-lived `hopa` CLI rejects async waits
+- `hopx_task_ledger` — the durable orchestration ledger (~/.hop2/orchestration): async dispatches with contracts survive manager/MCP restarts; pending entries reconcile lazily from turn counters + transcripts; acknowledge to consume
+
+### Reading terminal history
+
+- `hop_read_terminal` — recent and incremental output; the day-to-day read primitive (cursor-based deltas).
+- `hop_read_trajectory` — a Claude Code session's full conversation history from its transcript; prefer it when a transcript is available (the default `digest` mode is context-safe and shows far more than the terminal frame).
+- `hopx_capture_scrollback` — scrollback of non-Claude TUIs, or when no transcript file is reachable; best-effort and lossy for wrapped/redrawn content.
 
 ## Resources
 
@@ -227,11 +301,15 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
 
 - For long-running conditions, start a background wait with `hop_wait_terminal(terminal_id=<id>, async=true, ...)` (returns `wait_id` immediately) and poll with `hop_wait_poll(wait_id=..., wait=true)`
   - use `consume=true` on poll to remove completed jobs
-- `hop_wait_start` is a deprecated legacy alias for `hop_wait_terminal(async=true)`; prefer the latter
+  - use `cancel=true` on poll to abort a still-running wait and reclaim it
+  - async jobs default to a 15-minute wait window when `max_wait_ms` is not given (synchronous waits default to 30s)
+- `hop_wait_start` was removed; use `hop_wait_terminal(async=true)`
 
 ### `hopx_send_and_wait`
 
 - `hopx_send_and_wait` combines input send + optional enter/key + wait, and defaults to cursor-based delta capture from just before send.
+  - gotcha: `press_enter` defaults to **false** here but **true** on `hopx_agent_turn` (when data is provided) — sending text without `press_enter=true` types it but never submits it
+  - `clean_text=true` strips ANSI escape codes from captured output (also available on `hopx_agent_turn`)
   - helper defaults are token-thrifty for interactive loops: `capture_max_events=60`, `control_level=none`, `noise_filter=balanced`, `coalesce_ms=350` (unless overridden)
   - for `capture="readable_raw"`, `text_only` defaults to `true`; this condenses wait payloads by returning joined `wait.text`, setting `wait.events=[]`, `wait.eventCount=0`, and preserving prior count in `wait.originalEventCount` (set `text_only=false` to keep full events)
 - `hop_read_terminal` supports deterministic delta reads:
@@ -245,6 +323,7 @@ Helper tools (`hopx_`): convenience wrappers built on top of core tools.
   - in `mode="auto"`, if alternate-screen starts during the same turn, it auto-promotes to `ui` for that response
   - wait-only continuation is supported: omit `data`/`message` and use `control="wait"` to keep waiting on a terminal without sending new input
   - `async=true` starts the turn wait in the background and returns `wait_id` immediately; continue polling or controlling that turn with `hopx_agent_turn(wait_id=..., wait=true|false, control=...)`
+  - `until_reply_regex` is a completion contract; a finished turn that does not match returns `status="contract_failed"`, `ok=false`, and a tool error
   - `control="interrupt"` / `control="terminate"` send an explicit interrupt key (default `esc`); `terminate_message` can send a final follow-up after the interrupt
   - `mode="ui"` returns a UI snapshot payload after wait
   - for readable modes, `text_only` defaults to `true` and condenses waits the same way as `hopx_send_and_wait` (set `text_only=false` to keep full wait events)

package/README.md

@@ -12,6 +12,10 @@ Hop gives you secure browser access to local terminals and a built-in MCP server
            o_(")(")
 ```
 
+<p align="center">
+  <img src="docs/hero-overview.svg" width="980" alt="One hop runtime, three surfaces: a browser window, an MCP agent panel, and a CLI window all attached to the same live terminal session. Web sharing with presence and take/release control; MCP agents that create, drive, and read sessions; and a CLI that attaches from any terminal." />
+</p>
+
 ## Why Hop
 
 - **Browser terminal from anywhere** — Tunnel through Cloudflare with no port forwarding
@@ -31,6 +35,14 @@ Most users only need the npm install. Source install is mainly for development o
 npm install -g hop2
 ```
 
+That installs the **nightly** — a build from the latest green `main`, which
+is usually what you want here since almost every commit is a fix. To hold
+still on a version that was deliberately cut and used:
+
+```bash
+npm install -g hop2@stable
+```
+
 This installs:
 - `hop` — main CLI / daemon / browser terminal entrypoint
 - `hop-mcp` — MCP server exposing Hop terminals and sessions
@@ -80,6 +92,10 @@ source ~/.zshrc
 hop
 ```
 
+`hop` is safe to put at the end of your shell rc (`~/.zshrc`): it only launches
+for interactive terminals — non-interactive shells (`ssh host <cmd>`, scp/rsync,
+scripts, cron) and shells already inside a hop session are silently unaffected.
+
 First run:
 1. Optionally set a password with `hop password set`
 2. Scan the authenticator QR code
@@ -93,9 +109,10 @@ Then open the URL from another device, sign in, and pick or create a session.
 ```bash
 hop
 hop-mcp-setup
+hop agent-skill install
 ```
 
-Then restart your MCP client. `hop-mcp-setup` auto-detects and configures supported clients such as Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex CLI, VS Code / Copilot, and Antigravity.
+Then restart your MCP client. `hop-mcp-setup` auto-detects and configures supported clients such as Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex CLI, VS Code / Copilot, and Antigravity. `hop agent-skill install` installs Hop's bundled orchestration instructions for Claude Code and Codex.
 
 Typical use cases:
 - Launch a dedicated Claude Code / Codex / Gemini terminal and drive it over multiple turns
@@ -140,7 +157,7 @@ Use one dedicated terminal per subagent.
 2. Start the agent CLI with `hop_write_terminal`.
 3. Wait for readiness with `hop_wait_terminal(until_prompt=true)`.
 4. Prefer `hopx_agent_turn(mode="auto")` or `hopx_send_and_wait(...)` for one turn at a time.
-5. For long waits, use `hopx_agent_turn(async=true, ...)` or the lower-level `hop_wait_terminal(async=true, ...)` + `hop_wait_poll(...)` (`hop_wait_start` remains only as a legacy alias).
+5. For long waits, use `hopx_agent_turn(async=true, ...)` or the lower-level `hop_wait_terminal(async=true, ...)` + `hop_wait_poll(...)` (`hop_wait_start` was removed; use `hop_wait_terminal(async=true)`).
 6. Interrupt with `hop_send_key(key="ctrl_c")` and close with `hop_close_terminal`.
 
 Safety tips:
@@ -172,7 +189,13 @@ hop attach <session>
 ```
 
 This is useful when you want a browser, an MCP client, and a local shell to converge on the same named session.
-Local terminal sessions are persistent by default: they keep running in the Hay host if the local CLI detaches or the Hop daemon restarts. The local CLI status line shows `persists`; use `Ctrl+Q` inside the local Hop view to kill the session.
+Local terminal sessions are persistent by default: they keep running in the Hay host if the local CLI detaches or the Hop daemon restarts. Press `Ctrl+Q` twice inside the local Hop view to kill a session for everyone; `Ctrl+G` detaches and leaves it running.
+
+The attached-terminal UI adapts light/dark themes to your terminal and puts the session state at a glance:
+
+<p align="center">
+  <img src="docs/hero.svg" width="980" alt="The hop terminal UI, annotated: a session chip pinned flush-left, a live state dot (green connected, amber reconnecting, red dropped, purple locked), a scrollback position indicator, keycap-style hints, adaptive light/dark themes, and scrollback search with toast notices." />
+</p>
 
 ### Use Hop on Mobile
 
@@ -180,9 +203,37 @@ Hop’s mobile UI includes:
 
 - a terminal-oriented accessory row with `Esc`, `Tab`, `Ctrl`, `Alt`, and arrows
 - a native keyboard button for dictation, spellcheck, and autocomplete
-- a floating menu for keyboard toggle and session switching
+- a floating menu for keyboard toggle and session switching; the switcher starts with user sessions and can toggle to agent sessions or all sessions
 - draggable controls designed for one-handed use
 
+### Restore Sessions (incl. Claude Code)
+
+A restart kills the underlying processes, but hop can rebuild your sessions and — for Claude Code — resume each conversation where it left off.
+
+```bash
+hop claude-hook install   # one-time: lets hop track each session's Claude conversation
+hop restore               # recreate saved sessions; claude ones resume their own conversation
+hop restore --dry-run     # preview what would be restored
+```
+
+How it works: every hop terminal gets a `HOP_SESSION` env var; a Claude Code `SessionStart` hop hook records which conversation is running in each session. On `hop restore`, each session is reopened in its original directory and claude sessions relaunch with `claude --resume <id>` — so even multiple Claude sessions in the *same* directory each come back to their own conversation. Plain-shell sessions reopen a shell in their last directory and replay their last screen: on a graceful shutdown hop saves each session's recent output and, on restore, paints it back above a dim `──── session restored ────` separator before the fresh prompt — so you keep the context even though the old process is gone. `hop status` shows how many sessions can be restored.
+
+`hop claude-hook install` adds a `SessionStart` entry to `~/.claude/settings.json` (backed up first); `hop claude-hook remove` reverts it. The hook is a no-op outside hop terminals.
+
+### Render LaTeX math (`hop math`)
+
+Glance at a formula without leaving the terminal:
+
+```bash
+hop math 'e^{i\pi} + 1 = 0'
+hop math '\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}'
+echo '\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}' | hop math
+```
+
+Agents working inside hop terminals can render formulas for the humans watching by invoking the command themselves — install the bundled skills with `hop agent-skill install` so Claude and Codex sessions know to do this (plus ring the bell when blocked, and keep output phone-friendly).
+
+`hop math` renders a **2D Unicode layout** — fractions, roots, sums/limits, sub/superscripts, Greek + operators, and accents — with no dependencies. Inline-image rendering (Kitty/iTerm) is deferred until graphics support lands in the web client (xterm.js): the real payoff is math that renders *inside* a shared hop session, which the re-rendering clients can't show yet, so until then it's Unicode everywhere.
+
 ## Operations
 
 ### Logging and History

package/demo/README.md

@@ -10,6 +10,7 @@ Small reusable pieces for recording real Hop browser footage and driving real Ho
 - `static-preview-server.mjs` serves the sanitized demo workspace for preview clips
 - `stitch-demo-video.mjs` concatenates recorded WebM clips into one rough MP4
 - `hop-demo-lib.mjs` holds the shared state, auth, browser, and API helpers
+- `capture/` holds the sanitized product-video capture rig (see [Capture Rig](#capture-rig-democapture) below)
 
 The harness uses the local Hop daemon port from `~/.hop2/.tunnel-state` and injects the Hop session cookie directly into Playwright. That avoids interactive login during capture while still exercising the real Hop UI.
 
@@ -97,6 +98,57 @@ PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/stitch-demo-video.mjs \
 5. Record a mobile view of the same session
 6. Stitch the clips with `ffmpeg`
 
+## Capture Rig (`demo/capture/`)
+
+The capture rig records the sanitized, dark-theme live-footage clips used in the Hop product video. It drives the real Hop UI in headless Chrome with two sanitization layers installed before first paint: `/api/sessions` responses are filtered down to the demo session cast, and a document-start MutationObserver rewrites the internal session names (`Aurora2` → `Aurora`, `Lyra2` → `Lyra`, …) in every text node and attribute. Before the kept portion of each clip it asserts a genuinely dark rendered frame (ffmpeg signalstats) and that no identity strings (account email banner, home directory, username) are visible; it aborts rather than save a bad take. Recording starts at page open and the setup head is trimmed off with ffmpeg on save.
+
+### Files
+
+- `capture/capture.mjs` — the clip driver. `node demo/capture/capture.mjs <clip>` with `<clip>` one of `01-sessions`, `02-agent-live`, `02b-desktop-terminal`, `03-phone-live`, `04-phone-switcher`, `05-presence`, `06-math`, `07-theme`
+- `capture/setup-sessions.mjs` — creates the sanitized shell cast (`Lyra2`, `Nebula2`, `Polaris2`) with a clean `env -i` bash, wiped scrollback, and live ticker output, and seeds the demo workspace tree
+- `capture/setup-04.mjs` — recreates all four demo sessions phone-fit (46x40) for the `04-phone-switcher` clip, with a scripted agent-lookalike ticker in `Aurora2` instead of a real agent
+- `capture/spawn-aurora.mjs` — spawns a real coding agent (default `claude`, override with `HOP_CAPTURE_AGENT`) in session `Aurora2` via the Hop MCP server
+- `capture/dispatch-task.mjs` — sends a narration task to the `Aurora2` agent and waits until the identity banner has scrolled off the visible screen
+- `capture/capture-env.mjs` — shared configuration: paths, env overrides, the demo cast, forbidden identity strings, and `terminals.json` helpers
+- `capture/mcp-client.mjs` — minimal stdio MCP client for `mcp/hop-mcp.js`
+- `capture/native-css.mjs` — document-start CSS that hides all web chrome for the `02b-desktop-terminal` "native terminal" clip
+- `capture/tools/*.sh` — endless sanitized ticker scripts (build, metrics, agent-lookalike) that keep switcher preview cards alive
+
+### Prerequisites
+
+Same as above (running Hop daemon, Google Chrome, vendored Playwright, Homebrew Node), plus `ffmpeg` and — for the live-agent clips — a `claude`-style agent CLI on `PATH`.
+
+### Configuration
+
+Everything machine-specific is an env override with a macOS default (see `capture/capture-env.mjs`):
+
+- `HOP_HOME` — hop state directory (default `~/.hop2`)
+- `HOP_CAPTURE_ROOT` — sanitized demo tree: workspace, ticker scripts, fake `$HOME`, raw recordings, `terminals.json` (default `/tmp/hop-demo`)
+- `HOP_CAPTURE_OUT` — where finished clips land (default `demo-output/footage/live` in the repo)
+- `HOP_CAPTURE_CHROME`, `HOP_CAPTURE_FFMPEG` — binary paths
+- `HOP_CAPTURE_AGENT` — command launched in `Aurora2` by `spawn-aurora.mjs` (default `claude`)
+- `HOP_CAPTURE_FORBIDDEN` — extra comma-separated strings that must never appear in a kept frame, on top of the built-in home-directory/username/welcome-banner checks
+
+### Typical run
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/setup-sessions.mjs
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/spawn-aurora.mjs
+
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 01-sessions
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 02-agent-live
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 03-phone-live
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 05-presence
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 06-math
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 07-theme
+
+# Clip 04 uses its own phone-fit session setup:
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/setup-04.mjs
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/capture/capture.mjs 04-phone-switcher
+```
+
+Notes on ordering: `02b-desktop-terminal` must run against an agent session whose welcome banner has already scrolled off — dispatch a first narration turn with `dispatch-task.mjs` (or run `02-agent-live` first). A clip that would show a leak, a light frame, or a finished/static screen aborts with `ABORT`/`RESHOOT` instead of saving; rerun it. Rerunning `setup-sessions.mjs` after `setup-04.mjs` restores the desktop-width cast, but `Aurora2` needs `spawn-aurora.mjs` again since `setup-04.mjs` replaces the real agent with a ticker.
+
 ## Notes
 
 - The current scripts are intentionally small. The new `director.mjs` is still a thin orchestrator, not a large demo framework.

package/demo/capture/capture-env.mjs

@@ -0,0 +1,108 @@
+// Shared configuration for the capture rig (demo/capture/*). Every
+// machine-specific value lives here as an env override with a macOS default,
+// so the individual scripts stay free of hardcoded paths and identities.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { prepareSanitizedWorkspace } from "../hop-demo-lib.mjs";
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+export const REPO_ROOT = path.resolve(HERE, "../..");
+
+export const CHROME =
+  process.env.HOP_CAPTURE_CHROME ||
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+export const FFMPEG = process.env.HOP_CAPTURE_FFMPEG || "/opt/homebrew/bin/ffmpeg";
+
+// Root of the sanitized demo tree: workspace/ (session cwd), tools/ (ticker
+// scripts), home/ (fake $HOME for the sanitized shells), video/ (raw
+// Playwright recordings before trim), terminals.json (session registry).
+export const DEMO_ROOT = process.env.HOP_CAPTURE_ROOT || "/tmp/hop-demo";
+export const WORKSPACE = path.join(DEMO_ROOT, "workspace");
+export const TOOLS_DIR = path.join(DEMO_ROOT, "tools");
+export const DEMO_HOME = path.join(DEMO_ROOT, "home");
+export const VID_TMP = path.join(DEMO_ROOT, "video");
+export const TERMINALS_PATH = path.join(DEMO_ROOT, "terminals.json");
+
+// Where finished clips land.
+export const OUT =
+  process.env.HOP_CAPTURE_OUT || path.join(REPO_ROOT, "demo-output", "footage", "live");
+
+// Command launched inside Aurora2 by spawn-aurora.mjs.
+export const AGENT_CMD = process.env.HOP_CAPTURE_AGENT || "claude";
+
+// Demo cast, by INTERNAL session name. The capture driver's DOM rewriter
+// shows the display names (Aurora/Lyra/Nebula/Polaris); Vega appears via the
+// 01-sessions rename clip.
+export const ALLOWED = ["Aurora2", "Lyra2", "Nebula2", "Polaris2", "Vega"];
+
+// Strings that must NEVER be visible in a kept frame (identity leaks). The
+// defaults cover the account-email welcome banner plus the real home
+// directory and username; add more with HOP_CAPTURE_FORBIDDEN="a,b,c".
+export const SCREEN_FORBIDDEN = [
+  "Welcome back",
+  os.homedir(),
+  os.userInfo().username,
+  ...(process.env.HOP_CAPTURE_FORBIDDEN || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+];
+
+// Deterministic clean shell for demo sessions: env -i wipes the real
+// environment, --norc/--noprofile skip dotfiles, PS1 is the demo prompt.
+export const sanitizedShell = (prompt = "demo@hop workspace $ ") =>
+  `exec env -i HOME=${DEMO_HOME} USER=demo LOGNAME=demo TERM=xterm-256color ` +
+  "LANG=en_US.UTF-8 PATH=/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin " +
+  `PS1='${prompt}' /bin/bash --norc --noprofile`;
+
+// Wipe screen AND scrollback (removes the real zsh prompt from history).
+export const WIPE = "printf '\\033[2J\\033[3J\\033[H'";
+
+export function loadTerminals({ required = true } = {}) {
+  if (!fs.existsSync(TERMINALS_PATH)) {
+    if (!required) return {};
+    throw new Error(
+      `${TERMINALS_PATH} not found — run setup-sessions.mjs (and spawn-aurora.mjs) first`
+    );
+  }
+  return JSON.parse(fs.readFileSync(TERMINALS_PATH, "utf8"));
+}
+
+export function saveTerminals(map) {
+  fs.mkdirSync(DEMO_ROOT, { recursive: true });
+  fs.writeFileSync(TERMINALS_PATH, JSON.stringify(map, null, 2));
+}
+
+// Seed the sanitized demo tree: the workspace files the agent tours, the
+// ticker scripts the shell sessions run, the fake HOME, and the `hop math`
+// wrapper used by clip 06. Idempotent; never overwrites existing workspace
+// content except the rig-owned tools and wrapper.
+export function seedDemoTree() {
+  fs.mkdirSync(DEMO_HOME, { recursive: true });
+  fs.mkdirSync(TOOLS_DIR, { recursive: true });
+  prepareSanitizedWorkspace(WORKSPACE, { reset: false });
+  for (const f of fs.readdirSync(path.join(HERE, "tools"))) {
+    fs.copyFileSync(path.join(HERE, "tools", f), path.join(TOOLS_DIR, f));
+  }
+  const wsScripts = path.join(WORKSPACE, "scripts");
+  fs.mkdirSync(wsScripts, { recursive: true });
+  fs.copyFileSync(
+    path.join(REPO_ROOT, "scripts", "hop-math.js"),
+    path.join(wsScripts, "hop-math.js")
+  );
+  const hopWrapper = path.join(WORKSPACE, "hop");
+  fs.writeFileSync(
+    hopWrapper,
+    `#!/usr/bin/env node
+// hop (demo workspace copy) — \`hop math\` entry point.
+if (process.argv[2] === 'math') {
+  const { runMathCli } = require('./scripts/hop-math.js');
+  process.exit(runMathCli(process.argv.slice(3)));
+}
+console.error('hop (demo): only \`hop math\` is available in this workspace');
+process.exit(1);
+`
+  );
+  fs.chmodSync(hopWrapper, 0o755);
+}