cueline 0.2.2 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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.0",
   "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,40 @@
 # Changelog
 
+## 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,15 @@
 
 CueLine は独立した実装で、**ランタイムの npm 依存はゼロ**です。Omnilane のラッパーではありません。
 
-## 最新リリース：0.2.2
+## 最新リリース：0.3.0
 
-- 設定可能で永続的な job 単位のコントローラー証拠上限を追加し（0.2.1）、記録されるすべての job イベントにも適用しました。イベントログとコントローラーへ提供される証拠は常に同じ上限を共有します。
-- 実 run で観測された証拠枯渇デッドロックを修正しました。過大なワーカー出力がコントローラーをラウンド上限内に終わらない inspect ページングループへ追い込むことはもうありません。
-- 容量警告はコントローラーが実際にページングできる証拠だけを数えます。永続上限を超える真の総量は独立した決定的な通知で開示され、証拠が十分ならコントローラーは早期に判断できます。
-- リプレイされた証拠はバイト単位で安定します。検証済みの正規上限マーカーはそのまま保持され、旧形式の切り詰めマーカーは整合性エラーなしに決定的へ再適用されます。
-- 490/490 テストに加え、実 process runner で検証しました。真の総量を持つ上限イベントマーカーを 1 つ書き込み、コントローラー 2 ターンで完了しました。
+- 運用ツールを追加：終了済み run を掃除する `runs prune`（デフォルトは dry-run、削除は runtime lease ロックと直列化）、永続イベント中の秘密情報らしき文字列をマスク付きで走査する `run audit-secrets`、サニタイズ済みサポートバンドルを 1 ファイルで出力する `run export`。
+- リリースエンジニアリングを追加：オフラインで制御ループを検査する `self-test`、読み取り専用の移行レポート `upgrade preflight`、リリースゲート `release:check`、SHA-256 検証付きの再現可能なパッケージ成果物、ドキュメントバージョンガード、CI 上で証拠に裏付けられた Node サポート契約。
+- すべての読み取り専用 `--json` 出力にバージョン付きの厳格な JSON 契約を公開。契約テストは余分なフィールド、ネストされた注入、空セクション、矛盾した形状を拒否します。
+- fail-closed 挙動を強化：敵対的プロトコルファズコーパス、全 run コマンドの欠損 run 掃引、ENOENT のみを削除完了と数える prune 記帳。
+- 統一候補で 532/532 テストと全リリースゲートを検証し、独立した 2 系統が相互に敵対的レビューを実施しました。
 
-詳細は [changelog](CHANGELOG.md#022---2026-07-17) またはバージョン指定の [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2) を参照してください。
+詳細は [changelog](CHANGELOG.md#030---2026-07-17) またはバージョン指定の [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0) を参照してください。
 
 ## 1 回の実行は実際にどう進むか
 
@@ -71,15 +71,15 @@ ChatGPT Pro のサブスクリプションと、選択された Pro モデルは
 npm レジストリからインストールします。
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.0
 cueline install
 cueline doctor
 ```
 
-フォールバックとして、[v0.2.0 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) のパッケージ済み tarball をインストールすることもできます。同じリリースに `.sha256` チェックサムも置いてあります。
+フォールバックとして、[v0.3.0 リリース](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0) のパッケージ済み 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.0/cueline-0.3.0.tgz
 cueline install
 cueline doctor
 ```
@@ -186,7 +186,7 @@ CLI はブラウザーを駆動しません。状態を書き込むコマンド
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -292,7 +292,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,15 @@
 
 CueLine은 독립적인 구현이며 **런타임 npm 의존성이 전혀 없습니다**. Omnilane을 감싼 래퍼가 아닙니다.
 
-## 최신 릴리스: 0.2.2
+## 최신 릴리스: 0.3.0
 
-- 설정 가능한 영속적 job별 컨트롤러 증거 상한을 추가하고(0.2.1), 기록되는 모든 job 이벤트에도 적용했습니다. 이벤트 로그와 컨트롤러에 제공되는 증거는 항상 같은 상한을 공유합니다.
-- 실제 run에서 관측된 증거 고갈 교착을 수정했습니다. 과대한 워커 출력이 컨트롤러를 라운드 한도 안에 끝나지 않는 inspect 페이징 루프로 몰아넣는 일은 더 이상 없습니다.
-- 용량 경고는 컨트롤러가 실제로 페이징할 수 있는 증거만 계산합니다. 영속 상한을 넘는 실제 총량은 별도의 결정적 알림으로 공개되며, 증거가 충분하면 컨트롤러는 조기에 결정할 수 있습니다.
-- 재생된 증거는 바이트 단위로 안정적입니다. 검증된 정규 상한 마커는 그대로 유지되고, 구형 절단 마커는 무결성 오류 없이 결정적으로 다시 상한이 적용됩니다.
-- 490/490 테스트와 함께 실제 process runner로 검증했습니다. 실제 총량을 담은 상한 이벤트 마커 하나를 기록하고 컨트롤러 2턴 안에 완료했습니다.
+- 운영 도구 추가: 종료된 run을 정리하는 `runs prune`(기본 dry-run, 삭제는 runtime lease 잠금과 직렬화), 영속 이벤트에서 비밀 형태 문자열을 마스킹 방식으로 검사하는 `run audit-secrets`, 정제된 지원 번들을 한 파일로 내보내는 `run export`.
+- 릴리스 엔지니어링 추가: 오프라인 제어 루프 점검 `self-test`, 읽기 전용 마이그레이션 리포트 `upgrade preflight`, 릴리스 게이트 `release:check`, SHA-256 검증이 붙은 재현 가능한 패키지 산출물, 문서 버전 가드, CI에서 증거로 뒷받침되는 Node 지원 계약.
+- 모든 읽기 전용 `--json` 출력에 버전이 붙은 엄격한 JSON 계약을 공개. 계약 테스트는 추가 필드, 중첩 주입, 빈 섹션, 모순된 형태를 거부합니다.
+- fail-closed 동작 강화: 적대적 프로토콜 퍼즈 코퍼스, 전체 run 명령의 누락 run 점검, ENOENT만 삭제 완료로 인정하는 prune 회계.
+- 통합 후보에서 532/532 테스트와 모든 릴리스 게이트를 검증했으며, 독립된 두 라인이 상호 적대적 검토를 수행했습니다.
 
-전체 내용은 [changelog](CHANGELOG.md#022---2026-07-17) 또는 버전이 지정된 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)에서 확인할 수 있습니다.
+전체 내용은 [changelog](CHANGELOG.md#030---2026-07-17) 또는 버전이 지정된 [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0)에서 확인할 수 있습니다.
 
 ## 실행 한 번은 실제로 이렇게 흘러갑니다
 
@@ -71,15 +71,15 @@ ChatGPT Pro 구독과 선택된 Pro 모델은 서로 다른 것입니다. 계정
 npm 레지스트리에서 설치합니다:
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.0
 cueline install
 cueline doctor
 ```
 
-대안으로, [v0.2.0 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0)의 패키지 tarball을 설치할 수도 있습니다. 같은 릴리스에 `.sha256` 체크섬도 함께 있습니다.
+대안으로, [v0.3.0 릴리스](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0)의 패키지 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.0/cueline-0.3.0.tgz
 cueline install
 cueline doctor
 ```
@@ -186,7 +186,7 @@ CLI는 브라우저를 구동하지 않습니다. 상태를 쓰는 명령 전에
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -292,7 +292,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,15 @@ 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.0
 
-- 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.
+- 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.
+- Added release engineering: `self-test` offline controller-loop check, `upgrade preflight` read-only migration report, `release:check` gate, reproducible pack artifacts with SHA-256 verification, a documentation version guard, and an evidence-backed Node support contract in CI.
+- Published versioned strict JSON contracts for every read-only `--json` surface; contract tests reject added fields, nested injection, empty sections, and contradictory shapes.
+- Hardened fail-closed behavior: an adversarial protocol fuzz corpus, a missing-run sweep across all run-scoped commands, and ENOENT-only prune removal accounting.
+- Verified 532/532 tests plus all release gates on the unified candidate, cross-reviewed adversarially by two independent lines.
 
-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#030---2026-07-17) or the versioned [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0).
 
 ## How a run actually goes
 
@@ -73,15 +73,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.0
 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.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0), 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.0/cueline-0.3.0.tgz
 cueline install
 cueline doctor
 ```
@@ -197,7 +197,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.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -301,7 +301,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,15 @@
 
 CueLine 是独立实现，**没有任何运行时 npm 依赖**，也不是 Omnilane 的包装层。
 
-## 最新版本：0.2.2
+## 最新版本：0.3.0
 
-- 新增可配置的持久单 job 控制器证据上限（0.2.1），并应用到每一条写入的 job 事件，事件日志与提供给控制器的证据始终共用同一个上限。
-- 修复真实 run 中观察到的证据饥饿死锁：过大的 worker 输出不再能把控制器拖进轮次上限内走不完的 inspect 翻页循环。
-- 容量警告只统计控制器实际能翻到的证据；超过持久上限的真实总量改由独立的确定性通知披露，控制器在证据充分时即可提前决策。
-- 重放证据字节稳定：通过校验的规范上限标记原样保留，旧版截断标记则确定性地重新套用上限，不产生完整性错误。
-- 完成 490/490 测试，并用真实 process runner 验证：单个上限事件标记携带真实总量写入，两个控制器轮次内完成。
+- 新增运维工具：`runs prune` 清理已结束的 run（默认 dry-run，删除与 runtime lease 锁串行化）、`run audit-secrets` 以掩码方式扫描持久事件中的密钥形字符串、`run export` 一键导出脱敏支持包。
+- 新增发布工程：`self-test` 离线控制环检查、`upgrade preflight` 只读升级体检、`release:check` 发布闸门、可复现打包产物与 SHA-256 校验、文档版本守卫、以及 CI 上以证据背书的 Node 支持契约。
+- 为每个只读 `--json` 输出发布带版本的严格 JSON 契约；契约测试拒绝多余字段、嵌套注入、空区段与矛盾形状。
+- 强化 fail-closed 行为：对抗式协议 fuzz 语料、全 run 命令的缺失 run 扫描、prune 仅认 ENOENT 的删除记账。
+- 统一候选完成 532/532 测试与全部发布闸门，并由两条独立线互相对抗式复验。
 
-完整内容请查看 [changelog](CHANGELOG.md#022---2026-07-17) 或版本化的 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)。
+完整内容请查看 [changelog](CHANGELOG.md#030---2026-07-17) 或版本化的 [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0)。
 
 ## 一次运行实际是怎么走的
 
@@ -71,15 +71,15 @@ ChatGPT Pro 订阅套餐与“选定的 Pro 模型”是两回事。账号或个
 从 npm registry 安装：
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.0
 cueline install
 cueline doctor
 ```
 
-作为后备，也可以安装 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) 上的打包 tarball，该 release 同时附带它的 `.sha256` 校验值：
+作为后备，也可以安装 [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0) 上的打包 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.0/cueline-0.3.0.tgz
 cueline install
 cueline doctor
 ```
@@ -188,7 +188,7 @@ CLI 不驱动浏览器。执行写入状态的命令前，先用 `cueline help`
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -294,7 +294,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,15 @@
 
 CueLine 是獨立實作，**沒有任何 runtime npm 相依套件**，也不是 Omnilane 的包裝層。
 
-## 最新版本：0.2.2
+## 最新版本：0.3.0
 
-- 新增可設定的持久單一 job 主控證據上限（0.2.1），並套用到每一筆寫入的 job 事件，事件紀錄與提供給主控的證據永遠共用同一個上限。
-- 修復真實 run 觀察到的證據餓死卡死：過大的工人輸出不再能把主控拖進回合上限內走不完的 inspect 翻頁迴圈。
-- 容量警告只計算主控實際翻得到的證據；超過持久上限的真實總量改以獨立的決定性通知揭露，主控在證據足夠時即可提前決策。
-- 重播證據位元組穩定：通過驗證的正規上限標記原樣保留，舊版截斷標記則決定性地重新套用上限，不產生完整性錯誤。
-- 完成 490/490 測試，並以真實 process runner 驗證：單一上限事件標記帶真實總量寫入，兩個主控回合內完成。
+- 新增操作面工具：`runs prune` 清掃已結束的 run（預設 dry-run，刪除與 runtime lease 鎖序列化）、`run audit-secrets` 以遮罩方式掃描持久事件中的密鑰形字串、`run export` 一鍵匯出去敏支援包。
+- 新增發佈工程：`self-test` 離線控制迴圈檢查、`upgrade preflight` 唯讀升級體檢、`release:check` 發佈閘門、可重現打包產物與 SHA-256 驗證、文件版本守衛、以及 CI 上以證據背書的 Node 支援契約。
+- 為每個唯讀 `--json` 面發佈帶版本的嚴格 JSON 契約；契約測試會拒絕多餘欄位、巢狀注入、空區段與矛盾形狀。
+- 強化 fail-closed 行為：對抗式協定 fuzz 火力網、全 run-scoped 指令的缺失 run 掃描、prune 只認 ENOENT 的刪除記帳。
+- 統一候選完成 532/532 測試與全部發佈閘門，並由兩條獨立線互相對抗式複驗。
 
-完整內容請看 [changelog](CHANGELOG.md#022---2026-07-17) 或版本化的 [v0.2.2 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.2)。
+完整內容請看 [changelog](CHANGELOG.md#030---2026-07-17) 或版本化的 [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0)。
 
 ## 一次執行實際上怎麼跑
 
@@ -71,15 +71,15 @@ ChatGPT Pro 訂閱方案與「選定的 Pro 模型」是兩回事。帳號或個
 從 npm registry 安裝：
 
 ```bash
-npm install -g cueline@0.2.0
+npm install -g cueline@0.3.0
 cueline install
 cueline doctor
 ```
 
-作為備援，也可以安裝 [v0.2.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.2.0) 上的打包 tarball，該 release 同時附上它的 `.sha256` 校驗碼：
+作為備援，也可以安裝 [v0.3.0 release](https://github.com/Seraphim0916/cueline/releases/tag/v0.3.0) 上的打包 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.0/cueline-0.3.0.tgz
 cueline install
 cueline doctor
 ```
@@ -197,7 +197,7 @@ CLI 不驅動瀏覽器。執行寫入狀態的命令前，先用 `cueline help`
 
 ```console
 $ cueline doctor
-CueLine 0.2.0
+CueLine 0.3.0
 status	ok
 node	22.14.0	ok
 config	/usr/local/lib/node_modules/cueline/config/routing.default.json	valid
@@ -303,7 +303,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