throughline 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -10,6 +10,24 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.6.2] — release candidate (pending)
+
+### Added
+
+- Added an opt-in, local-only runtime error aggregate for BugHub factory
+  reporting. Collection requires the canonical dotagents config boolean
+  `collection.enabled: true`; it never performs network I/O or accepts raw
+  exceptions, stderr, stacks, prompts, sessions, paths, or arbitrary context.
+  Fixed hook error codes/templates are aggregated by SHA-256 fingerprint in an
+  owner-private atomic store with count, first/last seen, resolve/reopen,
+  monotonic cursor/ack, retention that preserves unacknowledged records, and
+  bounded `throughline runtime-errors ... --json` snapshot/diagnostics APIs.
+- Release candidate only: collection remains disabled by default and the local
+  store sends no network traffic. Publication, tag, CI, and registry-install
+  verification are pending.
+- Raised the Node.js floor to 22.13, where `node:sqlite` is available without
+  an experimental command-line flag; CI now exercises that exact minimum.
+
 ## [0.6.1] — 2026-07-13
 
 ### Added
@@ -970,6 +988,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.1...v0.6.2
 [0.3.22]: https://github.com/kitepon-rgb/Throughline/releases/tag/v0.3.22
 [0.3.21]: https://github.com/kitepon-rgb/Throughline/compare/v0.3.19...v0.3.21
 [0.3.20]: https://github.com/kitepon-rgb/Throughline/compare/v0.3.19...v0.3.20

package/README.md

@@ -58,7 +58,7 @@ guarded `trim --execute --host codex` surface.
 | **Tool I/O handling** | retired to L3, retrievable by `/sc-detail HH:MM:SS` | gone | folded into summary, unreadable | folded into summary |
 | **Coding-assistant fit** | high — tool I/O is the heavy 80% | low — you lose the thread | medium — but irreversible | medium |
 | **Auto-inheritance risk** | low (typed `/clear` / `/tl` names the predecessor) | n/a | n/a | high |
-| **Runtime deps** | **zero** (Node 22.5+ built-in `node:sqlite`) | n/a | n/a | many |
+| **Runtime deps** | **zero** (Node 22.13+ built-in `node:sqlite`) | n/a | n/a | many |
 | **Multi-session token monitor** | ✅ real `message.usage` / Codex rollout `token_count` | — | — | — |
 
 **Short version**: `/clear` throws everything away, `/compact` blurs everything together, Throughline keeps the *text* you wrote verbatim and only retires the *tool output* — which is where 80% of the bloat lives.
@@ -716,6 +716,11 @@ entry to the `tasks` array yourself:
 
 ## Commands
 
+**v0.6.2 は release candidate（公開待ち）です。** factory diagnostics と local
+runtime error aggregate は collection が既定OFFで、canonical dotagents config の
+`collection.enabled: true` を明示した場合だけ収集します。いずれも network I/O は
+行いません。npm公開、tag、CI、registry由来installの確認は未完了です。
+
 | Command                                        | What it does                                                 |
 | ---------------------------------------------- | ------------------------------------------------------------ |
 | `throughline install`                          | Register Claude user hooks/slash commands, the global Codex UserPromptSubmit/PostToolUse/Stop hooks, the global `$throughline` Codex skill, and the current VS Code monitor task when applicable |
@@ -728,6 +733,13 @@ entry to the `tasks` array yourself:
 | `throughline doctor --session <id-prefix>`     | Diagnose a specific session — detect state/transcript drift, idle vs. stuck |
 | `throughline doctor --trim --host claude\|codex` | Diagnose trim host boundaries, manual procedure, and Codex host primitive blockage |
 | `throughline doctor --codex`                   | Diagnose Codex primary entry state, captured DB sessions, context-refresh memory contract, new-thread handoff readiness, safe continuation status, and host primitive audit |
+| `throughline factory-diagnostics --json`       | Versioned read-only native factory readiness JSON for database schema/migration, connector hooks, and representative capture/restore/handoff; does not emit bodies, secrets, absolute paths, or raw state |
+| `throughline runtime-errors snapshot --json`   | Read the bounded product-owned runtime error aggregate. Collection occurs only when canonical dotagents config explicitly sets `collection.enabled: true`; this command performs no network I/O |
+| `throughline runtime-errors diagnostics --json` | Read bounded collection/store status without exposing the state path or raw errors |
+| `throughline runtime-errors ack <cursor> --json` | Explicitly acknowledge records through a monotonic cursor; unacknowledged records are never compacted |
+| `throughline runtime-errors resolve <fingerprint> --json` | Explicitly resolve an aggregate; observing the same fingerprint again reopens it |
+| `throughline runtime-errors reopen <fingerprint> --json` | Explicitly reopen a resolved aggregate without fabricating a new occurrence |
+| `throughline runtime-errors compact --json`    | Remove only acknowledged, resolved aggregates after retention; open or unacknowledged records remain |
 | `throughline handoff-preview --session <id>`   | Print a Codex-facing `throughline_handoff` JSON projection    |
 | `throughline codex-capture --codex-thread-id <id>` | Capture active Codex rollout turns into a `codex:<thread_id>` DB session |
 | `throughline codex-summarize --session codex:<id>` | Summarize captured Codex L2 into L1 with the Codex CLI backend |
@@ -820,7 +832,7 @@ throughline auditor-context --session claude-session-id --project "$PWD" \
 
 ## Requirements
 
-- **Node.js >= 22.5** (for the built-in `node:sqlite` module — no native build
+- **Node.js >= 22.13** (for the stable, flag-free built-in `node:sqlite` module — no native build
   required, no `npm install` of SQLite bindings)
 - **Claude Code** with hooks support (`SessionStart`, `Stop`)
 - **Claude Max subscription** (for Haiku-based L1 summarization via `claude -p`)

package/bin/throughline.mjs

@@ -11,6 +11,8 @@
  *   throughline detail <時刻> # L2+L3 詳細取得 (Claude が Bash 経由で呼ぶ想定)
  *   throughline handoff-preview # Codex-facing throughline_handoff JSON preview
  *   throughline auditor-context --json # Read-only bounded auditor context JSON
+ *   throughline factory-diagnostics --json # Native factory read-only readiness JSON
+ *   throughline runtime-errors snapshot --json # Product-owned runtime error aggregates
  *   throughline codex-capture # Capture active Codex rollout turns into Throughline DB
  *   throughline codex-hook user-prompt-submit # Codex current-session auto-refresh prompt hook
  *   throughline codex-hook post-tool-use # Codex current-session auto-refresh tool-loop hook
@@ -41,6 +43,7 @@
 
 const [, , cmd, ...rest] = process.argv;
 
+try {
 switch (cmd) {
   case 'install':
     await (await import('../src/cli/install.mjs')).run(rest);
@@ -71,6 +74,16 @@ switch (cmd) {
     if (exitCode !== 0) process.exitCode = exitCode;
     break;
   }
+  case 'factory-diagnostics': {
+    const exitCode = (await import('../src/cli/factory-diagnostics.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
+  case 'runtime-errors': {
+    const exitCode = (await import('../src/cli/runtime-errors.mjs')).run(rest);
+    if (exitCode !== 0) process.exitCode = exitCode;
+    break;
+  }
   case 'codex-capture':
     await (await import('../src/cli/codex-capture.mjs')).run(rest);
     break;
@@ -142,6 +155,18 @@ switch (cmd) {
   default:
     await showHelp();
 }
+} catch (error) {
+  const code = {
+    'session-start': 'HOOK_SESSION_START_FAILED',
+    'prompt-submit': 'HOOK_PROMPT_SUBMIT_FAILED',
+    'process-turn': 'HOOK_PROCESS_TURN_FAILED',
+  }[cmd];
+  if (code) {
+    const { recordRuntimeErrorBestEffort } = await import('../src/runtime-error-store.mjs');
+    recordRuntimeErrorBestEffort(code);
+  }
+  throw error;
+}
 
 async function showHelp() {
   const { createRequire } = await import('node:module');
@@ -159,6 +184,12 @@ Usage:
                               Read only bounded completed user/assistant context
                               for an auditor; requires either --host plus --transcript,
                               or explicit pair identity/hashes; always requires --json
+  throughline factory-diagnostics --json
+                              Read-only native factory readiness JSON. Never emits
+                              session/prompt bodies, secrets, absolute paths, or raw state
+  throughline runtime-errors snapshot --json
+                              Read bounded local runtime error aggregates. Also supports
+                              diagnostics, ack <cursor>, resolve <fingerprint>, and compact
   throughline codex-capture     Capture active Codex rollout turns into DB
                               (requires --codex-thread-id or env thread id)
   throughline codex-hook user-prompt-submit

package/docs/00_overview.md

@@ -17,6 +17,8 @@
 | [09_rollback_context_trim_insight.md](09_rollback_context_trim_insight.md) | rollback を context delete primitive と見る設計メモ |
 | [10_transcript_injection_plan.md](10_transcript_injection_plan.md) | transcript injection 検証計画と v0.5 実機結果 |
 | [11_codex_monitor_implementation_plan.md](11_codex_monitor_implementation_plan.md) | Codex monitor 対応の実装記録 |
+| [13_native_factory_diagnostics_plan.md](13_native_factory_diagnostics_plan.md) | native factory read-only readiness 診断の実装記録 |
+| [BUGHUB_RUNTIME_ERROR_STORE_PLAN.md](BUGHUB_RUNTIME_ERROR_STORE_PLAN.md) | local runtime error aggregate store の契約と実装 TODO |
 
 ## Supporting Records
 

package/docs/04_public_release_plan.md

@@ -137,6 +137,8 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **npm 公開 (v0.4.0): /clear auto-handoff + memo / save-inflight / /tl-trim retire** | 2026-05-08 Claude Code 2.1.128 で `source='clear'` が reliable になったため、`/clear` で自動引継ぎがデフォルト ON になる auto path を追加。`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` で OFF にできる。`/tl` slash command は明示意思マーカーへ簡素化 (memo 4 項目入力廃止、`save-inflight` CLI 削除、`/tl-trim` slash command 廃止、`updateBatonMemo` 関数削除、`handoff_batons.memo_text` を schema v8 で drop)。注入は L1 + L2 + L3 references のみに簡素化し、memo / 中断直前 thinking セクションを削除。Codex 側 trim path は維持。詳細は [CHANGELOG.md](../CHANGELOG.md) と [02_clear_auto_handoff_plan.md](02_clear_auto_handoff_plan.md) |
 | **npm 公開 (v0.4.1): typed `/clear` も baton を書く + 2 経路の優先順位入れ替え** | 2026-05-09 `/clear` を UserPromptSubmit hook で検出した時点で当該セッションの `session_id` を `handoff_batons` に書き込み、次 SessionStart が確定的にそのセッションを引き継ぐ。これで multi-window で「最新更新セッション ≠ /clear したセッション」になるシナリオで `findLatestClaudePredecessor` heuristic が誤った前任を選ぶ問題を解消。2 経路の優先順位を **baton path = primary、auto path = fallback** に変更 (auto path は VSCode 拡張メニュー由来など UserPromptSubmit に届かない経路のフォールバック)。`THROUGHLINE_DISABLE_AUTO_HANDOFF=1` は fallback path のみに作用するようになった (typed `/clear` / `/tl` は env と無関係に発火する)。あわせて `.vscode/tasks.json` を git 追跡から外し (gitignore)、`ensureMonitorTaskFile` が hook 発火ごとに絶対パスを書き換える挙動による別環境での dirty diff を解消。`src/prompt-submit.test.mjs` を新設し、`isClearCommand` / `isBatonCommand` 判定 14 件と subprocess+DB 実体テスト 3 件を追加。詳細は [CHANGELOG.md](../CHANGELOG.md) |
 | **npm 公開 (v0.4.7): Codex monitor direct discovery + 80% auto-refresh** | 2026-05-09 Codex Stop hook auto-refresh の verified usage threshold を 90% から 80% に変更し、Codex native auto-compact より先に Throughline DB memory refresh を試行する。estimate usage / estimated context window では mutation しない。`throughline monitor` は `~/.throughline/state` に加えて `~/.codex/sessions/**/rollout-*.jsonl` を直接 discovery し、Throughline state が未生成の現在 Codex thread も表示する。既存 state がある場合は state の usage snapshot を保持しつつ discovered rollout path / mtime を合流する。Codex 表示 ID は `codex:01` ではなく raw thread id 先頭 8 桁 (`019e085c`) にした。Codex open turn の transient `output_tokens` は token count に overlay するが、モデル欄の `live+<tokens>` marker は表示しない |
+| **npm 公開 (v0.6.1): Spotter auditor context projection** | `throughline auditor-context`を追加。exact session/projectと最新完了L2 pairのorigin/turn/hash freshnessを検査し、fresh時だけbounded user/assistant本文をversioned JSONで返す。DBはread-onlyで開き、作成・migration・WAL書き込みをしない。Spotter側はproject opt-inでのみ利用する。580 tests、CI 6/6、pack scan、registry global install / doctorを通過し、npm / tag / GitHub Releaseを2026-07-13に公開した |
+| **v0.6.2 release candidate（公開待ち）: factory diagnostics + local runtime error store** | `throughline factory-diagnostics --json` と `throughline runtime-errors ... --json` を公開候補へ同期する。collection は canonical dotagents config の `collection.enabled: true` が明示された時だけ有効で既定OFF、store は network I/O を行わない。npm公開、tag、CI、registry由来installの確認はこの時点で未実施であり、公開済みとは扱わない |
 | **未リリース: Codex current-session 75% trigger** | Codex 自動発火を token-monitor に依存させず、global install が Codex `UserPromptSubmit` / `PostToolUse` hooks も登録する。hook は当該 Codex session の rollout `token_count` を直接読み、verified 75% 以上なら同じ user turn または tool loop 継続前に `$throughline` workflow 実行指示を `additionalContext` で注入する。Stop hook の guarded auto-refresh は残す。`~/.codex/config.toml` は旧 `codex_hooks = true` に加えて現行 `hooks = true` も有効化する |
 | **グローバル E2E 検証** | 2026-04-17 別ディレクトリから `throughline doctor` 全緑を確認 |
 

package/docs/13_native_factory_diagnostics_plan.md

@@ -0,0 +1,46 @@
+# Wave 4: Native Factory Diagnostics
+
+## 目的
+
+`throughline factory-diagnostics --json` を追加し、Throughline の native
+factory 接続に必要な read-only readiness を、安定した機械可読 JSON として返す。
+この診断は capture / restore / handoff を実行せず、DB・state・hook 設定・rollout・
+session の本文、秘密、絶対パス、例外詳細を出力しない。
+
+## 契約
+
+- 診断 schema は versioned とし、CLI version、diagnostic schema、overall、database
+  schema/migration、hook、capture / restore / handoff の代表 read-only readiness を返す。
+- 判定値は `ready` / `not_ready` / `not_applicable` / `unverified`。正常に未設定な
+  代表入力は `not_applicable`、観測不能・判定不能は `unverified` とし、pass に丸めない。
+- `overall` は `ready` を、必須の applicable check がすべて `ready` の場合だけ返す。
+  `unverified` は成功に含めない。
+- 既存の `doctor` / `status` の人間向け stdout 契約は変更しない。既存 helper の
+  read-only projection だけを利用し、runtime error store / telemetry は追加しない。
+- CLIは`--json`をちょうど一つ必須とする。exit 0は有効snapshot、exit 1は固定文言の
+  internal diagnostic failure、exit 2は固定文言のusage errorを表す。
+- DBは`PRAGMA user_version`だけでgreenにせず、正規table/column/index shapeをread-onlyで
+  検証する。handoff memoryは一致確認済みproject/threadだけを数える。
+- restore capabilityとlive smoke evidenceを分離する。未実行smokeは`unverified`だが、
+  capability readinessを恒常的に失敗扱いにはしない。
+- Codex hookはcanonical shapeを検査するが、trust実火は機械検証不能なので`unverified`に
+  留める。Claude connectorはこの単位では未検査として明示`unverified`にする。
+
+## 実施 TODO
+
+- [x] 既存の doctor / status、Codex capture、restore、handoff、state schema、hook
+  入口、および関連するテストを実読する。
+- [x] 変更前のベースラインとして `npm test` を green で取得する。
+- [x] privacy / schema / characterization fixture を先に追加し、本文・秘密・絶対パスを
+  含めない JSON 契約を固定する。
+- [x] read-only factory diagnostics の projection と CLI entrypoint を実装する。
+- [x] version、diagnostic schema、overall、state schema、hook、capture / restore /
+  handoff readiness を段階別に返す。
+- [x] help / README の実装済み CLI 仕様を追記する。
+- [x] 対象テスト、`npm test`、`git diff --check` を通し、差分を再読して完了確認する。
+
+## 完了条件
+
+- JSON は stdout に一つだけ出力され、read-only fixture で DB・state・設定を作成・更新しない。
+- 代表 capture / restore / handoff の未設定と不明を区別し、unverified を ready にしない。
+- 出力・エラーには session / prompt 本文、秘密、絶対パス、raw state / log が含まれない。

package/docs/BUGHUB_RUNTIME_ERROR_STORE_PLAN.md

@@ -0,0 +1,52 @@
+# BugHub runtime error store plan
+
+Status: implementation complete; v0.6.2 release pending
+
+This plan is the implementation TODO for Throughline's product-owned, local
+runtime error projection. It implements the cross-repository contract in
+`dotagents/docs/plan_bughub-factory-integration.md` without changing the
+existing transcript, handoff, or SQLite memory contracts.
+
+## Contract
+
+- Collection is disabled unless the canonical dotagents factory reporter
+  config exists and contains the JSON boolean `collection.enabled: true`.
+- This module never performs network I/O and never reads
+  `reporting.enabled`, endpoints, or credentials.
+- Persist only an allow-listed aggregate: product/version, component, stable
+  error code, fixed message template, severity, SHA-256 fingerprint, count,
+  first/last seen, state schema version, OS/arch, status, and sequence.
+- Never accept or persist exception objects, stderr/stdout, stacks, prompts,
+  session/transcript bodies, absolute paths, file contents, tokens, cookies,
+  arbitrary context, or provider output.
+- One failure has one owning observation layer. Existing stderr remains local
+  operator diagnostics but is not copied into this store.
+- Store failure must not replace the product failure. Emit one fixed diagnostic
+  without reflecting the storage error. Observation runs in a bounded child
+  process so blocked config/state I/O cannot hold the original hook result.
+- Use an owner-private directory/file, atomic replacement, monotonic cursor,
+  explicit acknowledgement, explicit resolution/reopen, and retention that
+  never removes an unacknowledged record.
+- Serialize mutations with a private SQLite `BEGIN IMMEDIATE` mutex. The OS
+  releases the lock when a process crashes, so no PID/mtime stale-owner guess
+  or application-level reclaim can remove a newer writer's lock.
+
+## TODO
+
+- [x] Add characterization tests for disabled/missing/malformed config.
+- [x] Add privacy negative fixtures and stable fingerprint aggregation tests.
+- [x] Add acknowledgement, resolution/reopen, retention, mode, and atomic-write tests.
+- [x] Implement the product-owned aggregate store and read-only snapshot API.
+- [x] Add a machine-readable diagnostics projection without exposing state paths.
+- [x] Connect only the top-level hook processing failure boundaries, with fixed
+      codes/templates and no duplicate lower-layer observation.
+- [x] Run the complete test suite and update product documentation.
+- [x] Commit and push this repository independently.
+
+## Release wave
+
+- [x] Bump the package and release-facing documentation to `0.6.2` without moving an existing tag.
+- [x] Run the full test suite, pack inspection, secret/path scan, and temporary-prefix install smoke.
+- [ ] Push the release commit and require the public CI gate to pass.
+- [ ] After the owner H gate, publish `throughline@0.6.2`, create tag/release, and verify npm `latest` plus a registry-derived global install.
+- [ ] Confirm `throughline factory-diagnostics --json` and the runtime-error snapshot/ack commands from the published package, then record the public SHA and results in the changelog and canonical docs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [
@@ -34,6 +34,6 @@
     "test": "node --import ./src/test-env.mjs --test src/*.test.mjs src/cli/*.test.mjs"
   },
   "engines": {
-    "node": ">=22.5"
+    "node": ">=22.13"
   }
 }

package/src/auditor-context.test.mjs

@@ -283,7 +283,14 @@ function snapshotSqliteFiles(path) {
   return [path, `${path}-wal`, `${path}-shm`].map((file) => {
     if (!existsSync(file)) return { file, exists: false };
     const stat = lstatSync(file);
-    return { file, exists: true, size: stat.size, mtimeMs: stat.mtimeMs, bytes: readFileSync(file).toString('hex') };
+    try {
+      return { file, exists: true, size: stat.size, mtimeMs: stat.mtimeMs, bytes: readFileSync(file).toString('hex') };
+    } catch (error) {
+      // Windows denies byte reads for a live WAL handle.  Metadata still
+      // proves the read-only auditor did not create or mutate a sidecar.
+      if (error?.code === 'EBUSY') return { file, exists: true, size: stat.size, mtimeMs: stat.mtimeMs, readError: 'EBUSY' };
+      throw error;
+    }
   });
 }
 

package/src/cli/codex-hook.mjs

@@ -1,3 +1,5 @@
+import { recordRuntimeErrorBestEffort } from '../runtime-error-store.mjs';
+
 function parseArgs(argv) {
   const out = {
     event: null,
@@ -57,10 +59,9 @@ function parsePayload(raw) {
 
 function codexHomeFromTranscriptPath(transcriptPath) {
   if (typeof transcriptPath !== 'string') return null;
-  const marker = `${process.platform === 'win32' ? '\\' : '/'}sessions${process.platform === 'win32' ? '\\' : '/'}`;
-  const idx = transcriptPath.indexOf(marker);
-  if (idx <= 0) return null;
-  return transcriptPath.slice(0, idx);
+  const match = /[\\/]sessions[\\/]/.exec(transcriptPath);
+  if (!match || match.index <= 0) return null;
+  return transcriptPath.slice(0, match.index);
 }
 
 function suppressExperimentalWarnings() {
@@ -366,6 +367,7 @@ export async function run(argv = []) {
     parsed = parseArgs(argv);
     payload = parsePayload(await readStdin());
   } catch (err) {
+    recordRuntimeErrorBestEffort('HOOK_CODEX_FAILED', { env: process.env });
     const msg = err instanceof Error ? err.message : 'unknown';
     process.stderr.write(`[codex-hook] ${msg}\n`);
     process.exit(1);
@@ -399,6 +401,7 @@ export async function run(argv = []) {
     }
     process.exit(result.status === 'ok' || result.status === 'skipped' ? 0 : 1);
   } catch (err) {
+    recordRuntimeErrorBestEffort('HOOK_CODEX_FAILED', { env: process.env });
     const msg = err instanceof Error ? err.message : 'unknown';
     if (parsed.json) {
       process.stdout.write(

package/src/cli/codex-hook.test.mjs

@@ -500,6 +500,10 @@ test('codex-hook stop skips cleanly when Codex thread id is unavailable', async
 test('codexHomeFromTranscriptPath infers CODEX_HOME from rollout path', () => {
   const path = '/tmp/codex-home/sessions/2026/05/06/rollout-2026-05-06T09-40-50-id.jsonl';
   assert.equal(_internal.codexHomeFromTranscriptPath(path), '/tmp/codex-home');
+  assert.equal(
+    _internal.codexHomeFromTranscriptPath('C:\\codex-home\\sessions\\2026\\05\\06\\rollout-2026-05-06T09-40-50-id.jsonl'),
+    'C:\\codex-home',
+  );
 });
 
 test('parseArgs: accepts user-prompt-submit Codex hook event', () => {

package/src/cli/codex-restore-smoke.mjs

@@ -326,7 +326,8 @@ export async function run(args) {
 
   if (parsed.json) process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
   else process.stdout.write(renderTextResult(payload) + '\n');
-  process.exit(payload.status === 'app-server-restart-stable' && !payload.restoreSafetyRiskInspected ? 0 : 1);
+  process.exitCode =
+    payload.status === 'app-server-restart-stable' && !payload.restoreSafetyRiskInspected ? 0 : 1;
 }
 
 function buildRestoreTextNeedles(restoreSafety) {

package/src/cli/codex-restore-source-audit.mjs

@@ -296,7 +296,7 @@ export async function run(args) {
 
   if (parsed.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   else process.stdout.write(renderTextResult(result) + '\n');
-  process.exit(result.status === 'restore-source-audit-complete' ? 0 : 1);
+  process.exitCode = result.status === 'restore-source-audit-complete' ? 0 : 1;
 }
 
 export const _internal = {

package/src/cli/doctor.mjs

@@ -493,6 +493,9 @@ function readCodexHookDiagnosis(codexHome) {
     expectedPromptCommand,
     expectedPostToolUseCommand,
     hooksReadable: false,
+    hooksExists: existsSync(hooksPath),
+    configExists: existsSync(configPath),
+    configReadable: false,
     featureEnabled: false,
     codexHooksFeatureEnabled: false,
     hooksFeatureEnabled: false,
@@ -513,6 +516,7 @@ function readCodexHookDiagnosis(codexHome) {
   if (existsSync(configPath)) {
     try {
       const config = readFileSync(configPath, 'utf8');
+      out.configReadable = true;
       out.codexHooksFeatureEnabled = /^\s*codex_hooks\s*=\s*true\s*$/m.test(config);
       out.hooksFeatureEnabled = /^\s*hooks\s*=\s*true\s*$/m.test(config);
       out.featureEnabled = out.codexHooksFeatureEnabled || out.hooksFeatureEnabled;
@@ -522,7 +526,7 @@ function readCodexHookDiagnosis(codexHome) {
     }
   }
 
-  if (!existsSync(hooksPath)) return out;
+  if (!out.hooksExists) return out;
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(hooksPath, 'utf8'));

package/src/cli/factory-diagnostics.mjs

@@ -0,0 +1,246 @@
+import { existsSync } from 'node:fs';
+import { DatabaseSync } from 'node:sqlite';
+import { createRequire } from 'node:module';
+
+import { defaultAuditorContextDbPath } from '../auditor-context.mjs';
+import { buildFactoryDiagnostics } from '../factory-diagnostics.mjs';
+import { findCodexThreadCandidate, defaultCodexHome } from '../codex-thread-index.mjs';
+import { resolveCodexThreadIdentity } from '../codex-thread-identity.mjs';
+import { CURRENT_VERSION } from '../db.mjs';
+import { _internal as doctorInternal } from './doctor.mjs';
+
+const require = createRequire(import.meta.url);
+const PACKAGE_VERSION = require('../../package.json').version;
+const REQUIRED_DATABASE_COLUMNS = {
+  sessions: ['session_id', 'project_path', 'status', 'created_at', 'updated_at', 'merged_into'],
+  skeletons: ['id', 'session_id', 'turn_number', 'role', 'summary', 'created_at', 'origin_session_id'],
+  bodies: ['id', 'session_id', 'origin_session_id', 'turn_number', 'role', 'text', 'token_count', 'created_at'],
+  details: ['id', 'session_id', 'turn_number', 'tool_name', 'input_text', 'output_text', 'token_count', 'created_at', 'origin_session_id', 'kind', 'source_id'],
+  handoff_batons: ['project_path', 'session_id', 'created_at'],
+};
+const REQUIRED_DATABASE_INDEXES = ['uq_skeletons_turn_v3', 'uq_details_source'];
+const REQUIRED_INDEX_SHAPES = {
+  uq_skeletons_turn_v3: {
+    table: 'skeletons',
+    columns: ['session_id', 'origin_session_id', 'turn_number', 'role'],
+    partial: false,
+  },
+  uq_details_source: {
+    table: 'details',
+    columns: ['session_id', 'origin_session_id', 'source_id'],
+    partial: true,
+  },
+};
+
+export function parseArgs(argv = []) {
+  if (argv.length !== 1 || argv[0] !== '--json') throw new TypeError('usage error');
+  return { json: true };
+}
+
+export function inspectFactoryDatabase({
+  dbPath = defaultAuditorContextDbPath(),
+  threadId = null,
+  projectPath = null,
+} = {}) {
+  if (!existsSync(dbPath)) {
+    return databaseResult('not_applicable', null, false);
+  }
+
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    const schemaVersion = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
+    if (schemaVersion !== CURRENT_VERSION || !hasFactoryDatabaseShape(db)) {
+      return databaseResult('not_ready', schemaVersion, false);
+    }
+    if (!threadId || typeof projectPath !== 'string' || projectPath.length === 0) {
+      return databaseResult('ready', schemaVersion, false);
+    }
+    const sessionId = `codex:${threadId}`;
+    const counts = db.prepare(
+      `SELECT
+        (SELECT COUNT(*) FROM skeletons WHERE session_id = :sessionId) AS l1,
+        (SELECT COUNT(*) FROM bodies WHERE session_id = :sessionId) AS l2,
+        (SELECT COUNT(*) FROM details WHERE session_id = :sessionId) AS l3
+       WHERE EXISTS (
+         SELECT 1 FROM sessions
+         WHERE session_id = :sessionId AND lower(project_path) = lower(:projectPath)
+       )`,
+    ).get({ sessionId, projectPath });
+    const handoffMemory = counts !== undefined &&
+      Number(counts.l1 ?? 0) + Number(counts.l2 ?? 0) + Number(counts.l3 ?? 0) > 0;
+    return databaseResult('ready', schemaVersion, handoffMemory);
+  } catch {
+    return databaseResult('unverified', null, false);
+  } finally {
+    db?.close();
+  }
+}
+
+function databaseResult(status, schemaVersion, handoffMemory) {
+  return {
+    status,
+    schemaVersion,
+    supportedSchemaVersion: CURRENT_VERSION,
+    handoffMemory,
+  };
+}
+
+function hasFactoryDatabaseShape(db) {
+  const tableInfo = {};
+  for (const [table, requiredColumns] of Object.entries(REQUIRED_DATABASE_COLUMNS)) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    tableInfo[table] = new Map(rows.map((row) => [row.name, row]));
+    const actual = new Set(tableInfo[table].keys());
+    if (requiredColumns.some((column) => !actual.has(column))) return false;
+  }
+  if (tableInfo.sessions.get('session_id')?.pk !== 1 ||
+    tableInfo.handoff_batons.get('project_path')?.pk !== 1) return false;
+  for (const [table, columns] of Object.entries({
+    sessions: ['project_path', 'status', 'created_at', 'updated_at'],
+    handoff_batons: ['session_id', 'created_at'],
+  })) {
+    if (columns.some((column) => tableInfo[table].get(column)?.notnull !== 1)) return false;
+  }
+
+  for (const name of REQUIRED_DATABASE_INDEXES) {
+    const expected = REQUIRED_INDEX_SHAPES[name];
+    const index = db.prepare(`PRAGMA index_list(${expected.table})`).all()
+      .find((row) => row.name === name);
+    if (!index || index.unique !== 1 || Boolean(index.partial) !== expected.partial) return false;
+    const columns = db.prepare(`PRAGMA index_info(${name})`).all().map((row) => row.name);
+    if (columns.length !== expected.columns.length ||
+      columns.some((column, indexPosition) => column !== expected.columns[indexPosition])) return false;
+  }
+
+  const bodiesUnique = db.prepare('PRAGMA index_list(bodies)').all().some((index) => {
+    if (index.unique !== 1) return false;
+    const columns = db.prepare(`PRAGMA index_info(${index.name})`).all().map((row) => row.name);
+    return columns.join('\0') === ['session_id', 'origin_session_id', 'turn_number', 'role'].join('\0');
+  });
+  return bodiesUnique;
+}
+
+function eventStatus({ hooks, legacyHooks, featureEnabled, expectedCommand, timeoutSec }) {
+  if (hooks.length === 0) return featureEnabled ? 'not_ready' : 'not_applicable';
+  if (!featureEnabled || legacyHooks.length > 0 || hooks.length !== 1) return 'not_ready';
+  const hook = hooks[0];
+  return hook.type === 'command' && hook.command === expectedCommand && hook.timeoutSec === timeoutSec &&
+    hook.async === false ? 'ready' : 'not_ready';
+}
+
+export function inspectFactoryHooks({ codexHome = defaultCodexHome(), readHooks = doctorInternal.readCodexHookDiagnosis } = {}) {
+  try {
+    const diagnosis = readHooks(codexHome);
+    if ((diagnosis.configExists && !diagnosis.configReadable) ||
+      (diagnosis.hooksExists && !diagnosis.hooksReadable)) {
+      return { status: 'unverified', reason: 'hook_configuration_unreadable', events: {} };
+    }
+    const events = {
+      userPromptSubmit: eventStatus({
+        hooks: diagnosis.managedPromptHooks,
+        legacyHooks: diagnosis.legacyManagedPromptHooks,
+        featureEnabled: diagnosis.featureEnabled,
+        expectedCommand: diagnosis.expectedPromptCommand,
+        timeoutSec: 30,
+      }),
+      postToolUse: eventStatus({
+        hooks: diagnosis.managedPostToolUseHooks,
+        legacyHooks: diagnosis.legacyManagedPostToolUseHooks,
+        featureEnabled: diagnosis.featureEnabled,
+        expectedCommand: diagnosis.expectedPostToolUseCommand,
+        timeoutSec: 30,
+      }),
+      stop: eventStatus({
+        hooks: diagnosis.managedStopHooks,
+        legacyHooks: diagnosis.legacyManagedStopHooks,
+        featureEnabled: diagnosis.featureEnabled,
+        expectedCommand: diagnosis.expectedStopCommand,
+        timeoutSec: 300,
+      }),
+    };
+    const values = Object.values(events);
+    return {
+      status: values.includes('not_ready')
+        ? 'not_ready'
+        : values.includes('ready')
+          ? 'unverified'
+          : 'not_applicable',
+      reason: 'hooks_inspected',
+      events,
+    };
+  } catch {
+    return { status: 'unverified', reason: 'hook_inspection_failed', events: {} };
+  }
+}
+
+export function inspectFactoryThread({
+  env = process.env,
+  cwd = process.cwd(),
+  codexHome = env.CODEX_HOME || defaultCodexHome(),
+  resolveIdentity = resolveCodexThreadIdentity,
+  findCandidate = findCodexThreadCandidate,
+} = {}) {
+  const identity = resolveIdentity({ codexThreadId: null }, env);
+  if (!identity.codexThreadId) {
+    return {
+      status: 'not_applicable',
+      reason: 'codex_thread_not_detected',
+      rolloutAvailable: false,
+      threadId: null,
+    };
+  }
+  try {
+    const candidate = findCandidate({
+      threadId: identity.codexThreadId,
+      codexHome,
+      projectPath: cwd,
+      requireProjectMatch: true,
+    });
+    return candidate
+      ? { status: 'ready', reason: 'thread_and_rollout_detected', rolloutAvailable: true, threadId: identity.codexThreadId }
+      : { status: 'not_ready', reason: 'rollout_not_found_for_project', rolloutAvailable: false, threadId: null };
+  } catch {
+    return { status: 'unverified', reason: 'rollout_inspection_failed', rolloutAvailable: false, threadId: identity.codexThreadId };
+  }
+}
+
+export function collectFactoryDiagnostics({
+  env = process.env,
+  cwd = process.cwd(),
+  version = PACKAGE_VERSION,
+  inspectThread = inspectFactoryThread,
+  inspectDatabase = inspectFactoryDatabase,
+  inspectHooks = inspectFactoryHooks,
+} = {}) {
+  const thread = inspectThread({ env, cwd });
+  const database = inspectDatabase({ threadId: thread.threadId ?? null, projectPath: cwd });
+  const hooks = inspectHooks({ codexHome: env.CODEX_HOME || defaultCodexHome() });
+  return buildFactoryDiagnostics({ version, database, hooks, thread });
+}
+
+export function run(argv = [], { stdout = process.stdout, ...dependencies } = {}) {
+  try {
+    parseArgs(argv);
+  } catch {
+    stdout.write(`${JSON.stringify({
+      schema: 'throughline.native_factory_diagnostics.v1',
+      version: PACKAGE_VERSION,
+      overall: { status: 'unverified' },
+      error: 'invalid_diagnostics_request',
+    })}\n`);
+    return 2;
+  }
+  try {
+    stdout.write(`${JSON.stringify(collectFactoryDiagnostics(dependencies))}\n`);
+    return 0;
+  } catch {
+    stdout.write(`${JSON.stringify({
+      schema: 'throughline.native_factory_diagnostics.v1',
+      version: PACKAGE_VERSION,
+      overall: { status: 'unverified' },
+      error: 'diagnostics_internal_error',
+    })}\n`);
+    return 1;
+  }
+}