cueline 0.1.0

package/docs/assets/cueline-loop-ko.svg

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 590" width="1000" height="590" role="img" aria-label="CueLine 실행 한 번을 프롬프트북처럼 읽기: 머신이 관측을 보내고, 컨트롤러가 명령 하나를 내리고, 등록된 runner가 실행하며, complete가 나올 때까지 이어집니다.">
+  <title>CueLine 실행을 프롬프트북처럼 읽기</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Apple SD Gothic Neo", "Noto Sans CJK KR", "Malgun Gothic", monospace }
+    .hd   { fill: #0F1720; font-size: 17px; letter-spacing: .02em }
+    .sub  { fill: #8B949E; font-size: 13.5px }
+    .rule { stroke: #E4E8EC; stroke-width: 1 }
+    .spine{ stroke: #0F1720; stroke-width: 2 }
+    .tick { stroke: #C3CAD2; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 15px }
+    .note { fill: #8B949E; font-size: 13.5px }
+    .rnd  { fill: #B6BEC7; font-size: 12px; letter-spacing: .14em }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    .cue  { fill: #C8553D }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .note, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .spine { stroke: #C9D1D9 }
+      .tick { stroke: #30363D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+      .rnd { fill: #484F58 }
+      .cue { fill: #E0674C }
+    }
+  </style>
+
+  <text x="505" y="44" class="hd" text-anchor="end">ChatGPT 웹 대화</text>
+  <text x="505" y="64" class="sub" text-anchor="end">컨트롤러 — 계획하고, 지시하고, 판단합니다</text>
+  <text x="555" y="44" class="hd">당신의 머신</text>
+  <text x="555" y="64" class="sub">CueLine — 검증 · 라우팅 · 실행 · 기록</text>
+
+  <path d="M40 84H505" class="rule"/>
+  <path d="M555 84H960" class="rule"/>
+  <path d="M530 84V520" class="spine"/>
+
+  <text x="40" y="126" class="rnd">라운드 1</text>
+  <path d="M505 122H524" class="tick"/>
+  <text x="555" y="126" class="obs">observation · 당신의 요청, 아직 작업 없음</text>
+  <path d="M524 118 517 122 524 126z" class="cue"/>
+
+  <path d="M536 158 545 162 536 166z" class="cue"/>
+  <text x="505" y="166" class="say" text-anchor="end">dispatch · review · lane default · advise</text>
+  <path d="M545 162H565" class="tick"/>
+  <text x="575" y="166" class="note">프로세스가 뜨기 전에 경로가 정해집니다</text>
+
+  <text x="555" y="200" class="note">codex exec (읽기 전용) → 성공 · 출력 저장</text>
+
+  <text x="40" y="264" class="rnd">라운드 2</text>
+  <path d="M505 260H524" class="tick"/>
+  <text x="555" y="264" class="obs">observation · 증거를 그대로</text>
+  <path d="M524 256 517 260 524 264z" class="cue"/>
+
+  <path d="M536 296 545 300 536 304z" class="cue"/>
+  <text x="505" y="304" class="say" text-anchor="end">dispatch · patch · mode work</text>
+  <path d="M545 300H565" class="tick"/>
+  <text x="575" y="304" class="note">argv[0]은 미리 허용되어 있어야 합니다</text>
+
+  <text x="555" y="338" class="note">codex exec (workspace-write) → 성공</text>
+
+  <text x="40" y="402" class="rnd">라운드 3</text>
+  <path d="M505 398H524" class="tick"/>
+  <text x="555" y="402" class="obs">observation · 갱신된 증거</text>
+  <path d="M524 394 517 398 524 402z" class="cue"/>
+
+  <path d="M536 434 545 438 536 442z" class="cue"/>
+  <text x="505" y="442" class="say" text-anchor="end">complete · final_delivery_text</text>
+  <path d="M545 438H565" class="tick"/>
+  <text x="575" y="442" class="note">그대로 당신에게 반환</text>
+
+  <text x="555" y="476" class="note">실행 봉인 · events.jsonl이 곧 기록</text>
+
+  <path d="M40 520H960" class="rule"/>
+  <text x="40" y="546" class="foot">동작은 다섯 개뿐 — dispatch · wait · inspect · complete · blocked.</text>
+  <text x="40" y="568" class="foot">엔벨로프 밖은 실행되지 않고, 시작된 워커는 재시도되지 않습니다.</text>
+</svg>

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

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 590" width="1000" height="590" role="img" aria-label="一次 CueLine 运行像一本提示本：机器发出观测，控制器发出一条指令，已注册的 runner 执行它，直到控制器发出 complete。">
+  <title>一次 CueLine 运行，像读一本提示本</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Noto Sans CJK SC", "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 }
+    .spine{ stroke: #0F1720; stroke-width: 2 }
+    .tick { stroke: #C3CAD2; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 15px }
+    .note { fill: #8B949E; font-size: 13.5px }
+    .rnd  { fill: #B6BEC7; font-size: 12px; letter-spacing: .14em }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    .cue  { fill: #C8553D }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .note, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .spine { stroke: #C9D1D9 }
+      .tick { stroke: #30363D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+      .rnd { fill: #484F58 }
+      .cue { fill: #E0674C }
+    }
+  </style>
+
+  <text x="505" y="44" class="hd" text-anchor="end">ChatGPT 网页会话</text>
+  <text x="505" y="64" class="sub" text-anchor="end">控制器 — 规划、发令、审阅证据</text>
+  <text x="555" y="44" class="hd">你的机器</text>
+  <text x="555" y="64" class="sub">CueLine — 校验、路由、执行、记录</text>
+
+  <path d="M40 84H505" class="rule"/>
+  <path d="M555 84H960" class="rule"/>
+  <path d="M530 84V520" class="spine"/>
+
+  <text x="40" y="126" class="rnd">第 1 轮</text>
+  <path d="M505 122H524" class="tick"/>
+  <text x="555" y="126" class="obs">observation · 你的需求，尚无任何作业</text>
+  <path d="M524 118 517 122 524 126z" class="cue"/>
+
+  <path d="M536 158 545 162 536 166z" class="cue"/>
+  <text x="505" y="166" class="say" text-anchor="end">dispatch · review · lane default · advise</text>
+  <path d="M545 162H565" class="tick"/>
+  <text x="575" y="166" class="note">任何进程启动之前就先确定路由</text>
+
+  <text x="555" y="200" class="note">codex exec（只读）→ 成功 · 输出已保存</text>
+
+  <text x="40" y="264" class="rnd">第 2 轮</text>
+  <path d="M505 260H524" class="tick"/>
+  <text x="555" y="264" class="obs">observation · 证据原样回传</text>
+  <path d="M524 256 517 260 524 264z" class="cue"/>
+
+  <path d="M536 296 545 300 536 304z" class="cue"/>
+  <text x="505" y="304" class="say" text-anchor="end">dispatch · patch · mode work</text>
+  <path d="M545 300H565" class="tick"/>
+  <text x="575" y="304" class="note">argv[0] 必须事先被允许</text>
+
+  <text x="555" y="338" class="note">codex exec（workspace-write）→ 成功</text>
+
+  <text x="40" y="402" class="rnd">第 3 轮</text>
+  <path d="M505 398H524" class="tick"/>
+  <text x="555" y="402" class="obs">observation · 更新后的证据</text>
+  <path d="M524 394 517 398 524 402z" class="cue"/>
+
+  <path d="M536 434 545 438 536 442z" class="cue"/>
+  <text x="505" y="442" class="say" text-anchor="end">complete · final_delivery_text</text>
+  <path d="M545 438H565" class="tick"/>
+  <text x="575" y="442" class="note">原样返回给你</text>
+
+  <text x="555" y="476" class="note">本次运行封存 · events.jsonl 就是记录</text>
+
+  <path d="M40 520H960" class="rule"/>
+  <text x="40" y="546" class="foot">只有五个动作 — dispatch · wait · inspect · complete · blocked。</text>
+  <text x="40" y="568" class="foot">信封之外的文本一律不执行；worker 一旦启动就不会自动重试。</text>
+</svg>

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

@@ -0,0 +1,77 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 590" width="1000" height="590" role="img" aria-label="一次 CueLine 執行像一本提示本：機器送出觀測，主控端喊出一道指令，已註冊的 runner 執行它，直到主控端喊 complete。">
+  <title>一次 CueLine 執行，像讀一本提示本</title>
+  <style>
+    text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Noto Sans CJK TC", "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 }
+    .spine{ stroke: #0F1720; stroke-width: 2 }
+    .tick { stroke: #C3CAD2; stroke-width: 1 }
+    .say  { fill: #C8553D; font-size: 15px }
+    .obs  { fill: #4A5561; font-size: 15px }
+    .note { fill: #8B949E; font-size: 13.5px }
+    .rnd  { fill: #B6BEC7; font-size: 12px; letter-spacing: .14em }
+    .foot { fill: #8B949E; font-size: 13.5px }
+    .cue  { fill: #C8553D }
+    @media (prefers-color-scheme: dark) {
+      .hd { fill: #E6EDF3 }
+      .sub, .note, .foot { fill: #7D8590 }
+      .rule { stroke: #21262D }
+      .spine { stroke: #C9D1D9 }
+      .tick { stroke: #30363D }
+      .say { fill: #E0674C }
+      .obs { fill: #ADBAC7 }
+      .rnd { fill: #484F58 }
+      .cue { fill: #E0674C }
+    }
+  </style>
+
+  <text x="505" y="44" class="hd" text-anchor="end">ChatGPT 網頁對話</text>
+  <text x="505" y="64" class="sub" text-anchor="end">主控端 — 規劃、喊 cue、審查證據</text>
+  <text x="555" y="44" class="hd">你的機器</text>
+  <text x="555" y="64" class="sub">CueLine — 驗證、路由、執行、記錄</text>
+
+  <path d="M40 84H505" class="rule"/>
+  <path d="M555 84H960" class="rule"/>
+  <path d="M530 84V520" class="spine"/>
+
+  <text x="40" y="126" class="rnd">第 1 輪</text>
+  <path d="M505 122H524" class="tick"/>
+  <text x="555" y="126" class="obs">observation · 你的需求，還沒有任何工作</text>
+  <path d="M524 118 517 122 524 126z" class="cue"/>
+
+  <path d="M536 158 545 162 536 166z" class="cue"/>
+  <text x="505" y="166" class="say" text-anchor="end">dispatch · review · lane default · advise</text>
+  <path d="M545 162H565" class="tick"/>
+  <text x="575" y="166" class="note">任何程序啟動之前就先決定路由</text>
+
+  <text x="555" y="200" class="note">codex exec（唯讀）→ 成功 · 輸出已保存</text>
+
+  <text x="40" y="264" class="rnd">第 2 輪</text>
+  <path d="M505 260H524" class="tick"/>
+  <text x="555" y="264" class="obs">observation · 證據原樣送回</text>
+  <path d="M524 256 517 260 524 264z" class="cue"/>
+
+  <path d="M536 296 545 300 536 304z" class="cue"/>
+  <text x="505" y="304" class="say" text-anchor="end">dispatch · patch · mode work</text>
+  <path d="M545 300H565" class="tick"/>
+  <text x="575" y="304" class="note">argv[0] 必須事先被允許</text>
+
+  <text x="555" y="338" class="note">codex exec（workspace-write）→ 成功</text>
+
+  <text x="40" y="402" class="rnd">第 3 輪</text>
+  <path d="M505 398H524" class="tick"/>
+  <text x="555" y="402" class="obs">observation · 更新後的證據</text>
+  <path d="M524 394 517 398 524 402z" class="cue"/>
+
+  <path d="M536 434 545 438 536 442z" class="cue"/>
+  <text x="505" y="442" class="say" text-anchor="end">complete · final_delivery_text</text>
+  <path d="M545 438H565" class="tick"/>
+  <text x="575" y="442" class="note">原樣回傳給你</text>
+
+  <text x="555" y="476" class="note">本次執行封存 · events.jsonl 就是紀錄</text>
+
+  <path d="M40 520H960" class="rule"/>
+  <text x="40" y="546" class="foot">只有五個動作 — dispatch · wait · inspect · complete · blocked。</text>
+  <text x="40" y="568" class="foot">封包以外的文字一律不執行；工作行程一旦啟動就不會自動重試。</text>
+</svg>

package/docs/assets/cueline-mark-dark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48" role="img" aria-label="CueLine">
+  <title>CueLine</title>
+  <g fill="none" stroke-linecap="butt">
+    <path d="M12 8V40" stroke="#E6EDF3" stroke-width="3"/>
+    <path d="M26 15H40" stroke="#8B949E" stroke-width="3"/>
+    <path d="M26 24H40" stroke="#E6EDF3" stroke-width="3"/>
+    <path d="M26 33H40" stroke="#8B949E" stroke-width="3"/>
+  </g>
+  <path d="M14 18.5 23 24l-9 5.5z" fill="#E0674C"/>
+</svg>

package/docs/assets/cueline-mark-light.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48" role="img" aria-label="CueLine">
+  <title>CueLine</title>
+  <g fill="none" stroke-linecap="butt">
+    <path d="M12 8V40" stroke="#0F1720" stroke-width="3"/>
+    <path d="M26 15H40" stroke="#5B6672" stroke-width="3"/>
+    <path d="M26 24H40" stroke="#0F1720" stroke-width="3"/>
+    <path d="M26 33H40" stroke="#5B6672" stroke-width="3"/>
+  </g>
+  <path d="M14 18.5 23 24l-9 5.5z" fill="#C8553D"/>
+</svg>

package/docs/assets/cueline-wordmark-dark.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 186 48" width="186" height="48" role="img" aria-label="CueLine">
+  <title>CueLine</title>
+  <g fill="none" stroke="#E6EDF3" stroke-width="3" stroke-linecap="butt" stroke-linejoin="miter">
+    <path d="M21.81 14.68A11.5 14.5 0 1 0 21.81 33.32"/>
+    <path d="M31.5 8V24A11.5 14.5 0 0 0 54.5 24V8"/>
+    <path d="M64.5 8V40"/>
+    <path d="M63 9.5H83"/>
+    <path d="M63 24H79"/>
+    <path d="M63 38.5H83"/>
+    <path d="M93.5 8V38.5"/>
+    <path d="M92 38.5H112"/>
+    <path d="M120.5 8V40"/>
+    <path d="M132.5 40V8L155.5 40V8"/>
+    <path d="M167.5 8V40"/>
+    <path d="M166 9.5H186"/>
+    <path d="M166 24H182"/>
+    <path d="M166 38.5H186"/>
+  </g>
+</svg>

package/docs/assets/cueline-wordmark-light.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 186 48" width="186" height="48" role="img" aria-label="CueLine">
+  <title>CueLine</title>
+  <g fill="none" stroke="#0F1720" stroke-width="3" stroke-linecap="butt" stroke-linejoin="miter">
+    <path d="M21.81 14.68A11.5 14.5 0 1 0 21.81 33.32"/>
+    <path d="M31.5 8V24A11.5 14.5 0 0 0 54.5 24V8"/>
+    <path d="M64.5 8V40"/>
+    <path d="M63 9.5H83"/>
+    <path d="M63 24H79"/>
+    <path d="M63 38.5H83"/>
+    <path d="M93.5 8V38.5"/>
+    <path d="M92 38.5H112"/>
+    <path d="M120.5 8V40"/>
+    <path d="M132.5 40V8L155.5 40V8"/>
+    <path d="M167.5 8V40"/>
+    <path d="M166 9.5H186"/>
+    <path d="M166 24H182"/>
+    <path d="M166 38.5H186"/>
+  </g>
+</svg>

package/docs/compatibility.md

@@ -0,0 +1,60 @@
+# Compatibility
+
+## Runtime matrix
+
+| Surface | v0.1 status | Notes |
+|---|---|---|
+| Node.js 22+ ESM | Supported | Core protocol, state, router, runners, fake browser tests |
+| Codex Node REPL + built-in Browser (IAB) | Required for live control | Provides the imported API with the authenticated ChatGPT tab/browser client |
+| `codex` CLI | Required by default route | Custom routing may register a different executable |
+| ChatGPT web conversation | Supported, text only | Uses the model currently selected in the page |
+| macOS | Primary supported desktop | Codex desktop + symlink installer target |
+| Linux | Core/CI target | Live Codex IAB availability depends on the host product |
+| Windows | Not verified | `install.sh` and symlink layout are not a Windows installer |
+
+The npm package has no runtime dependencies. Development requires TypeScript and Node type definitions from `devDependencies`.
+
+## ChatGPT requirements
+
+CueLine is designed for a conversation already authenticated by the user at `chatgpt.com`, including a ChatGPT Pro account when Pro is the intended controller. CueLine neither handles credentials nor verifies plan entitlement. It does not switch models; the page's current selection is authoritative.
+
+The v0.1 adapter relies on accessible textbox/button roles and assistant-message markup in the current ChatGPT web UI. UI changes can cause explicit `COMPOSER_MISSING`, `SEND_BUTTON_MISSING`, or response-timeout errors. A fake adapter test cannot prove that the current live page still matches.
+
+## Supported in v0.1
+
+- one ChatGPT conversation per run
+- text controller observations and commands
+- `dispatch`, `wait`, `inspect`, `complete`, and `blocked`
+- foreground and background local jobs
+- deterministic routing before spawn
+- append-only run recovery and atomic snapshots
+- continuation by run ID and stored conversation URL
+- read-only persisted-state loading through `loadCueLineRunState`
+- injected fake browser/runner for offline tests
+
+## Not supported in v0.1
+
+- automatic model selection or switching in ChatGPT
+- images, screenshots as controller input, audio, or binary payloads
+- file upload/download through the ChatGPT page
+- Deep Research, Projects, Apps, or custom GPT UI flows
+- multiple simultaneous controller conversations for one run
+- direct browser-to-local tool calls
+- automatic retry/fallback after a worker starts
+- cross-host transfer of browser sessions, credentials, child processes, or local runtime state
+- unattended guarantee across ChatGPT UI or authentication changes
+
+## CLI boundary
+
+`cueline doctor`, `routing`, `jobs`, and `config path` diagnose the local installation and state. They do not drive the ChatGPT page. Live orchestration is an imported API run inside Codex so that the IAB browser object can be injected or resolved.
+
+## Live readiness checklist
+
+1. `node --version` reports 22 or newer.
+2. `npm run build` succeeds for a checkout, or the installed package contains `dist/`.
+3. Codex exposes its built-in Browser runtime.
+4. A logged-in `https://chatgpt.com/` tab is open and the intended model/conversation is selected.
+5. `cueline doctor` reports a readable routing config and `codex-default` (or a configured alternative) as available.
+6. A text-only live smoke completes one harmless controller round before using `work` mode.
+
+Readiness does not prove a worker will succeed. Preserve the run evidence and report the exact missing prerequisite when a step fails.

package/docs/controller-protocol.md

@@ -0,0 +1,106 @@
+# Controller protocol
+
+CueLine `0.1` exchanges text messages with one ChatGPT web conversation. Each outbound prompt contains a `<CueLineObservation>` JSON document. The controller must answer with exactly one usable command in a complete `<CueLineControl>` envelope.
+
+## Identity
+
+Every command must echo these values from the pending observation:
+
+- `protocol`: `cueline/0.1`
+- `run_id`: the current persisted run
+- `round`: the current controller round
+- `request_id`: the deterministic identity of this 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.
+
+## Observation
+
+```json
+{
+  "protocol": "cueline/0.1",
+  "run_id": "run-example",
+  "round": 2,
+  "request_id": "msg-example",
+  "user_request": "Review the repository and recommend the next change.",
+  "jobs": [
+    {
+      "job_id": "job-example",
+      "job_key": "review",
+      "required": true,
+      "status": "succeeded",
+      "output": "Review evidence"
+    }
+  ],
+  "notices": []
+}
+```
+
+Job states are `pending`, `running`, `succeeded`, `failed`, `timed_out`, or `ambiguous`. Before browser submission, a single output/error field is bounded to 40,000 characters and only the most recent 20 notices are sent. The local event log remains the recovery record.
+
+## Command envelope
+
+```text
+<CueLineControl>
+{
+  "protocol": "cueline/0.1",
+  "run_id": "run-example",
+  "round": 2,
+  "request_id": "msg-example",
+  "action": "complete",
+  "final_delivery_text": "The review is complete."
+}
+</CueLineControl>
+```
+
+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.
+
+## Actions
+
+### `dispatch`
+
+Schedules one or more local jobs.
+
+```json
+{
+  "protocol": "cueline/0.1",
+  "run_id": "run-example",
+  "round": 1,
+  "request_id": "msg-example",
+  "action": "dispatch",
+  "jobs": [
+    {
+      "job_key": "architecture-review",
+      "lane": "default",
+      "mode": "advise",
+      "task": "Read the supplied repository evidence and propose a plan.",
+      "required": true,
+      "timeout_ms": 120000,
+      "background": false
+    }
+  ]
+}
+```
+
+`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`. The local runtime—not ChatGPT—resolves the configured executable. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. Repeating an already persisted deterministic job is ignored rather than spawned again.
+
+### `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.
+
+### `inspect`
+
+Asks CueLine to present the currently persisted job state on the next round. It does not grant the web controller a new local inspection tool.
+
+### `complete`
+
+Ends the run with non-empty `final_delivery_text`. Completion is rejected while any required job remains `pending` or `running`; the controller receives a notice and must decide again. Completed required jobs may have failed—the controller is responsible for judging that evidence.
+
+### `blocked`
+
+Ends the run with a non-empty `reason` and optional `final_delivery_text`. This is a terminal, explicit statement that the controller cannot responsibly proceed with the available evidence or authority.
+
+## Validation and repair
+
+CueLine rejects missing markers, malformed JSON, invalid actions, stale identity, invalid supported-field values, and duplicate `job_key` values 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.
+
+The JSON Schema files under `schemas/` are publication references. Runtime structural validation is implemented locally and does not require a schema package.

package/docs/provenance.md

@@ -0,0 +1,10 @@
+# Provenance
+
+CueLine is a new implementation combining two ideas behind one public API:
+
+- A deterministic lane router inspired by Omnilane's candidate chains and pre-spawn availability checks.
+- A text-only ChatGPT web controller adapter informed by GPT Relay's observed browser behavior.
+
+No CueLine runtime module imports either project. No browser cookies, local credentials, provider sessions, or machine-specific state are included in this repository.
+
+The initial architecture was reviewed through a ChatGPT Pro conversation. That review recommended a TypeScript state-machine core, append-only events, deterministic identifiers, explicit controller envelopes, and no automatic worker fallback after execution starts.

package/docs/runner-contract.md

@@ -0,0 +1,61 @@
+# Runner contract
+
+## Routing happens before spawn
+
+A controller job names a lane, not arbitrary shell text. CueLine loads an enabled lane and examines candidates in configured order. Disabled or unavailable candidates are skipped before execution. The first available candidate becomes the resolved route.
+
+Once its process starts, the selection is final. A failure, timeout, empty result, or ambiguous side effect is returned to the controller; CueLine does not silently try the next candidate.
+
+## Registered executable boundary
+
+Every process uses a `RunnerSpec`:
+
+```ts
+interface RunnerSpec {
+  jobId: string;
+  argv: readonly string[];
+  stdin?: string;
+  mode: "advise" | "work";
+  timeoutMs: number;
+  background?: boolean;
+  lane?: string;
+  task?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}
+```
+
+`argv[0]` must exactly match an executable registered from the loaded routing config. A route explicitly chooses task input through a `{task}` argv placeholder or stdin; materialization rejects a missing or duplicate placement. Other supported placeholders are expanded as individual argv elements before spawn. CueLine invokes Node's process API with `shell: false`; it does not concatenate controller text into a shell command. Registration is an allow-list, not a sandbox: the registered program still has the OS permissions of the local CueLine process.
+
+## Execution semantics
+
+- `CUELINE_DEPTH=1` is injected into the child.
+- A pre-existing `CUELINE_DEPTH` in the process or job environment rejects nested routing.
+- Standard input is closed unless the route explicitly selects stdin task input; stdout and stderr are captured as UTF-8 text.
+- The effective output is stdout, stderr, or both in that order.
+- Exit code 0 is `succeeded`; a non-zero exit or spawn error is `failed`.
+- At timeout CueLine sends `SIGTERM`, then schedules `SIGKILL` after 250 ms if needed; the result is `timed_out`.
+- Empty output is explicitly recorded instead of being replaced with invented content.
+- Results are never marked retryable by the process runner.
+
+For an unsuccessful `work` job, `ambiguousSideEffects` is true because CueLine cannot prove how much mutation occurred before failure. That flag is preserved in the job result. Such work must be inspected and explicitly decided by the web controller; it must not be auto-retried.
+
+## Foreground and background
+
+A foreground `start` waits for the single execution and persists its terminal status. A background `start` persists and returns `running` immediately while the same completion promise continues. `waitForCompletion(jobId)` returns that completion or the last persisted status.
+
+The controller loop derives deterministic job IDs from the run, `job_key`, and job specification. A duplicate dispatch already present in run state is recorded as a notice and skipped. This is the run-level at-most-once gate; it is not a distributed transaction across hosts.
+
+## Availability
+
+Candidate availability is evaluated locally through an injected function/checker or candidate-ID map. Availability means only that the runtime has accepted the candidate before spawn. It does not guarantee that credentials, network services, model quotas, or the target worker will remain healthy after start.
+
+## Side-effect policy
+
+Use `advise` for analysis that should not mutate the target. Use `work` only when the user request authorizes local changes and the selected worker has a suitable work directory. CueLine does not broaden permissions from `advise` to `work`, publish externally, or grant browser ChatGPT direct machine access.
+
+The controller chooses the intent; Codex and local runtime policy remain responsible for whether that intent is authorized and executable.
+
+## Bundled default
+
+The `default` lane contains one candidate, `codex-default`. It runs `codex exec` without a shell, sends the task over stdin, uses the requested work directory, and maps `advise` to `read-only` and `work` to `workspace-write`. The default route is unavailable when the `codex` executable is not on `PATH`; CueLine reports that fact instead of selecting an unrelated worker.

package/docs/state-and-recovery.md

@@ -0,0 +1,67 @@
+# State and recovery
+
+## Default layout
+
+CueLine state defaults to:
+
+```text
+${CUELINE_HOME:-$HOME/.cueline}/
+├── runs/
+│   └── <run-id>/
+│       ├── events.jsonl
+│       └── snapshot.json
+└── jobs/
+    └── <job-id>.json
+```
+
+`CUELINE_HOME` accepts an absolute or relative path. `~` and `~/...` are expanded against `HOME`. Run and job IDs are validated before they are used in filesystem paths.
+
+## Event log
+
+`events.jsonl` is append-only and authoritative. Each line contains a monotonically increasing sequence number, timestamp, event type, and payload. The writer opens the file with owner-only mode when creating it and calls `sync` after every append.
+
+Important transitions include:
+
+- run creation and resumption
+- controller turn intent, response, rejection, and accepted command
+- job registration and status changes
+- notices
+- complete, blocked, and failed terminal records
+
+The controller turn is recorded before sending it through the browser, and a job is registered before its process starts. This ordering leaves evidence when an interruption occurs between intent and side effect.
+
+## Snapshot
+
+`snapshot.json` is a materialized view of the event stream. CueLine writes a temporary file in the same directory and renames it over the destination. A snapshot records its state protocol, run ID, and last applied sequence.
+
+On load, CueLine uses a snapshot only when its identity and sequence are valid. A missing, malformed, or out-of-range snapshot is ignored and the state is replayed from event 1. Events newer than a valid snapshot are applied afterward.
+
+The snapshot is therefore disposable. Do not edit the event log by hand; invalid JSON or a broken sequence makes the run unreplayable and is reported rather than silently skipped.
+
+## Job status
+
+The supervisor atomically replaces one JSON file per job. Foreground work returns its terminal status directly. Background work first persists `running`; later `wait` reads the same in-process completion or the last persisted status.
+
+The run event log still records the controller-visible job transitions. A status file is execution evidence, not a substitute for the run history.
+
+## Continue behavior
+
+`continueCueLineRun` loads the exact `runId`, replays state as needed, and resumes the next controller round in the same persisted run. The public runtime also reuses the stored ChatGPT conversation URL unless an explicit compatible adapter is supplied.
+
+- `complete` and `blocked` runs are returned as-is; they are not dispatched again.
+- a non-terminal or locally `failed` run can be marked resumed and driven for additional rounds
+- deterministic job IDs suppress a repeated dispatch already present in state
+- running jobs can be observed or waited through their persisted status
+
+Continuation cannot reconstruct an expired ChatGPT login, a deleted conversation, an unavailable registered executable, or an in-memory child process that disappeared with the host process. In those cases CueLine reports the concrete failure; it does not fabricate completion.
+
+## Recovery procedure
+
+1. Preserve `CUELINE_HOME`; do not delete the run directory.
+2. Record the `runId` from the earlier result or directory name.
+3. Restore access to the same ChatGPT conversation in Codex's built-in Browser.
+4. Restore any locally required executable/configuration without copying browser credentials.
+5. Call `continueCueLineRun({ runId, ... })`.
+6. Treat the new terminal result as valid only after its event and job evidence is present.
+
+For manual diagnosis, use `cueline jobs` and inspect the run's JSONL as read-only evidence. Do not copy `CUELINE_HOME` between machines as a replacement for local process or browser session state.