@turmind/halo 2.0.8 → 2.1.1

package/bundled-docs/design/ws.md

@@ -25,7 +25,7 @@ Two OS/browser signals supplement the timer:
 
 **Auth expiry**: when the WS handshake itself is rejected (close before `onopen` — `verifyClient` returns 401 on an expired JWT cookie, but the browser WS API hides the HTTP status), the client probes `/api/auth/check`. On 401 it stops reconnecting and emits `_auth_expired`; the admin page listens and swaps to the login screen. Any other probe outcome (server restarting, network blip) falls through to normal backoff.
 
-After a successful `_connected` event, session-resume messages are re-issued: `subscribe` (chat / agent state — sent by **use-websocket.ts only**, and only for the **chat tab on screen**: `releaseBackgroundTabs()` in `chat-tabs.ts` drops every background tab's store, keeping only its header, and returns the active tab's session, `''` for a draft; a released tab subscribes again when it is next shown. The `_connected` subscribe is skipped while `useChatTabs.projectId` is not yet the active project — `restoreTabs` subscribes once it runs, and it is also the only subscriber on a workspace switch. A second subscribe on reconnect would consume the detached-session reattach and then re-run the normal path over it) and `terminal:reattach` (PTY pool, terminal-panel.tsx).
+After a successful `_connected` event, session-resume messages are re-issued: `subscribe` (chat / agent state — sent by **use-websocket.ts only**, and only for the **chat tab on screen**: `releaseBackgroundTabs()` in `chat-tabs.ts` drops every background tab's store, keeping only its header, and returns the active tab's session, `''` for a draft; a released tab subscribes again when it is next shown. The `_connected` subscribe is skipped while `useChatTabs.projectId` is not yet the active project — `restoreTabs` subscribes once it runs, and it is also the only subscriber on a workspace switch. A second subscribe on reconnect would consume the detached-session reattach and then re-run the normal path over it) and `terminal:reattach` (terminal-panel.tsx: re-attaches every PTY of the workspace — a snapshot each, then live output — and re-subscribes to PTYs other pages start there).
 
 ### Abandoned-listener reclaim and the `__ping__` contract
 
@@ -68,11 +68,11 @@ Both directions are typed in `packages/core/src/protocol/ws-frames.ts` (`WsClien
 | `session:delete` | Delete session files + cascade-delete descendants in SQLite (handled inline), then release this connection's listener for it (no save — the session is gone) |
 | `exchange:delete` | Delete one exchange (a user turn + its responses): **soft-delete** in the UI log (`deleted: true` markers, kept visible/greyed) + **physical-delete** the turn's copy from `rawMessages` (LLM context; located by the row's `stamp` — a row from before stamps by its text, among old rows and turns only) → `deleteExchange`. Fields: `userOrdinal` (0-based index among *main-conversation* user turns, i.e. excluding `taskId` sub-agent messages — matches the admin's `isMainConversationMessage` count), `archiveCount` (the archived-segment count the client's view was opened against — its archive anchor, from the `state:snapshot` it got on subscribe), optional `sessionId` / `projectId`. Rejected (→ `error`) while the session is running or compacting. The server also compares `archiveCount` against the archive segments on disk (`countArchiveSegments`); only a **mismatch** is refused, with `code: 'archived'` ("… archived history since it was opened — reopen it to delete individual turns") — a session with archives can still be deleted from as long as the anchor matches. A turn after the last compaction whose raw copy can't be located (a stamped row whose block raw doesn't hold — never a text fallback; an unstamped row merged with others, or its text not found), a stamp shared by two rows or two raw blocks, or a summary row is refused with `code: 'raw_unmatched'`, nothing changed. See [session.md](session.md#exchange-deletion-soft-ui--hard-raw). |
 | `command:<name>` | Route through shared `dispatchCommand` (see [command.md](command.md)); `/session compact` handled inline for UI callbacks |
-| `terminal:start` | Spawn a new PTY |
-| `terminal:input` | Send keystrokes. `terminalId` is **required** — an id-less frame is logged and dropped (it used to fall back to the first entry of the process-global terminal map, which with several admin connections open could write into another browser's PTY) |
-| `terminal:resize` | Resize terminal. `terminalId` required, same rejection as `terminal:input` |
-| `terminal:close` | Kill the PTY |
-| `terminal:reattach` | Re-attach every detached terminal after reconnect |
+| `terminal:start` | Spawn a new PTY in `workspacePath`, named `name` (the tab name every page shows); pushed to the workspace's other subscribers as `terminal:opened` |
+| `terminal:input` | Send keystrokes; the sender becomes the PTY's size driver (PTY switches to the size it last reported). `terminalId` is **required** — an id-less frame is logged and dropped (it used to fall back to the first entry of the process-global terminal map, which could write into a PTY of another workspace) |
+| `terminal:resize` | Report this page's size; applied when the sender is the driver or no driver is attached, otherwise only recorded. `terminalId` required, same rejection as `terminal:input` |
+| `terminal:close` | Kill the PTY — every attached page gets `terminal:exit` |
+| `terminal:reattach` | `{workspacePath}` — attach to every PTY of that workspace (any browser / device: no per-browser owner) and subscribe to the workspace |
 
 `session:clear` (and its `session:cleared` reply) was removed in 1.5.3-alpha. "Start fresh" (`/session new`, `/clear`, "+ New Session", the Agents tab's Test button) now opens a **draft tab** on the client (`newTab` in `chat-tabs.ts`) and sends nothing. The previous session stays subscribed in its own tab. A draft gets its session id on its first `chat` or `command:*`, which the server's `bindOrCreateSession` creates and subscribes.
 
@@ -133,7 +133,7 @@ Server-internal flags on `AgentSessionEvent` that are **not** carried into the W
 | `listener:released` | `reclaimIfAbandoned` (this client only) | One of this connection's event listeners was reclaimed (silent >3 min / CLOSED) — `{sessionId}` (never null), one frame per released session. Client must re-`subscribe` to reattach; the admin does so only for the tab on screen. See [Abandoned-listener reclaim](#abandoned-listener-reclaim-and-the-__ping__-contract). |
 | `chat:queued` | `handleChat` while the session is compacting | User-message-queued notification — `{reason, message, sessionId}` |
 | `file:changed` | WorkspaceWatcher · GitDirWatcher · `routes/git.ts` | File change notification (path + action). Three sources: (1) **WorkspaceWatcher** — recursive workspace watch, deliberately excludes `.git`, one per workspace root shared across connections (`ws/watcher-pool.ts`); (2) **`routes/git.ts`** — every git mutation route re-broadcasts `path:'.git'` itself (the recursive watcher ignores `.git`), via `broadcastToWorkspace` so only clients bound to that workspace are woken (a git write in A used to make every tab showing B refetch status + ignored + log); (3) **GitDirWatcher** — a non-recursive `.git`-dir watch for command-line git ops, *plus* a degraded "watch the workspace root for `.git` appearing" phase that fires `path:'.git'` on a terminal `git init`/`clone` so the Source Control entry auto-surfaces. See [source-control.md](../requirements/source-control.md#auto-refresh-no-polling). |
-| `terminal:ready` / `terminal:output` / `terminal:exit` / `terminal:reattached` | TerminalManager | PTY output |
+| `terminal:ready` / `terminal:output` / `terminal:exit` / `terminal:reattached` / `terminal:opened` / `terminal:snapshot` | TerminalManager | PTY output / exit to every attached page; `reattached {terminals:[{id,name}]}` answers `terminal:reattach`; `opened {terminalId,name}` pushes a PTY another page started in a subscribed workspace; `snapshot {terminalId,data,cols,rows}` is the serialized headless mirror sent on each attach, joined to the live stream with nothing lost or repeated. See [requirements/terminal.md](../requirements/terminal.md#shared-persistent-terminals) |
 | `session:changed` | `SessionManager` (broadcast to all clients) | Root session list changed — re-fetch. Fires on root-session create *and* on each root turn `complete` (so channel-driven messages refresh the count/title/ordering, not just admin's own turns). |
 | `session:switched` | handler.ts (this client only) | The server added a session to this connection's subscription set after a command `switchTo` or a goal-mode divert — `{sessionId, fromSessionId?, clientMsgId?}`. See [switchTo & `session:switched`](#switchto--sessionswitched) |
 | `goal:changed` | `writeGoalState` (`agents/goal-mode.ts`, broadcast to all clients) | Retained legacy event: `{goalSessionId, workerSessionId, status, round, maxRounds}`, no workspace marker. Emitted on goal state writes for existing goal bindings, unchanged. |
@@ -147,6 +147,7 @@ Server-internal flags on `AgentSessionEvent` that are **not** carried into the W
 | `skills:changed` | `ws/skills-changed.ts` `notifySkillsChanged` (REST `POST` / `DELETE /skills`, `PATCH /skills/:id/toggle`, `/skill disable` · `enable` · `delete`) · `ws/watcher-pool.ts` (the workspace watcher saw `.halo/skills/**` change) | A skill was created / deleted / toggled, or a workspace skill folder changed on disk (an agent's `file_write`, a hand edit). No payload: the admin bumps its skill bus, and the chat slash-command popup, the Skills page and the agent form's skill picker re-fetch. Scoped on the server: a workspace skill or a toggle (the disable flag lives in that workspace's db) goes via `broadcastToWorkspace`, a global skill via `broadcast`. Only real changes emit: a no-op mutation (409 / 404 / already disabled) sends nothing, and the watcher path compares a per-workspace key (folder ids + each SKILL.md's frontmatter), so body / resource edits and the echo of a mutation that already notified stay silent. The watcher debounce is 300 ms on top of the file watcher's own 300 ms flush. `~/.halo/global/skills/` has no watcher, so a hand edit there shows on the Skills page's window-focus refetch. Also bumped on WS reconnect while the Skills page is open. |
 | `extension:changed` | `extensions/watcher.ts` `rescanAndBroadcast` (broadcast to all clients) | `~/.halo/global/extensions/` changed (install / upgrade / uninstall / on-off switch, from the admin upload, the one-click update, the `extension` skill, or a manual `mv`/`rm`; a switch rewrites `.state.json`, which trips the same watcher) — carries the **full** `ExtensionsSnapshot` (`{extensions, disabled, errors}`: switched on, switched off, refused), not a diff, and only fires when the snapshot key differs from the last one. The admin replaces its extension list wholesale (a missing `disabled`, from an older server, reads as `[]`): the preview registry re-resolves open tabs from `extensions` only (an upgraded extension remounts, or shows a banner if the tab is dirty; an uninstalled or switched-off one falls back to the "no built-in preview" page, or keeps a dirty tab alive with a banner) and the Settings → Extensions panel re-renders. Global, no workspace marker — extensions are server-wide. See [canvas-extensions.md](canvas-extensions.md). |
 | `updates:changed` | `updates/core-check.ts` · `updates/extension-check.ts` (broadcast to all clients) | An update check finished, or (extensions scope) a watcher rescan changed a cached verdict — `{scope: 'core' \| 'extensions', status}`, `status` = the same `CoreUpdateStatus` / `ExtensionsUpdateStatus` that `GET /api/updates?scope=…` returns. Checks start only from that GET (cache ≥ 24 h old) or `POST /api/updates/check`, never on a timer. The Settings sidebar foot (`core`) and Settings → Extensions (`extensions`) replace their status with it; nothing else listens. Global, no workspace marker. See [canvas-extensions.md → Updates](canvas-extensions.md#updates-updatejson). |
+| `nodes:changed` | `nodes/hub.ts` `announce` (broadcast to all clients) | A `halo node` connected or disconnected — carries the **full** list of online machines, `{online: [{accountId, root, shell, os, since}]}` (`root: null` = whole-machine mode), not a diff. The admin's Channels → Linked machines page replaces its online map wholesale and re-fetches the account list on WS reconnect. Global, no workspace marker (the channels page is a global view). See [node.md](node.md). |
 
 ### `error` frames: optional `code`
 

package/bundled-docs/dev/api.md

@@ -338,6 +338,26 @@ SSE responses (`/api/web/chat`, `/api/web/subscribe`) carry an SSE comment line
 
 See [design/web.md](../design/web.md).
 
+## Linked machines (`halo node`)
+
+File: `packages/server/src/nodes/routes.ts` (+ `hub.ts` for the WebSocket). Not mounted in AgentCore mode. Design: [design/node.md](../design/node.md).
+
+### Admin endpoints (cookie auth)
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/nodes/accounts` | All machine tokens → `{accounts: [{accountId, name, workspacePath, workspaceMissing, token, createdAt, online: {root \| null, shell, os, since} \| null}]}` (`root: null` = whole-machine mode) |
+| POST | `/api/nodes/accounts` | Create. Body `{workspacePath, name}` (`name` = `^[a-z0-9][a-z0-9-]{0,31}$`) → `{accountId, token, name, workspacePath}`. 400 bad name / workspace (must be an absolute path that exists; `.halo/` is created if missing), 409 name already used in that workspace |
+| DELETE | `/api/nodes/accounts/:id` | Delete; a connected machine is closed with `4001` and exits → `{ok: true}` |
+
+### Machine connection
+
+`GET /api/nodes/connect` + WebSocket upgrade, headers `authorization: Bearer <token>`, `x-halo-node-protocol: 1`, `x-halo-node-instance: <uuid>`, `x-halo-node-info: <base64url JSON>`. Refusals before the upgrade: 429 locked out (5 bad tokens / 15 min, `node-token` bucket) · 426 protocol · 401 token · 404 workspace gone · 400 info / instance missing · 409 connected from another instance. Frames and close codes: [design/node.md](../design/node.md#protocol-v1).
+
+### Internal relay
+
+`POST /api/nodes/call` — loopback only and header `x-halo-node-relay: <per-boot secret>` (else 403); in `PUBLIC_PATHS`, used by cron's `halo cli` child. Body `{workspace, op, node?, args?}` (`op: 'nodes'` = node_list) → `{ok: true, text}` or `{ok: false, error}`. Not a public API.
+
 ## A2A (Agent-to-Agent)
 
 Files: `packages/server/src/a2a/routes.ts` (JSON-RPC handler), `exposure.ts` (path resolution, auth, card), `outbound.ts` (push receiver). A2A v1.0, JSON-RPC binding only. Mounted in normal server mode outside `/api/*` (no admin cookie) and before the static frontend; not in the CLI / TUI. AgentCore mode serves the same handler at `/` instead — see [AgentCore runtime container](#agentcore-runtime-container-halo-agentcore-only). Design: [design/a2a.md](../design/a2a.md).
@@ -1082,5 +1102,6 @@ It does not remove session files. The full delete (rows + JSON + archive segment
 | `chat:ack` | `clientMsgId` | Chat appended to the session log (or re-acked on resend) |
 | `listener:released` | `sessionId` | Event listener reclaimed — re-send `subscribe` (see above) |
 | `skills:changed` | — | A skill was created / deleted / toggled, or a workspace skill folder changed on disk — re-fetch skill lists and `/api/commands`. Workspace-scoped changes reach only that workspace's sockets (see [Skills](#skills)) |
+| `nodes:changed` | `online: [{accountId, root \| null, shell, os, since}]` | A `halo node` connected / disconnected — full snapshot of online machines (global broadcast; `root: null` = whole machine). See [Linked machines](#linked-machines-halo-node) |
 
 Events with `taskId` set belong to sub-agent turns (nested sessions); events without are the root agent's. Session-scoped frames carry `sessionId` (the root session they belong to); the admin routes each one to the tab holding that session, and a frame without one goes to the tab on screen. Full list in [design/ws.md](../design/ws.md).

package/bundled-docs/dev/env.md

@@ -106,7 +106,6 @@ Source: `packages/server/src/config.ts`
 | `HALO_WEB_FETCH_TIMEOUT` | `10000` | `config.yaml timeout.web_fetch` | web_fetch timeout |
 | `HALO_MODEL_TIMEOUT` | `600000` | `config.yaml timeout.model_request` | Per model-call idle timeout (ms, 10 min): every provider streams (Bedrock, the Anthropic-Messages providers anthropic / mimo / minimax / qwen, the OpenAI-family openai / deepseek / kimi / zhipu / doubao / hunyuan, and Mantle aws-bedrock-mantle / aws-bedrock-openai) and re-arms it on any data the stream delivers — text / thinking deltas, pings, tool-argument fragments, empty reasoning chunks, SSE comment frames — so it fires only when the model goes silent for this long, not on a long but live answer. It is also the only bound on a compact's LLM summary (no separate compact timeout). A bare fetch has no default timeout, so a half-open connection would hang the request forever; on expiry the call aborts and the agent loop retries with backoff. |
 | `HALO_SESSION_GRACE` | `300000` | `config.yaml timeout.session_grace` | WS-disconnect session grace |
-| `HALO_TERMINAL_GRACE` | `300000` | `config.yaml timeout.terminal_grace` | Terminal disconnect grace |
 | `HALO_MAX_CACHED_SESSIONS` | `50` | — | In-memory session cache |
 | `HALO_LOG_MAX_SIZE` | `10485760` | `config.yaml logging.max_file_size` | Log file size cap (10 MB) |
 | `HALO_LOG_MAX_FILES` | `5` | `config.yaml logging.max_files` | Retained rotated logs |
@@ -123,6 +122,7 @@ Source: `packages/server/src/config.ts`
 | `HALO_DEFAULT_PROVIDER` | (none) | — | Read by `halo setup --non-interactive`: binds every built-in agent to this provider id (and its default model) and, for each of its env-backed keys whose variable is set, writes the `<<NAME>>` placeholder into `settings.yaml` (Bedrock excepted). An unknown id only prints a warning |
 | `HALO_CLI` | `halo` (`halo.cmd` on Windows) | — | `halo` cli executable that cron runs and the evolution wrapper spawn — a dev override |
 | `HALO_VERSION` | `dev` | — | Version string reported by `GET /api/health` and the cli; stamped by the bundle / desktop launcher, so normally not set by hand |
+| `HALO_NODE_TOKEN` | (none) | — | `halo node` only (on the linked machine): pairing token, used when `--token` isn't given — preferred over the flag, which shows up in `ps` / shell history. Stripped from child-process env (see [design/node.md](../design/node.md)) |
 | `HALO_PROMPT` | (none) | — | `plain` makes `halo setup` use numbered-menu prompts instead of the raw-mode TUI |
 | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | (none) | `settings.yaml general.observability.capture_content` | `true` / `false` / `1` / `0` (any case) overrides `capture_content` either way; unset or any other value → the setting. Read at process start (see [design/observability.md](../design/observability.md)) |
 
@@ -169,7 +169,7 @@ settings.yaml-driven `general.limits.*` (no env override):
 - `general.limits.tool_result_render_chars` (default 8000)
 - `general.limits.tool_result_ui_chars` (default 64 KiB)
 - `general.limits.auto_report_chars` (default 8192)
-- `general.limits.terminal_scrollback_bytes` (default 50000)
+- `general.limits.terminal_scrollback_lines` (default 5000)
 
 Two ways to authenticate:
 

package/bundled-docs/dev/tools.md

@@ -535,6 +535,63 @@ The remotes configured on this server (the same list in every workspace) — eac
 
 Returns `{ "code": 0, "remotes": [{ name, agent, description, skills }], "pending": [{ remote, context_id, task_id, since }] }`.
 
+## Node tools
+
+File: `packages/server/src/nodes/tools.ts` (`buildNodeTools`). Design notes in [design/node.md](../design/node.md); user guide [guide/node.md](../guide/node.md).
+
+Act on the user's **linked machines** — computers running `halo node`, paired with this workspace in Admin → Channels → Linked machines. Each node tool mirrors one local workspace tool and runs **that same tool** on the machine (same arguments, same output), plus a required `node` argument naming the machine:
+
+| Tool | Mirrors | Extra / different args |
+|---|---|---|
+| `node_list` | — | none |
+| `node_read` | `file_read` | `node` |
+| `node_write` | `file_write` | `node` |
+| `node_edit` | `file_edit` | `node` |
+| `node_list_dir` | `file_list` | `node` |
+| `node_grep` | `grep` | `node` |
+| `node_glob` | `glob` | `node` |
+| `node_run` | `shell_exec` | `node`, `command`, `cwd` (default: the machine's folder) |
+
+**Enabling**: opt-in by the single name `node_list` in `agent.yaml`'s `tools:` — it brings all eight; the other seven names are not recognised on their own. **Full-access sessions only** (`accessLevel === null`). The bundled `default` agent lists it. The admin tool picker shows one `node_list` chip naming the set. Names, descriptions and schemas are constants — which machines are online never changes the tool list or the system prompt (prompt-cache invariant); online state is only in `node_list`'s result.
+
+**Paths**: a machine shares one folder (`--root`; `root` in `node_list`) — relative paths resolve against it, paths that resolve outside it (symlinks included) are refused: `"<p>" is outside this machine's shared folder (<root>) — node tools can only reach paths inside it`. A whole-machine node (`root: null, wholeMachine: true`) has no such check; relative paths resolve against its `base`.
+
+**Runtime**: in `halo server` calls go over the machine's WebSocket; cron runs (a `halo cli` child) reach it through the server's loopback relay. In the standalone CLI / TUI, the evo sandbox and AgentCore mode the tools are listed but every one — `node_list` included — returns `linked machines are not available in this runtime — only \`halo server\` accepts \`halo node\` connections. This is permanent for this runtime, not a temporary outage: do not retry. …`.
+
+**Errors** (returned as the tool error text):
+
+| Case | Message |
+|---|---|
+| Machine linked but not connected | `machine "<n>" is offline (\`halo node\` is not connected). Do not retry in a loop — tell the user to start it.` |
+| Name not linked to this workspace | `unknown machine "<n>" — machines linked to this workspace: <a, b \| (none)> (see node_list)` |
+| Link dropped mid-call | `machine "<n>" went offline during the call (connection lost). The operation may or may not have completed on the machine — check its state before retrying.` |
+| No answer in time (120 s; node_run: shell timeout + 15 s) | `machine "<n>" did not answer within <s>s — the call was cancelled; it may or may not have taken effect.` |
+| node_run without `--allow-shell` | `node_run is disabled on this machine — the user must restart \`halo node\` with --allow-shell to allow commands` |
+| Request over 8 MB | `request too large to send to the machine (<x> MB > 8 MB limit)` |
+
+Results over 256K chars are cut on the machine (`[Content truncated on the machine: N chars total]`); the usual tool-result budget then applies.
+
+### node_list
+
+The machines linked to this workspace and whether each is online. No arguments. Its description doubles as the usage note for the whole set.
+
+Returns `{ "code": 0, "nodes": [...] }`, one entry per linked machine:
+
+- offline: `{ "name": "nas", "online": false }`
+- online: `{ "name": "mbp", "online": true, "root": "/Users/a/proj", "shell": true, "shellTimeoutSec": 120, "os": "darwin", "since": "<ISO>" }` — whole-machine: `"root": null, "wholeMachine": true, "base": "<start dir>"`; `shellTimeoutSec` only when `shell` is true.
+
+No machines at all → `"nodes": []` plus `"hint": "No machines linked — create a token in Admin → Channels → Linked machines, then run \`halo node\` on the machine."`.
+
+### node_run
+
+`shell_exec` on the machine; needs `shell: true` in `node_list`. Runs unsandboxed as the machine's user in `cwd` (default: its folder; in folder mode `cwd` must stay inside it, the command itself is not confined). Killed after `shellTimeoutSec`; output capped like `shell_exec` (~8000 chars to the model) — redirect large output to a file, start long jobs with `nohup … &`. `{{ns.params.x}}` placeholders are not substituted.
+
+| Arg | Type | Required | Description |
+|---|---|---|---|
+| `node` | string | yes | Machine name from `node_list` |
+| `command` | string | yes | Shell command |
+| `cwd` | string | no | Directory to run in, like `path` (default: the machine's folder) |
+
 ## Tool assignment
 
 Workspace tools are enabled strictly by name in `agent.yaml`'s `tools` list:
@@ -547,7 +604,7 @@ skills:
   - code-review    # auto-injects activate_skill
 ```
 
-Tools not listed are not injected. Session/delegation tools do **not** go in `tools:` — they ride on a non-empty `team` (see [Session tools](#session-tools) above). `activate_skill` is auto-injected whenever the YAML lists `skills` (no need to put it in `tools`), and `continue_task` is auto-injected for **every** agent unconditionally (see [continue_task](#continue_task)). The relay and A2A sets are the two name-gated bundles: listing `relay_send` alone brings `relay_interrupt` / `relay_stop` / `relay_read` / `relay_list` with it, full-access sessions only (see [Relay tools](#relay-tools)); listing `a2a_send` alone brings `a2a_stop` / `a2a_read` / `a2a_list`, at every access level except the A2A read-only profile (see [A2A tools](#a2a-tools)).
+Tools not listed are not injected. Session/delegation tools do **not** go in `tools:` — they ride on a non-empty `team` (see [Session tools](#session-tools) above). `activate_skill` is auto-injected whenever the YAML lists `skills` (no need to put it in `tools`), and `continue_task` is auto-injected for **every** agent unconditionally (see [continue_task](#continue_task)). The relay, A2A and node sets are the three name-gated bundles: listing `relay_send` alone brings `relay_interrupt` / `relay_stop` / `relay_read` / `relay_list` with it, full-access sessions only (see [Relay tools](#relay-tools)); listing `a2a_send` alone brings `a2a_stop` / `a2a_read` / `a2a_list`, at every access level except the A2A read-only profile (see [A2A tools](#a2a-tools)); listing `node_list` alone brings the other seven `node_*` tools, full-access sessions only (see [Node tools](#node-tools)).
 
 There is **no implicit default tool set**: `filterTools()` (in `agent-loader.ts`) returns only the tools whose names appear in `agent.yaml`'s `tools:` list. If the field is absent or empty, the agent has zero workspace tools. The admin UI's "Create agent" form scaffolds a fresh agent with an empty `tools: []` for the same reason — fill it in deliberately. The `default` agent's bundled `agent.yaml` lists the common set (`file_read` / `file_write` / `file_edit` / `view_image` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`) that most agents will want; copy that line if you're starting from scratch.
 

package/bundled-docs/guide/README.md

@@ -24,6 +24,10 @@ Aimed at Halo end-users. Pick the doc that matches your situation.
 - [WeChat](channels/wechat.md) — QR-scan iLink bot
 - [ACP](channels/acp.md) — Zed / JetBrains or other ACP clients driving a remote halo
 
+## Linked machines
+
+[node.md](node.md) — run `halo node` on your own computer so a workspace's agents can work on files there.
+
 ## Related docs
 
 - Development: [dev/](../dev/) — environment, API, tool reference

package/bundled-docs/guide/agents.md

@@ -69,7 +69,7 @@ team:                 # a non-empty team is what enables delegation
   - executor          # the agent ids this one may spawn
 ```
 
-**Workspace tools**: `file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`.
+**Workspace tools**: `file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch` — listed by name under `tools`. `node_list` switches on the eight `node_*` tools for [linked machines](node.md) as one set (full-access sessions only).
 
 **Session tools**: `start_session / session_list / query_session / interrupt_session / stop_session / archive_session / get_session_output / query_agent` — **not** listed under `tools`. The whole bundle is granted automatically the moment an agent declares a non-empty `team`; an empty/absent `team` means no delegation (no session tools, no roster). To let a sub-agent delegate further, give it its own `team`. Add the agent's own id to its `team` to enable parallel self-spawn.
 

package/bundled-docs/guide/cli.md

@@ -308,6 +308,29 @@ the caller-side `auth: sigv4` remote, session dirs and ops notes:
 [design/agentcore.md](../design/agentcore.md). The hub skill `agentcore-deploy`
 builds the image and creates the runtime for you.
 
+## Linked machine (`halo node`)
+
+```bash
+HALO_NODE_TOKEN=<token> halo node --server https://halo.example.com --root ~/proj [--allow-shell]
+```
+
+Links this machine to a workspace on a halo server, so that workspace's
+full-access agents can work on files here with the `node_*` tools. Runs in the
+foreground, reconnects on its own, Ctrl-C to stop. Needs no `halo setup` and
+no model keys — nothing is written under `~/.halo/`. Create the token in
+Admin → Channels → Linked machines.
+
+| Flag / env | Meaning |
+|---|---|
+| `--server <url>` | Server address, `http(s)://host:port` (`ws(s)://` also accepted) — required |
+| `--token <t>` / `HALO_NODE_TOKEN` | Pairing token — required; prefer the env var (flags show up in `ps`) |
+| `--root <dir>` | Folder to share; every path must stay inside it. Omit (or `/`) for whole-machine mode: any path this user can reach, relative paths from the current dir |
+| `--allow-shell` | Let agents run commands (`node_run`) as this user, not sandboxed. Off by default |
+| `--header "Name: value"` | Repeatable. Extra header on the connection, for an auth proxy in front of the server |
+
+Exits 1 on a rejected / revoked token, a deleted workspace or a protocol
+mismatch; retries everything else. Full guide: [node.md](node.md).
+
 ## Architecture
 
 ```

package/bundled-docs/guide/delegation-and-access.md

@@ -94,7 +94,7 @@ Three session levels, stored per session (`agent_sessions.access_level`; `full`
 
 | Level | Tools the agent can get (from its `tools:` list) | Sandbox |
 |---|---|---|
-| `full` | all 9 workspace tools | none (the `rm` guard still applies) |
+| `full` | all 9 workspace tools, plus the full-only bundles `relay_send` and `node_list` (linked machines) when listed | none (the `rm` guard still applies) |
 | `workspace` | all 9 | writes only inside the workspace; credentials and workspace runtime state are hidden |
 | `readonly` | all 9 with an OS sandbox (writes fail); only `file_read`, `view_image`, `file_list`, `grep`, `glob` without one | nothing writable |
 
@@ -103,7 +103,7 @@ Extra rules:
 - A readonly `shell_exec` gets no secret substitution — `{{…params…}}` / `<<ENV>>` placeholders stay literal.
 - `view_image` also needs a vision-capable model.
 - A skill with `requiresAccess` above the session level is hidden (no metadata, no `activate_skill`).
-- Relay tools are only built for `full` sessions. A2A tools (`a2a_send` in `tools:`) are built at every level except the A2A read-only profile; a non-full session's `files` must sit in the workspace or the temp dir ([dev/tools.md → A2A tools](../dev/tools.md#a2a-tools)).
+- Relay tools and linked-machine tools (`node_list` in `tools:` → the eight `node_*` tools, [node.md](node.md)) are only built for `full` sessions. A2A tools (`a2a_send` in `tools:`) are built at every level except the A2A read-only profile; a non-full session's `files` must sit in the workspace or the temp dir ([dev/tools.md → A2A tools](../dev/tools.md#a2a-tools)).
 - Hidden from `workspace` / `readonly` sessions only (Full sessions, the admin file explorer and the terminal see everything): a built-in list that is always included (`~/.halo/secrets`, `~/.aws`, `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.config/gh`, `~/.gitconfig`, `~/.git-credentials`, `~/.npmrc`, `~/.netrc`, the global evo/cron/runs databases, internal-session transcripts, logs, …), any extra paths added in `general.sandbox.hidden_dirs` / `hidden_files` (they add to the built-in list, never replace it), plus the workspace's own `.halo/sessions`, `.halo/logs`, `.halo/evo`, `.halo/halo.db*` (fixed in code). The rest of `.halo/` stays readable.
 
 ### Where a session's level comes from

package/bundled-docs/guide/node.md

@@ -0,0 +1,86 @@
+# Linked machines (`halo node`)
+
+Let a workspace's agents work on files on **your own computer** — a laptop, a desktop, a box behind NAT — while the agents themselves keep running on the halo server. You run `halo node` on that machine; it dials out to the server (no port to open), and the workspace's agents get `node_*` tools that read, write, search and (if you allow it) run commands there.
+
+```
+[your laptop]                               [server]
+halo node --root ~/proj ──WebSocket──────▶ halo server ── agent in workspace W
+  (files, optional shell)                     node_read / node_write / … / node_run
+```
+
+The machine needs only the `halo` package — no `halo setup`, no model keys, nothing under `~/.halo/`.
+
+Supported: **macOS and Linux**. Windows works on a best-effort basis (not regularly tested; `node_run` commands go to `cmd.exe`).
+
+## 1. Create a token
+
+Admin → **Channels → Linked machines** → **Add machine**. Pick the workspace and a machine name (`a-z 0-9 -`, e.g. `mbp`; unique within the workspace — the agent uses it to address the machine). The dialog shows a command to copy:
+
+```bash
+HALO_NODE_TOKEN=<token> halo node --server https://halo.example.com --root <folder>
+```
+
+The token stays on the list row (copy button). Deleting the row revokes it at once and disconnects the machine.
+
+## 2. Run `halo node` on the machine
+
+```bash
+npm install -g @turmind/halo                   # once
+export HALO_NODE_TOKEN=<token>                 # better than --token: flags show up in ps / shell history
+halo node --server https://halo.example.com --root ~/proj
+```
+
+It runs in the foreground and logs each call (`[Node] read src/app.ts`, `[Node] refused write ../x: outside root`). Ctrl-C stops it. It reconnects by itself after network drops or a server restart; it exits on a bad / revoked token or when the workspace is gone.
+
+The admin row turns green (live, no refresh) and shows `folder · shell on/off · os`.
+
+### Folder mode vs whole-machine mode
+
+- **`--root <folder>`** — share one folder. Every path the agent passes must stay inside it (symlinks pointing out are refused too); relative paths start from it.
+- **No `--root`** (or `--root /`) — **whole-machine mode**: the agent can reach every path your user can, like a full-access local session. Relative paths start from the directory you ran `halo node` in. A startup line warns about it, and the admin shows "Whole machine".
+
+Prefer `--root` unless you really mean the whole machine.
+
+### `--allow-shell`
+
+Off by default — `node_run` then refuses with "restart `halo node` with --allow-shell". With it, agents can run **any command as your user, not sandboxed**. In folder mode only the command's working directory is held inside the folder; the command itself (`cat ~/.ssh/...`, `curl ...`) can reach anything your user can. Turn it on only for agents and workspaces you trust. Commands are killed after the shell timeout (120 s, or `HALO_SHELL_TIMEOUT` in ms on the machine).
+
+### What the agent can see
+
+Everything inside the shared folder — including `.env` files, keys, credentials and git history. Don't share a folder that holds secrets you wouldn't paste into the chat. Whole-machine mode exposes your whole home directory.
+
+### Behind a login proxy
+
+`halo node` sends a bearer token, nothing else. If the server sits behind an auth proxy (Cloudflare Access, an SSO gateway, basic auth), either point `--server` at an address the machine can reach directly, or pass the proxy's credentials with `--header` (repeatable, `Name: value`, split on the first colon):
+
+```bash
+halo node --server https://halo.example.com --root ~/proj \
+  --header "CF-Access-Client-Id: <id>" --header "CF-Access-Client-Secret: <secret>"
+```
+
+## 3. Let the agent use it
+
+Node tools are enabled per agent by **`node_list`** in `agent.yaml`'s `tools:` — that one name brings all eight (`node_list`, `node_read`, `node_write`, `node_edit`, `node_list_dir`, `node_grep`, `node_glob`, `node_run`). The bundled `default` agent lists it. If your workspace overrides the default agent (`<workspace>/.halo/agents/default/agent.yaml`), or you use another agent, add it yourself:
+
+```yaml
+tools:
+  - file_read
+  # …
+  - node_list   # linked machines (whole node_* set)
+```
+
+Only **Full** access sessions get node tools — a Workspace or Readonly session listing `node_list` gets none. Cron jobs in the workspace can use them too.
+
+Then just ask: "list my machines", "read `notes/todo.md` on mbp", "run the tests on mbp". The agent calls `node_list` first to see which machines are online.
+
+## Troubleshooting
+
+| Message | Meaning |
+|---|---|
+| `token rejected by the server (401)` | Wrong / deleted token — create a new one. 5 bad tries in 15 min lock the address out for a while (429). |
+| `the workspace this token is bound to no longer exists (404)` | The workspace folder was removed on the server. |
+| `protocol mismatch (426)` | `halo` versions too far apart — upgrade the older side. |
+| `this token is already connected from another process` | Another `halo node` with the same token is running; this one keeps retrying until that one stops. Also normal right after the machine rebooted or woke from sleep: the server needs 40–60 s to notice the old connection is dead, so the new process backs off and can take up to ~90 s to come online. |
+| agent: `machine "mbp" is offline` | `halo node` isn't running / connected. |
+| agent: `went offline during the call` | The connection dropped mid-call; the operation may or may not have happened. Running commands on the machine were stopped. |
+| agent: `not available in this runtime` | You're in the standalone CLI / TUI — linked machines only work through `halo server` (admin UI or a channel). |

package/bundled-docs/guide/workspace.md

@@ -102,7 +102,8 @@ Bottom-panel Terminal tab:
 - xterm.js frontend + node-pty backend
 - Multi-instance (each terminal owns its own PTY), listed as a collapsible vertical tab strip on the right
 - cwd = current project root
-- Reconnect grace: 5 min (`timeout.terminal_grace`)
+- Terminals are shared by every browser / device that opens the workspace and kept until closed with ✕ (or the shell exits, or the server restarts): reconnecting, refreshing or coming back days later restores the full screen — scrollback, and vim / htop as they were
+- Local echo: what you type shows at once (dimmed) and turns normal when the server echoes it back, so a slow link doesn't lag typing; vim / nano / tmux and other full-screen programs are not predicted
 
 ## Settings
 
@@ -140,12 +141,14 @@ See [requirements/settings.md](../requirements/settings.md), [secrets-and-creden
 | `Cmd/Ctrl + P` | Quick Open |
 | `Cmd/Ctrl + S` | Save file |
 | `Alt + W` | Close editor tab (browser; the desktop app uses `Cmd/Ctrl + W`) |
-| `Cmd/Ctrl + \`` | Switch the bottom panel between Chat and Terminal |
+| `Cmd/Ctrl + \`` | Switch the bottom panel between Chat and Terminal (no-op in split view) |
 | `Esc` | Leave editor maximize |
 
 ## Bottom panel switching
 
-Two tabs in the header: Chat / Terminal, plus maximize and float / dock buttons. The panel opens on Chat after a refresh.
+Two tabs in the header: Chat / Terminal, plus split, maximize and float / dock buttons. The panel opens on Chat after a refresh, unless split view is on.
+
+**Split view** shows Chat and Terminal at once — side by side, or stacked when the panel is narrow (e.g. floating); drag the divider to resize. It stays on across refreshes; click either tab to go back to a single view.
 
 ## Login / logout
 

package/bundled-docs/requirements/agent.md

@@ -60,7 +60,7 @@ Same id present in both scopes: workspace wins; the overridden global is greyed
 
 ### Tool selection
 - **Session tools**: `start_session` / `session_list` / `query_session` / `interrupt_session` / `stop_session` / `archive_session` / `get_session_output` / `query_agent` — **not** selected by name; the whole bundle is granted automatically by a non-empty `team` (see below). Listing them under `agent.yaml tools` has no effect.
-- **Workspace tools**: `file_read` / `view_image` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, plus the single `relay_send` chip (grants the whole cross-workspace relay set, full-access sessions only) and the single `a2a_send` chip (grants the cross-server A2A set — `a2a_send` / `a2a_stop` / `a2a_read` / `a2a_list` — at every access level except the A2A read-only profile), returned by `GET /api/agent-configs/tools`. `view_image` is dropped at runtime when the model can't take images (the form dims it)
+- **Workspace tools**: `file_read` / `view_image` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, plus the single `relay_send` chip (grants the whole cross-workspace relay set, full-access sessions only) the single `a2a_send` chip (grants the cross-server A2A set — `a2a_send` / `a2a_stop` / `a2a_read` / `a2a_list` — at every access level except the A2A read-only profile) and the single `node_list` chip (grants the eight linked-machine `node_*` tools, full-access sessions only — see [design/node.md](../design/node.md)), returned by `GET /api/agent-configs/tools`. `view_image` is dropped at runtime when the model can't take images (the form dims it)
 - **`activate_skill`**: auto-injected when the YAML lists at least one usable skill (not disabled, allowed at the session's access level); loads the full SKILL.md on demand
 
 ### Team (delegation switch + whitelist)

package/bundled-docs/requirements/terminal.md

@@ -22,25 +22,32 @@ xterm.js terminal with a node-pty backend, multi-tab, reconnect-resilient.
 
 Derivation in `createTerminal` in [packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx); backend resolution in `TerminalManager.start` in [packages/server/src/ws/terminal-manager.ts](../../../packages/server/src/ws/terminal-manager.ts).
 
-Workspace switch reloads the page and does **not** migrate existing terminals — they keep their original cwd and are only reattached in their own workspace (within the grace period); the new workspace starts a fresh terminal at its root.
+Workspace switch reloads the page and does **not** migrate existing terminals — they keep their original cwd and are reattached only in their own workspace; the new workspace shows its own terminals, or starts a fresh one at its root if it has none.
 
-### Reconnect resilience
+### Shared, persistent terminals
+
+A workspace's terminals belong to the workspace, not to a browser: the admin has one login, so every page that opens the workspace — another tab, another browser, another device — sees and drives the same terminals.
 
-When the WebSocket drops:
+- **Persistence**: a PTY ends only when it is closed with ✕, when its shell exits, or when the server restarts. Closing the browser, losing the connection, or leaving for days doesn't end it — there is no grace timer.
+- **Full restore**: the server mirrors each PTY into a headless xterm (`@xterm/headless`). A page that attaches gets a serialized snapshot of it (`@xterm/addon-serialize`): the scrollback (`general.limits.terminal_scrollback_lines`, default 5000 lines), the screen, a full-screen program's alternate screen (vim, htop), and the terminal modes — bracketed paste, application cursor keys, mouse tracking and SGR mouse encoding, hidden cursor. Output made while nobody was attached is part of the snapshot.
+- **Live sync**: every attached page receives the output and can type; all input goes to the one PTY.
+- **Close everywhere**: ✕ on any page sends `terminal:close` and the PTY ends; every attached page gets `terminal:exit` and prints `[Process exited]`.
+- **Size**: the PTY follows its *driver*, the page that last typed into it. Each page reports its size (`terminal:resize`); when a page types and its size differs from the PTY's, the PTY (and the mirror) switch to that size. A resize from a page that isn't the driver is only recorded, unless no driver is attached any more — then it applies at once. Pages with a different size than the driver see the driver's layout reflowed into their own width.
+
+### Reconnect resilience
 
-1. PTYs are **not killed** — they stay in the module-level `terminals` map with `currentWs = null` (`packages/server/src/ws/terminal-manager.ts`)
-2. Output during detach is buffered (ring buffer, up to `config.limits.terminalOutputBuffer` = 50 KB per terminal)
-3. Grace period: `config.timeout.terminalGrace` (default 5 min)
-4. On reconnect, the client sends `terminal:reattach` with its `browserId` and workspace path (sent on initial mount **and** on every subsequent `_connected` event); only PTYs of that browser × workspace are claimed
-5. Server replays the entire output buffer, reattaches live I/O, and responds with `terminal:reattached { terminalIds: [...] }`
-6. If the grace timer expires first, the PTY is killed and the detach entry removed
+1. On mount (once the workspace is known — with split view on, the panel mounts before the page has resolved its workspace) **and** on every `_connected`, the panel sends `terminal:reattach { workspacePath }`. The server attaches the connection to every PTY of that workspace and subscribes it to the workspace
+2. The server answers `terminal:reattached { terminals: [{ id, name }] }`, then one `terminal:snapshot` per PTY, then live `terminal:output`. Snapshot and live stream join exactly: output that arrives while a snapshot is being taken is queued for that page and sent right after it — nothing lost, nothing repeated
+3. A PTY another page starts later is pushed to every subscribed page as `terminal:opened { terminalId, name }` + its snapshot — no polling
+4. When a connection closes, the server only removes it from the PTYs' attached sets and from the workspace subscription; no timer is started
 
 Connection-level liveness and reconnect (server keepalive tolerance, client self-check timer, auth-expiry handling) are owned by the shared WS client — see [design/ws.md](../design/ws.md#client-side-liveness--reconnect).
 
-When the WS drops, the bottom panel remounts `TerminalPanel` (fresh key on `_disconnected`): local xterm instances are disposed without sending `terminal:close`, and the new panel reattaches like a page load. The local scrollback is lost; the server replays only what was buffered while detached. On the reattach handler ([packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx)), each id in `terminalIds` is dispatched by whether a local xterm instance already exists:
+When the WS drops, the bottom panel remounts `TerminalPanel` (fresh key on `_disconnected`): local xterm instances are disposed without sending `terminal:close`, and the new panel reattaches like a page load — its screen comes back from the snapshots. In the panel ([packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx)):
 
-- **Already exists** (a reattach without a remount): only a `terminal:resize` is sent so server PTY dimensions resync; the existing instance keeps its scrollback and continues receiving live output.
-- **Does not exist** (first mount, or after the remount above): a fresh xterm container is created and bound to that id. Bracketed paste mode is resynced by locally writing `\x1b[?2004h` into the new instance — bash enabled the mode on the PTY at spawn time, but that sequence went to the disposed instance; without the resync, a multi-line paste into the reattached terminal would be sent unbracketed and execute line by line.
+- `terminal:reattached` / `terminal:opened`: a tab is added for each id not shown yet, named as the server says (the name the creating page gave in `terminal:start`).
+- `terminal:snapshot`: the local xterm (created if missing) is `reset()`, sized to the snapshot's `cols × rows`, given the snapshot, then fit to its container; the fitted size is reported with `terminal:resize`.
+- If 2 s after the connection is up the panel still has no terminal, it starts one (the timer is armed only while connected, so an outage doesn't add a PTY per remount).
 
 ### Environment
 - Shell: `$SHELL` or `/bin/bash` (`ComSpec` / `powershell.exe` on Windows); bash / zsh / sh / fish start as login shells (`-l`)
@@ -61,45 +68,59 @@ Keys depend on the client's OS (the keyboard in front of the user — the PTY is
 - **Right-click menu** (inside the terminal): Copy (disabled with no selection) · Paste · Select all · Clear. Menu copy / paste use the async Clipboard API; when paste is refused (plain-http origin or no clipboard-read permission) the menu says to use the keyboard shortcut instead
 - Key mapping: `terminalClipboardKey` in [packages/admin/src/features/terminal/terminal-clipboard.ts](../../../packages/admin/src/features/terminal/terminal-clipboard.ts); menu in `terminal-context-menu.tsx`
 
+### Local echo (predictive)
+Keystrokes show up before the server's echo comes back, so typing over a slow link doesn't lag. This is a port of VS Code's terminal type-ahead ([packages/admin/src/features/terminal/type-ahead/](../../../packages/admin/src/features/terminal/type-ahead/)), and it is always on. No setting turns it off.
+
+- A predicted character is drawn **dim**. When the PTY echoes the same character, it is redrawn normally. When the PTY sends something else, the prediction is rolled back: the original cell and cursor come back, then the real output is written. This happens, for example, when another page typed into the same terminal first (see Shared, persistent terminals). No residue is left.
+- Predicted keys: printable characters, Backspace, ←/→ (also `Esc b` / `Esc f`), and Enter when the cursor isn't on the last row. Any other key ends prediction until the PTY answers: Tab, ↑/↓, Ctrl-keys and the like. This is why **Tab completion and history paging are not predicted**.
+- The first keystroke on a line is drawn only after the PTY has echoed one. A prompt that doesn't echo starts nothing.
+- Not predicted:
+  - while the title names `vim`, `vi`, `nano` or `tmux`;
+  - in any full-screen program on the alternate screen (htop, less in full-screen mode…);
+  - at a `less`-style `:` prompt on the bottom row.
+- A prediction the PTY never echoes is withdrawn after a timeout: at least 500 ms, or 1.5 × the slowest confirmed echo, whichever is longer. **Password prompts**: if the prompt is on a line where echo was already confirmed, a typed character may flash dim and then be withdrawn. At a fresh prompt nothing is drawn.
+- A `terminal:snapshot` drops all pending predictions without rolling them back, because the snapshot replaces the whole screen.
+
 ### Lifecycle
 
 ```
-          ┌─────────────┐
-create ──▶│ in this WS  │
-          │ session map │
-          └──────┬──────┘
-                 │ WS drops
-                 ▼
-          ┌─────────────┐
-          │  detached   │  (grace timer = 5min, ring buffer active)
-          │    pool     │
-          └──┬───────┬──┘
-   reattach  │       │  grace expires
-             ▼       ▼
-       ┌─────────┐  kill PTY, clean up
-       │ replay +│
-       │ live IO │
-       └─────────┘
+               terminal:start
+                     │
+                     ▼
+   ┌──────────────────────────────────┐   page attaches
+   │ PTY + headless mirror            │◀── (reattach / opened):
+   │ attached pages: 0..n             │    snapshot, then live
+   │ (output + exit go to all)        │
+   └──┬──────────────┬─────────────┬──┘
+      │ page leaves  │ ✕ / shell   │ server
+      │ (WS drops)   │ exits       │ restart
+      ▼              ▼             ▼
+   still running   exit to all   gone
+   (0 pages ok,    pages, PTY
+    no timer)      removed
 ```
 
 Close semantics:
-- Explicit `terminal:close` — PTY killed immediately, detach entry (if any) cleaned up
-- WS drop → grace expires (default 5 min) without reattach → PTY killed
+- Explicit `terminal:close` (✕ on any page) — PTY killed immediately; every attached page gets `terminal:exit`
+- The shell exits by itself — every attached page gets `terminal:exit` with its exit code
 - Server shutdown — all PTYs die with the process
+- WS drop / browser closed — **not** an end: the PTY keeps running with no page attached, for as long as it takes
 
 ## WebSocket protocol
 
 | Direction | Type | Fields | Purpose |
 |---|---|---|---|
-| C→S | `terminal:start` | `terminalId?`, `cwd?`, `cols?`, `rows?` | Spawn a new PTY |
-| C→S | `terminal:input` | `terminalId`, `data` | Send user keystrokes |
-| C→S | `terminal:resize` | `terminalId`, `cols`, `rows` | Resize PTY (screen resize) |
-| C→S | `terminal:close` | `terminalId` | Explicit close |
-| C→S | `terminal:reattach` | — | Reattach all detached terminals after reconnect |
-| S→C | `terminal:ready` | `terminalId` | PTY spawned and ready |
-| S→C | `terminal:output` | `terminalId`, `data` | PTY stdout/stderr |
-| S→C | `terminal:exit` | `terminalId`, `exitCode` | PTY exited |
-| S→C | `terminal:reattached` | `terminalIds` | Reattach completed for these |
+| C→S | `terminal:start` | `terminalId?`, `cwd?`, `cols?`, `rows?`, `workspacePath?`, `name?` | Spawn a new PTY in the workspace; `name` is the tab name every page shows. Pushed to the workspace's other subscribers |
+| C→S | `terminal:input` | `terminalId`, `data` | Send user keystrokes; makes the sender the PTY's size driver. Rejected without `terminalId` |
+| C→S | `terminal:resize` | `terminalId`, `cols`, `rows` | Report this page's size; applied if it is the driver or no driver is attached. Rejected without `terminalId` |
+| C→S | `terminal:close` | `terminalId` | Explicit close — ends the PTY for every page |
+| C→S | `terminal:reattach` | `workspacePath` | Attach to every PTY of the workspace and subscribe to it |
+| S→C | `terminal:ready` | `terminalId` | PTY spawned and ready (to its creator) |
+| S→C | `terminal:output` | `terminalId`, `data` | PTY stdout/stderr, to every attached page |
+| S→C | `terminal:exit` | `terminalId`, `exitCode` | PTY ended (close or shell exit), to every attached page |
+| S→C | `terminal:reattached` | `terminals: [{ id, name }]` | The workspace's PTYs, all now attached; a snapshot follows for each |
+| S→C | `terminal:opened` | `terminalId`, `name` | Another page started a PTY in a subscribed workspace; a snapshot follows |
+| S→C | `terminal:snapshot` | `terminalId`, `data`, `cols`, `rows` | Serialized scrollback + screen + modes at attach time, taken at `cols × rows`; live output continues right after it |
 
 Source: [packages/server/src/ws/terminal-manager.ts](../../../packages/server/src/ws/terminal-manager.ts).
 
@@ -107,8 +128,9 @@ Source: [packages/server/src/ws/terminal-manager.ts](../../../packages/server/sr
 
 | Config key | Default | Purpose |
 |---|---|---|
-| `config.timeout.terminalGrace` | 300,000 ms | Detach retention period |
-| `config.limits.terminalOutputBuffer` (setting `general.limits.terminal_scrollback_bytes`) | 50,000 bytes | Detach output ring buffer cap |
+| `config.limits.terminalScrollbackLines` (setting `general.limits.terminal_scrollback_lines`) | 5000 lines | Scrollback the server-side mirror keeps per terminal (restored on attach); applies to terminals opened after a change |
+
+`timeout.terminal_grace` / `HALO_TERMINAL_GRACE` and `general.limits.terminal_scrollback_bytes` are gone; a value left in an existing `config.yaml` / `settings.yaml` is ignored.
 
 Defined in [packages/server/src/config.ts](../../../packages/server/src/config.ts).
 
@@ -119,17 +141,27 @@ Defined in [packages/server/src/config.ts](../../../packages/server/src/config.t
 | T1 | Start, run `ls` | Output arrives; prompt returns |
 | T2 | Explorer → right-click a folder → Open in Integrated Terminal | A new terminal whose cwd is that folder (`pwd` confirms) |
 | T3 | Resize window | PTY cols/rows update; long-running process (e.g. `watch ls`) reflows |
-| T4 | Disconnect mid-command (`sleep 5 && echo done`) → reconnect within grace period | Buffered output replayed; `done` visible |
-| T5 | Disconnect → wait > grace period → reconnect | Terminal gone (PTY killed at grace expiry) |
+| T4 | Disconnect mid-command (`sleep 5 && echo done`) → reconnect | Screen restored from the snapshot: scrollback from before the drop plus `done` |
+| T5 | Disconnect (or close the browser) → come back hours later | The terminal is still there, scrollback and running programs intact |
+| T5b | Run `vim` (or `htop`) → refresh the page | vim's screen is back as it was; keys and mouse work in it; after `:q` the shell's scrollback is back |
+| T5c | Open the same workspace in two browsers | Both show the same terminals; typing in either shows on both; ✕ in one prints `[Process exited]` in both |
+| T5d | Open a terminal in browser A while B has the workspace open | B gets the new tab with A's name, live |
+| T5e | Open the workspace on another device | Same terminals with their full scrollback; another workspace's terminals don't appear |
+| T5f | Two browsers with different window sizes, type in the narrow one, then in the wide one | `stty size` follows whoever typed last |
 | T6 | Open 3 tabs, close 1 explicitly | Other 2 keep their PTYs; closed one gets `terminal:exit` |
 | T7 | `exit` from within shell | `terminal:exit` with the shell's exit code; the terminal prints `[Process exited]` and its tab stays until closed |
 | T8 | Paste a 10 KB block | Sent as `terminal:input` without choking; shell echoes in chunks |
 | T9 | Windows/Linux: select text → `Ctrl+C`; then `Ctrl+C` again with nothing selected | First copies and clears the selection; second sends `^C` (interrupts a running `sleep 30`) |
 | T10 | Right-click in the terminal → Paste | Clipboard text inserted at the prompt (or the "use the shortcut" hint on a plain-http origin) |
+| T11 | Over a slow link (e.g. 300 ms RTT), type `ls -la` after a first confirmed character | Characters appear at once, dim. They turn normal as the echo arrives. Backspace and ←/→ are instant too |
+| T12 | Two browsers on one terminal, type different characters in both at the same moment | Each page ends up showing exactly what the shell echoed. A dim prediction from the losing page is rolled back with no stray character left |
+| T13 | Type in `vim`, `nano`, `tmux`, `htop`, `less` | Nothing is drawn ahead of the program's own output |
+| T14 | `sudo -k; sudo true`, then type the password | Nothing stays on screen. At most a dim character flashes and is withdrawn within about 0.5 s |
+| T15 | Type, then Tab to complete or ↑ for history | The completion or history entry appears only when the shell sends it. The characters typed before it are kept |
 
 Follows the pattern of [test/session.md](../test/session.md).
 
 ## Related design
 
-- Detach / reattach plumbing: [design/architecture.md#terminalmanager](../design/architecture.md#terminalmanager--pty-management)
+- Attach / snapshot plumbing: [design/architecture.md#terminalmanager](../design/architecture.md#terminalmanager--pty-management)
 - WS envelope shape: [design/ws.md](../design/ws.md)