cueline 0.1.7 → 0.2.0

package/README.md

@@ -5,6 +5,9 @@
 
 <p align="center">
   <a href="https://github.com/Seraphim0916/cueline/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/Seraphim0916/cueline/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/cueline"><img alt="npm" src="https://img.shields.io/npm/v/cueline"></a>
+  <a href="package.json"><img alt="node" src="https://img.shields.io/node/v/cueline"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/cueline"></a>
 </p>
 
 <p align="center">
@@ -15,16 +18,19 @@
 
 The web page never touches your machine and has no local tools. It only emits one text command per round. CueLine decides whether that command is well-formed and belongs to this run. By default, it persists caller jobs for the current Codex: `advise` is a coordination-only handoff, while `work` requires a durable claim and start before any mutation. An explicitly double-authorized process executor can instead run registered local workers. CueLine keeps bounded controller evidence and the full local record.
 
+<img alt="CueLine architecture: a ChatGPT web conversation issues one text command per round, CueLine validates and records it, and the current Codex performs the permitted local work." src="docs/assets/cueline-architecture-en.svg" width="100%">
+
 CueLine is a standalone implementation with **no runtime npm dependencies**. It is not a wrapper around Omnilane or GPT Relay.
 
-## Latest release: 0.1.7
+## Latest release: 0.2.0
 
+- Add four read-only observability commands and strengthen confirmed-not-sent submission recovery, with fail-closed redaction and pre-spawn routing explanations.
 - Added safe run inventory, doctor, watch, timeline, handoff, verification, protocol lint, browser diagnostics, and deterministic inspected-evidence pagination.
 - Hardened browser tab/control evidence, command/routing bounds, atomic job status, private durable state, workdir identity, runtime/cancellation records, and redacted CLI output.
 - Added opt-in exact-conversation archiving after durable `complete`, with a one-click write-ahead fence, Pro-active/navigation checks, and no retry after ambiguity.
-- Verified 454/454 tests and a disposable real ChatGPT Web Pro run that completed and archived exactly once without interrupting Pro or touching the existing user conversation.
+- Verified 479/479 tests and a disposable real ChatGPT Web Pro run that completed and archived exactly once without interrupting Pro or touching the existing user conversation.
 
-Read the complete [changelog](CHANGELOG.md#017---2026-07-16) or the immutable [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7).
+Read the complete [changelog](CHANGELOG.md#020---2026-07-16) or the versioned [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0).
 
 ## How a run actually goes
 
@@ -46,6 +52,12 @@ The controller protocol keeps routing levels explicit: `lane` names the lane (`d
 
 That process route is an allow-list, not a sandbox. A registered worker runs with the same permissions as the CueLine process itself; `advise` maps to a read-only Codex sandbox and `work` to `workspace-write`, but what you register is what you have authorized.
 
+## Run states
+
+<img alt="CueLine run states: ready, awaiting_controller, awaiting_caller, awaiting_caller_work, complete, blocked, cancelled — and what each one means." src="docs/assets/cueline-states-en.svg" width="100%">
+
+`cueline run status <run-id> --json` reports the durable state plus a `safeNextAction`; `cueline run doctor <run-id> --json` turns the same snapshot into stable finding codes and one safe next step. When anything is ambiguous — a possibly-sent click, an expired started claim, a manual attachment send — CueLine stops and asks for an explicit reconcile instead of resending. The full recovery contract lives in [state and recovery](docs/state-and-recovery.md).
+
 ## The controller must be a Pro model
 
 CueLine refuses to send unless the composer's model selector reads `Pro`. If the conversation sits on another model, CueLine switches the composer to `Pro` first — that is the only model switch it is allowed to make. In a verified live run it switched Instant to Pro and the reply came back as `gpt-5-6-pro`.
@@ -61,15 +73,15 @@ You need Node.js 22+, Codex with its built-in Browser, and — for the bundled d
 Install from the npm registry:
 
 ```bash
-npm install -g cueline@0.1.7
+npm install -g cueline@0.2.0
 cueline install
 cueline doctor
 ```
 
-As a fallback, install the packaged tarball from the [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7), which also carries its `.sha256` checksum:
+As a fallback, install the packaged tarball from the [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0), which also carries its `.sha256` checksum:
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.7/cueline-0.1.7.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
 cueline install
 cueline doctor
 ```
@@ -173,14 +185,17 @@ Inside Codex's runtime, import the absolute module that `cueline api path` print
 
 ## The CLI
 
-The CLI does not drive the browser. `doctor`, `routing`, `jobs`, `runs`, `run status`, `run verify`, `api path`, and `config path` are read-only. `install`/`uninstall` change the package-owned skill link. `run reconcile`, `run takeover`, `run reconcile-runtime`, `run cancel`/`run stop`, and `job cancel` append evidence or change durable local run/job state. Run `cueline help` for every positional argument and option before using a state-changing command.
+The CLI does not drive the browser. Run `cueline help` for every positional argument and option before using a state-changing command.
 
-```console
-$ cueline install
-CueLine skill installed: /Users/you/.codex/skills/cueline
+| Group | Commands | Effect |
+| --- | --- | --- |
+| Inspect | `doctor` · `routing` · `jobs` · `runs` · `run status` · `run doctor` · `run watch` · `run timeline` · `run verify` · `run handoff` · `protocol lint` · `api path` · `config path` | Read-only |
+| Install | `install` · `uninstall` | Create or remove only the package-owned skill link |
+| Recover | `run reconcile` · `run takeover` · `run reconcile-runtime` · `run cancel` / `run stop` · `job cancel` | Append evidence or change durable local run/job state |
 
+```console
 $ cueline doctor
-CueLine 0.1.7
+CueLine 0.2.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -189,82 +204,33 @@ caller_ready	yes
 caller_lanes	1
 process_available_lanes	1
 
-$ cueline doctor --json
-{"version":"0.1.7","status":"ok","node":{"version":"22.14.0","ok":true,"requirement":">=22"},...}
-
-$ cueline api path
-/usr/local/lib/node_modules/cueline/dist/src/api.js
-
 $ cueline routing
 default	codex-default	available
 
-$ cueline routing --json
-{"version":"0.1.7","availableLanes":1,"lanes":[{"name":"default","status":"available","selectedRunnerId":"codex-default"}],...}
-
-$ cueline jobs
-No jobs.
-
-$ cueline protocol lint response.txt --run-id run_... --round 3 --request-id msg_... --json
-{"valid":false,"issues":[{"code":"LEGACY_RUNNER_ID_FIELD",...}]}
-
-$ cueline runs
-No runs.
-
 $ cueline run status run_... --json
 {"status":"running","executor":"caller","phase":"caller_jobs_pending","runtime":{"ownership":"missing"},...}
 
 $ cueline run doctor run_... --json
 {"outcome":"action_required","phase":"caller_jobs_pending","nextAction":"execute_caller_jobs",...}
 
-$ cueline run watch run_... --after 42 --timeout-ms 5000 --json
-{"outcome":"changed","previousSequence":42,"currentSequence":43,...}
-
-$ cueline run handoff run_... --json
-{"schema":"cueline-handoff/0.1","run":{"runId":"run_...","safeNextAction":"execute_caller_jobs"},...}
-
-$ cueline run timeline run_... --after 40 --limit 20 --json
-{"schema":"cueline-timeline/0.1","entries":[{"sequence":41,"type":"job_status",...}],...}
-
-$ cueline run verify run_... --json
-{"runId":"run_...","outcome":"verified","marker":"valid",...}
-
-$ cueline run takeover stale_run_... --json
-{"runId":"stale_run_...","outcome":"taken_over","next":"continue",...}
-
 $ cueline run reconcile run_... --request-id msg_... --manual-send-confirmed --conversation-url https://chatgpt.com/c/...
 run_...\tmsg_...\tconfirmed
 
 $ cueline run cancel run_...
 run_...	requested	affected_jobs=0
-
-$ cueline config path
-/usr/local/lib/node_modules/cueline/config/routing.default.json
-
-$ cueline uninstall
-CueLine skill removed: /Users/you/.codex/skills/cueline
 ```
 
-`cueline doctor` exits non-zero when Node is too old or no enabled caller lane exists. `process_available_lanes` may be zero without degrading caller mode; use `cueline routing` to inspect process availability before explicitly selecting that executor. `cueline api path` is what the skill imports, so a packaged install needs no repository checkout. `cueline help` lists every command's exact syntax, including `--json` and the manual-reconcile confirmation flags.
-
-The experimental `run doctor` command converts a run snapshot into stable
-finding codes, bounded evidence, and a safe next action without writing state.
-See [`docs/experiments/run-doctor.md`](docs/experiments/run-doctor.md).
-
-The experimental `run watch` command performs a bounded, lease-free observation
-using the durable event sequence as its cursor. See
-[`docs/experiments/run-watch.md`](docs/experiments/run-watch.md).
+`cueline doctor` exits non-zero when Node is too old or no enabled caller lane exists. `process_available_lanes` may be zero without degrading caller mode; use `cueline routing` to inspect process availability before explicitly selecting that executor. `cueline api path` is what the skill imports, so a packaged install needs no repository checkout. Every command supports `--json` where shown by `cueline help`.
 
-The experimental `protocol lint` command validates a Pro envelope offline and
-reports all known contract corrections in one pass. See
-[`docs/experiments/protocol-lint.md`](docs/experiments/protocol-lint.md).
+The experimental diagnosis commands each have a focused doc:
 
-The experimental `run handoff` command produces a safe restart packet with
-exact identities and absolute paths. See
-[`docs/experiments/run-handoff.md`](docs/experiments/run-handoff.md).
-
-The experimental `run timeline` command exposes a sanitized, cursor-paginated
-audit view without raw event payloads. See
-[`docs/experiments/run-timeline.md`](docs/experiments/run-timeline.md).
+| Command | What it does | Doc |
+| --- | --- | --- |
+| `run doctor` | Converts a run snapshot into stable finding codes, bounded evidence, and a safe next action without writing state | [run-doctor](docs/experiments/run-doctor.md) |
+| `run watch` | Bounded, lease-free observation using the durable event sequence as its cursor | [run-watch](docs/experiments/run-watch.md) |
+| `protocol lint` | Validates a Pro envelope offline and reports all known contract corrections in one pass | [protocol-lint](docs/experiments/protocol-lint.md) |
+| `run handoff` | Produces a safe restart packet with exact identities and absolute paths | [run-handoff](docs/experiments/run-handoff.md) |
+| `run timeline` | Sanitized, cursor-paginated audit view without raw event payloads | [run-timeline](docs/experiments/run-timeline.md) |
 
 Use `run takeover` only when `run status` reports an exact stale owner. It refuses a fresh active heartbeat and returns `next: continue` or `next: reconcile_runtime`; follow that value instead of guessing.
 
@@ -274,6 +240,8 @@ Use `run takeover` only when `run status` reports an exact stale owner. It refus
 
 Caller execution needs no spawned route. When `executor: "process"` and `allowProcessExecution: true` are both selected, the bundled `default` lane holds one candidate, `codex-default`: isolated `codex exec --ignore-user-config` with the task on stdin, `read-only` for `advise`, and `workspace-write` for `work`. To register a different process worker, copy [`config/routing.default.json`](config/routing.default.json), add your candidate, and point `CUELINE_CONFIG` at it.
 
+For multiple model-specific candidates and advise-only wrapper examples, see [Multi-model routing](docs/multi-model-routing.md).
+
 State lives under `CUELINE_HOME`:
 
 ```text
@@ -315,7 +283,14 @@ See [compatibility](docs/compatibility.md) for the full matrix.
 
 ## Docs
 
-[architecture](docs/architecture.md) · [controller protocol](docs/controller-protocol.md) · [runner contract](docs/runner-contract.md) · [state and recovery](docs/state-and-recovery.md) · [compatibility](docs/compatibility.md) · [provenance](docs/provenance.md)
+| Doc | What it covers |
+| --- | --- |
+| [architecture](docs/architecture.md) | How the pieces fit and where the trust boundaries sit |
+| [controller protocol](docs/controller-protocol.md) | The `<CueLineControl>` envelope, the five actions, and repair rules |
+| [runner contract](docs/runner-contract.md) | What a registered process worker must and must not do |
+| [state and recovery](docs/state-and-recovery.md) | Durable state layout, ownership, and every recovery path |
+| [compatibility](docs/compatibility.md) | Supported platforms, runtimes, and UI assumptions |
+| [provenance](docs/provenance.md) | Where the design comes from and what it is not |
 
 ## Development
 

package/README.zh-CN.md

@@ -5,6 +5,9 @@
 
 <p align="center">
   <a href="https://github.com/Seraphim0916/cueline/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/Seraphim0916/cueline/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/cueline"><img alt="npm" src="https://img.shields.io/npm/v/cueline"></a>
+  <a href="package.json"><img alt="node" src="https://img.shields.io/node/v/cueline"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/cueline"></a>
 </p>
 
 <p align="center">
@@ -13,18 +16,21 @@
 
 **CueLine 把方向盘交给一个已经打开的 ChatGPT 网页会话：由它规划运行、发出每一步文本指令；CueLine 负责校验，当前 Codex 才在本机执行获准的工作。**
 
-那个网页碰不到你的机器，也没有本地工具。CueLine 默认把 caller 作业持久化：`advise` 是协调式交接；`work` 必须先获得持久 claim 并正式 start。只有双重显式授权 `process` executor，才会启动已注册的本地 worker。
+那个网页碰不到你的机器，也没有本地工具。它每一轮只发出一条文本控制指令。CueLine 默认把 caller 作业持久化：`advise` 是协调式交接；`work` 必须先获得持久 claim 并正式 start。只有双重显式授权 `process` executor，才会启动已注册的本地 worker。
+
+<img alt="CueLine 架构：ChatGPT 网页会话每轮发出一条文本指令，CueLine 校验并记录，当前 Codex 执行获准的本地工作。" src="docs/assets/cueline-architecture-zh-CN.svg" width="100%">
 
 CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnilane 或 GPT Relay 的包装层。
 
-## 最新版本：0.1.7
+## 最新版本：0.2.0
 
+- 新增四个只读可观测性命令，并强化“确认未发送”的提交恢复；输出保持 fail-closed 脱敏，路由解释也只发生在进程启动前。
 - 新增安全的 run 清单、doctor、watch、timeline、handoff、完整性验证、协议 lint、浏览器诊断与 inspect 证据分页。
 - 强化标签页／按钮证据、命令与路由上限、原子 job 状态、私有持久数据、workdir 身份、runtime／取消记录和 CLI 脱敏。
 - 新增可选的 `complete` 后精确会话归档：点击前有持久 fence，Pro 再次回答或页面切换时拒绝，进入模糊状态后绝不重复点击。
-- 完成 454/454 测试和一次可丢弃的真实 ChatGPT Web Pro 验收；控制器自然完成、只归档一次，原有用户会话未被触碰。
+- 完成 479/479 测试和一次可丢弃的真实 ChatGPT Web Pro 验收；控制器自然完成、只归档一次，原有用户会话未被触碰。
 
-完整内容请查看 [changelog](CHANGELOG.md#017---2026-07-16) 或不可变的 [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7)。
+完整内容请查看 [changelog](CHANGELOG.md#020---2026-07-16) 或版本化的 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0)。
 
 ## 一次运行实际是怎么走的
 
@@ -32,6 +38,8 @@ CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnil
 
 每一轮：CueLine 先把“接下来要问什么”写入记录，向会话发送一份观测（observation），之后再读回**恰好一个** `<CueLineControl>` 信封。控制器从五个动作中选一个——`dispatch`、`wait`、`inspect`、`complete`、`blocked`——信封之外的任何文本都不会被执行。循环会在一次可靠发送后以 `awaiting_controller` 暂停，也会停在 caller 交接、`complete`、`blocked` 或轮次上限（默认 12 轮）。
 
+控制器命令还有 fail-closed 资源上限：每个信封 131,072 字符、每次 dispatch 最多 64 个作业、每次 wait 或 inspect 最多 256 个显式 job ID。这些检查发生在注册作业或启动进程之前。
+
 非默认的 `maxRounds` 会在创建 run 时固定，并跨所有无 owner 的暂停累计控制器总轮次。后续继续通常省略它并复用持久值；传入不同数值会被拒绝，不会暗中重置或放宽预算。
 
 `startCueLineRun` 与 `runCueLine` 都默认使用 `caller`。CueLine 发送一次后返回 `awaiting_controller` 并释放 lease；继续只做一次只读观测，绝不重发。`advise` 返回 `awaiting_caller`，没有副作用 claim；`work` 返回 `awaiting_caller_work`，必须由当前 Codex 调用 `claimCueLineCallerJob` 与 `startCueLineCallerJob` 后才能修改。claim 绑定 run、job、task hash、绝对 workdir、caller identity 与 fencing token；已开始的工作不会自动重试，过期后成为 `ambiguous`。Pro 只提出和审查文本指令，不会使用本地工具。
@@ -42,6 +50,12 @@ Process 模式必须同时指定 `executor: "process"` 与 `allowProcessExecutio
 
 这是白名单（allow-list），不是沙箱。已注册的 worker 拥有与 CueLine 进程本身相同的权限；`advise` 对应 Codex 的只读沙箱、`work` 对应 `workspace-write`，但你注册了什么，就等于你授权了什么。
 
+## 运行状态
+
+<img alt="CueLine 运行状态：ready、awaiting_controller、awaiting_caller、awaiting_caller_work、complete、blocked、cancelled，以及每个状态的含义。" src="docs/assets/cueline-states-zh-CN.svg" width="100%">
+
+`cueline run status <run-id> --json` 报告持久状态和 `safeNextAction`；`cueline run doctor <run-id> --json` 把同一份快照转成稳定的 finding 代码和一个安全的下一步。任何模糊情形——可能已发送的点击、过期的已启动 claim、人工附件发送——CueLine 都会停下来要求显式 reconcile，而不是重发。完整恢复契约见 [state and recovery](docs/state-and-recovery.md)。
+
 ## 控制器必须是 Pro 模型
 
 除非输入框的模型选择器显示 `Pro`，否则 CueLine 拒绝发送。会话若停在别的模型，CueLine 会先把输入框切换到 `Pro`——这是它唯一被允许做的模型切换。在一次已验证的实机运行中，它把 Instant 切换为 Pro，返回的响应是 `gpt-5-6-pro`。
@@ -57,15 +71,15 @@ ChatGPT Pro 订阅套餐与“选定的 Pro 模型”是两回事。账号或个
 从 npm registry 安装：
 
 ```bash
-npm install -g cueline@0.1.7
+npm install -g cueline@0.2.0
 cueline install
 cueline doctor
 ```
 
-作为后备，也可以安装 [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
+作为后备，也可以安装 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.7/cueline-0.1.7.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
 cueline install
 cueline doctor
 ```
@@ -88,7 +102,7 @@ cueline doctor
 然后，在 Codex 里：
 
 1. 用 Codex 的内置浏览器打开 `https://chatgpt.com` 并登录。
-2. 让你想让它当控制器的那个会话保持选中——该页面就是控制器。它的输入框必须停在 `Pro` 模型；若不是，CueLine 会替你选成 `Pro`，否则就拒绝发送。
+2. 让你想让它当控制器的那个会话保持选中——该页面就是控制器。若没有已选中的标签页、且同时存在多个匹配的 ChatGPT 标签页，CueLine 会返回 `IAB_CHATGPT_TAB_AMBIGUOUS`，而不是擅自挑第一个。它的输入框必须停在 `Pro` 模型；若不是，CueLine 会替你选成 `Pro`，否则就拒绝发送。
 3. 让 Codex 用 CueLine 处理任务：*“用 CueLine，让那个打开的 ChatGPT Pro 会话来指挥这项任务。”*
 4. 保留返回的 `runId`。被中断的运行要续跑，就靠它。
 
@@ -148,22 +162,31 @@ if (result.status === "complete") {
 }
 ```
 
+`archiveControllerConversationOnComplete` 默认为 `false`，并在创建 run 时固定。启用后，CueLine 会先把 `complete` 写入持久记录，再在 Pro 空闲时只归档那一个精确绑定的会话。点击 fence 前能证明尚未点击的失败可以重试；fence 之后只要超时、重启、页面切换或缺少完成证据，就标为 `ambiguous` 且永不再点。`blocked` 与 `cancelled` 一律保留原会话。
+
 `awaiting_controller` 只读观测且不重发；`awaiting_caller` 交接 `advise`；`awaiting_caller_work` 必须依次 claim、start、执行、heartbeat 并带 claim proof 提交。Pro 网页从不直接使用本地工具。
 
+`listCueLineRuns()` 是只读且已脱敏的 run 清单，可用来找回持久化的 run ID；它不包含控制器文本、会话 URL、作业内容或 worker 输出。
+
+`verifyCueLineRun(runId)` 是只读完整性检查，会核对创建 marker、event replay 与 authority fence、可选 snapshot、runtime lease 和 job status 证据；只返回稳定 finding，不返回持久 run 内容。
+
 在 Codex 的 runtime 里，import `cueline api path` 打印出的那个绝对路径模块——那就是你安装的那份包构建出来的 API。
 
 `startCueLineRun` 只创建持久 run 并返回 `ready`；`runCueLine` 创建并推进到持久 controller 观测暂停、caller 交接或终态。缺少 owner 的 `controller_response_pending` 若只有一个正常发送的回合且显示 `safeNextAction: observe`，表示同一个 Pro 回复仍待只读观测；稍后继续即可且不得重发。`safeNextAction: reconcile` 只用于模糊、人工发送或多个待对账回合。缺少 owner 的 `caller_jobs_pending` 是正常本地交接，并非 orphan，也不是仍在等 ChatGPT。CLI 的 `run status` 只输出交接所需元数据，不包含 task 正文、caller 身份、task hash、workdir 或 runtime owner ID；正式 claim 后，API 才把精确 task 与 workdir 交给获授权的 caller。
 
 ## CLI
 
-CLI 不驱动浏览器。`doctor`、`routing`、`jobs`、`runs`、`run status`、`run verify`、`api path`、`config path` 都是只读；`install`/`uninstall` 只修改包所拥有的 skill 链接；`run reconcile`、`run takeover`、`run reconcile-runtime`、`run cancel`/`run stop`、`job cancel` 会追加审计证据或修改持久 run/job 状态。执行写入状态的命令前，先用 `cueline help` 核对完整参数。
+CLI 不驱动浏览器。执行写入状态的命令前，先用 `cueline help` 核对完整参数。
 
-```console
-$ cueline install
-CueLine skill installed: /Users/you/.codex/skills/cueline
+| 分组 | 命令 | 效果 |
+| --- | --- | --- |
+| 查看 | `doctor` · `routing` · `jobs` · `runs` · `run status` · `run doctor` · `run watch` · `run timeline` · `run verify` · `run handoff` · `protocol lint` · `api path` · `config path` | 只读 |
+| 安装 | `install` · `uninstall` | 只创建或移除包所拥有的 skill 链接 |
+| 恢复 | `run reconcile` · `run takeover` · `run reconcile-runtime` · `run cancel` / `run stop` · `job cancel` | 追加审计证据或修改持久 run/job 状态 |
 
+```console
 $ cueline doctor
-CueLine 0.1.7
+CueLine 0.2.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -172,52 +195,41 @@ caller_ready	yes
 caller_lanes	1
 process_available_lanes	1
 
-$ cueline doctor --json
-{"version":"0.1.7","status":"ok","node":{"version":"22.14.0","ok":true,"requirement":">=22"},...}
-
-$ cueline api path
-/usr/local/lib/node_modules/cueline/dist/src/api.js
-
 $ cueline routing
 default	codex-default	available
 
-$ cueline routing --json
-{"version":"0.1.7","availableLanes":1,"lanes":[{"name":"default","status":"available","selectedRunnerId":"codex-default"}],...}
-
-$ cueline jobs
-No jobs.
-
-$ cueline runs
-No runs.
-
 $ cueline run status run_... --json
 {"status":"running","executor":"caller","phase":"caller_jobs_pending","runtime":{"ownership":"missing"},...}
 
-$ cueline run verify run_... --json
-{"runId":"run_...","outcome":"verified","marker":"valid",...}
+$ cueline run doctor run_... --json
+{"outcome":"action_required","phase":"caller_jobs_pending","nextAction":"execute_caller_jobs",...}
 
-$ cueline run takeover stale_run_... --json
-{"runId":"stale_run_...","outcome":"taken_over","next":"continue",...}
+$ cueline run reconcile run_... --request-id msg_... --manual-send-confirmed --conversation-url https://chatgpt.com/c/...
+run_...\tmsg_...\tconfirmed
 
 $ cueline run cancel run_...
 run_...	requested	affected_jobs=0
-
-$ cueline config path
-/usr/local/lib/node_modules/cueline/config/routing.default.json
-
-$ cueline uninstall
-CueLine skill removed: /Users/you/.codex/skills/cueline
 ```
 
 当 Node 版本过旧、或没有任何已启用的 caller 通道时，`cueline doctor` 会以非零状态退出。`process_available_lanes` 可以为 0 而不影响 caller 模式；只有显式选择 process executor 前才需要用 `cueline routing` 检查 process 可用性。`cueline api path` 打印的就是 skill 会 import 的模块，所以使用打包安装时完全不需要 clone 源码。`cueline help` 会列出每个命令的精确语法，包括 `--json` 和人工 reconcile 的必需确认参数。
 
+实验性的诊断命令各有专属文档：
+
+| 命令 | 用途 | 文档 |
+| --- | --- | --- |
+| `run doctor` | 把 run 快照转成稳定 finding 代码、有界证据与一个安全下一步，不写入任何状态 | [run-doctor](docs/experiments/run-doctor.md) |
+| `run watch` | 以持久事件序号为游标，做有界、不占 lease 的观察 | [run-watch](docs/experiments/run-watch.md) |
+| `protocol lint` | 离线校验 Pro 信封，一次报告所有已知的契约修正 | [protocol-lint](docs/experiments/protocol-lint.md) |
+| `run handoff` | 产出带精确身份与绝对路径的安全重启包 | [run-handoff](docs/experiments/run-handoff.md) |
+| `run timeline` | 脱敏、游标分页的审计视图，不含原始事件内容 | [run-timeline](docs/experiments/run-timeline.md) |
+
 只有 `run status` 明确显示 stale owner 时才能使用 `run takeover`。新鲜的 active heartbeat 会被拒绝；命令返回 `next: continue` 或 `next: reconcile_runtime`，请按该值行动，不要自行猜测。
 
 ## 配置
 
 `CUELINE_CONFIG` 用于指定路由配置文件；`CUELINE_HOME` 用于迁移本地状态（默认 `~/.cueline`）。
 
-Caller 模式不会启动路由进程。只有同时选择 `executor: "process"` 与 `allowProcessExecution: true` 时，内置 `default` 通道才以 `codex-default` 运行隔离的 `codex exec --ignore-user-config`；独立 `advise` 默认全局/每 lane 并发上限均为 2，包含 `work` 的批次保持串行。
+Caller 模式不会启动路由进程。只有同时选择 `executor: "process"` 与 `allowProcessExecution: true` 时，内置 `default` 通道才以 `codex-default` 运行隔离的 `codex exec --ignore-user-config`；独立 `advise` 默认全局/每 lane 并发上限均为 2，包含 `work` 的批次保持串行。要注册不同的 process worker，复制 [`config/routing.default.json`](config/routing.default.json)、加入你的候选项，再把 `CUELINE_CONFIG` 指过去。
 
 状态位于 `CUELINE_HOME` 之下：
 
@@ -233,7 +245,11 @@ jobs/<job-id>.json            每个作业的执行证据
 
 事件日志才是记录本身：控制器这一轮在发送之前先写入、作业在进程启动之前先注册，因此“意图”与“副作用”之间若被中断，会留下痕迹。损坏的快照会被忽略并从第 1 号事件重建，而不是被信任。
 
-续跑只接回完全相同的会话 URL。ChatGPT 自动把长文本转换成附件时，CueLine 识别 `attachment_ready` 且最多点击一次；模糊点击记为 `possibly_sent`，绝不补点或重发。人工发送附件后，使用 `cueline run reconcile RUN_ID --request-id REQUEST_ID --manual-send-confirmed` 写入正式确认；仍须通过完全一致的 conversation、Pro 证据与 protocol/run/round/request identity。控制器证据优先使用成功且非空的 stdout，全局上限 12,000 字符；完整 stdout/stderr 保留在本地。
+续跑只接回完全相同的会话 URL。ChatGPT 自动把长文本转换成附件时，CueLine 识别 `attachment_ready` 且最多点击一次；模糊点击记为 `possibly_sent`，绝不补点或重发。只有实际可见、启用且可操作的 Stop 按钮才表示 Pro 仍在回答；隐藏残留按钮不会挡住已完成的回复。人工发送附件后，使用 `cueline run reconcile RUN_ID --request-id REQUEST_ID --manual-send-confirmed` 写入正式确认；仍须通过完全一致的 conversation、Pro 证据与 protocol/run/round/request identity。
+
+Pro 回答时绝不要打断它，也不要用 `Answer now`、`Respond now`、`Stop` 或任何等效的加速控制。Pro 没有本地工具，也不默认了解 repository 布局或本地路径。Caller 证据必须包含精确的代码/错误标识、相关代码摘录与绝对本地路径，并明确询问 Pro 是否还需要更多本地证据。
+
+控制器证据优先使用成功且非空的 stdout，全局上限 12,000 字符；完整 stdout/stderr 保留在本地。若 Pro 接受 `inspect(job_ids)`，下一轮会先为指定 job 保留证据预算，再处理无关作业。
 
 ## 验证
 
@@ -250,13 +266,22 @@ npm pack --dry-run
 
 ## 0.1 的限制
 
-仅支持文本控制命令。一次运行只对应一个会话。支持 ChatGPT 自动将长文本转为附件，但不支持主动文件上传、图片、Deep Research、Projects 或 Apps。Caller `work` 必须显式 claim/start；process 执行必须双重授权。模糊发送和已启动工作都不会被自动重试。
+仅支持文本控制命令。一次运行只对应一个会话。选成 `Pro` 是 CueLine 唯一会做的模型切换。支持 ChatGPT 自动将长文本转为附件，但不支持主动文件上传、图片、Deep Research、Projects 或 Apps。Caller `work` 必须显式 claim/start，长工作需要 heartbeat；process 执行必须双重授权。模糊发送和已启动工作都不会被自动重试。macOS 是主要桌面目标、Linux 是 CI 目标；Windows 未验证。adapter 依赖当前 ChatGPT 网页 UI，UI 改版会被显式暴露，绝不会变成捏造的答案。
 
 完整矩阵见 [compatibility](docs/compatibility.md)。
 
 ## 文档
 
-[architecture](docs/architecture.md) · [controller protocol](docs/controller-protocol.md) · [runner contract](docs/runner-contract.md) · [state and recovery](docs/state-and-recovery.md) · [compatibility](docs/compatibility.md) · [provenance](docs/provenance.md)（均为英文）
+| 文档 | 内容 |
+| --- | --- |
+| [architecture](docs/architecture.md) | 各组件如何组合、信任边界在哪里 |
+| [controller protocol](docs/controller-protocol.md) | `<CueLineControl>` 信封、五个动作与修复规则 |
+| [runner contract](docs/runner-contract.md) | 已注册的 process worker 必须做与不得做的事 |
+| [state and recovery](docs/state-and-recovery.md) | 持久状态布局、ownership 与每一条恢复路径 |
+| [compatibility](docs/compatibility.md) | 支持的平台、runtime 与 UI 假设 |
+| [provenance](docs/provenance.md) | 设计从哪里来、它不是什么 |
+
+（以上均为英文）
 
 ## 开发