dsh-computers 1.1.0 → 1.3.0

package/PROTOCOL.md

@@ -557,3 +557,138 @@ the raw materials for the desktop path: below the command box, a muted line
 「也可以在这台电脑的 DSH 桌面端打开 设置 → 电脑 → 本机运行时，填入下面的地址和密钥」 plus
 two compact copyable rows — the server URL and the enrollment key (`/keys` already returns
 `serverUrl` and `key`). That is how a user connects a machine without a terminal.
+
+---
+
+## 11. Stage 1 (v1.3.0): capabilities, streaming, remote files
+
+Everything here is additive: an agent that reports no capabilities keeps the v1 behaviour
+exactly. The wire stays SSE (host → agent) + HTTP POST (agent → host); no inbound ports.
+
+### 11.1 Capabilities and version gate
+
+`POST /agent/enroll` and `POST /agent/heartbeat` carry
+`"capabilities": ["exec" | "fs" | "pty"]` and `agentVersion` (already present). The registry
+stores the last reported set and `capabilitiesUpdatedAt`. Rules:
+
+- A computer with no reported capabilities is treated as `["exec"]` (v1 agents).
+- Host tool availability is gated per session: the `computer_*_file` tools are only
+  registered/offered when at least one allowed computer reports `fs`; the terminal backend
+  only serves computers reporting `pty`. Gating uses `ctx.tools.restrict`-style filtering
+  (drop the schema) rather than failing at call time, so the model never sees a tool it
+  cannot use; a call that still arrives for an incapable computer answers with an
+  actionable "this machine's agent does not support file access (upgrade the agent)".
+- `hello` echoes the host's view: `{ computerId, name, heartbeatMs, capabilities }`.
+- `/state` and `/health` expose each computer's `agentVersion` and `capabilities`; the
+  settings page shows a drift badge when `agentVersion` differs from the host plugin's.
+
+### 11.2 Streaming results
+
+`exec` gains `"stream": true`. The agent then POSTs incremental output to
+`POST /api/dsh-computers/agent/results/chunk`:
+
+```json
+{ "requestId": "req_…", "seq": 0, "stdout": "<base64>", "stderr": "<base64>" }
+```
+
+- `seq` starts at 0 and increases by 1; the host drops out-of-order duplicates and
+  reassembles. Batches are sent at most every 100 ms (or 32 KiB, whichever first).
+- The final `POST /agent/results` stays authoritative for `exitCode`/`durationMs`/
+  `timedOut`/`truncated` and carries the same capped buffers as v1 (so a host that missed
+  chunks still ends with the tail).
+- Host side, a streaming execution feeds the **DSH jobs** registry: `computer_exec` with
+  `run_in_background: true` registers one job (`kind: 'computer-exec'`, label
+  `<name>: <command>`, owner = calling session), returns its id immediately, and appends
+  every chunk to the job's output ring so the built-in `job_output` / `job_kill` tools work
+  unchanged. Killing the job sends `cancel` to the agent and settles the job.
+- A foreground call still returns the complete result (v1 shape) but the host keeps the
+  tail in the job ring for the conversation's progress view.
+
+### 11.3 Remote file access
+
+Host → agent, over the same SSE stream:
+
+```json
+{ "event": "fs", "data": { "requestId": "fsr_…", "op": "read", "path": "/abs", "encoding": "utf8", "offset": 0, "limit": 2000 } }
+```
+
+`op` ∈ `read | write | list | stat | mkdir | rename | delete | glob | grep`.
+Agent → host: `POST /api/dsh-computers/agent/fs/result`
+
+```json
+{ "requestId": "fsr_…", "ok": true, "op": "read", "path": "/abs",
+  "content": "<base64 for write/read binary>", "text": "<utf8 for text reads>",
+  "encoding": "utf8|base64", "bytes": 123, "lines": 20, "truncated": false,
+  "entries": [{ "name": "a", "path": "/abs/a", "type": "file|dir|symlink", "size": 1, "mtimeMs": 0 }],
+  "stat": { "type": "file", "size": 1, "mtimeMs": 0, "mode": 420 },
+  "matches": [{ "path": "/abs/a", "line": 3, "text": "…" }],
+  "error": null }
+```
+
+Limits: read 1 MiB / 20 000 lines, write 4 MiB, list 5 000 entries, glob 2 000 paths,
+grep 500 matches, per-request timeout 15 s. Paths must be absolute; the agent rejects a
+relative path with `ok:false, error:"path must be absolute"`.
+
+Host tools (registered only when a `fs`-capable computer is available, §11.1):
+
+| tool | arguments (JSON Schema) | value |
+|---|---|---|
+| `computer_read` | `computer?`, `path`, `offset?`, `limit?` | `{ computer, path, text, lines, bytes, truncated }` |
+| `computer_write` | `computer?`, `path`, `content`, `createDirs?` | `{ computer, path, bytes, created }` |
+| `computer_edit` | `computer?`, `path`, `old`, `new`, `replaceAll?` | `{ computer, path, replacements, bytes }` |
+| `computer_glob` | `computer?`, `pattern`, `cwd?` | `{ computer, paths }` |
+| `computer_grep` | `computer?`, `pattern`, `path?`, `include?`, `maxMatches?` | `{ computer, matches }` |
+
+`computer` is optional in all of them and falls back to the session pin (§10/§9 selection),
+same as `computer_exec`. Renders mirror the built-in `read`/`write`/`edit`/`glob`/`grep`
+tool output style so the model reads them the same way. A write/edit to a path the agent
+cannot touch answers `ok:false` with the OS error text, surfaced as a tool error.
+
+### 11.4 PTY (terminal backend) — follows in v1.4.0
+
+Reserved events, not implemented in v1.3.0:
+`{"event":"pty.open"|"pty.input"|"pty.resize"|"pty.close", data:{ ptyId, … }}` and
+`POST /agent/pty/out` `{ ptyId, seq, data(base64) }` + `POST /agent/pty/exit` `{ ptyId, exitCode }`.
+The host will register a DSH `terminals` backend (`ctx.terminals.registerBackend`) so the
+built-in terminal tools and UI work against a connected computer; agents advertise `pty`
+only once they implement it.
+
+### 11.5 Compatibility
+
+- v1 agents: no capabilities, no streaming, no fs — everything above degrades to §3/§4.
+- New host + old agent: `computer_exec` unchanged; file tools hidden; a manual call errors
+  with the upgrade hint.
+- New agent + old host: the agent never sends `stream:true` payloads unless the host's
+  `hello` advertises `"features":["stream","fs","pty"]`, so an old host is unaffected.
+
+### 11.6 Interaction details aligned with the reference product
+
+These mirror the reference implementation's runtime protocol *behaviour* (handshake metadata,
+stream frames, background adoption, update-required) without copying any of its code.
+
+1. **Handshake metadata.** The agent's enroll body and every reconnect carry a metadata block:
+   `{ version: 1, agentVersion, hostname, os, arch, capabilities, workspaceBase }`, where
+   `workspaceBase` is the agent's default working directory (config `workspaceBase`, default
+   `os.homedir()`), reported back to the host at connect and used as the default `cwd` for
+   `exec` and the base for relative `glob`/`grep`. The host stores it and shows it in the
+   computer detail view. Same shape as the reference product's `RuntimeHandshakeMetadataV1`.
+2. **Stream frames.** Chunk payloads carry a `type`:
+   `{ type: 'stdout' | 'stderr' | 'heartbeat', data(base64, empty for heartbeat) }`.
+   The agent emits a `heartbeat` frame for every 10 s of a silent command so the host can keep
+   the execution alive and the conversation's progress view ticking instead of timing out.
+   Exit code still arrives exactly once in the final `/agent/results`.
+3. **Timeout adopts instead of killing.** When a foreground `computer_exec` reaches
+   `timeoutMs`, the host does NOT kill it by default: it moves the still-running execution
+   into the background-job path (config `promoteOnTimeout`, default true), returns `{ jobId,
+   promoted: true }`, and the model continues with `job_output`/`job_kill`. With
+   `promoteOnTimeout: false` the v1 cancel-and-error behaviour applies.
+4. **Pending → activated lifecycle.** An enrollment key is `pending` until the agent's first
+   successful stream; that moment sets `activatedAt` and marks the key used. A never-activated
+   computer is hidden from the list (only `pendingKey` shows in the connect dialog), matching
+   the reference product's activation lifecycle.
+5. **Update-required.** Config `minAgentVersion` (default: the plugin's major.minor) gates
+   tool calls: an older agent gets an actionable "upgrade this computer's agent" error, and
+   `/state` marks the computer `drift: true` with `updateRequired: true`.
+6. **Revoke kicks the stream.** Deleting a computer ends its live SSE stream in the same
+   request and invalidates the token, so a stale agent gets `401 invalid-token` and stops
+   retrying until re-enrolled.

package/README.md

@@ -26,25 +26,36 @@
 
 插件是纯 JavaScript，无构建、无第三方依赖，直接从 GitHub 装：
 
+**推荐从 npm 安装**（和官方插件包一样）：
+
 ```bash
-# 方式 A：CLI（推荐用分支，不用 tag，见下面「更新」）
-dsh plugin install github:9Ashwin/dsh-computers
+# 方式 A：CLI
+dsh plugin install dsh-computers
+
+# 方式 B：DSH 设置 → 插件市场 → 安装，搜 dsh-computers
+```
 
-# 方式 B：DSH 设置 → 插件市场 → 安装，粘贴
-#   https://github.com/9Ashwin/dsh-computers
+也可以直接从 GitHub 装（跟随仓库最新提交）：
+
+```bash
+dsh plugin install github:9Ashwin/dsh-computers
 ```
 
 ### 更新
 
-GitHub 安装的插件在 profile 里是**按 spec 固定**的（`github:user/repo` 或 `github:user/repo#v1.0.2`，lockfile 会钉到具体 commit），所以：
+**npm 安装**：插件市场 → 已安装 → 「检查更新」即可，或者在 CLI 里装具体版本：
 
-- **装 tag（`#v1.0.2`）= 冻在那个版本**，插件市场的「检查更新」永远发现不了新版本。
-- **装分支（不带 `#`）= 可更新**：插件市场 → 已安装 → 「检查更新」会重新解析分支 HEAD 并自动重装，不需要手动卸载。
-- 手动更新时**必须换 spec 才会生效**：用同样的 spec 再装一次只会得到 `already-installed`（这就是"再安装没法更新"的原因）。要升级到某个新版本，直接装新 tag：
-  ```bash
-  dsh plugin install github:9Ashwin/dsh-computers#v1.0.2
-  ```
-  或者先移除再装；种 spec 变了才会真正重新拉取。
+```bash
+dsh plugin install dsh-computers@1.3.0
+```
+
+**GitHub 安装**：profile 里是按 spec + commit 固定的（`github:user/repo` 或 `#v1.0.2`），所以
+
+- 用**同一个 spec** 再装一次只会得到 `already-installed`（这就是「再安装没法更新」的原因）；
+- 装 **tag** 会被冻住，市场永远检测不到更新；装**分支**（不带 `#`）才能被市场「检查更新」发现新提交；
+- 手动升级到某个版本要**换 spec**：`dsh plugin install github:9Ashwin/dsh-computers#v1.3.0`。
+
+> 更新完记得重启 Host 并刷新页面，具体见 [docs/deploy.md](./docs/deploy.md)。
 
 装好后重启 `dsh web`，设置里会出现 **电脑** 页。
 
@@ -97,20 +108,38 @@ tail -f ~/.dsh-computers/agent.log
 
 ## 3. 对话里怎么用
 
-智能体会看到两个工具：
+智能体会看到这些工具（`computer` 参数都可省略，省略时用输入框左侧选中的目标电脑）：
 
-- `computer_list` —— 列出已连接电脑（名字、平台、在线状态）
-- `computer_exec` —— 在指定电脑上执行命令：`{"computer": "my-mac-mini.local", "command": "sysctl -n hw.memsize"}`
+| 工具 | 作用 |
+|---|---|
+| `computer_list` | 列出可用电脑（名字、平台、在线、能力、当前固定目标） |
+| `computer_exec` | 执行命令，支持 `run_in_background`；超时默认**转后台**而不是杀掉 |
+| `computer_read` | 读远端文件（offset/limit 行） |
+| `computer_write` | 写远端文件（会自动建目录） |
+| `computer_edit` | 字面替换（`old` 必须唯一，除非 `replaceAll`） |
+| `computer_glob` | 远端 glob（`*`、`?`、`**`、`{a,b}`） |
+| `computer_grep` | 远端正则搜索（支持 `include`、命中上限） |
+
+文件类工具需要那台电脑的 agent 上报 `fs` 能力（见下）。
 
 系统提示里会自动附上当前电脑清单，所以直接说「看看两台 mac 的内存」它就会分别调用。
 
+## 3.1 能力、流式与后台任务
+
+- **能力协商**：agent 在握手时上报 `capabilities`（`exec` / `fs`，以后还有 `pty`）和 `workspaceBase`（默认工作目录）。服务器据此决定是否提供文件类工具；agent 过旧时工具调用会明确提示"升级这台电脑的 agent"，设置页也会显示 `可升级`。
+- **流式**：长命令的分块输出会随帧回传（含心跳），后台任务的输出可在 DSH 的任务里查看。
+- **超时转后台**：前台命令超时默认不杀（`promoteOnTimeout: true`），而是转入后台任务并返回 jobId，之后用内置的 `job_output` / `job_kill` 接管。
+- **激活时机**：新电脑要等 agent 首次建流后才出现在列表（从生成密钥到真正连上之间，弹窗会一直显示"等待电脑连接…"）。
+
 ## 4. 端点一览
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | POST | `/api/dsh-computers/agent/enroll` | 加入密钥换取电脑 token（runtime 卡片也走这里） |
 | GET | `/api/dsh-computers/agent/events` | 被控端的 SSE 长连接（Bearer token） |
-| POST | `/api/dsh-computers/agent/results` | 命令执行结果回传 |
+| POST | `/api/dsh-computers/agent/results` | 命令执行结果回传（最终结果，权威） |
+| POST | `/api/dsh-computers/agent/results/chunk` | 流式输出分块（stdout/stderr/heartbeat） |
+| POST | `/api/dsh-computers/agent/fs/result` | 远端文件操作结果 |
 | POST | `/api/dsh-computers/agent/heartbeat` | 心跳 |
 | GET | `/api/dsh-computers/state` | 设置页数据（角色、电脑列表，需要浏览器会话） |
 | POST | `/api/dsh-computers/keys` | 生成一次性加入密钥 |

package/agent/README.md

@@ -21,6 +21,13 @@ The same file is used two ways, with one implementation:
   *本机运行时* card calls the module's exported `startRuntime()` in-process, so
   the user never opens a terminal (PROTOCOL §10.4).
 
+Since v1.3.0 the agent implements PROTOCOL §11: it advertises the `exec` and
+`fs` capabilities, streams live output when the host asks for it, serves remote
+file operations over the same SSE stream, and reports §11.6 handshake metadata
+(`agentVersion`, `hostname`, `os`, `arch`, `capabilities`, `workspaceBase`) at
+enroll and on every reconnect. Old hosts that advertise no `features` get
+exactly the v1 behaviour.
+
 The file is served verbatim by the host plugin at
 `/api/dsh-computers/agent.mjs`, so what you run is exactly what the repository
 contains. It imports only Node built-ins, never opens a listening socket, and
@@ -70,7 +77,7 @@ node ~/.dsh-computers/agent.mjs enroll --server http://<server> --key dshc_… -
 ## Commands
 
 ```
-dsh-computers-agent enroll --server <url> --key <key> [--name <name>] [--replace]
+dsh-computers-agent enroll --server <url> --key <key> [--name <name>] [--workspace-base <path>] [--replace]
 dsh-computers-agent run
 dsh-computers-agent service install|uninstall|start|stop|restart|status
 dsh-computers-agent status
@@ -79,7 +86,7 @@ dsh-computers-agent --version | --help
 
 | Command | What it does |
 | --- | --- |
-| `enroll` | POSTs the join key to `/api/dsh-computers/agent/enroll`, saves `{serverUrl, computerId, token, name, enrolledAt}` to `config.json` (atomic, `0600`), then opens the SSE stream for ~5 s to prove the round trip. Exits non-zero with the server's message on failure. |
+| `enroll` | POSTs the join key (plus `capabilities` and §11.6 `metadata`) to `/api/dsh-computers/agent/enroll`, saves `{serverUrl, computerId, token, name, enrolledAt, workspaceBase}` to `config.json` (atomic, `0600`), then opens the SSE stream for ~5 s to prove the round trip. `--workspace-base` sets the default working directory (default `$HOME`). Exits non-zero with the server's message on failure. |
 | `run` | Foreground worker: one SSE stream to `/api/dsh-computers/agent/events`; executes `exec` events, kills the process group on `cancel`, POSTs results, sends heartbeats, reconnects with jittered 1 s → 30 s backoff. |
 | `status` | Prints server, computer id/name, redacted token (last 6 chars only), config/log paths and service state. Exit `0` when enrolled, `1` when not. |
 | `service` | Login/auto-restart service. See below. |
@@ -155,11 +162,95 @@ Semantics guaranteed to the host:
 
 `AGENT_VERSION` is exported too (the host can put it in the §3.1 enroll body).
 
+## Protocol v1.3.0 / §11 features
+
+### Capabilities and gating (§11.1, §11.5)
+
+The agent reports `capabilities: ["exec", "fs"]` in the enroll body, in the
+heartbeat `meta`, in the §11.6 metadata and in `startRuntime().status()`.
+Nothing new is sent to an old host: the `hello` event's `features` list decides
+what is enabled per connection —
+
+| `hello.features` | behaviour |
+| --- | --- |
+| absent / no `stream`, no `fs` | exactly v1: `exec` results only, `fs` events ignored, no chunk POSTs |
+| `stream` | `exec` with `"stream": true` gets incremental chunk POSTs |
+| `fs` | `fs` events are served and answered on `/agent/fs/result` |
+
+### Handshake metadata (§11.6)
+
+Enroll sends `metadata: { version: 1, agentVersion, hostname, os, arch,
+capabilities, workspaceBase }`, and every SSE connect (probe and each
+reconnect) carries the same JSON in the `x-dsh-computers-metadata` header as
+base64url — an SSE GET has no body, so the header is how the reference-product
+handshake metadata maps onto this wire. `workspaceBase` comes from
+`config.json` (`--workspace-base`, default `$HOME`), is the default `cwd` for
+`exec`, and is the base for relative `glob`/`grep` patterns.
+
+### Streaming results (§11.2 + §11.6 frames)
+
+When the host advertises `stream` and an `exec` event has `stream: true`, the
+agent POSTs frames to `/api/dsh-computers/agent/results/chunk`:
+
+```json
+{ "requestId": "req_…", "seq": 0, "type": "stdout", "data": "<base64>" }
+```
+
+- `type` is `stdout`, `stderr`, or `heartbeat` (empty `data`).
+- `seq` starts at 0 and increases by one per frame; frames are posted strictly
+  sequentially so arrival order matches `seq` (the host can still drop dupes).
+- Batches flush at most every 100 ms or 32 KiB (whichever first); a heartbeat
+  frame is emitted after each 10 s of silence from a running command.
+- A failed chunk POST retries once, then that batch is dropped — the command
+  keeps running and the final authoritative `POST /agent/results` still carries
+  the capped `stdout`/`stderr` buffers, `exitCode`, `durationMs`, `timedOut`
+  and `truncated`.
+- `stop()` drops buffered frames, clears every chunk timer and leaves no pending
+  POSTs (they are aborted with the runtime).
+
+### Remote file access (§11.3)
+
+`fs` events are served in-process (no shell) and answered on
+`POST /api/dsh-computers/agent/fs/result` with the §11.3 field set.
+
+| op | request fields | response highlights |
+| --- | --- | --- |
+| `read` | `path`, `offset?`, `limit?`, `encoding?` (`utf8`/`base64`) | `encoding`, `text` (utf8) or `content` (base64), `bytes`, `lines`, `truncated` |
+| `write` | `path`, `content`, `encoding?`, `createDirs?` | `bytes`, `created` |
+| `list` | `path` | `entries[{name,path,type,size,mtimeMs}]`, `truncated` |
+| `stat` | `path` | `stat{type,size,mtimeMs,mode}` |
+| `mkdir` | `path`, `recursive?` | `created` |
+| `rename` | `path`, `to` | `path` (new) |
+| `delete` | `path`, `recursive?` | `ok` |
+| `glob` | `pattern` (`*`, `?`, `**`, `{a,b}`) | `paths`, `truncated` |
+| `grep` | `pattern` (RegExp), `path?`, `include?` (glob), `maxMatches?` | `matches[{path,line,text}]`, `truncated` |
+
+Rules and limits:
+
+- `read`/`write`/`list`/`stat`/`mkdir`/`rename`/`delete` require **absolute**
+  paths (`ok:false, error:"path must be absolute"`); `glob`/`grep` accept
+  relative paths/patterns resolved against `workspaceBase`.
+- read 1 MiB / 20 000 lines, write 4 MiB, list 5 000 entries, glob 2 000
+  paths, grep 500 matches, 15 s per request (a timed-out request answers
+  `ok:false, error:"request timed out"`).
+- Text vs binary: a NUL byte in the first 8 KiB (or `encoding:"base64"`) makes
+  the read return base64 `content`; everything else returns utf8 `text`.
+- Symlinks: `read` follows them like `cat`; `stat`/`list` report the link
+  itself; directory walks never follow symlinked directories (loop safety) and
+  skip `.git`; `write` follows an existing symlink.
+- grep skips binary files and files larger than 8 MiB; `include` matches the
+  basename or workspace-relative path.
+- OS errors are returned verbatim in `error` (e.g. `ENOENT: no such file or
+  directory, open '…'`); a request never throws out of the loop.
+
+`startRuntime().status()` additionally exposes `workspaceBase`, `capabilities`
+and the last advertised `features`.
+
 ## Files and environment
 
 | Path | Purpose |
 | --- | --- |
-| `${DSH_COMPUTERS_HOME:-$HOME/.dsh-computers}/config.json` | Credentials, mode `0600`, atomic tmp+rename |
+| `${DSH_COMPUTERS_HOME:-$HOME/.dsh-computers}/config.json` | Credentials + `workspaceBase`, mode `0600`, atomic tmp+rename |
 | `${DSH_COMPUTERS_HOME}/agent.log` | Append-only log, rotates at 5 MiB (keeps one `agent.log.1`) |
 | `~/Library/LaunchAgents/com.dsh.computers.agent.plist` | macOS service unit |
 | `~/.config/systemd/user/dsh-computers-agent.service` | Linux service unit |
@@ -178,7 +269,13 @@ Environment variables:
 - **Token**: generated by the server, stored only on this machine in a `0600`
   file, sent as `authorization: Bearer …` on every request. It is never printed,
   never logged, and `status` shows only its last 6 characters.
-- **Outbound only**: enroll, SSE stream, result POSTs, heartbeats. No listener.
+- **Outbound only**: enroll, SSE stream, result POSTs, heartbeats, chunk/fs
+  result POSTs. No listener.
+- **Remote files**: when the server advertises the `fs` feature it can read and
+  write files as your user, but only through the ops above; paths outside
+  `workspaceBase` are allowed when absolute (documented §11.3 semantics), while
+  relative paths are anchored at `workspaceBase`. Directory walks skip `.git`
+  and symlinked directories.
 - **Execution identity**: commands run as your user through
   `/bin/sh -lc '<command>'` (Windows: `cmd.exe /d /s /c`), inheriting your
   environment — the same power as your own terminal. Only connect your server
@@ -213,6 +310,7 @@ removed).
 | `launchctl bootstrap` fails (`5: Input/output error` / domain unsupported) | The `gui/<uid>` domain is unavailable — usually an SSH session without a GUI login. The agent falls back to `launchctl load -w`; if both fail, run `service start` once from a logged-in desktop terminal. |
 | `✗ 需要 Node.js >= 22` | Upgrade Node; the script relies on global `fetch` and modern ESM. |
 | Computer shows offline in the UI | Check `agent.log` for reconnect lines; the stream reconnects with 1 s → 30 s backoff. |
+| Streaming/file tools unavailable after upgrading | The host must advertise `stream`/`fs` in `hello.features`; old hosts get v1 behaviour by design (§11.5). The agent log line `已连接 … features=…` shows what the host offered. |
 
 ## Protocol notes (intentional choices)
 
@@ -273,4 +371,13 @@ paths:
   `running: false, connected: false, exitCode: 0`;
 - a foreign bare/other-JSON 401 is retried and the machine reconnects (throttled
   single warning), while JSON `invalid-token` exits 1 without retry;
-- 404/503 during connect are retried and the stream recovers.
+- 404/503 during connect are retried and the stream recovers;
+- §11: enroll reports `capabilities:['exec','fs']` + full handshake metadata,
+  the metadata header is on every SSE connect, `exec` defaults to
+  `workspaceBase`, typed chunk frames arrive with contiguous `seq` (stdout,
+  stderr and silent-command heartbeats), chunk POSTs retry once / drop without
+  killing the command, an old host (no `features`) gets no chunks and no fs,
+  and the fs ops round-trip (read text/binary + windows + limits, relative-path
+  rejection, write/list/stat/mkdir/rename/delete, glob with `**` and `{a,b}`,
+  grep with `include`/`maxMatches`/binary skip, and `stop()` during an
+  in-flight fs request leaves no result POST).