cueline 0.1.6 → 0.2.0

package/docs/assets/cueline-states-zh-CN.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 424" width="1000" height="424" role="img" aria-label="CueLine 运行状态：ready、awaiting_controller、awaiting_caller、awaiting_caller_work、complete、blocked、cancelled，以及每个状态的含义。">
+  <title>CueLine 运行状态</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", "PingFang SC", "Microsoft YaHei", monospace }
+    .hd   { fill: #0F1720; font-size: 17px; letter-spacing: .02em }
+    .sub  { fill: #8B949E; font-size: 13.5px }
+    .rule { stroke: #E4E8EC; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 14px }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+    }
+  </style>
+
+  <text x="40" y="44" class="hd">运行状态</text>
+  <text x="40" y="64" class="sub">状态值为 API 原文字符串</text>
+  <path d="M40 84H960" class="rule"/>
+
+  <text x="60" y="122" class="say">ready</text>
+  <text x="340" y="122" class="obs">已创建且持久化；尚未发送任何内容</text>
+
+  <text x="60" y="156" class="say">awaiting_controller</text>
+  <text x="340" y="156" class="obs">已完成一次持久发送——只观测、绝不重发</text>
+
+  <text x="60" y="190" class="say">awaiting_caller</text>
+  <text x="340" y="190" class="obs">advise 交接——仅协调，无副作用 claim</text>
+
+  <text x="60" y="224" class="say">awaiting_caller_work</text>
+  <text x="340" y="224" class="obs">work 待办——claim + start 之前绝不开始</text>
+
+  <text x="60" y="258" class="say">complete</text>
+  <text x="340" y="258" class="obs">最终交付逐字返回；可选归档，恰好一次</text>
+
+  <text x="60" y="292" class="say">blocked</text>
+  <text x="340" y="292" class="obs">控制器附明确理由停下</text>
+
+  <text x="60" y="326" class="say">cancelled</text>
+  <text x="340" y="326" class="obs">持久取消；已开始的无主工作变为 ambiguous</text>
+
+  <path d="M40 352H960" class="rule"/>
+  <text x="40" y="378" class="foot">任何模糊状态都需要显式 reconcile——CueLine 绝不重发、绝不靠猜。</text>
+  <text x="40" y="400" class="foot">轮次上限默认 12；非默认 maxRounds 在创建 run 时即固定。</text>
+</svg>

package/docs/assets/cueline-states-zh-TW.svg

@@ -0,0 +1,48 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 424" width="1000" height="424" role="img" aria-label="CueLine 執行狀態：ready、awaiting_controller、awaiting_caller、awaiting_caller_work、complete、blocked、cancelled，以及每個狀態的意義。">
+  <title>CueLine 執行狀態</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", "PingFang TC", "Microsoft JhengHei", monospace }
+    .hd   { fill: #0F1720; font-size: 17px; letter-spacing: .02em }
+    .sub  { fill: #8B949E; font-size: 13.5px }
+    .rule { stroke: #E4E8EC; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 14px }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+    }
+  </style>
+
+  <text x="40" y="44" class="hd">執行狀態</text>
+  <text x="40" y="64" class="sub">狀態值為 API 原文字串</text>
+  <path d="M40 84H960" class="rule"/>
+
+  <text x="60" y="122" class="say">ready</text>
+  <text x="340" y="122" class="obs">已建立且持久化；尚未送出任何東西</text>
+
+  <text x="60" y="156" class="say">awaiting_controller</text>
+  <text x="340" y="156" class="obs">已完成一次持久送出——只觀測、絕不重送</text>
+
+  <text x="60" y="190" class="say">awaiting_caller</text>
+  <text x="340" y="190" class="obs">advise 交接——僅協調，無副作用 claim</text>
+
+  <text x="60" y="224" class="say">awaiting_caller_work</text>
+  <text x="340" y="224" class="obs">work 待辦——claim + start 之前絕不開始</text>
+
+  <text x="60" y="258" class="say">complete</text>
+  <text x="340" y="258" class="obs">最終交付逐字回傳；選用封存，恰好一次</text>
+
+  <text x="60" y="292" class="say">blocked</text>
+  <text x="340" y="292" class="obs">主控端附明確理由停下</text>
+
+  <text x="60" y="326" class="say">cancelled</text>
+  <text x="340" y="326" class="obs">持久取消；已開始的無主工作轉為 ambiguous</text>
+
+  <path d="M40 352H960" class="rule"/>
+  <text x="40" y="378" class="foot">任何含糊狀態都需要明確 reconcile——CueLine 絕不重送、絕不用猜的。</text>
+  <text x="40" y="400" class="foot">輪數上限預設 12；非預設 maxRounds 在建立 run 時即固定。</text>
+</svg>

package/docs/compatibility.md

@@ -54,7 +54,7 @@ The v0.1 adapter relies on accessible textbox/button roles, attachment chips, an
 
 ## CLI boundary
 
-`cueline doctor`, `routing`, `jobs`, `run status`, `api path`, and `config path` are read-only. `install`/`uninstall` change only the package-owned skill link. `run reconcile`, `run takeover`, `run reconcile-runtime`, `run cancel` / `run stop`, and `job cancel` append audit evidence or change local durable state; `cueline help` lists their exact positional syntax and options. None drives the ChatGPT page. `run reconcile --manual-send-confirmed --conversation-url URL` can atomically bind the first exact URL created by a manual send; the imported API still performs identity/Pro reconciliation through Codex's IAB browser object. `run takeover` retires only an exact stale owner/heartbeat and refuses a fresh active owner; every process run is directed through `reconcile-runtime` before continuation.
+`cueline doctor`, `routing`, `jobs`, `runs`, `run status`, `run verify`, `api path`, and `config path` are read-only. `doctor --json` returns typed caller/process readiness and keeps invalid routing configuration failures parseable without echoing configuration content. `routing --json` reports each lane's enabled/available state and selected runner ID without exposing candidate argv or environment values. `install`/`uninstall` change only the package-owned skill link. `run reconcile`, `run takeover`, `run reconcile-runtime`, `run cancel` / `run stop`, and `job cancel` append audit evidence or change local durable state; `cueline help` lists their exact positional syntax and options. None drives the ChatGPT page. `run reconcile --manual-send-confirmed --conversation-url URL` can atomically bind the first exact URL created by a manual send; the imported API still performs identity/Pro reconciliation through Codex's IAB browser object. `run takeover` retires only an exact stale owner/heartbeat and refuses a fresh active owner; every process run is directed through `reconcile-runtime` before continuation.
 
 ## Live readiness checklist
 

package/docs/controller-protocol.md

@@ -13,6 +13,12 @@ Every command must echo these values from the pending observation:
 
 A stale or mismatched value is rejected. CueLine parses only the **last complete** control envelope, which prevents an older example earlier in the assistant response from winning.
 
+### Not-sent retry identity
+
+Operator-confirmed not-sent recovery abandons the original request identity and creates exactly one new request ID. The controller sees the new identity in the next observation and must echo it. CueLine verifies that the regenerated prompt matches the abandoned checkpoint hash after replacing only the request ID; a changed instruction, observation, or other prompt content is not a recovery retry.
+
+The abandoned identity remains durable. If later browser evidence or a control envelope proves that the abandoned user message or response actually appeared, CueLine fails closed and requires manual review. It never accepts an old envelope as the new retry's result.
+
 ## Observation
 
 ```json
@@ -28,14 +34,22 @@ A stale or mismatched value is rejected. CueLine parses only the **last complete
       "job_key": "review",
       "required": true,
       "status": "succeeded",
-      "output": "Review evidence"
+      "output": "Review evidence",
+      "evidence_window": {
+        "field": "output",
+        "offset": 0,
+        "end": 15,
+        "total_chars": 15,
+        "next_offset": null,
+        "content_hash": "61f2be400c13cff37284a92d51a9e4c3445bf8bbf67b8b8e92e5e1e4e1b337de"
+      }
     }
   ],
   "notices": []
 }
 ```
 
-Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`, or `ambiguous`. Successful jobs with non-empty stdout use stdout as controller evidence instead of a combined stdout/stderr stream. Failed and timed-out jobs retain bounded diagnostic error evidence. All job evidence in one controller observation shares a global 12,000-character budget; omitted content is reported once with the exact omitted count. After an accepted `inspect(job_ids)`, the named jobs receive that budget before unrelated jobs. Full stdout/stderr remain in local job status, and only the most recent 20 notices are sent. The local event log remains the recovery record.
+Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`, or `ambiguous`. Successful jobs with non-empty stdout use stdout as controller evidence instead of a combined stdout/stderr stream. Failed and timed-out jobs retain bounded diagnostic error evidence. All job evidence in one controller observation shares a global 12,000-character budget; omitted content is reported once with the exact omitted count. `evidence_window` identifies the preferred field and its raw-character `offset`, exclusive `end`, `total_chars`, deterministic `next_offset`, and SHA-256 `content_hash`. Full stdout/stderr remain in local job status, and only the most recent 20 notices are sent. The local event log remains the recovery record.
 
 ## Command envelope
 
@@ -54,6 +68,14 @@ Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, `cancel
 
 Text outside the envelope is not executed. CueLine does not request or consume private chain-of-thought; concise user-facing rationale may stay outside the envelope.
 
+Each action has an exact field set. Unknown top-level fields and fields defined for a different action are rejected before the command is accepted; CueLine never silently drops them and then executes a different interpretation.
+
+One control envelope is limited to 131,072 characters before JSON parsing. A
+single `dispatch` may contain at most 64 jobs, and `wait` or `inspect` may name
+at most 256 job IDs. Omit `job_ids` to select all current jobs instead of
+building an oversized reference list. Exceeding a bound requests a repaired
+command with the same pending identity; no job is registered or started.
+
 ## Actions
 
 ### `dispatch`
@@ -81,19 +103,34 @@ Schedules one or more local jobs.
 }
 ```
 
-`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. `runner_id` is invalid and produces an explicit correction to use `runner`. The local runtime—not ChatGPT—resolves the configured executable. `lane` must be a listed available lane; a runner ID is not a lane name. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. CueLine validates every new route in the dispatch before registering or starting any job. One invalid route rejects the whole command and requests a corrected envelope with the same pending identity. Repeating an already persisted deterministic job is ignored rather than executed again.
+`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. `prompt` is invalid and produces an explicit correction to use `task`; `runner_id` likewise produces a correction to use `runner`. The local runtime—not ChatGPT—resolves the configured executable. `lane` must be a listed available lane; a runner ID is not a lane name. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. CueLine validates every new route in the dispatch before registering or starting any job. One invalid route rejects the whole command and requests a corrected envelope with the same pending identity. Repeating an already persisted deterministic job is ignored rather than executed again.
 
 The default executor is `caller`. It persists pending `advise` jobs and returns them as `awaiting_caller`. A caller `work` job must include an absolute `workdir`; it returns as `awaiting_caller_work` without executing. The current Codex must acquire a claim bound to run/job/task hash/workdir/caller/fencing token, durably start it before mutation, heartbeat long work, and submit the result with the exact proof. A non-success after start is reported as `ambiguous`, not as proof that no side effect occurred. A `dispatch` alone never means local work started. The web controller has no local tool access or implicit knowledge of local paths/repository layout. Local evidence must include absolute paths, relevant code excerpts, exact code/error identifiers, and an explicit request for any missing local evidence.
 
-The `process` executor requires both `executor: "process"` and `allowProcessExecution: true`; each non-terminal continuation repeats the second authorization. Independent `advise` jobs run with a default global concurrency of two and a default per-lane limit of two (both configurable). If any job is `work`, the entire batch remains serial in command order.
+The `process` executor requires both `executor: "process"` and `allowProcessExecution: true`; each non-terminal continuation repeats the second authorization. A supplied process `workdir` must be absolute. When omitted, CueLine writes the local runtime's resolved absolute workspace into the accepted command before hashing, registration, or execution. This keeps replay bound to the same directory after a restart. Independent `advise` jobs run with a default global concurrency of two and a default per-lane limit of two (both configurable). If any job is `work`, the entire batch remains serial in command order.
 
 ### `wait`
 
-Waits for selected running jobs (`job_ids`) or all current running jobs when omitted. `wait_ms` is part of the v0.1 schema but does not override the supervisor's job timeout.
+Waits for selected running jobs (`job_ids`) or all current running jobs when omitted. When present, `job_ids` must be a non-empty, unique list of valid IDs that exactly match jobs in the current run. One unknown target rejects the whole command with `CONTROL_JOB_TARGET_UNKNOWN` before any wait begins. `wait_ms` is part of the v0.1 schema but does not override the supervisor's job timeout.
 
 ### `inspect`
 
-Asks CueLine to present the currently persisted job state on the next round. Named `job_ids` receive the bounded evidence budget before unrelated jobs, so a completed result is not reduced to status merely because earlier jobs consumed the prompt budget. It does not grant the web controller a new local inspection tool.
+Asks CueLine to present the currently persisted job state on the next round. Named `job_ids` must form a non-empty, unique list that exactly matches jobs in the current run and receives the bounded evidence budget before unrelated jobs. One unknown target rejects the entire command before any selected job is inspected. To read a truncated tail, select exactly one job and copy its non-null `evidence_window.next_offset` verbatim:
+
+```json
+{
+  "protocol": "cueline/0.1",
+  "run_id": "run-example",
+  "round": 3,
+  "request_id": "msg-example-3",
+  "action": "inspect",
+  "job_ids": ["job-example"],
+  "evidence_offset": 11842,
+  "evidence_hash": "61f2be400c13cff37284a92d51a9e4c3445bf8bbf67b8b8e92e5e1e4e1b337de"
+}
+```
+
+`evidence_offset` is a raw-character cursor from 0 through 1,000,000,000. It is valid only with one explicit job ID and the exact lowercase SHA-256 `evidence_hash` copied from that window's `content_hash`. CueLine validates and persists the pair, returns the next bounded window, and never reruns the job. If evidence changes before validation, the command is rejected for repair; if a process refresh changes it after validation, the next observation resets to offset 0 with a notice. An offset beyond unchanged evidence is clamped to the end and reported. This action does not grant the web controller a new local inspection tool.
 
 ### `complete`
 
@@ -105,6 +142,6 @@ Ends the run with a non-empty `reason` and optional `final_delivery_text`. Like
 
 ## Validation and repair
 
-CueLine rejects missing markers, malformed JSON, invalid actions, stale identity, invalid supported-field values, duplicate `job_key` values, and unavailable pre-spawn routes with stable error codes. Only the supported fields retained by runtime validation can affect execution. CueLine then sends a validation error back to the same conversation with the same pending identity. By default, two repair attempts are allowed; exhaustion fails the local run rather than guessing a command.
+CueLine rejects missing markers, malformed JSON, invalid actions, stale identity, unknown or action-incompatible fields, invalid supported-field values, empty/duplicate/malformed `job_ids`, duplicate `job_key` values, and unavailable pre-spawn routes with stable error codes. Only the exact fields for the selected action can affect execution. CueLine then sends a validation error back to the same conversation with the same pending identity. By default, two repair attempts are allowed; exhaustion fails the local run rather than guessing a command.
 
 The JSON Schema files under `schemas/` are publication references. Runtime structural validation is implemented locally and does not require a schema package.

package/docs/experiments/protocol-lint.md

@@ -0,0 +1,40 @@
+# Experiment: controller protocol lint
+
+Branch: `codex/exp-protocol-lint`
+
+## Hypothesis
+
+Known Pro contract mistakes should be found offline in one pass before they
+consume another controller round or touch durable run state.
+
+## Surface
+
+```bash
+cueline protocol lint response.txt \
+  --run-id run_... \
+  --round 3 \
+  --request-id msg_... \
+  --json
+```
+
+The public API exports `lintControllerCommandText()`. It accepts either a raw
+JSON object or the last complete `<CueLineControl>` envelope.
+
+## Checks unique to this experiment
+
+- Exact run, round, and request identity.
+- `prompt` versus required `task`.
+- `runner_id` versus supported `runner`.
+- A runner ID mistakenly placed in `lane`, using active routing evidence.
+- Unknown top-level and job fields.
+- Fields that exist in the protocol but belong to a different action.
+- Required absolute `workdir` for caller `work`.
+- Existing schema, duplicate-key, mode, timeout, and terminal-field validation.
+
+Invalid JSON produces bounded diagnostics and does not echo the source. Linting
+never rewrites, sends, accepts, or records a command.
+
+## Review decision
+
+Merge if preventing wasted Pro repair rounds is worth a new offline CLI surface.
+Reject if the runtime validator alone should remain the only contract authority.

package/docs/experiments/run-doctor.md

@@ -0,0 +1,39 @@
+# Experiment: run doctor
+
+Branch: `codex/exp-run-doctor`
+
+## Hypothesis
+
+A persisted CueLine run should explain *why* it is waiting or blocked without an
+operator reconstructing state from `status`, `jobs`, leases, and event files.
+The diagnosis must be read-only and must never turn ambiguous evidence into a
+retry recommendation.
+
+## Surface
+
+```bash
+cueline run doctor <run-id>
+cueline run doctor <run-id> --json
+```
+
+The public API exports `diagnoseCueLineRun()` for persisted runs and
+`diagnoseCueLineRunStatus()` for already loaded status summaries.
+
+Each result includes a stable outcome, phase, event sequence, safe next action,
+and findings with machine-readable codes, bounded evidence, and an operator
+action. A blocked diagnosis exits `1`; healthy and action-required diagnoses
+exit `0` because the command itself completed successfully.
+
+## Safety properties
+
+- Controller response pending means observe the exact turn and **do not resend**.
+- Proposed caller work is distinguished from claimed or started work.
+- Stale/unknown ownership, orphaned work, and ambiguous work are blockers.
+- Timeout and failure are evidence for Pro, not implicit retry permission.
+- Diagnosis does not append events, claim leases, cancel jobs, or drive a browser.
+
+## Review decision
+
+Merge if a single causal report is more useful than manually correlating the
+existing read-only commands. Reject if the project should keep all policy out of
+diagnostics and expose only raw state.

package/docs/experiments/run-handoff.md

@@ -0,0 +1,39 @@
+# Experiment: safe run handoff
+
+Branch: `codex/exp-run-handoff`
+
+## Hypothesis
+
+A new Codex session should be able to resume one exact CueLine run from a single
+read-only packet instead of reconstructing controller identity, paths, jobs, and
+ownership from chat history.
+
+## Surface
+
+```bash
+cueline run handoff <run-id>
+cueline run handoff <run-id> --json
+cueline run handoff <run-id> --include-content --max-content-chars 2000
+```
+
+The public API exports `createCueLineRunHandoff()`,
+`buildCueLineRunHandoff()`, and `renderCueLineRunHandoffMarkdown()`.
+
+## Default packet
+
+- Exact run, round, event sequence, phase, executor, and safe next action.
+- Exact ChatGPT conversation and pending request identities.
+- Submission, Pro-label, composer, and write-ahead evidence.
+- Absolute CueLine home, run directory, event log, snapshot, and lease paths.
+- Job IDs, keys, modes, status, task hashes, workdirs, and claim/start flags.
+- Concrete CLI/API continuation example and the warning that Pro has no tools.
+
+The default packet contains no user request, controller prompt, task text,
+stdout, stderr, job output, claim proof, or token. `--include-content` adds only
+request/task/final text under one shared total character budget; prompt and
+worker output remain excluded.
+
+## Review decision
+
+Merge if cross-session recovery benefits from a canonical local packet. Reject
+if all consumers should reconstruct handoff context directly from public APIs.

package/docs/experiments/run-timeline.md

@@ -0,0 +1,35 @@
+# Experiment: sanitized run timeline
+
+Branch: `codex/exp-run-timeline`
+
+## Hypothesis
+
+Operators need an auditable chronological view without reading raw event
+payloads that can contain controller prompts, tasks, stdout, stderr, or local
+secrets.
+
+## Surface
+
+```bash
+cueline run timeline <run-id> [--after <sequence>] [--limit <1..1000>] [--json]
+```
+
+The public API exports `loadCueLineRunTimeline()` and the pure
+`buildCueLineRunTimeline()` formatter.
+
+## Safety properties
+
+- Pagination uses an exclusive durable event-sequence cursor.
+- A cursor ahead of the run is rejected instead of returning a false empty page.
+- Entries expose only allowlisted identity/status/model metadata.
+- Prompt, request, task, output, error text, URL, and raw owner ID are excluded.
+- Runtime owner IDs become 12-character one-way fingerprints.
+- Payloads become canonical SHA-256 hashes for correlation, never raw JSON.
+- Event types use an explicit known allowlist; unknown types are redacted.
+- Invalid timestamps are replaced with `null`.
+- Timeline reads never append events or claim ownership.
+
+## Review decision
+
+Merge if a safe audit view is worth maintaining an event-type allowlist. Reject
+if direct local event-log access is preferred despite its disclosure risk.

package/docs/experiments/run-watch.md

@@ -0,0 +1,31 @@
+# Experiment: bounded run watch
+
+Branch: `codex/exp-run-watch`
+
+## Hypothesis
+
+Long controller runs should be observed through a short, cursor-based read call,
+not by keeping one foreground tool call and runtime lease alive for minutes.
+
+## Surface
+
+```bash
+cueline run watch <run-id> --after <event-sequence> [--timeout-ms <0..30000>] [--json]
+```
+
+The public API exports `waitForCueLineRunChange()`. It returns `changed`,
+`terminal`, or `timed_out` with the latest full run status. The default timeout
+is five seconds and the hard maximum is thirty seconds.
+
+## Safety properties
+
+- The observer never claims a runtime lease or appends an event.
+- A cursor ahead of durable state is rejected instead of waiting forever.
+- Terminal state returns immediately even when no newer event exists.
+- Abort and timeout do not change ownership, retry a turn, or cancel work.
+- Every follow-up call is independently recoverable from its sequence cursor.
+
+## Review decision
+
+Merge if short polling with a durable cursor better fits Codex tool lifetimes.
+Reject if consumers should implement polling entirely outside CueLine.

package/docs/multi-model-routing.md

@@ -0,0 +1,256 @@
+# Multi-model routing
+
+## What ships by default
+
+CueLine ships one enabled lane, `default`, with one candidate, `codex-default`. That candidate runs the bundled `codex exec --ignore-user-config` process route when process execution is explicitly authorized.
+
+Process execution is not the default. `startCueLineRun` and `runCueLine` default to `executor: "caller"`, which spawns no worker process at all. A controller dispatch is persisted and handed back to the current Codex for execution. Multi-model process routing is therefore an opt-in user configuration, not a CueLine code change.
+
+## What the controller can see
+
+For a process run, CueLine builds a routing instruction before every controller turn. ChatGPT Pro sees only:
+
+- enabled lane names;
+- enabled, currently available candidate IDs inside each lane.
+
+The controller never sees candidate `argv`, executable paths, wrapper contents, environment handling, or flags such as `--model`. It may select a lane and may name one advertised candidate with the optional `runner` field. CueLine validates that choice locally before any process starts.
+
+Candidate IDs are therefore the controller's menu. Encode both the model and intended purpose in each ID so the choice remains meaningful without exposing implementation details:
+
+- `claude-opus-4-8-advise`
+- `gemini-3-1-pro-advise`
+- `grok-4-5-advise-search`
+
+Keep IDs stable after they are used in durable runs. Change the `argv` behind an ID only when the new command preserves the same intended contract; otherwise add a new candidate ID.
+
+## Known limitations and wrapper boundaries
+
+The following constraints were verified against CueLine `0.1.7` and working local multi-model runners on 2026-07-16.
+
+### Candidates cannot define environment variables
+
+The routing schema accepts `id`, `argv`, `task_input`, and `enabled`. It has no `env` field.
+
+A worker CLI that requires environment setup must therefore use a wrapper script as `argv[0]`. For example, the Antigravity `agy` CLI needs `NO_BROWSER=1` for headless execution and should have API-key variables removed when the intended path is the existing CLI login. A wrapper can establish that environment before replacing itself with the real worker process.
+
+Keep secrets out of the routing JSON and wrapper source. Wrappers should unset conflicting variable names or inherit an already authorized local login; they should not embed credential values.
+
+### Candidate argv cannot branch on `advise` versus `work`
+
+CueLine expands fixed placeholders inside individual argv elements. `{mode}` expands to the literal `advise` or `work`. `{sandbox}` is the only mode-derived argument value: it expands to `read-only` for `advise` and `workspace-write` for `work`. Those values are designed for the Codex sandbox flag and are not a portable permission contract for other CLIs.
+
+The routing format has no conditional expression that can select one argv sequence for `advise` and another for `work`. For non-Codex workers, prefer an advise-only lane:
+
+- Claude: hardcode `--tools Read Glob Grep`.
+- Antigravity: hardcode `--mode plan`.
+- Grok: hardcode `--permission-mode plan`.
+
+Keep mutating `work` jobs on the bundled `default` lane unless a separate worker has an independently verified work-mode permission contract.
+
+### Registration is not a sandbox
+
+The runner contract states:
+
+> Registration is an allow-list, not a sandbox: the registered program still has the OS permissions of the local CueLine process.
+
+CueLine verifies that `argv[0]` came from the loaded routing configuration and launches it without a shell. That prevents the controller from supplying an arbitrary executable, but it does not reduce the executable's operating-system permissions.
+
+A registered non-Codex worker therefore runs with the full OS permissions of the local CueLine process. Its read-only behavior depends entirely on the CLI flags, wrapper behavior, credentials, and working directory chosen by the user.
+
+## Worked four-lane configuration
+
+This example keeps `work` on the bundled Codex route and adds three advise-only lanes:
+
+- `taste-final`: Claude Opus for final prose and judgment;
+- `long-context`: Gemini through an Antigravity wrapper;
+- `live-search`: Grok through a live-search wrapper.
+
+Create a private runner directory and replace `/absolute/path/to/cueline-runners` below with its real absolute path. Do not use `$HOME` or `~` inside JSON; CueLine passes argv directly and does not perform shell expansion.
+
+### Routing configuration
+
+```json
+{
+  "$schema": "/absolute/path/to/cueline/config/routing.schema.json",
+  "version": 1,
+  "lanes": {
+    "default": {
+      "enabled": true,
+      "candidates": [
+        {
+          "id": "codex-default",
+          "argv": [
+            "codex",
+            "exec",
+            "--ignore-user-config",
+            "--skip-git-repo-check",
+            "--ephemeral",
+            "--color",
+            "never",
+            "-C",
+            "{workdir}",
+            "-s",
+            "{sandbox}",
+            "-"
+          ],
+          "task_input": "stdin"
+        }
+      ]
+    },
+    "taste-final": {
+      "enabled": true,
+      "candidates": [
+        {
+          "id": "claude-opus-4-8-advise",
+          "argv": [
+            "claude",
+            "--disable-slash-commands",
+            "--model",
+            "claude-opus-4-8",
+            "--output-format",
+            "text",
+            "--effort",
+            "high",
+            "--tools",
+            "Read",
+            "Glob",
+            "Grep",
+            "-p",
+            "{task}"
+          ],
+          "task_input": "argv"
+        }
+      ]
+    },
+    "long-context": {
+      "enabled": true,
+      "candidates": [
+        {
+          "id": "gemini-3-1-pro-advise",
+          "argv": [
+            "/absolute/path/to/cueline-runners/gemini-advise.sh",
+            "Gemini 3.1 Pro (High)"
+          ],
+          "task_input": "stdin"
+        }
+      ]
+    },
+    "live-search": {
+      "enabled": true,
+      "candidates": [
+        {
+          "id": "grok-4-5-advise-search",
+          "argv": [
+            "/absolute/path/to/cueline-runners/grok-advise.sh",
+            "grok-4.5"
+          ],
+          "task_input": "stdin"
+        }
+      ]
+    }
+  }
+}
+```
+
+The `$schema` path is editor metadata; set it to the installed or checked-out `routing.schema.json` when schema-aware validation is desired. CueLine validates the routing object independently at load time.
+
+### Gemini wrapper
+
+Save as `gemini-advise.sh` and make it executable:
+
+```bash
+#!/usr/bin/env bash
+# CueLine advise-only Gemini runner through Antigravity.
+# argv: gemini-advise.sh "<agy model display string>"; task arrives on stdin.
+set -euo pipefail
+
+MODEL="${1:-Gemini 3.1 Pro (High)}"
+TASK="$(cat)"
+
+# Stay on the existing CLI login and avoid browser interaction.
+exec env -u GEMINI_API_KEY -u GOOGLE_API_KEY -u GOOGLE_AI_API_KEY \
+  NO_BROWSER=1 \
+  agy --dangerously-skip-permissions --add-dir "$PWD" \
+  --mode plan --model "$MODEL" \
+  --print-timeout 570s \
+  --print "$TASK"
+```
+
+`--dangerously-skip-permissions` disables Antigravity's interactive permission prompts; it does not make the process read-only. The enforced read-only intent in this wrapper comes from `--mode plan`. Verify that contract against the installed `agy` version before registering it.
+
+### Grok wrapper
+
+Save as `grok-advise.sh` and make it executable:
+
+```bash
+#!/usr/bin/env bash
+# CueLine advise-only Grok runner for live web and X search.
+# argv: grok-advise.sh "<model>"; task arrives on stdin.
+set -euo pipefail
+
+MODEL="${1:-grok-4.5}"
+
+TMP="$(mktemp)"
+trap '{ rm -- "$TMP"; } 2>/dev/null || true' EXIT
+cat > "$TMP"
+
+# Keep the subscription login path when an API-key variable would override it.
+unset XAI_API_KEY 2>/dev/null || true
+
+grok --cwd "$PWD" --model "$MODEL" \
+  --no-memory --no-subagents --no-plan --no-alt-screen \
+  --output-format plain --verbatim --permission-mode plan \
+  --prompt-file "$TMP"
+```
+
+Make both wrappers executable:
+
+```bash
+chmod 700 /absolute/path/to/cueline-runners/gemini-advise.sh
+chmod 700 /absolute/path/to/cueline-runners/grok-advise.sh
+```
+
+### Verify the routing file
+
+Point `CUELINE_CONFIG` at the completed file and inspect it through CueLine's real routing surface:
+
+```bash
+CUELINE_CONFIG=/absolute/path/to/routing.multimodel.json \
+  cueline routing --json
+```
+
+The command validates the file and checks whether each candidate's `argv[0]` is executable in the current environment. A valid file has this output shape:
+
+```json
+{
+  "version": "0.1.7",
+  "config": {
+    "path": "/absolute/path/to/routing.multimodel.json",
+    "valid": true
+  },
+  "availableLanes": 4,
+  "lanes": [
+    {
+      "name": "default",
+      "enabled": true,
+      "status": "available",
+      "selectedRunnerId": "codex-default"
+    }
+  ],
+  "findings": []
+}
+```
+
+The real `lanes` array contains one entry per configured lane. `availableLanes` may be less than four, and individual lanes may report `status: "unavailable"`, when a CLI or wrapper is not executable on the current `PATH` or at the configured absolute path. That is an availability result, not a schema-validation failure.
+
+Use the same `CUELINE_CONFIG` value when creating and continuing the process run. Process execution still requires both `executor: "process"` and `allowProcessExecution: true`.
+
+## What the controller sees
+
+With all four candidates available, the per-round routing instruction includes a line shaped like:
+
+```text
+Available routing lanes: default [codex-default]; taste-final [claude-opus-4-8-advise]; long-context [gemini-3-1-pro-advise]; live-search [grok-4-5-advise-search].
+```
+
+That is the complete routing menu exposed to ChatGPT Pro. The wrapper paths, CLI arguments, model flags, environment cleanup, and permission flags remain local.