cueline 0.2.2 → 0.3.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Use a ChatGPT web conversation as the text controller for durable local advice or explicitly claimed work executed by the current Codex.",
   "author": {
     "name": "CueLine contributors"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Use a ChatGPT web conversation as the text controller for durable local advice or explicitly claimed work executed by the current Codex.",
   "author": {
     "name": "CueLine contributors"

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.3.1 - 2026-07-18
+
+### Fixed
+
+- Accept cancelled `ambiguous` job-result evidence produced when a running
+  `work` job is interrupted, keeping persisted run and job listings readable
+  without weakening cancellation checks for other terminal statuses.
+- Backfill `cancelled: false` when reading pre-0.1.7 job-result evidence that
+  predates the field, so legacy runs stay readable; writes still require the
+  full strict shape.
+
+### Verification
+
+- Verified with a red/green regression oracle (new tests fail on the 0.3.0
+  validator), TypeScript typecheck, build, 535/535 tests, all release gates,
+  and live recovery of three previously unreadable on-disk runs, cross-checked
+  by an independent adversarial review line.
+
+## 0.3.0 - 2026-07-17
+
+### Added
+
+- Operator tooling: `runs prune` retention sweep over terminal runs (dry-run
+  by default, deletion serialized with the runtime lease lock), `run
+  audit-secrets` masked scan of durable events for secret-shaped strings, and
+  `run export` one-file sanitized support bundles.
+- Release engineering: `self-test` offline controller-loop check, `upgrade
+  preflight` read-only migration report, `npm run release:check` release
+  gate, reproducible pack artifacts with SHA-256 verification, a
+  documentation version guard, and a Node 22/24/26 support contract in CI.
+- Machine-output contracts: versioned strict JSON Schemas for `doctor`,
+  `routing`, `routing explain`, `runs prune`, `run audit-secrets`, and
+  `run export`; contract tests reject added fields, nested injection, empty
+  sections, and contradictory shapes.
+
+### Fixed
+
+- Run-scoped commands fail closed for an absent run instead of fabricating a
+  healthy view; a sweep pins this for every read and mutating surface.
+- Secret audit reports a secret-shaped object key as a finding and masks it
+  in the finding path instead of echoing it verbatim.
+- Prune re-reads runtime ownership inside the lease mutation lock before
+  deletion, and only a definite ENOENT counts as a completed removal; any
+  other filesystem error keeps the run and records the error.
+
+### Verification
+
+- Verified TypeScript typecheck, build, 532/532 unit/integration/smoke tests,
+  plugin validation, pack dry-run, release:check, offline self-test, and
+  upgrade preflight on the unified candidate, cross-reviewed adversarially by
+  two independent lines (AJV negative oracle: seven malicious mutations all
+  rejected).
+
 ## 0.2.2 - 2026-07-17
 
 ### Fixed

package/README.ja.md

@@ -22,15 +22,12 @@
 
 CueLine は独立した実装で、**ランタイムの npm 依存はゼロ**です。Omnilane のラッパーではありません。
 
-## 最新リリース：0.2.2
+## 最新リリース：0.3.1
 
-- 設定可能で永続的な job 単位のコントローラー証拠上限を追加し（0.2.1）、記録されるすべての job イベントにも適用しました。イベントログとコントローラーへ提供される証拠は常に同じ上限を共有します。
-- 実 run で観測された証拠枯渇デッドロックを修正しました。過大なワーカー出力がコントローラーをラウンド上限内に終わらない inspect ページングループへ追い込むことはもうありません。
-- 容量警告はコントローラーが実際にページングできる証拠だけを数えます。永続上限を超える真の総量は独立した決定的な通知で開示され、証拠が十分ならコントローラーは早期に判断できます。
-- リプレイされた証拠はバイト単位で安定します。検証済みの正規上限マーカーはそのまま保持され、旧形式の切り詰めマーカーは整合性エラーなしに決定的へ再適用されます。
-- 490/490 テストに加え、実 process runner で検証しました。真の総量を持つ上限イベントマーカーを 1 つ書き込み、コントローラー 2 ターンで完了しました。
+- 永続 job ステータスのバリデータが、runner が実際に書き出す 2 つの形状を誤って拒否する問題を修正しました：キャンセルされた `work` job が `ambiguous` と `cancelled: true` で記録される形状、および `cancelled` フィールド導入前（0.1.7 未満）の旧証跡です。いずれか一方だけでも該当 run が恒久的に読み取り不能になり、jobs 一覧全体が失敗していました。読み取り側は両形状を受け入れ、書き込み側は完全な厳格契約を維持します。
+- 赤/緑の回帰オラクル、535/535 テスト、全リリースゲート、さらに読み取り不能だった 3 つの実 run の復旧で検証し、独立した敵対的レビューで相互確認しました。
 
-詳細は [changelog](CHANGELOG.md#022---2026-07-17) またはバージョン指定の [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2) を参照してください。
+詳細は [changelog](CHANGELOG.md#031---2026-07-18) またはバージョン指定の [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1) を参照してください。
 
 ## 1 回の実行は実際にどう進むか
 
@@ -71,15 +68,15 @@ ChatGPT Pro のサブスクリプションと、選択された Pro モデルは
 npm レジストリからインストールします。
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.1
 cueline install
 cueline doctor
 ```
 
-フォールバックとして、[v0.2.0 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) のパッケージ済み tarball をインストールすることもできます。同じリリースに `.sha256` チェックサムも置いてあります。
+フォールバックとして、[v0.3.1 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1) のパッケージ済み tarball をインストールすることもできます。同じリリースに `.sha256` チェックサムも置いてあります。
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.3.1/cueline-0.3.1.tgz
 cueline install
 cueline doctor
 ```
@@ -186,7 +183,7 @@ CLI はブラウザーを駆動しません。状態を書き込むコマンド
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.1
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -292,7 +289,7 @@ npm pack --dry-run
 
 ## 開発
 
-TypeScript、ESM、Node の組み込みモジュールのみ。`npm run build` は `dist/` へコンパイルし、テストは `node --test` でコンパイル済みの成果物に対して実行します。CI は Ubuntu と macOS 上の Node 22 / 24 を対象とします。
+TypeScript、ESM、Node の組み込みモジュールのみ。`npm run build` は `dist/` へコンパイルし、テストは `node --test` でコンパイル済みの成果物に対して実行します。CI は Ubuntu と macOS 上の Node 22 / 24 / 26 を対象とします。
 
 CueLine は独立したプロジェクトであり、OpenAI やその他いかなる企業とも提携しておらず、推奨・後援も受けていません。[provenance](docs/provenance.md) と [third-party notices](THIRD_PARTY_NOTICES.md) を参照してください。
 

package/README.ko.md

@@ -22,15 +22,12 @@
 
 CueLine은 독립적인 구현이며 **런타임 npm 의존성이 전혀 없습니다**. Omnilane을 감싼 래퍼가 아닙니다.
 
-## 최신 릴리스: 0.2.2
+## 최신 릴리스: 0.3.1
 
-- 설정 가능한 영속적 job별 컨트롤러 증거 상한을 추가하고(0.2.1), 기록되는 모든 job 이벤트에도 적용했습니다. 이벤트 로그와 컨트롤러에 제공되는 증거는 항상 같은 상한을 공유합니다.
-- 실제 run에서 관측된 증거 고갈 교착을 수정했습니다. 과대한 워커 출력이 컨트롤러를 라운드 한도 안에 끝나지 않는 inspect 페이징 루프로 몰아넣는 일은 더 이상 없습니다.
-- 용량 경고는 컨트롤러가 실제로 페이징할 수 있는 증거만 계산합니다. 영속 상한을 넘는 실제 총량은 별도의 결정적 알림으로 공개되며, 증거가 충분하면 컨트롤러는 조기에 결정할 수 있습니다.
-- 재생된 증거는 바이트 단위로 안정적입니다. 검증된 정규 상한 마커는 그대로 유지되고, 구형 절단 마커는 무결성 오류 없이 결정적으로 다시 상한이 적용됩니다.
-- 490/490 테스트와 함께 실제 process runner로 검증했습니다. 실제 총량을 담은 상한 이벤트 마커 하나를 기록하고 컨트롤러 2턴 안에 완료했습니다.
+- 영속 job 상태 검증기가 runner가 실제로 기록하는 두 가지 형태를 잘못 거부하던 문제를 수정했습니다: 취소된 `work` job이 `ambiguous`와 `cancelled: true`로 기록되는 형태, 그리고 `cancelled` 필드 도입 이전(0.1.7 미만)의 레거시 증거입니다. 둘 중 하나만 있어도 해당 run이 영구적으로 읽을 수 없게 되고 전체 jobs 목록이 실패했습니다. 읽기 경로는 두 형태를 모두 수용하며, 쓰기 경로는 완전한 엄격 계약을 유지합니다.
+- 레드/그린 회귀 오라클, 535/535 테스트, 모든 릴리스 게이트, 그리고 읽을 수 없던 실제 run 3개의 복구로 검증했으며 독립적인 적대적 리뷰로 교차 확인했습니다.
 
-전체 내용은 [changelog](CHANGELOG.md#022---2026-07-17) 또는 버전이 지정된 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)에서 확인할 수 있습니다.
+전체 내용은 [changelog](CHANGELOG.md#031---2026-07-18) 또는 버전이 지정된 [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1)에서 확인할 수 있습니다.
 
 ## 실행 한 번은 실제로 이렇게 흘러갑니다
 
@@ -71,15 +68,15 @@ ChatGPT Pro 구독과 선택된 Pro 모델은 서로 다른 것입니다. 계정
 npm 레지스트리에서 설치합니다:
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.1
 cueline install
 cueline doctor
 ```
 
-대안으로, [v0.2.0 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0)의 패키지 tarball을 설치할 수도 있습니다. 같은 릴리스에 `.sha256` 체크섬도 함께 있습니다.
+대안으로, [v0.3.1 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1)의 패키지 tarball을 설치할 수도 있습니다. 같은 릴리스에 `.sha256` 체크섬도 함께 있습니다.
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.3.1/cueline-0.3.1.tgz
 cueline install
 cueline doctor
 ```
@@ -186,7 +183,7 @@ CLI는 브라우저를 구동하지 않습니다. 상태를 쓰는 명령 전에
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.1
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -292,7 +289,7 @@ npm pack --dry-run
 
 ## 개발
 
-TypeScript, ESM, Node 내장 모듈만 사용합니다. `npm run build`는 `dist/`로 컴파일하고, 테스트는 `node --test`로 컴파일된 결과물을 대상으로 실행합니다. CI는 Ubuntu와 macOS의 Node 22와 24를 다룹니다.
+TypeScript, ESM, Node 내장 모듈만 사용합니다. `npm run build`는 `dist/`로 컴파일하고, 테스트는 `node --test`로 컴파일된 결과물을 대상으로 실행합니다. CI는 Ubuntu와 macOS의 Node 22, 24, 26을 다룹니다.
 
 CueLine은 독립 프로젝트이며 OpenAI를 비롯한 어떤 회사와도 제휴하거나 보증·후원을 받지 않았습니다. [provenance](docs/provenance.md)와 [third-party notices](THIRD_PARTY_NOTICES.md)를 참고하세요.
 

package/README.md

@@ -22,15 +22,12 @@ The web page never touches your machine and has no local tools. It only emits on
 
 CueLine is a standalone implementation with **no runtime npm dependencies**. It is not a wrapper around Omnilane.
 
-## Latest release: 0.2.2
+## Latest release: 0.3.1
 
-- Added a durable, configurable per-job controller-evidence cap (0.2.1), now applied to every recorded job event so event-log and controller-served evidence always share one cap.
-- Fixed the evidence-starvation deadlock observed in a real run: oversized worker output can no longer force the controller into an inspect-pagination treadmill that cannot finish within the round limit.
-- Capacity warnings count only evidence the controller can actually page through; true totals beyond the durable cap are reported in a separate deterministic notice, and the controller may decide as soon as evidence is sufficient.
-- Replayed evidence stays byte-stable: a validated canonical cap marker is preserved as-is, and legacy truncation markers re-cap deterministically without integrity errors.
-- Verified 490/490 tests, plus a real process-runner run that wrote one capped event marker carrying the true total and completed in two controller turns.
+- Fixed the durable job-status validator rejecting two shapes real runners persist: a cancelled `work` job recorded as `ambiguous` with `cancelled: true`, and pre-0.1.7 evidence that predates the `cancelled` field. Either one permanently marked the owning run unreadable and made the whole jobs listing throw. Reads accept both shapes now; writes keep the full strict contract.
+- Verified with a red/green regression oracle, 535/535 tests, all release gates, and live recovery of three previously unreadable on-disk runs, cross-checked by an independent adversarial review.
 
-Read the complete [changelog](CHANGELOG.md#022---2026-07-17) or the versioned [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2).
+Read the complete [changelog](CHANGELOG.md#031---2026-07-18) or the versioned [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1).
 
 ## How a run actually goes
 
@@ -73,15 +70,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.2.0
+npm install -g cueline@0.3.1
 cueline install
 cueline doctor
 ```
 
-As a fallback, install the packaged tarball from the [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0), which also carries its `.sha256` checksum:
+As a fallback, install the packaged tarball from the [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1), which also carries its `.sha256` checksum:
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.3.1/cueline-0.3.1.tgz
 cueline install
 cueline doctor
 ```
@@ -197,7 +194,7 @@ The CLI does not drive the browser. Run `cueline help` for every positional argu
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.1
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -301,7 +298,7 @@ See [compatibility](docs/compatibility.md) for the full matrix.
 
 ## Development
 
-TypeScript, ESM, Node built-ins only. `npm run build` compiles to `dist/`; tests run on the compiled output with `node --test`. CI covers Node 22 and 24 on Ubuntu and macOS.
+TypeScript, ESM, Node built-ins only. `npm run build` compiles to `dist/`; tests run on the compiled output with `node --test`. CI covers Node 22, 24, and 26 on Ubuntu and macOS.
 
 CueLine is an independent project and is not affiliated with, endorsed by, or sponsored by OpenAI or any other company. See [provenance](docs/provenance.md) and [third-party notices](THIRD_PARTY_NOTICES.md).
 

package/README.zh-CN.md

@@ -22,15 +22,12 @@
 
 CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnilane 的包装层。
 
-## 最新版本：0.2.2
+## 最新版本：0.3.1
 
-- 新增可配置的持久单 job 控制器证据上限（0.2.1），并应用到每一条写入的 job 事件，事件日志与提供给控制器的证据始终共用同一个上限。
-- 修复真实 run 中观察到的证据饥饿死锁：过大的 worker 输出不再能把控制器拖进轮次上限内走不完的 inspect 翻页循环。
-- 容量警告只统计控制器实际能翻到的证据；超过持久上限的真实总量改由独立的确定性通知披露，控制器在证据充分时即可提前决策。
-- 重放证据字节稳定：通过校验的规范上限标记原样保留，旧版截断标记则确定性地重新套用上限，不产生完整性错误。
-- 完成 490/490 测试，并用真实 process runner 验证：单个上限事件标记携带真实总量写入，两个控制器轮次内完成。
+- 修复持久 job 状态验证器误拒两种 runner 实际会写出的形状：被取消的 `work` job 以 `ambiguous` 搭配 `cancelled: true` 记录，以及 0.1.7 之前、尚无 `cancelled` 字段的旧证据。两者任一都会让所属 run 永久无法读取，并使整个 jobs 列表直接失败。现在读取端接受这两种形状；写入端仍维持完整严格契约。
+- 以红绿回归测试、535/535 测试、全部发布闸门，加上三个原本无法读取的实际 run 成功恢复验证，并经独立对抗式审查交叉确认。
 
-完整内容请查看 [changelog](CHANGELOG.md#022---2026-07-17) 或版本化的 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)。
+完整内容请查看 [changelog](CHANGELOG.md#031---2026-07-18) 或版本化的 [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1)。
 
 ## 一次运行实际是怎么走的
 
@@ -71,15 +68,15 @@ ChatGPT Pro 订阅套餐与“选定的 Pro 模型”是两回事。账号或个
 从 npm registry 安装：
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.1
 cueline install
 cueline doctor
 ```
 
-作为后备，也可以安装 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
+作为后备，也可以安装 [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.3.1/cueline-0.3.1.tgz
 cueline install
 cueline doctor
 ```
@@ -188,7 +185,7 @@ CLI 不驱动浏览器。执行写入状态的命令前，先用 `cueline help`
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.1
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -294,7 +291,7 @@ npm pack --dry-run
 
 ## 开发
 
-TypeScript、ESM，仅使用 Node 内置模块。`npm run build` 编译到 `dist/`；测试以 `node --test` 运行编译产物。CI 覆盖 Ubuntu 与 macOS 上的 Node 22 与 24。
+TypeScript、ESM，仅使用 Node 内置模块。`npm run build` 编译到 `dist/`；测试以 `node --test` 运行编译产物。CI 覆盖 Ubuntu 与 macOS 上的 Node 22、24、26。
 
 CueLine 是独立项目，与 OpenAI 或任何其他公司均无隶属关系，也未获其背书或赞助。见 [provenance](docs/provenance.md) 与 [third-party notices](THIRD_PARTY_NOTICES.md)。
 

package/README.zh-TW.md

@@ -22,15 +22,12 @@
 
 CueLine 是獨立實作，**沒有任何 runtime npm 相依套件**，也不是 Omnilane 的包裝層。
 
-## 最新版本：0.2.2
+## 最新版本：0.3.1
 
-- 新增可設定的持久單一 job 主控證據上限（0.2.1），並套用到每一筆寫入的 job 事件，事件紀錄與提供給主控的證據永遠共用同一個上限。
-- 修復真實 run 觀察到的證據餓死卡死：過大的工人輸出不再能把主控拖進回合上限內走不完的 inspect 翻頁迴圈。
-- 容量警告只計算主控實際翻得到的證據；超過持久上限的真實總量改以獨立的決定性通知揭露，主控在證據足夠時即可提前決策。
-- 重播證據位元組穩定：通過驗證的正規上限標記原樣保留，舊版截斷標記則決定性地重新套用上限，不產生完整性錯誤。
-- 完成 490/490 測試，並以真實 process runner 驗證：單一上限事件標記帶真實總量寫入，兩個主控回合內完成。
+- 修正持久 job 狀態驗證器誤拒兩種 runner 實際會寫出的形狀：被取消的 `work` job 以 `ambiguous` 搭配 `cancelled: true` 記錄，以及 0.1.7 之前、尚無 `cancelled` 欄位的舊證據。兩者任一都會讓所屬 run 永久無法讀取，並使整個 jobs 清單直接失敗。現在讀取端接受這兩種形狀；寫入端仍維持完整嚴格契約。
+- 以紅綠迴歸測試、535/535 測試、全部發佈閘門，加上三個原本無法讀取的實際 run 成功復原驗證，並經獨立對抗式審查交叉確認。
 
-完整內容請看 [changelog](CHANGELOG.md#022---2026-07-17) 或版本化的 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)。
+完整內容請看 [changelog](CHANGELOG.md#031---2026-07-18) 或版本化的 [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1)。
 
 ## 一次執行實際上怎麼跑
 
@@ -71,15 +68,15 @@ ChatGPT Pro 訂閱方案與「選定的 Pro 模型」是兩回事。帳號或個
 從 npm registry 安裝：
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.1
 cueline install
 cueline doctor
 ```
 
-作為備援，也可以安裝 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) 上的打包 tarball，該 release 同時附上它的 `.sha256` 校驗碼：
+作為備援，也可以安裝 [v0.3.1 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.1) 上的打包 tarball，該 release 同時附上它的 `.sha256` 校驗碼：
 
 ```bash
-npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.2.0/cueline-0.2.0.tgz
+npm install -g https://github.com/Seraphim0916/cueline/releases/download/v0.3.1/cueline-0.3.1.tgz
 cueline install
 cueline doctor
 ```
@@ -197,7 +194,7 @@ CLI 不驅動瀏覽器。執行寫入狀態的命令前，先用 `cueline help`
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.1
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -303,7 +300,7 @@ npm pack --dry-run
 
 ## 開發
 
-TypeScript、ESM，只用 Node 內建模組。`npm run build` 會編譯到 `dist/`；測試以 `node --test` 跑編譯後的產物。CI 涵蓋 Ubuntu 與 macOS 上的 Node 22 與 24。
+TypeScript、ESM，只用 Node 內建模組。`npm run build` 會編譯到 `dist/`；測試以 `node --test` 跑編譯後的產物。CI 涵蓋 Ubuntu 與 macOS 上的 Node 22、24、26。
 
 CueLine 是獨立專案，與 OpenAI 或任何其他公司皆無隸屬關係，亦未獲其背書或贊助。見 [provenance](docs/provenance.md) 與 [third-party notices](THIRD_PARTY_NOTICES.md)。
 

package/dist/src/api-run-prune.d.ts

@@ -0,0 +1,41 @@
+import type { CueLineRuntimeOptions } from "./api-contracts.js";
+export declare const PRUNABLE_RUN_STATES: readonly ["complete", "blocked", "cancelled"];
+export type PrunableRunState = (typeof PRUNABLE_RUN_STATES)[number];
+export type CueLineRunPruneKeptReason = "unreadable" | "non_terminal" | "state_excluded" | "runtime_active" | "active_jobs" | "too_recent" | "delete_failed";
+export interface CueLineRunPruneDecision {
+    runId: string;
+    decision: "pruned" | "eligible" | "kept";
+    reason?: CueLineRunPruneKeptReason;
+    status?: string;
+    lastEventAt?: string;
+}
+export interface CueLineRunPruneError {
+    runId: string;
+    message: string;
+}
+export interface CueLineRunPruneResult {
+    home: string;
+    apply: boolean;
+    olderThanMs: number;
+    cutoff: string;
+    states: PrunableRunState[];
+    decisions: CueLineRunPruneDecision[];
+    prunedRuns: number;
+    eligibleRuns: number;
+    keptRuns: number;
+    removedJobRecords: number;
+    errors: CueLineRunPruneError[];
+}
+export interface CueLineRunPruneOptions extends Pick<CueLineRuntimeOptions, "home" | "environment" | "now"> {
+    olderThanMs: number;
+    states?: readonly PrunableRunState[];
+    apply?: boolean;
+}
+/**
+ * Retention sweep over persisted runs. Only terminal runs (complete, blocked,
+ * cancelled) whose runtime lease is not active, with zero pending or running
+ * jobs, and whose last durable event is older than the cutoff are eligible.
+ * Dry-run by default: nothing is deleted unless `apply` is true. Unreadable
+ * runs are always kept; deciding about corrupt evidence requires a human.
+ */
+export declare function pruneCueLineRuns(options: CueLineRunPruneOptions): Promise<CueLineRunPruneResult>;

package/dist/src/api-run-prune.js

@@ -0,0 +1,218 @@
+import { access, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { listCueLineRuns } from "./api-runtime-lifecycle.js";
+import { CueLineError } from "./core/errors.js";
+import { runtimeEnvironment } from "./core/runtime.js";
+import { JobStatusStore } from "./jobs/status.js";
+import { defaultCueLineHome, runPaths } from "./state/paths.js";
+import { readRuntimeLease, withRuntimeLeaseMutation, } from "./state/runtime-lease.js";
+export const PRUNABLE_RUN_STATES = ["complete", "blocked", "cancelled"];
+function normalizedStates(states) {
+    const requested = states === undefined ? PRUNABLE_RUN_STATES : states;
+    const unique = [];
+    for (const state of requested) {
+        if (!PRUNABLE_RUN_STATES.includes(state)) {
+            throw new CueLineError("RUN_PRUNE_STATE_INVALID", `Only terminal run states may be pruned; '${state}' is not one of: ${PRUNABLE_RUN_STATES.join(", ")}.`);
+        }
+        if (!unique.includes(state))
+            unique.push(state);
+    }
+    if (unique.length === 0) {
+        throw new CueLineError("RUN_PRUNE_STATE_INVALID", "At least one terminal run state is required.");
+    }
+    return unique;
+}
+/**
+ * Only a definite ENOENT counts as "gone". Any other filesystem error
+ * (EACCES, EIO, …) must propagate, otherwise the RUNTIME_MUTATION_FENCED
+ * recovery path would misclassify an unverifiable directory as pruned.
+ */
+async function definitelyMissing(target) {
+    try {
+        await access(target);
+        return false;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+}
+async function removeJobRecordsForRuns(home, runIds, errors) {
+    if (runIds.size === 0)
+        return 0;
+    const directory = path.join(home, "jobs");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    const jobIds = new Set();
+    for (const name of names) {
+        if (name.endsWith(".json"))
+            jobIds.add(name.slice(0, -".json".length));
+        else if (name.endsWith(".terminal"))
+            jobIds.add(name.slice(0, -".terminal".length));
+    }
+    const statusStore = new JobStatusStore(home);
+    let removed = 0;
+    for (const jobId of [...jobIds].sort()) {
+        let runId;
+        try {
+            runId = (await statusStore.read(jobId))?.runId;
+        }
+        catch {
+            // An unparsable job record never names a run; leave it for `jobs` to surface.
+            continue;
+        }
+        if (runId === undefined || !runIds.has(runId))
+            continue;
+        try {
+            await rm(path.join(directory, `${jobId}.json`), { force: true });
+            await rm(path.join(directory, `${jobId}.terminal`), { force: true });
+            removed += 1;
+        }
+        catch (error) {
+            errors.push({
+                runId,
+                message: `job record '${jobId}': ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    return removed;
+}
+/**
+ * Retention sweep over persisted runs. Only terminal runs (complete, blocked,
+ * cancelled) whose runtime lease is not active, with zero pending or running
+ * jobs, and whose last durable event is older than the cutoff are eligible.
+ * Dry-run by default: nothing is deleted unless `apply` is true. Unreadable
+ * runs are always kept; deciding about corrupt evidence requires a human.
+ */
+export async function pruneCueLineRuns(options) {
+    if (!Number.isFinite(options.olderThanMs) ||
+        options.olderThanMs < 0) {
+        throw new CueLineError("RUN_PRUNE_AGE_INVALID", "olderThanMs must be a non-negative finite number of milliseconds.");
+    }
+    const environment = options.environment ?? runtimeEnvironment();
+    const home = options.home ?? defaultCueLineHome(environment);
+    const states = normalizedStates(options.states);
+    const apply = options.apply === true;
+    const now = options.now === undefined ? new Date() : options.now();
+    const cutoffMs = now.getTime() - options.olderThanMs;
+    const cutoff = new Date(cutoffMs).toISOString();
+    const runs = await listCueLineRuns({
+        home,
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    const decisions = [];
+    const errors = [];
+    const prunedRunIds = new Set();
+    let eligibleRuns = 0;
+    let keptRuns = 0;
+    for (const run of runs) {
+        if (!run.readable) {
+            decisions.push({ runId: run.runId, decision: "kept", reason: "unreadable" });
+            keptRuns += 1;
+            continue;
+        }
+        const base = {
+            runId: run.runId,
+            status: run.status,
+            lastEventAt: run.lastEventAt,
+        };
+        if (!PRUNABLE_RUN_STATES.includes(run.status)) {
+            decisions.push({ ...base, decision: "kept", reason: "non_terminal" });
+            keptRuns += 1;
+            continue;
+        }
+        if (!states.includes(run.status)) {
+            decisions.push({ ...base, decision: "kept", reason: "state_excluded" });
+            keptRuns += 1;
+            continue;
+        }
+        if (run.runtimeOwnership === "active") {
+            decisions.push({ ...base, decision: "kept", reason: "runtime_active" });
+            keptRuns += 1;
+            continue;
+        }
+        if (run.activeJobs > 0) {
+            decisions.push({ ...base, decision: "kept", reason: "active_jobs" });
+            keptRuns += 1;
+            continue;
+        }
+        const lastEventMs = Date.parse(run.lastEventAt);
+        if (!Number.isFinite(lastEventMs) || lastEventMs >= cutoffMs) {
+            decisions.push({ ...base, decision: "kept", reason: "too_recent" });
+            keptRuns += 1;
+            continue;
+        }
+        if (!apply) {
+            decisions.push({ ...base, decision: "eligible" });
+            eligibleRuns += 1;
+            continue;
+        }
+        try {
+            // The inventory above is a snapshot; a runtime could claim the lease
+            // between listing and deletion. Re-read and delete inside the lease
+            // mutation lock so this serializes with RuntimeLease.claim — a plain
+            // re-read before rm still leaves a window for a claim to land between
+            // the two awaits.
+            const deleted = await withRuntimeLeaseMutation(home, run.runId, async () => {
+                const recheck = await readRuntimeLease(home, run.runId, {
+                    ...(options.now === undefined ? {} : { now: options.now }),
+                });
+                if (recheck.ownership === "active")
+                    return false;
+                await rm(runPaths(home, run.runId).runDir, { recursive: true, force: true });
+                return true;
+            });
+            if (!deleted) {
+                decisions.push({ ...base, decision: "kept", reason: "runtime_active" });
+                keptRuns += 1;
+                continue;
+            }
+            prunedRunIds.add(run.runId);
+            decisions.push({ ...base, decision: "pruned" });
+        }
+        catch (error) {
+            // Deleting the run directory removes its own fence record, so the
+            // lock's post-operation fence check reports RUNTIME_MUTATION_FENCED
+            // for runs that ever had a runtime generation. Under the mutation lock
+            // nobody else can rotate the fence, so if the directory is gone the
+            // mismatch is self-inflicted and the deletion succeeded.
+            if (error instanceof CueLineError &&
+                error.code === "RUNTIME_MUTATION_FENCED" &&
+                (await definitelyMissing(runPaths(home, run.runId).runDir).catch(() => false))) {
+                prunedRunIds.add(run.runId);
+                decisions.push({ ...base, decision: "pruned" });
+                continue;
+            }
+            errors.push({
+                runId: run.runId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            decisions.push({ ...base, decision: "kept", reason: "delete_failed" });
+            keptRuns += 1;
+        }
+    }
+    const removedJobRecords = await removeJobRecordsForRuns(home, prunedRunIds, errors);
+    return {
+        home,
+        apply,
+        olderThanMs: options.olderThanMs,
+        cutoff,
+        states,
+        decisions,
+        prunedRuns: prunedRunIds.size,
+        eligibleRuns,
+        keptRuns,
+        removedJobRecords,
+        errors,
+    };
+}
+//# sourceMappingURL=api-run-prune.js.map