cueline 0.1.5 → 0.1.7

package/README.md

@@ -13,21 +13,34 @@
 
 **CueLine hands the wheel to an open ChatGPT web conversation: it plans the run and calls each next step, while CueLine checks every text command and the current Codex does the permitted local work.**
 
-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 `advise` jobs for the current Codex to execute and submit; an explicitly selected process executor can instead run registered local workers. CueLine keeps bounded controller evidence and the full local record.
+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.
 
 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
+
+- 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.
+
+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).
+
 ## How a run actually goes
 
 <img alt="A caller-first CueLine run: ChatGPT emits text commands, the current Codex performs local advice, and CueLine returns bounded evidence until complete." src="docs/assets/cueline-loop-en.svg" width="100%">
 
 Each round: CueLine writes down what it is about to ask, sends one observation into the conversation, and later reads back exactly one `<CueLineControl>` envelope. The controller picks one of five actions — `dispatch`, `wait`, `inspect`, `complete`, `blocked` — and nothing outside that envelope is ever executed. A command that names the wrong run, the wrong round, or a malformed job is sent back for a bounded repair attempt rather than guessed at. The loop pauses at `awaiting_controller` after one durable send, at a caller handoff, or stops at `complete`, `blocked`, or the round limit (12 by default).
 
+Controller commands also have fail-closed resource bounds: 131,072 characters
+per envelope, 64 jobs per dispatch, and 256 explicit job IDs per wait or
+inspect. These checks happen before job registration or process execution.
+
 A non-default `maxRounds` is fixed when the run is created and counts total controller rounds across every ownerless pause. Later continuations normally omit it and reuse the durable value; supplying a different value is rejected rather than silently resetting or widening the budget.
 
-`caller` is the default executor for both `startCueLineRun` and `runCueLine`. With the built-in browser, CueLine submits once, captures the exact conversation URL, returns `awaiting_controller`, and releases the runtime lease instead of holding one tool call open while Pro thinks. A later `continueCueLineRun` performs one read-only observation: unfinished work returns `awaiting_controller` again without resending. A dispatch then produces durable pending `advise` jobs and returns `awaiting_caller`; the current Codex executes each exact task with its local tools, calls `submitCueLineCallerJobResult`, and continues the same run. ChatGPT planned the work—it did not perform the inspection. Caller advice has no execution claim, so coordinate one session: two sessions may both perform it, while only the first terminal evidence submitted wins. Caller-mode `work` is rejected until CueLine can issue a duplicate-safe execution claim.
+`caller` is the default executor for both `startCueLineRun` and `runCueLine`. With the built-in browser, CueLine submits once, captures the exact conversation URL, returns `awaiting_controller`, and releases the runtime lease instead of holding one tool call open while Pro thinks. A later `continueCueLineRun` performs one read-only observation: unfinished work returns `awaiting_controller` again without resending. A dispatch produces durable pending jobs. `advise` returns `awaiting_caller`; it has no side-effect claim, so coordinate one session. `work` returns `awaiting_caller_work` and remains unstarted until the current Codex calls `claimCueLineCallerJob` and `startCueLineCallerJob`. The claim is bound to run, job, task hash, absolute workdir, canonical directory identity, caller identity, and a fencing token; callers execute only in its returned `resolvedWorkdir`. Started work is never automatically retried; an expired started claim becomes `ambiguous`. ChatGPT proposed and reviewed the work—it did not use local tools or perform the work itself.
 
-For explicit `executor: "process"`, the controller chooses *what should happen* and the local side chooses *whether and how it may happen*: the lane must be enabled, the candidate must be available **before** anything spawns, and `argv[0]` must already be registered by your routing config. Nothing is passed through a shell. Independent advice defaults to two concurrent jobs globally and per lane; a batch containing `work` is serial. Once a worker starts, there is no silent fallback to a second candidate.
+Process execution requires both `executor: "process"` and `allowProcessExecution: true`; a non-terminal continuation must pass the second authorization again. The bundled route also uses `--ignore-user-config`, preventing hidden workers from loading user-configured MCP servers or their command arguments. The controller chooses *what should happen* and the local side chooses *whether and how it may happen*: the lane must be enabled, the candidate must be available **before** anything spawns, and `argv[0]` must already be registered by your routing config. Nothing is passed through a shell. A process `workdir` must be absolute; when omitted, CueLine binds the accepted job to the runtime's resolved absolute workspace so recovery cannot silently move it to another checkout. Independent advice defaults to two concurrent jobs globally and per lane; a batch containing `work` is serial. Once a worker starts, there is no silent fallback to a second candidate. Status exposes the resolved runner, PID, phase, last progress time, and safely observed model/provider metadata.
 
 The controller protocol keeps routing levels explicit: `lane` names the lane (`default`), while `codex-default` is a candidate runner inside that lane, not a lane. CueLine validates the entire `dispatch` before registering any job; an invalid lane or runner rejects the whole dispatch for repair, so no valid-looking subset starts early.
 
@@ -48,15 +61,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.5
+npm install -g cueline@0.1.7
 cueline install
 cueline doctor
 ```
 
-As a fallback, install the packaged tarball from the [v0.1.5 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.5), which also carries its `.sha256` checksum:
+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:
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.5/cueline-0.1.5.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.7/cueline-0.1.7.tgz
 cueline install
 cueline doctor
 ```
@@ -79,7 +92,7 @@ cueline doctor
 Then, in Codex:
 
 1. Open `https://chatgpt.com` in Codex's built-in Browser and sign in.
-2. Leave the conversation you want to be in charge selected — that page is the controller. Its composer must be on a `Pro` model; CueLine selects `Pro` for you if it is not, and refuses to send otherwise.
+2. Leave the conversation you want to be in charge selected — that page is the controller. If no selected tab is available and several matching ChatGPT tabs exist, CueLine returns `IAB_CHATGPT_TAB_AMBIGUOUS` instead of choosing the first one. Its composer must be on a `Pro` model; CueLine selects `Pro` for you if it is not, and refuses to send otherwise.
 3. Ask Codex to use CueLine for the task: *"Use CueLine and let the open ChatGPT Pro conversation direct this task."*
 4. Keep the returned `runId`. It is how an interrupted run is resumed.
 
@@ -89,23 +102,27 @@ The bundled `cueline` skill drives the package from Codex's own Node runtime, wh
 
 ```js
 import {
+  claimCueLineCallerJob,
   continueCueLineRun,
   createCodexIabAdapter,
+  heartbeatCueLineCallerJob,
   runCueLine,
+  startCueLineCallerJob,
   submitCueLineCallerJobResult,
 } from "cueline";
 
 let result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
-  browser: createCodexIabAdapter(),
+  browser: createCodexIabAdapter({ browser: globalThis.browser }),
+  // Optional opt-in: archiveControllerConversationOnComplete: true,
   // Optional: conversationUrl, routingConfig / routingConfigPath, home, cwd,
   // runTimeoutMs, signal, and per-job/default limits.
 }); // defaults to executor: "caller"
 
-while (result.status === "awaiting_controller" || result.status === "awaiting_caller") {
+while (["awaiting_controller", "awaiting_caller", "awaiting_caller_work"].includes(result.status)) {
   if (result.status === "awaiting_controller") {
     await waitBeforeNextObservation(); // bounded backoff; never resend
-  } else {
+  } else if (result.status === "awaiting_caller") {
     for (const job of result.pendingJobs ?? []) {
       const stdout = await executeExactLocalAdvice(job.spec.task);
       await submitCueLineCallerJobResult(result.runId, job.jobId, {
@@ -113,6 +130,28 @@ while (result.status === "awaiting_controller" || result.status === "awaiting_ca
         stdout,
       });
     }
+  } else {
+    for (const job of result.pendingJobs ?? []) {
+      if (job.spec.mode !== "work") continue;
+      const claim = await claimCueLineCallerJob(result.runId, job.jobId, {
+        callerId: "stable-codex-task-identity",
+      });
+      const proof = {
+        claimId: claim.claimId,
+        callerId: claim.callerId,
+        fencingToken: claim.fencingToken,
+      };
+      await startCueLineCallerJob(result.runId, job.jobId, proof);
+      const stdout = await executeExactLocalWork(job.spec.task, claim.resolvedWorkdir, {
+        heartbeat: () => heartbeatCueLineCallerJob(result.runId, job.jobId, proof),
+      });
+      await submitCueLineCallerJobResult(
+        result.runId,
+        job.jobId,
+        { status: "succeeded", stdout },
+        { claim: proof },
+      );
+    }
   }
   result = await continueCueLineRun({ runId: result.runId });
 }
@@ -122,20 +161,26 @@ if (result.status === "complete") {
 }
 ```
 
-`startCueLineRun` creates the durable run and returns `ready` without driving the browser. `runCueLine` creates and advances it to a durable controller-observation pause, caller handoff, or terminal state. `continueCueLineRun({ runId })` advances the same conversation and reuses its stored URL. `loadCueLineRunState(runId)` is read-only. A terminal run is returned as-is. Before continuation, run `cueline run status <run-id> --json`: ownerless `controller_response_pending` with exactly one normally submitted turn and `safeNextAction: observe` means Pro's response has not yet been observed; wait briefly and continue it without resend. `phase: prompt_not_sent` with `safeNextAction: retry` is used only when the exact request has built-in write-ahead evidence or request-correlated `definitely_not_sent` evidence. `safeNextAction: reconcile` is reserved for ambiguous, manually submitted, or multiple pending turns. Ownerless `caller_jobs_pending` is a healthy local handoff; an accepted response plus `jobs_running` means an explicit process executor is active.
+`archiveControllerConversationOnComplete` defaults to `false` and is fixed when the run is created. When enabled, CueLine first persists `complete`, then archives only the exact bound conversation while Pro is idle. A proven failure before the durable click checkpoint can be retried; after that checkpoint, any timeout, restart, navigation race, or missing proof becomes `ambiguous` and CueLine never clicks Archive again. `blocked` and `cancelled` runs are left open.
+
+`startCueLineRun` creates the durable run and returns `ready` without driving the browser. `runCueLine` creates and advances it to a durable controller-observation pause, caller handoff, or terminal state. `continueCueLineRun({ runId })` advances the same conversation and reuses its stored URL. `loadCueLineRunState(runId)` is read-only. A terminal run is returned as-is. Before continuation, run `cueline run status <run-id> --json`: `controller_response_pending` with exactly one normally submitted turn and `safeNextAction: observe` means Pro's response has not yet been observed; wait briefly and continue it without resend. That exact read-only observer can be safely fenced even after its lease becomes stale, but ambiguous/manual submissions, jobs, pending commands, cancellation, or a missing/mismatched URL still require explicit recovery. `phase: prompt_not_sent` with `safeNextAction: retry` is used only with write-ahead or request-correlated `definitely_not_sent` evidence. Caller work phases report `claim_caller_work`, `start_caller_work`, or `continue_caller_work`; a dispatch alone is not local execution. An accepted response plus `jobs_running` means a double-authorized process executor is active. CLI status output is an explicit metadata allowlist: it omits task bodies, caller identities, task hashes, workdirs, and runtime owner IDs. The formal caller claim API returns the exact task and workdir to the authorized caller; the detailed read-only API remains available for trusted local diagnostics.
+
+`listCueLineRuns()` is a read-only, sanitized inventory for discovering persisted run IDs. It omits controller text, conversation URLs, job tasks, and worker output.
+
+`verifyCueLineRun(runId)` is a read-only integrity check for the creation marker, event replay and authority fences, optional snapshot, runtime lease, and job status evidence. It returns stable findings without returning durable run content.
 
 Inside Codex's runtime, import the absolute module that `cueline api path` prints — that is the built API of the package you installed.
 
 ## The CLI
 
-The CLI does not drive the browser. `doctor`, `routing`, `jobs`, `run status`, `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. `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.
 
 ```console
 $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.5
+CueLine 0.1.7
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -144,18 +189,45 @@ 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",...}
 
@@ -174,13 +246,33 @@ 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).
+
+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 `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).
+
 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.
 
 ## Configuration
 
 `CUELINE_CONFIG` selects a routing file; `CUELINE_HOME` moves local state (default `~/.cueline`).
 
-Caller execution needs no spawned route. When `executor: "process"` is explicitly selected, the bundled `default` lane holds one candidate, `codex-default`: `codex exec` 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.
+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.
 
 State lives under `CUELINE_HOME`:
 
@@ -196,11 +288,11 @@ jobs/<job-id>.json            per-job execution evidence
 
 The event log is the record: the controller turn is written before it is sent, and a job is registered before its process starts, so an interruption between intent and side effect leaves a trace. A corrupt snapshot is ignored and rebuilt from event 1 rather than trusted.
 
-Recovery reattaches only to the exact recorded conversation URL. CueLine recognizes long prompts that ChatGPT automatically converts into attachment chips and makes at most one send attempt. Contenteditable block newlines are normalized before readiness comparison. An ambiguous click is `possibly_sent` and is never clicked again. If an operator manually sends that attachment after ChatGPT creates the first `/c/...` URL, `cueline run reconcile ... --manual-send-confirmed --conversation-url URL` atomically binds the exact URL and records an append-only confirmation; CueLine then requires exact conversation, Pro model, and protocol/run/round/request identity before importing the response without resend or duplicate dispatch.
+Recovery reattaches only to the exact recorded conversation URL. CueLine recognizes long prompts that ChatGPT automatically converts into attachment chips and makes at most one send attempt. Contenteditable block newlines are normalized before readiness comparison. An ambiguous click is `possibly_sent` and is never clicked again. A response is considered in progress only while a visible, enabled, actionable Stop control exists; hidden residual buttons do not suppress a completed Pro response. If an operator manually sends an attachment after ChatGPT creates the first `/c/...` URL, `cueline run reconcile ... --manual-send-confirmed --conversation-url URL` atomically binds the exact URL and records an append-only confirmation; CueLine then requires exact conversation, Pro model, and protocol/run/round/request identity before importing the response without resend or duplicate dispatch.
 
 Never interrupt Pro or use `Answer now`, `Respond now`, `Stop`, or an equivalent acceleration control while it is answering. Pro has no local tools and no default knowledge of repository layout or local paths. Caller evidence must include exact code/error identifiers, relevant code excerpts, and absolute local paths, then explicitly ask whether Pro needs more local evidence.
 
-Controller observations prefer successful non-empty stdout, retain full stdout/stderr in local job status, and share one 12,000-character evidence budget with an explicit truncation marker.
+Controller observations prefer successful non-empty stdout, retain full stdout/stderr in local job status, and share one 12,000-character evidence budget with an explicit truncation marker. Every preferred output/error field includes a raw-character `evidence_window` and SHA-256 `content_hash`. When `next_offset` is non-null, Pro can inspect exactly one job by copying it as `evidence_offset` and the hash as `evidence_hash`; CueLine returns the next bounded window without rerunning the job. Changed evidence invalidates the cursor instead of mixing versions. An accepted `inspect(job_ids)` reserves that budget for the named jobs before unrelated evidence, so the next Pro turn receives the requested output instead of only its terminal status. `wait` and `inspect` targets must be exact job IDs from the current observation; one unknown target rejects the entire command for repair before any partial wait or inspection. Controller commands are exact per action: unknown top-level fields, fields belonging to another action, empty/duplicate/malformed `job_ids`, `prompt` in place of `task`, and `runner_id` in place of `runner` are rejected with a repair error instead of silently ignored.
 
 ## Verify
 
@@ -217,7 +309,7 @@ npm pack --dry-run
 
 ## Limits in 0.1
 
-Text commands only. One conversation per run. Selecting `Pro` is the only model switch CueLine makes. Automatic long-text-to-attachment conversion is supported, but deliberate file upload, images, Deep Research, Projects, and Apps are not. Caller mode is `advise` only; process `work` must be explicit. No automatic retry or fallback starts a worker twice. macOS is the primary desktop target and Linux is the CI target; Windows is unverified. The adapter depends on the current ChatGPT web UI, so a UI change surfaces explicitly, never as a fabricated answer.
+Text commands only. One conversation per run. Selecting `Pro` is the only model switch CueLine makes. Automatic long-text-to-attachment conversion is supported, but deliberate file upload, images, Deep Research, Projects, and Apps are not. Caller `work` requires an explicit durable claim/start and a heartbeat for long work; process execution requires two explicit authorization fields. No automatic retry or fallback starts work twice. macOS is the primary desktop target and Linux is the CI target; Windows is unverified. The adapter depends on the current ChatGPT web UI, so a UI change surfaces explicitly, never as a fabricated answer.
 
 See [compatibility](docs/compatibility.md) for the full matrix.
 

package/README.zh-CN.md

@@ -13,10 +13,19 @@
 
 **CueLine 把方向盘交给一个已经打开的 ChatGPT 网页会话：由它规划运行、发出每一步文本指令；CueLine 负责校验，当前 Codex 才在本机执行获准的工作。**
 
-那个网页碰不到你的机器，也没有本地工具。CueLine 默认把 `advise` 作业持久化并交回当前 Codex 执行；只有显式选择 `process` executor，才会启动已注册的本地 worker。
+那个网页碰不到你的机器，也没有本地工具。CueLine 默认把 caller 作业持久化：`advise` 是协调式交接；`work` 必须先获得持久 claim 并正式 start。只有双重显式授权 `process` executor，才会启动已注册的本地 worker。
 
 CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnilane 或 GPT Relay 的包装层。
 
+## 最新版本：0.1.7
+
+- 新增安全的 run 清单、doctor、watch、timeline、handoff、完整性验证、协议 lint、浏览器诊断与 inspect 证据分页。
+- 强化标签页／按钮证据、命令与路由上限、原子 job 状态、私有持久数据、workdir 身份、runtime／取消记录和 CLI 脱敏。
+- 新增可选的 `complete` 后精确会话归档：点击前有持久 fence，Pro 再次回答或页面切换时拒绝，进入模糊状态后绝不重复点击。
+- 完成 454/454 测试和一次可丢弃的真实 ChatGPT Web Pro 验收；控制器自然完成、只归档一次，原有用户会话未被触碰。
+
+完整内容请查看 [changelog](CHANGELOG.md#017---2026-07-16) 或不可变的 [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7)。
+
 ## 一次运行实际是怎么走的
 
 <img alt="Caller-first CueLine 运行：ChatGPT 发出文本命令，当前 Codex 执行本地只读检查，CueLine 回传有界证据直至 complete。" src="docs/assets/cueline-loop-zh-CN.svg" width="100%">
@@ -25,9 +34,9 @@ CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnil
 
 非默认的 `maxRounds` 会在创建 run 时固定，并跨所有无 owner 的暂停累计控制器总轮次。后续继续通常省略它并复用持久值；传入不同数值会被拒绝，不会暗中重置或放宽预算。
 
-`startCueLineRun` 与 `runCueLine` 都默认使用 `caller`。使用内置浏览器时，CueLine 只发送一次、保存精确会话 URL，然后返回 `awaiting_controller` 并释放 runtime lease，不会让单次工具调用一直等待 Pro。之后的 `continueCueLineRun` 只做一次只读观测；若尚未完成，会再次返回 `awaiting_controller`，绝不重发。`dispatch` 才返回 `awaiting_caller`；当前 Codex 执行各个 `advise` 任务、调用 `submitCueLineCallerJobResult`，再继续同一 run。Pro 控制器只下文本命令，不能使用本地工具。Caller advice 没有 execution claim，请协调由单一 session 执行；两个 session 可能都做同一项检查，但只有第一份提交的终态证据生效。Caller 模式明确拒绝 `work`。
+`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 只提出和审查文本指令，不会使用本地工具。
 
-控制器决定*应该发生什么*；本地这一侧决定*是否允许发生、以何种方式发生*：通道（lane）必须启用、候选必须在任何进程启动**之前**确认可用、`argv[0]` 必须早已由你的路由配置注册。没有任何内容会经过 shell。worker 一旦启动，就不会悄悄退回到第二个候选——失败以证据的形式返回，而不是自动重试。
+Process 模式必须同时指定 `executor: "process"` 与 `allowProcessExecution: true`，非终态继续也要再次传入第二道授权。内置 route 还使用 `--ignore-user-config`，不会让隐藏 worker 加载用户配置的 MCP server 或其命令参数。通道必须启用、候选必须在任何进程启动**之前**确认可用、`argv[0]` 必须已注册。没有内容经过 shell，也不会在启动后自动换候选。
 
 控制器协议有意区分路由层级：`lane` 填的是通道名称 `default`；`codex-default` 是该通道内的候选执行器，不是通道。CueLine 会在注册任何作业之前先验证整份 `dispatch`；只要包含无效通道或执行器，整份派工就会被退回修复，不会先执行其中一部分。
 
@@ -48,15 +57,15 @@ ChatGPT Pro 订阅套餐与“选定的 Pro 模型”是两回事。账号或个
 从 npm registry 安装：
 
 ```bash
-npm install -g cueline@0.1.5
+npm install -g cueline@0.1.7
 cueline install
 cueline doctor
 ```
 
-作为后备，也可以安装 [v0.1.5 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.5) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
+作为后备，也可以安装 [v0.1.7 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.7) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.5/cueline-0.1.5.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.7/cueline-0.1.7.tgz
 cueline install
 cueline doctor
 ```
@@ -89,23 +98,27 @@ cueline doctor
 
 ```js
 import {
+  claimCueLineCallerJob,
   continueCueLineRun,
   createCodexIabAdapter,
+  heartbeatCueLineCallerJob,
   runCueLine,
+  startCueLineCallerJob,
   submitCueLineCallerJobResult,
 } from "cueline";
 
 let result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
-  browser: createCodexIabAdapter(),
+  browser: createCodexIabAdapter({ browser: globalThis.browser }),
+  // 可选并显式启用：archiveControllerConversationOnComplete: true,
   // 可选：conversationUrl、routingConfig / routingConfigPath、home、cwd、
   // runTimeoutMs、signal，以及作业/默认期限。
 }); // 默认 executor: "caller"
 
-while (result.status === "awaiting_controller" || result.status === "awaiting_caller") {
+while (["awaiting_controller", "awaiting_caller", "awaiting_caller_work"].includes(result.status)) {
   if (result.status === "awaiting_controller") {
     await waitBeforeNextObservation(); // 有界退避；绝不重发
-  } else {
+  } else if (result.status === "awaiting_caller") {
     for (const job of result.pendingJobs ?? []) {
       const stdout = await executeExactLocalAdvice(job.spec.task);
       await submitCueLineCallerJobResult(result.runId, job.jobId, {
@@ -113,6 +126,19 @@ while (result.status === "awaiting_controller" || result.status === "awaiting_ca
         stdout,
       });
     }
+  } else {
+    for (const job of result.pendingJobs ?? []) {
+      if (job.spec.mode !== "work") continue;
+      const claim = await claimCueLineCallerJob(result.runId, job.jobId, {
+        callerId: "stable-codex-task-identity",
+      });
+      const proof = { claimId: claim.claimId, callerId: claim.callerId, fencingToken: claim.fencingToken };
+      await startCueLineCallerJob(result.runId, job.jobId, proof);
+      const stdout = await executeExactLocalWork(job.spec.task, claim.resolvedWorkdir, {
+        heartbeat: () => heartbeatCueLineCallerJob(result.runId, job.jobId, proof),
+      });
+      await submitCueLineCallerJobResult(result.runId, job.jobId, { status: "succeeded", stdout }, { claim: proof });
+    }
   }
   result = await continueCueLineRun({ runId: result.runId });
 }
@@ -122,22 +148,22 @@ if (result.status === "complete") {
 }
 ```
 
-若返回 `awaiting_controller`，表示同一个精确 request 已发送、但 Pro 回复尚未被观测；稍后继续只会执行只读观测，不会重发。若返回 `awaiting_caller`，由当前 Codex 执行 `result.pendingJobs` 中的每个 `advise`，用 `submitCueLineCallerJobResult` 提交真实结果，再调用 `continueCueLineRun`。这不是 Pro 网页直接使用本地工具。
+`awaiting_controller` 只读观测且不重发；`awaiting_caller` 交接 `advise`；`awaiting_caller_work` 必须依次 claim、start、执行、heartbeat 并带 claim proof 提交。Pro 网页从不直接使用本地工具。
 
 在 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。
+`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`、`run status`、`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 不驱动浏览器。`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` 核对完整参数。
 
 ```console
 $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.5
+CueLine 0.1.7
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -146,18 +172,30 @@ 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 takeover stale_run_... --json
 {"runId":"stale_run_...","outcome":"taken_over","next":"continue",...}
 
@@ -179,7 +217,7 @@ CueLine skill removed: /Users/you/.codex/skills/cueline
 
 `CUELINE_CONFIG` 用于指定路由配置文件；`CUELINE_HOME` 用于迁移本地状态（默认 `~/.cueline`）。
 
-Caller 模式不会启动路由进程。只有显式选择 `process` executor 时，内置 `default` 通道才以 `codex-default` 运行 `codex exec`；独立 `advise` 默认全局/每 lane 并发上限均为 2，包含 `work` 的批次保持串行。
+Caller 模式不会启动路由进程。只有同时选择 `executor: "process"` 与 `allowProcessExecution: true` 时，内置 `default` 通道才以 `codex-default` 运行隔离的 `codex exec --ignore-user-config`；独立 `advise` 默认全局/每 lane 并发上限均为 2，包含 `work` 的批次保持串行。
 
 状态位于 `CUELINE_HOME` 之下：
 
@@ -212,7 +250,7 @@ npm pack --dry-run
 
 ## 0.1 的限制
 
-仅支持文本控制命令。一次运行只对应一个会话。支持 ChatGPT 自动将长文本转为附件，但不支持主动文件上传、图片、Deep Research、Projects 或 Apps。Caller 模式只允许 `advise`；`work` 必须显式选择 process executor。模糊发送和已启动工作都不会被自动重试。
+仅支持文本控制命令。一次运行只对应一个会话。支持 ChatGPT 自动将长文本转为附件，但不支持主动文件上传、图片、Deep Research、Projects 或 Apps。Caller `work` 必须显式 claim/start；process 执行必须双重授权。模糊发送和已启动工作都不会被自动重试。
 
 完整矩阵见 [compatibility](docs/compatibility.md)。