cueline 0.1.2 → 0.1.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Use a ChatGPT web conversation as the controller for durable local agent work.",
   "author": {
     "name": "CueLine contributors"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Use a ChatGPT web conversation as the controller for durable local agent work.",
   "author": {
     "name": "CueLine contributors"

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.3 - 2026-07-15
+
+### Fixed
+
+- Add `cueline run status <run-id> --json` with accepted-controller-response evidence, the last accepted action and job keys, runtime ownership, safe next action, cancellation requests, and derived `orphaned` jobs. A new session no longer calls a persisted `running` value active when no live owner is proven.
+- Add an owner heartbeat lease. A second session refuses to continue an active run, and a missing or stale owner requires inspection instead of another controller send.
+- Run independent all-`advise` dispatches concurrently. Any dispatch containing `work` remains serial to avoid overlapping mutations.
+- Add durable `run cancel` / `run stop` and `job cancel` requests, API `AbortSignal` support, and `runTimeoutMs`. Active `advise` cancellation becomes `cancelled`; interrupted `work` or ownerless legacy work becomes `ambiguous`.
+- Persist job run ID, job key, lane, mode, and child PID for diagnosis. `cueline jobs --json` reports an observed status and never uses PID alone as kill authorization.
+- Reject unsupported `runner_id` explicitly, require `runner`, and explain when a runner ID such as `codex-default` was placed in `lane`.
+- Preserve built-in-browser attach failures instead of converting them to an empty tab list. Retry safe pre-submit attachment once, recheck an empty discovery result once, cache a new tab only after it loads, and use at most one CUA coordinate fallback after a transient send-locator failure.
+
+### Documentation
+
+- Require `run status` before continuation and distinguish controller response acceptance, local job execution, runtime ownership, and outer waiter timeout.
+- Document cancellation, run-level deadlines, `advise` concurrency, `work` serialization, and stale-job recovery semantics.
+
 ## 0.1.2 - 2026-07-15
 
 ### Fixed

package/README.ja.md

@@ -44,15 +44,15 @@ ChatGPT Pro のサブスクリプションと、選択された Pro モデルは
 npm レジストリからインストールします。
 
 ```bash
-npm install -g cueline@0.1.2
+npm install -g cueline@0.1.3
 cueline install
 cueline doctor
 ```
 
-フォールバックとして、[v0.1.2 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.2) のパッケージ済み tarball をインストールすることもできます。同じリリースに `.sha256` チェックサムも置いてあります。
+フォールバックとして、[v0.1.3 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.3) のパッケージ済み tarball をインストールすることもできます。同じリリースに `.sha256` チェックサムも置いてあります。
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.2/cueline-0.1.2.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.3/cueline-0.1.3.tgz
 cueline install
 cueline doctor
 ```
@@ -89,7 +89,8 @@ import { createCodexIabAdapter, runCueLine } from "cueline";
 const result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
   browser: createCodexIabAdapter(),
-  // 任意：conversationUrl、routingConfig / routingConfigPath、home、cwd、limits。
+  // 任意：conversationUrl、routingConfig / routingConfigPath、home、cwd、
+  // runTimeoutMs、signal、ジョブごと／既定の期限。
 });
 
 if (result.status === "complete") {
@@ -99,7 +100,7 @@ if (result.status === "complete") {
 
 Codex のランタイムでは、`cueline api path` が出力する絶対パスのモジュールを import します。それがインストールしたパッケージのビルド済み API です。
 
-`startCueLineRun` が明示的な開始点です（`runCueLine` はその別名）。`continueCueLineRun({ runId })` は中断した実行を同じ会話で再開し、新しいアダプターを渡さないかぎり保存済みの会話 URL を再利用します。`loadCueLineRunState(runId)` は永続化された状態を読むだけで、何も駆動しません。すでに `complete` または `blocked` に達した実行はそのまま返され、二度とディスパッチされません。
+`startCueLineRun` が明示的な開始点です（`runCueLine` はその別名）。`continueCueLineRun({ runId })` は中断した実行を同じ会話で再開し、新しいアダプターを渡さないかぎり保存済みの会話 URL を再利用します。`loadCueLineRunState(runId)` は永続化された状態を読むだけで、何も駆動しません。すでに `complete`、`blocked`、または `cancelled` に達した実行はそのまま返され、二度とディスパッチされません。再開前に `cueline run status <run-id> --json` を実行してください。応答が受理済みで phase が `jobs_running` なら、ChatGPT の応答後にローカルジョブを実行中です。
 
 ## CLI
 
@@ -110,7 +111,7 @@ $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.2
+CueLine 0.1.3
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -126,6 +127,12 @@ default	codex-default	available
 $ cueline jobs
 No jobs.
 
+$ cueline run status run_... --json
+{"status":"running","phase":"jobs_running","runtime":{"ownership":"active"},...}
+
+$ cueline run cancel run_...
+run_...	requested	affected_jobs=0
+
 $ cueline config path
 /usr/local/lib/node_modules/cueline/config/routing.default.json
 
@@ -145,6 +152,8 @@ Node が古すぎる場合、あるいは解決できるレーンが一つもな
 
 ```text
 runs/<run-id>/events.jsonl    追記のみ、正本
+runs/<run-id>/runtime.json   ライブ owner の heartbeat 証拠
+runs/<run-id>/cancel.json    存在する場合は永続キャンセル要求
 runs/<run-id>/snapshot.json   リプレイの最適化、破棄可能
 jobs/<job-id>.json            ジョブごとの実行証拠
 ```

package/README.ko.md

@@ -44,15 +44,15 @@ ChatGPT Pro 구독과 선택된 Pro 모델은 서로 다른 것입니다. 계정
 npm 레지스트리에서 설치합니다:
 
 ```bash
-npm install -g cueline@0.1.2
+npm install -g cueline@0.1.3
 cueline install
 cueline doctor
 ```
 
-대안으로, [v0.1.2 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.2)의 패키지 tarball을 설치할 수도 있습니다. 같은 릴리스에 `.sha256` 체크섬도 함께 있습니다.
+대안으로, [v0.1.3 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.3)의 패키지 tarball을 설치할 수도 있습니다. 같은 릴리스에 `.sha256` 체크섬도 함께 있습니다.
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.2/cueline-0.1.2.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.3/cueline-0.1.3.tgz
 cueline install
 cueline doctor
 ```
@@ -89,7 +89,8 @@ import { createCodexIabAdapter, runCueLine } from "cueline";
 const result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
   browser: createCodexIabAdapter(),
-  // 선택: conversationUrl, routingConfig / routingConfigPath, home, cwd, limits.
+  // 선택: conversationUrl, routingConfig / routingConfigPath, home, cwd,
+  // runTimeoutMs, signal, 작업별/기본 제한 시간.
 });
 
 if (result.status === "complete") {
@@ -99,7 +100,7 @@ if (result.status === "complete") {
 
 Codex 런타임에서는 `cueline api path`가 출력하는 절대 경로 모듈을 import하세요. 그것이 설치한 패키지의 빌드된 API입니다.
 
-`startCueLineRun`이 명시적인 시작점입니다(`runCueLine`은 그 별칭). `continueCueLineRun({ runId })`은 중단된 실행을 같은 대화에서 재개하며, 새 어댑터를 넘기지 않는 한 저장된 대화 URL을 재사용합니다. `loadCueLineRunState(runId)`는 저장된 상태를 읽기만 하고 아무것도 구동하지 않습니다. 이미 `complete`나 `blocked`에 도달한 실행은 그대로 반환되며, 두 번 디스패치되지 않습니다.
+`startCueLineRun`이 명시적인 시작점입니다(`runCueLine`은 그 별칭). `continueCueLineRun({ runId })`은 중단된 실행을 같은 대화에서 재개하며, 새 어댑터를 넘기지 않는 한 저장된 대화 URL을 재사용합니다. `loadCueLineRunState(runId)`는 저장된 상태를 읽기만 하고 아무것도 구동하지 않습니다. 이미 `complete`, `blocked`, `cancelled`에 도달한 실행은 그대로 반환되며, 두 번 디스패치되지 않습니다. 재개 전 `cueline run status <run-id> --json`을 실행하십시오. 응답이 수락되었고 phase가 `jobs_running`이면 ChatGPT 응답은 끝났고 로컬 작업이 실행 중입니다.
 
 ## CLI
 
@@ -110,7 +111,7 @@ $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.2
+CueLine 0.1.3
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -126,6 +127,12 @@ default	codex-default	available
 $ cueline jobs
 No jobs.
 
+$ cueline run status run_... --json
+{"status":"running","phase":"jobs_running","runtime":{"ownership":"active"},...}
+
+$ cueline run cancel run_...
+run_...	requested	affected_jobs=0
+
 $ cueline config path
 /usr/local/lib/node_modules/cueline/config/routing.default.json
 
@@ -145,6 +152,8 @@ Node 버전이 너무 낮거나 해석 가능한 레인이 하나도 없으면 `
 
 ```text
 runs/<run-id>/events.jsonl    추가 전용, 정본
+runs/<run-id>/runtime.json   활성 owner의 heartbeat 증거
+runs/<run-id>/cancel.json    존재할 때 지속 취소 요청
 runs/<run-id>/snapshot.json   재생 최적화용, 버려도 무방
 jobs/<job-id>.json            작업별 실행 증거
 ```

package/README.md

@@ -44,15 +44,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.2
+npm install -g cueline@0.1.3
 cueline install
 cueline doctor
 ```
 
-As a fallback, install the packaged tarball from the [v0.1.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.2), which also carries its `.sha256` checksum:
+As a fallback, install the packaged tarball from the [v0.1.3 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.3), which also carries its `.sha256` checksum:
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.2/cueline-0.1.2.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.3/cueline-0.1.3.tgz
 cueline install
 cueline doctor
 ```
@@ -89,7 +89,8 @@ import { createCodexIabAdapter, runCueLine } from "cueline";
 const result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
   browser: createCodexIabAdapter(),
-  // Optional: conversationUrl, routingConfig / routingConfigPath, home, cwd, limits.
+  // Optional: conversationUrl, routingConfig / routingConfigPath, home, cwd,
+  // runTimeoutMs, signal, and per-job/default limits.
 });
 
 if (result.status === "complete") {
@@ -97,7 +98,7 @@ if (result.status === "complete") {
 }
 ```
 
-`startCueLineRun` is the explicit start (`runCueLine` is its alias). `continueCueLineRun({ runId })` resumes an interrupted run in the same conversation, and reuses the stored conversation URL unless you hand it a new adapter. `loadCueLineRunState(runId)` reads persisted state without driving anything. A run that already reached `complete` or `blocked` is returned as-is, never dispatched twice.
+`startCueLineRun` is the explicit start (`runCueLine` is its alias). `continueCueLineRun({ runId })` resumes an interrupted run in the same conversation, and reuses the stored conversation URL unless you hand it a new adapter. `loadCueLineRunState(runId)` reads persisted state without driving anything. A run that already reached `complete`, `blocked`, or `cancelled` is returned as-is, never dispatched twice. Before continuation, run `cueline run status <run-id> --json`: an accepted response plus `jobs_running` means ChatGPT already answered and local jobs are executing.
 
 Inside Codex's runtime, import the absolute module that `cueline api path` prints — that is the built API of the package you installed.
 
@@ -110,7 +111,7 @@ $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.2
+CueLine 0.1.3
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -126,6 +127,12 @@ default	codex-default	available
 $ cueline jobs
 No jobs.
 
+$ cueline run status run_... --json
+{"status":"running","phase":"jobs_running","runtime":{"ownership":"active"},...}
+
+$ cueline run cancel run_...
+run_...	requested	affected_jobs=0
+
 $ cueline config path
 /usr/local/lib/node_modules/cueline/config/routing.default.json
 
@@ -145,6 +152,8 @@ State lives under `CUELINE_HOME`:
 
 ```text
 runs/<run-id>/events.jsonl    append-only, authoritative
+runs/<run-id>/runtime.json   live-owner heartbeat evidence
+runs/<run-id>/cancel.json    durable cancellation request, when present
 runs/<run-id>/snapshot.json   a replay optimization, disposable
 jobs/<job-id>.json            per-job execution evidence
 ```

package/README.zh-CN.md

@@ -44,15 +44,15 @@ ChatGPT Pro 订阅套餐与“选定的 Pro 模型”是两回事。账号或个
 从 npm registry 安装：
 
 ```bash
-npm install -g cueline@0.1.2
+npm install -g cueline@0.1.3
 cueline install
 cueline doctor
 ```
 
-作为后备，也可以安装 [v0.1.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.2) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
+作为后备，也可以安装 [v0.1.3 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.3) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.2/cueline-0.1.2.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.3/cueline-0.1.3.tgz
 cueline install
 cueline doctor
 ```
@@ -89,7 +89,8 @@ import { createCodexIabAdapter, runCueLine } from "cueline";
 const result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
   browser: createCodexIabAdapter(),
-  // 可选：conversationUrl、routingConfig / routingConfigPath、home、cwd、limits。
+  // 可选：conversationUrl、routingConfig / routingConfigPath、home、cwd、
+  // runTimeoutMs、signal，以及作业/默认期限。
 });
 
 if (result.status === "complete") {
@@ -99,7 +100,7 @@ if (result.status === "complete") {
 
 在 Codex 的 runtime 里，import `cueline api path` 打印出的那个绝对路径模块——那就是你安装的那份包构建出来的 API。
 
-`startCueLineRun` 是显式的启动入口（`runCueLine` 是它的别名）。`continueCueLineRun({ runId })` 会在同一个会话中续跑被中断的运行，并复用已保存的会话链接，除非你传入新的 adapter。`loadCueLineRunState(runId)` 只读取已持久化的状态，不驱动任何东西。已经到达 `complete` 或 `blocked` 的运行会原样返回，绝不会被再次派发。
+`startCueLineRun` 是显式的启动入口（`runCueLine` 是它的别名）。`continueCueLineRun({ runId })` 会在同一个会话中续跑被中断的运行，并复用已保存的会话链接，除非你传入新的 adapter。`loadCueLineRunState(runId)` 只读取已持久化的状态，不驱动任何东西。已经到达 `complete`、`blocked` 或 `cancelled` 的运行会原样返回，绝不会被再次派发。续跑前先执行 `cueline run status <run-id> --json`；已接受回复且 phase 为 `jobs_running` 表示 ChatGPT 已回复，本地作业正在执行。
 
 ## CLI
 
@@ -110,7 +111,7 @@ $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.2
+CueLine 0.1.3
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -126,6 +127,12 @@ default	codex-default	available
 $ cueline jobs
 No jobs.
 
+$ cueline run status run_... --json
+{"status":"running","phase":"jobs_running","runtime":{"ownership":"active"},...}
+
+$ cueline run cancel run_...
+run_...	requested	affected_jobs=0
+
 $ cueline config path
 /usr/local/lib/node_modules/cueline/config/routing.default.json
 
@@ -145,6 +152,8 @@ CueLine skill removed: /Users/you/.codex/skills/cueline
 
 ```text
 runs/<run-id>/events.jsonl    仅追加、具权威性
+runs/<run-id>/runtime.json   活跃 owner 的 heartbeat 证据
+runs/<run-id>/cancel.json    存在时表示持久取消请求
 runs/<run-id>/snapshot.json   重放优化产物，可丢弃
 jobs/<job-id>.json            每个作业的执行证据
 ```

package/README.zh-TW.md

@@ -44,15 +44,15 @@ ChatGPT Pro 訂閱方案與「選定的 Pro 模型」是兩回事。帳號或個
 從 npm registry 安裝：
 
 ```bash
-npm install -g cueline@0.1.2
+npm install -g cueline@0.1.3
 cueline install
 cueline doctor
 ```
 
-作為備援，也可以安裝 [v0.1.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.2) 上的打包 tarball，該 release 同時附上它的 `.sha256` 校驗碼：
+作為備援，也可以安裝 [v0.1.3 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.1.3) 上的打包 tarball，該 release 同時附上它的 `.sha256` 校驗碼：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.2/cueline-0.1.2.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.1.3/cueline-0.1.3.tgz
 cueline install
 cueline doctor
 ```
@@ -89,7 +89,8 @@ import { createCodexIabAdapter, runCueLine } from "cueline";
 const result = await runCueLine({
   request: "Inspect the repository, delegate an implementation plan, and report the evidence.",
   browser: createCodexIabAdapter(),
-  // 選填：conversationUrl、routingConfig / routingConfigPath、home、cwd、limits。
+  // 選填：conversationUrl、routingConfig / routingConfigPath、home、cwd、
+  // runTimeoutMs、signal，以及各工作／預設期限。
 });
 
 if (result.status === "complete") {
@@ -99,7 +100,7 @@ if (result.status === "complete") {
 
 在 Codex 的 runtime 裡，import `cueline api path` 印出的那個絕對路徑模組——那就是你安裝的那份套件建置出來的 API。
 
-`startCueLineRun` 是明確的啟動入口（`runCueLine` 是它的別名）。`continueCueLineRun({ runId })` 會在同一個對話裡續跑被中斷的執行，並沿用已保存的對話網址，除非你另外傳入新的 adapter。`loadCueLineRunState(runId)` 只讀取已保存的狀態，不驅動任何東西。已經走到 `complete` 或 `blocked` 的執行會原樣回傳，絕不會被再派工一次。
+`startCueLineRun` 是明確的啟動入口（`runCueLine` 是它的別名）。`continueCueLineRun({ runId })` 會在同一個對話裡續跑被中斷的執行，並沿用已保存的對話網址，除非你另外傳入新的 adapter。`loadCueLineRunState(runId)` 只讀取已保存的狀態，不驅動任何東西。已經走到 `complete`、`blocked` 或 `cancelled` 的執行會原樣回傳，絕不會被再派工一次。續跑前先執行 `cueline run status <run-id> --json`；若回覆已採用且 phase 是 `jobs_running`，代表 ChatGPT 已回覆，現在跑的是本機工作。
 
 ## CLI
 
@@ -110,7 +111,7 @@ $ cueline install
 CueLine skill installed: /Users/you/.codex/skills/cueline
 
 $ cueline doctor
-CueLine 0.1.2
+CueLine 0.1.3
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -126,6 +127,12 @@ default	codex-default	available
 $ cueline jobs
 No jobs.
 
+$ cueline run status run_... --json
+{"status":"running","phase":"jobs_running","runtime":{"ownership":"active"},...}
+
+$ cueline run cancel run_...
+run_...	requested	affected_jobs=0
+
 $ cueline config path
 /usr/local/lib/node_modules/cueline/config/routing.default.json
 
@@ -145,6 +152,8 @@ Node 版本太舊、或沒有任何通道解析得出來時，`cueline doctor`
 
 ```text
 runs/<run-id>/events.jsonl    只追加、具權威性
+runs/<run-id>/runtime.json   活 owner 的 heartbeat 證據
+runs/<run-id>/cancel.json    存在時代表持久取消要求
 runs/<run-id>/snapshot.json   重播的最佳化產物，可丟棄
 jobs/<job-id>.json            每個工作的執行證據
 ```

package/dist/src/api.d.ts

@@ -1,6 +1,7 @@
 import type { BrowserAdapter } from "./browser/browser-adapter.js";
 import { createCodexIabAdapter, type CodexIabAdapterOptions } from "./browser/codex-iab/chatgpt-client.js";
 import { type CueLineResult } from "./core/controller-loop.js";
+import { type CueLineRunStatusSummary } from "./core/run-status.js";
 import { type CueLineRunState } from "./core/state-machine.js";
 import type { RoutingConfig } from "./router/types.js";
 export interface CueLineRuntimeOptions {
@@ -16,6 +17,9 @@ export interface CueLineRuntimeOptions {
     maxRounds?: number;
     maxRepairAttempts?: number;
     now?: () => Date;
+    signal?: AbortSignal;
+    cancellationPollIntervalMs?: number;
+    runTimeoutMs?: number;
 }
 export interface StartCueLineRunOptions extends CueLineRuntimeOptions {
     request: string;
@@ -26,11 +30,29 @@ export interface ContinueCueLineRunOptions extends CueLineRuntimeOptions {
     reconcileRequestId?: string;
     abandonOtherPendingTurns?: boolean;
 }
+export interface CueLineRunCancellationResult {
+    runId: string;
+    outcome: "requested" | "cancelled" | "already_terminal";
+    affectedJobs: number;
+}
+export interface CueLineJobCancellationResult {
+    runId: string;
+    jobId: string;
+    outcome: "requested" | "ambiguous" | "already_terminal";
+}
 export declare function defaultRoutingConfigPath(): string;
 export declare function routingConfigPath(environment?: NodeJS.ProcessEnv, explicitPath?: string): string;
 export declare function loadCueLineRunState(runId: string, options?: Pick<CueLineRuntimeOptions, "home" | "environment">): Promise<CueLineRunState>;
+export declare function loadCueLineRunStatus(runId: string, options?: Pick<CueLineRuntimeOptions, "home" | "environment" | "now">): Promise<CueLineRunStatusSummary>;
+export declare function cancelCueLineRun(runId: string, options?: Pick<CueLineRuntimeOptions, "home" | "environment" | "now"> & {
+    reason?: string;
+}): Promise<CueLineRunCancellationResult>;
+export declare function cancelCueLineJob(runId: string, jobId: string, options?: Pick<CueLineRuntimeOptions, "home" | "environment" | "now"> & {
+    reason?: string;
+}): Promise<CueLineJobCancellationResult>;
 export declare function startCueLineRun(options: StartCueLineRunOptions): Promise<CueLineResult>;
 export declare function runCueLine(options: StartCueLineRunOptions): Promise<CueLineResult>;
 export declare function continueCueLineRun(options: ContinueCueLineRunOptions): Promise<CueLineResult>;
 export { createCodexIabAdapter };
-export type { BrowserAdapter, CueLineResult, CueLineRunState, RoutingConfig };
+export { CUELINE_VERSION } from "./version.js";
+export type { BrowserAdapter, CueLineResult, CueLineRunState, CueLineRunStatusSummary, RoutingConfig, };

package/dist/src/api.js

@@ -3,6 +3,7 @@ import { createCodexIabAdapter, } from "./browser/codex-iab/chatgpt-client.js";
 import { continueControllerLoop, runControllerLoop, } from "./core/controller-loop.js";
 import { CueLineError } from "./core/errors.js";
 import { runtimeCwd, runtimeEnvironment } from "./core/runtime.js";
+import { acceptedControllerCommandEvidence, assertRunCanContinue, summarizeCueLineRunState, } from "./core/run-status.js";
 import { initialRunState, reduceRunState, } from "./core/state-machine.js";
 import { JobStatusStore } from "./jobs/status.js";
 import { JobSupervisor } from "./jobs/supervisor.js";
@@ -12,7 +13,10 @@ import { materializeRunnerSpec } from "./router/materialize.js";
 import { resolveRoute } from "./router/resolver.js";
 import { ProcessRunner } from "./runners/process-runner.js";
 import { RunnerRegistry } from "./runners/registry.js";
-import { defaultCueLineHome } from "./state/paths.js";
+import { readCancellationObservation, requestJobCancellation, requestRunCancellation, } from "./state/cancellation.js";
+import { readEvents } from "./state/event-log.js";
+import { defaultCueLineHome, runPaths } from "./state/paths.js";
+import { readRuntimeLease } from "./state/runtime-lease.js";
 import { RunStore } from "./state/store.js";
 function assertNotNested(environment) {
     if (environment.CUELINE_DEPTH !== undefined) {
@@ -25,7 +29,7 @@ export function defaultRoutingConfigPath() {
 export function routingConfigPath(environment = runtimeEnvironment(), explicitPath) {
     return explicitPath ?? environment.CUELINE_CONFIG ?? defaultRoutingConfigPath();
 }
-async function persistedRunState(home, runId) {
+async function persistedRunStore(home, runId) {
     const store = await RunStore.load({
         home,
         runId,
@@ -36,10 +40,15 @@ async function persistedRunState(home, runId) {
     if (state.request === "") {
         throw new CueLineError("RUN_NOT_FOUND", `No persisted CueLine run '${runId}' was found.`);
     }
-    return state;
+    return store;
+}
+async function persistedRunState(home, runId) {
+    return (await persistedRunStore(home, runId)).state;
 }
 function terminalResult(state) {
-    if (state.status !== "complete" && state.status !== "blocked") {
+    if (state.status !== "complete" &&
+        state.status !== "blocked" &&
+        state.status !== "cancelled") {
         throw new CueLineError("RUN_NOT_TERMINAL", "CueLine result requested before a terminal state.");
     }
     return {
@@ -47,6 +56,7 @@ function terminalResult(state) {
         status: state.status,
         ...(state.finalDeliveryText === null ? {} : { finalDeliveryText: state.finalDeliveryText }),
         ...(state.conversationUrl === null ? {} : { conversationUrl: state.conversationUrl }),
+        ...(state.cancelledReason === null ? {} : { cancelledReason: state.cancelledReason }),
         state,
     };
 }
@@ -54,6 +64,86 @@ export async function loadCueLineRunState(runId, options = {}) {
     const environment = options.environment ?? runtimeEnvironment();
     return persistedRunState(options.home ?? defaultCueLineHome(environment), runId);
 }
+export async function loadCueLineRunStatus(runId, options = {}) {
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const store = await persistedRunStore(home, runId);
+    const runtime = await readRuntimeLease(home, runId, {
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const cancellation = await readCancellationObservation(home, runId);
+    const acceptedCommand = acceptedControllerCommandEvidence(await readEvents(runPaths(home, runId).events));
+    return summarizeCueLineRunState(store.state, store.lastSequence, runtime, cancellation, acceptedCommand);
+}
+function isTerminalRun(state) {
+    return (state.status === "complete" || state.status === "blocked" || state.status === "cancelled");
+}
+export async function cancelCueLineRun(runId, options = {}) {
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const store = await persistedRunStore(home, runId);
+    if (isTerminalRun(store.state)) {
+        return { runId, outcome: "already_terminal", affectedJobs: 0 };
+    }
+    const reason = options.reason ?? "operator requested cancellation";
+    await requestRunCancellation(home, runId, reason, options.now);
+    const runtime = await readRuntimeLease(home, runId, {
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    if (runtime.ownership === "active" ||
+        runtime.ownership === "stale" ||
+        runtime.ownership === "invalid") {
+        return { runId, outcome: "requested", affectedJobs: 0 };
+    }
+    const active = Object.values(store.state.jobs).filter((job) => job.status === "pending" || job.status === "running");
+    for (const job of active) {
+        await store.append("job_status", {
+            job_id: job.jobId,
+            status: "ambiguous",
+            error: "Run cancelled without a verifiable active runtime; process outcome is unknown.",
+        });
+    }
+    await store.append("run_cancelled", { reason });
+    await store.snapshot();
+    return { runId, outcome: "cancelled", affectedJobs: active.length };
+}
+export async function cancelCueLineJob(runId, jobId, options = {}) {
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const store = await persistedRunStore(home, runId);
+    const job = store.state.jobs[jobId];
+    if (job === undefined) {
+        throw new CueLineError("JOB_NOT_FOUND", `No job '${jobId}' exists in run '${runId}'.`);
+    }
+    if (isTerminalRun(store.state) ||
+        (job.status !== "pending" && job.status !== "running")) {
+        return { runId, jobId, outcome: "already_terminal" };
+    }
+    const reason = options.reason ?? "operator requested job cancellation";
+    await requestJobCancellation(home, runId, jobId, reason, options.now);
+    const runtime = await readRuntimeLease(home, runId, {
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    if (runtime.ownership === "active" ||
+        runtime.ownership === "stale" ||
+        runtime.ownership === "invalid") {
+        return { runId, jobId, outcome: "requested" };
+    }
+    await store.append("job_status", {
+        job_id: jobId,
+        status: "ambiguous",
+        error: "Job cancelled without a verifiable active runtime; process outcome is unknown.",
+    });
+    if (store.state.status === "running") {
+        await store.append("run_failed", {
+            code: "JOB_CANCELLED_WITHOUT_ACTIVE_RUNTIME",
+            message: `Job '${jobId}' was marked ambiguous because no active owner could confirm termination.`,
+            stage: "job_cancellation",
+        });
+    }
+    await store.snapshot();
+    return { runId, jobId, outcome: "ambiguous" };
+}
 async function resolvedRoutingConfig(options, environment) {
     return (options.routingConfig ??
         (await loadRoutingConfig(routingConfigPath(environment, options.routingConfigPath))));
@@ -78,7 +168,7 @@ function routingInstruction(config, availability) {
             .map((candidate) => candidate.id);
         return `${name} [${candidates.length > 0 ? candidates.join(", ") : "unavailable"}]`;
     });
-    return `Available routing lanes: ${lanes.join("; ")}. Use only a listed available lane and optional runner id.`;
+    return `Available routing lanes: ${lanes.join("; ")}. Use only a listed lane. Select an optional candidate with the field runner; never use runner_id or place a runner ID in lane.`;
 }
 async function prepareRuntime(options, persistedConversationUrl) {
     const environment = options.environment ?? runtimeEnvironment();
@@ -126,6 +216,11 @@ export async function startCueLineRun(options) {
             ? {}
             : { maxRepairAttempts: options.maxRepairAttempts }),
         ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.cancellationPollIntervalMs === undefined
+            ? {}
+            : { cancellationPollIntervalMs: options.cancellationPollIntervalMs }),
+        ...(options.runTimeoutMs === undefined ? {} : { runTimeoutMs: options.runTimeoutMs }),
     });
 }
 export async function runCueLine(options) {
@@ -135,9 +230,12 @@ export async function continueCueLineRun(options) {
     const environment = options.environment ?? runtimeEnvironment();
     const home = options.home ?? defaultCueLineHome(environment);
     const state = await persistedRunState(home, options.runId);
-    if (state.status === "complete" || state.status === "blocked") {
+    if (isTerminalRun(state)) {
         return terminalResult(state);
     }
+    assertRunCanContinue(state, await readRuntimeLease(home, options.runId, {
+        ...(options.now === undefined ? {} : { now: options.now }),
+    }), await readCancellationObservation(home, options.runId));
     assertNotNested(environment);
     const runtime = await prepareRuntime(options, state.conversationUrl ?? undefined);
     return continueControllerLoop({
@@ -154,7 +252,13 @@ export async function continueCueLineRun(options) {
             ? {}
             : { maxRepairAttempts: options.maxRepairAttempts }),
         ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.cancellationPollIntervalMs === undefined
+            ? {}
+            : { cancellationPollIntervalMs: options.cancellationPollIntervalMs }),
+        ...(options.runTimeoutMs === undefined ? {} : { runTimeoutMs: options.runTimeoutMs }),
     });
 }
 export { createCodexIabAdapter };
+export { CUELINE_VERSION } from "./version.js";
 //# sourceMappingURL=api.js.map