claude-spotter 1.4.21 → 1.4.23

package/CHANGELOG.md

@@ -1,12 +1,37 @@
 # Changelog
 
+## 1.4.23 — release candidate (pending)
+
+- **Factory diagnostics と local runtime error store。** factory diagnostics と
+  `spotter diagnostics runtime-errors` の公開候補。収集は canonical dotagents config の
+  JSON boolean `collection.enabled: true` が明示された時だけ有効で既定OFF、保存は
+  local-only、network送信は行わない。npm公開、tag、CI、registry由来installの確認は未実施。
+- **隔離observerのdeadlineを実測へ整合。** 並列full-suite負荷でcold workerとreceipt
+  reconcilerが500msに収まらず、commit済みreceiptを`store_unavailable`へ誤分類するraceを
+  再現した。絶対deadlineを1.5秒へ広げたうえでreceipt reconcilerを観測workerと
+  並行prewarmし、後段cold-startの競合を除去。worker treeの強制終了と本体処理を
+  止めない契約は維持する。
+
+## 1.4.22 — 2026-07-13
+
+- **default-on裁定の文書修正。** v1.4.21の実装どおりdefault-onは確定事項であり、7日・30 fresh resultの測定は精度改善にだけ使う。ON/OFFの再審査やdefault-off rollbackを選択肢としていた誤記をREADME、正典、SLO、計画、課題台帳から削除した。
+- **公開。** 478 tests（476 pass / 2 skip）、CI 6/6 green。公開commit`3c7c820`をnpm `claude-spotter@1.4.22`、tag / GitHub Release、registry由来global installへ同期した。
+
 ## 1.4.21 — 2026-07-13
 
 ### Changed
 
 - **Throughline監査文脈をdefault-onへ変更。** `spotter install`がPATH上のThroughlineをabsolute pathへ解決できる場合、project markerへ既定設定する。marker v2の`origin:default|explicit`で旧既定disabledだけを移行し、明示OFFは再install後も維持する。POSIXはrealpath、Windows npm shimはabsolute `node.exe + throughline.mjs`を保存する。
 - **不在時は明示disabled。** Throughlineが見つからない場合は固定理由付きdisabledとし、current-only監査や別backendへfallbackしない。installerとdoctorが状態・OFF手順を表示する。
-- **実運用効果測定。** default-onで7日以上・fresh 30件以上を集め、過検出・見逃し・stale率・latencyから維持、修正、default-off rollbackを判断する。L2本文は評価ログへ保存しない。
+- **実運用効果測定。** default-onはowner確定済み。7日以上・fresh 30件以上の過検出・見逃し・stale率・latencyは精度改善にだけ使い、ON/OFFを再審査しない。L2本文は評価ログへ保存しない。
+
+### 検証・公開
+
+478 tests（476 pass / 2 skip）、macOS/Linux/Windows × Node 22.5/22.xのCI 6/6、packの秘密・
+開発者固有path scan、隔離tarball installを通過。公開commitは`5026ace`。npm `claude-spotter@1.4.21`、
+tag / GitHub Release `v1.4.21`、registry由来global installを同期した。registry版の空projectへ
+`spotter install -y`を実行し、marker v2がThroughlineのglobal実体を`origin:default`で設定し、
+doctorがconnector availableを返すことを確認した。
 
 ## 1.4.20 — 2026-07-13
 

package/README.ja.md

@@ -190,7 +190,7 @@ spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.js
   --recent-turns 2 --body-cap 600
 ```
 
-評価結論はN=2 / 600です。既定ONの実運用で7日・30 fresh resultを集め、維持・修正・rollbackを判断します。
+評価結論はN=2 / 600です。既定ONは確定済みで、7日・30 fresh resultの実運用測定は精度改善に使います。
 
 ## よく使うコマンド
 

package/README.md

@@ -80,7 +80,7 @@ spotter codex-hook install
 
 ## Requirements
 
-- **Node.js 22.5+**
+- **Node.js 22.13+**
 - **Claude Code 2.0+**
 - **Codex CLI** for the default Codex-native backend and the preferred Claude-host auditor path. The auto-selected Codex backend does not fall back to Haiku after a runtime failure
 - **Claude Max plan** only when a Claude host selects the Haiku path (Codex CLI is absent or `SPOTTER_AUDITOR_BACKEND=haiku` is explicit)
@@ -195,8 +195,8 @@ spotter auditor model-matrix --fixtures test/fixtures/auditor-model-matrix.v2.js
   --recent-turns 2 --body-cap 600
 ```
 
-The evaluated setting is N=2 / 600. Default-on operation now collects the 7-day,
-30-fresh-result sample used to decide whether to keep, adjust, or roll back the default.
+The evaluated setting is N=2 / 600. Default-on is final; the 7-day,
+30-fresh-result sample is used only to identify precision improvements.
 
 ## Common commands
 
@@ -214,6 +214,8 @@ spotter db rebuild       # wipe Claude local + Claude global DBs and refresh fro
 spotter status           # list running daemons
 spotter doctor           # environment check (Node / claude CLI / Codex readiness / tool-db integrity)
 spotter diagnostics logs # summarize daemon logs for pass=false / backend latency / anomaly signals
+spotter diagnostics runtime-errors
+                         # print the local allow-listed runtime-error aggregate snapshot (no network)
 spotter codex risk-check --findings findings.json --host-agent claude
                          # run read-only codex-sidecar risk analysis for Spotter findings
 spotter codex review|explore|opinion --findings findings.json --host-agent claude
@@ -243,6 +245,38 @@ in a detached process. Hook responses do not wait for Codex. Add
 Primary auditor backend policy: Claude hooks automatically select Codex CLI when it is available on PATH,
 otherwise the Haiku-compatible path. Codex native hooks automatically select Codex CLI. An explicit
 `SPOTTER_AUDITOR_BACKEND` override wins on either host; runtime failure never triggers a hidden fallback.
+
+## Local runtime error aggregates
+
+**v1.4.23 は release candidate（公開待ち）です。** 以下の factory diagnostics と
+local runtime error aggregate は collection が既定OFFで、公開・tag・CI・registry由来
+installの確認はいずれも未完了です。
+
+Spotter collects fixed-code runtime failures only when the canonical dotagents factory reporter
+configuration contains the JSON boolean `collection.enabled: true`. Missing, malformed, and disabled
+configuration all fail closed. Collection is local-only: Spotter has no reporting credential or network
+transport code. The owner-private atomic store contains only fixed templates and allow-listed aggregates;
+raw exceptions, stdout/stderr, stacks, prompts, hook payloads, findings, file contents, and absolute paths
+are not accepted by its API.
+
+Daemon and direct Codex-hook owner boundaries perform collection in a killable child-process group with
+a bounded timeout. A blocked FIFO or descendant therefore cannot stall the hook or daemon. HTTP reporting
+metadata, when present in the shared config, is accepted only when `new URL(value).href === value` and the
+scheme is HTTP(S); Spotter still neither reads credentials nor sends the aggregate anywhere.
+
+On POSIX, every config/store read revalidates the current uid and exact `0600` file / `0700` directory
+modes. Store mutations use a private SQLite `BEGIN IMMEDIATE` mutex that the OS releases on process crash;
+there is no PID/mtime stale-owner reclaim path. On Windows, every
+store access rebuilds the DACL to one FullControl ACE for the current process SID and verifies the ACL
+readback before use.
+
+`spotter diagnostics runtime-errors` emits the read-only cursor snapshot. Its
+`ack`, `resolve`, `reopen`, and `compact` actions are the machine lifecycle
+surface used after report acceptance. `spotter diagnostics logs`
+and `spotter diagnostics factory` include only bounded store counts/status, never the store/config path
+or record payload. Programmatic consumers can import `readRuntimeErrorSnapshot`,
+`acknowledgeRuntimeErrors`, `resolveRuntimeError`, `reopenRuntimeError`, and `compactRuntimeErrors`.
+Acknowledgement is monotonic, and compaction never removes an unacknowledged record.
 The Codex SessionStart hook refreshes `.spotter/tool-db.codex.json` in the background
 without touching the Claude DB.
 Codex CLI auditor child processes use a versioned product policy. The production selection is

package/bin/spotter.mjs

@@ -11,6 +11,7 @@ import { runCodexCommand } from '../src/cli/codex-cmd.mjs';
 import { runCodexHookCommand } from '../src/cli/codex-hook-cmd.mjs';
 import { runAuditorCommand } from '../src/cli/auditor-cmd.mjs';
 import { runDiagnosticsCommand } from '../src/cli/diagnostics-cmd.mjs';
+import { runFactoryDiagnostics } from '../src/cli/factory-diagnostics.mjs';
 import { runDaemonStart } from '../src/cli/daemon-cmd.mjs';
 import { runSessionStart } from '../src/hooks/session-start.mjs';
 import { runUserPrompt } from '../src/hooks/user-prompt.mjs';
@@ -42,6 +43,8 @@ Usage:
   spotter status                        show running daemons
   spotter doctor                        environment diagnostic
   spotter diagnostics logs [--json]     summarize daemon logs for precision diagnostics
+  spotter diagnostics runtime-errors [snapshot|ack|resolve|reopen|compact]
+                                        consume the local allow-listed aggregate store
   spotter codex risk-check --findings FILE
                                         run read-only codex-sidecar risk analysis
   spotter codex review|explore|opinion --findings FILE
@@ -114,6 +117,11 @@ async function main() {
       await runAuditorCommand({ argv: rest });
       return;
     case 'diagnostics':
+      if (rest[0] === 'factory') {
+        if (rest.length !== 1) throw invalidFactoryDiagnosticsArgs();
+        process.stdout.write(`${JSON.stringify(await runFactoryDiagnostics())}\n`);
+        return;
+      }
       await runDiagnosticsCommand({ argv: rest });
       return;
     case 'daemon': {
@@ -197,6 +205,13 @@ function invalidInstallArgs() {
   return err;
 }
 
+function invalidFactoryDiagnosticsArgs() {
+  const err = new Error('usage: spotter diagnostics factory');
+  err.stack = '';
+  err.exitCode = 2;
+  return err;
+}
+
 main().catch((err) => {
   process.stderr.write(`spotter: ${err.stack || err.message || err}\n`);
   process.exit(err.exitCode ?? 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-spotter",
-  "version": "1.4.21",
+  "version": "1.4.23",
   "description": "Audit agent running alongside Claude Code that catches missed tool calls — 気づく役と実行する役の分離",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
   },
   "homepage": "https://github.com/kitepon-rgb/Spotter#readme",
   "engines": {
-    "node": ">=22.5.0"
+    "node": ">=22.13.0"
   },
   "dependencies": {
     "js-yaml": "^4.1.0"

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

@@ -32,6 +32,7 @@ import {
   loadAuditorContext,
   readProjectAuditorContextConfig,
 } from '../core/auditor-context.mjs';
+import { observeRuntimeErrorIsolatedSafe } from '../core/runtime-error-store.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(HERE, '..', '..');
@@ -77,11 +78,11 @@ export async function runCodexHookCommand({ argv = process.argv.slice(2) } = {})
     return;
   }
   if (sub === 'user-prompt-submit') {
-    await runCodexUserPromptSubmitHook();
+    await runCodexUserPromptSubmitHook({ runtimeErrorObserver: observeRuntimeErrorIsolatedSafe });
     return;
   }
   if (sub === 'stop') {
-    await runCodexStopHook();
+    await runCodexStopHook({ runtimeErrorObserver: observeRuntimeErrorIsolatedSafe });
     return;
   }
   process.stderr.write(`unknown codex-hook subcommand: ${sub}\n${CODEX_HOOK_USAGE}`);
@@ -121,6 +122,7 @@ export async function runCodexUserPromptSubmitHook({
   loadAuditorContextFn = loadAuditorContext,
   writeOutput = (text) => process.stdout.write(text),
   writeError = (text) => process.stderr.write(text),
+  runtimeErrorObserver = async () => ({ collected: false, reason: 'observer_not_configured' }),
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -160,6 +162,7 @@ export async function runCodexUserPromptSubmitHook({
     });
     contextDurationMs = Date.now() - contextStartedAt;
   } catch (err) {
+    await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     contextDurationMs = Date.now() - contextStartedAt;
     const failure = projectBackendFailure(err?.code);
     safeWriteError(writeError, failure.stderr);
@@ -179,6 +182,7 @@ export async function runCodexUserPromptSubmitHook({
     return;
   }
   if (context.status === 'unavailable' || context.status === 'schema_mismatch') {
+    await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     const failure = projectBackendFailure(context.status === 'unavailable'
       ? 'E_AUDITOR_CONTEXT_UNAVAILABLE'
       : 'E_AUDITOR_CONTEXT_SCHEMA');
@@ -219,8 +223,10 @@ export async function runCodexUserPromptSubmitHook({
   let catalog;
   let backend;
   let judgment;
+  let enteredAuditorBoundary = false;
   try {
     catalog = await readLocalFn({ projectRoot, hostAgent: 'codex' });
+    enteredAuditorBoundary = true;
     backend = createCodexHookAuditorBackend({ catalog, projectRoot, createAuditorBackendFn });
     judgment = await backend.judge({
       stage: 'user_input',
@@ -229,6 +235,7 @@ export async function runCodexUserPromptSubmitHook({
       contextStatus: 'fresh',
     });
   } catch (err) {
+    if (enteredAuditorBoundary) await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     const failure = projectBackendFailure(err?.code);
     safeWriteError(writeError, failure.stderr);
     await recordCodexHookEventSafe(recordHookEventFn, {
@@ -281,6 +288,7 @@ export async function runCodexStopHook({
   recordHookEventFn = appendCodexHookEvent,
   writeOutput = (text) => process.stdout.write(text),
   writeError = (text) => process.stderr.write(text),
+  runtimeErrorObserver = async () => ({ collected: false, reason: 'observer_not_configured' }),
 } = {}) {
   if (isChildCall()) return;
   const input = await readInput();
@@ -331,11 +339,14 @@ export async function runCodexStopHook({
   let catalog;
   let backend;
   let judgment;
+  let enteredAuditorBoundary = false;
   try {
     catalog = await readLocalFn({ projectRoot, hostAgent: 'codex' });
+    enteredAuditorBoundary = true;
     backend = createCodexHookAuditorBackend({ catalog, projectRoot, createAuditorBackendFn });
     judgment = await backend.judge({ stage: 'turn_end', finalResponse, usedTools });
   } catch (err) {
+    if (enteredAuditorBoundary) await observeRuntimeFailure(runtimeErrorObserver, 'auditor_unavailable');
     const failure = projectBackendFailure(err?.code);
     reportError(failure.stderr);
     writeCodexSystemMessage({ systemMessage: failure.systemMessage, writeOutput });
@@ -653,6 +664,14 @@ function createCodexHookAuditorBackend({ catalog, projectRoot, createAuditorBack
   });
 }
 
+async function observeRuntimeFailure(observer, kind) {
+  try {
+    await observer(kind);
+  } catch {
+    // Runtime error telemetry must not alter hook output or exit behavior.
+  }
+}
+
 function resolveCodexHookAuditorBackend({ env }) {
   if (!env?.SPOTTER_AUDITOR_BACKEND) return 'codex-cli';
   return selectAuditorBackend({ hostAgent: 'codex', env }).backend;

package/src/cli/daemon-cmd.mjs

@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { open } from 'node:fs/promises';
 import { writeFileSync } from 'node:fs';
+import { observeRuntimeErrorIsolatedSafe } from '../core/runtime-error-store.mjs';
 
 function parseArgs(argv) {
   const out = { sessionId: null, projectRoot: null };
@@ -69,7 +70,12 @@ export async function runDaemonStart({ argv }) {
     // removed along with the stateless regime that required it.
     // v0.7.0: projectRoot drives tool-db loading (replaces the old tools.yaml catalog).
     // v0.12.0: orphan-cleanup is heartbeat-based inside startDaemon (no parent-PID arg).
-    running = await startDaemon({ sessionId, projectRoot, logFn: log });
+    running = await startDaemon({
+      sessionId,
+      projectRoot,
+      logFn: log,
+      runtimeErrorObserver: observeRuntimeErrorIsolatedSafe,
+    });
   } catch (err) {
     if (err instanceof DaemonAlreadyRunningError) {
       // v0.2 PID-preexist layer: a sibling daemon already serves this session.

package/src/cli/diagnostics-cmd.mjs

@@ -1,11 +1,23 @@
 import { resolve } from 'node:path';
 import { defaultDaemonLogDir, summarizeDaemonLogs } from '../core/daemon-log-diagnostics.mjs';
 import { summarizeHookEvents } from '../core/hook-event-log.mjs';
+import {
+  acknowledgeRuntimeErrors,
+  compactRuntimeErrors,
+  readRuntimeErrorSnapshot,
+  readRuntimeErrorStoreStatus,
+  reopenRuntimeError,
+  resolveRuntimeError,
+} from '../core/runtime-error-store.mjs';
 
 const DIAGNOSTICS_USAGE = `spotter diagnostics — read-only operational diagnostics
 
 Usage:
   spotter diagnostics logs [--log-dir DIR] [--project DIR] [--json]
+  spotter diagnostics runtime-errors [snapshot] [--after-cursor N] [--limit N]
+  spotter diagnostics runtime-errors ack CURSOR
+  spotter diagnostics runtime-errors resolve|reopen FINGERPRINT
+  spotter diagnostics runtime-errors compact
 
   --log-dir   daemon log directory (default: ~/.spotter/runtime)
   --project   project root for hook-events.jsonl (default: cwd)
@@ -17,6 +29,10 @@ export async function runDiagnosticsCommand({ argv = process.argv.slice(2) } = {
     await runDiagnosticsLogsCommand({ argv: argv.slice(1) });
     return;
   }
+  if (sub === 'runtime-errors') {
+    await runRuntimeErrorDiagnosticsCommand({ argv: argv.slice(1) });
+    return;
+  }
   process.stderr.write(`unknown diagnostics subcommand: ${sub}\n${DIAGNOSTICS_USAGE}`);
   process.exit(2);
 }
@@ -25,6 +41,7 @@ export async function runDiagnosticsLogsCommand({
   argv = [],
   summarizeDaemonLogsFn = summarizeDaemonLogs,
   summarizeHookEventsFn = summarizeHookEvents,
+  readRuntimeErrorStoreStatusFn = readRuntimeErrorStoreStatus,
   writeOutput = (text) => process.stdout.write(text),
 } = {}) {
   const opts = parseLogsArgs(argv);
@@ -33,7 +50,8 @@ export async function runDiagnosticsLogsCommand({
   // the hook-side observations (skip reasons, drained pending counts, transport errors
   // that never reach the daemon) surface in the same diagnostics output.
   const hookEvents = await summarizeHookEventsFn({ projectRoot: opts.projectRoot });
-  const merged = { ...summary, hookEvents };
+  const runtimeErrors = await readRuntimeErrorStoreStatusFn();
+  const merged = { ...summary, hookEvents, runtimeErrors };
   if (opts.json) {
     writeOutput(JSON.stringify(merged, null, 2) + '\n');
     return;
@@ -110,9 +128,78 @@ export function formatDaemonLogSummary(summary) {
     }
   }
 
+  const runtimeErrors = summary.runtimeErrors;
+  if (runtimeErrors) {
+    lines.push(
+      `  runtime-errors: collection=${runtimeErrors.collection}, store=${runtimeErrors.store}, records=${runtimeErrors.records}, open=${runtimeErrors.open}, resolved=${runtimeErrors.resolved}, unacknowledged=${runtimeErrors.unacknowledged}`
+    );
+  }
+
   return lines.join('\n') + '\n';
 }
 
+export async function runRuntimeErrorDiagnosticsCommand({
+  argv = [],
+  readSnapshotFn = readRuntimeErrorSnapshot,
+  acknowledgeFn = acknowledgeRuntimeErrors,
+  resolveFn = resolveRuntimeError,
+  reopenFn = reopenRuntimeError,
+  compactFn = compactRuntimeErrors,
+  writeOutput = (text) => process.stdout.write(text),
+} = {}) {
+  const action = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'snapshot';
+  const actionArgs = action === 'snapshot' && argv[0] !== 'snapshot' ? argv : argv.slice(1);
+  if (!['snapshot', 'ack', 'resolve', 'reopen', 'compact'].includes(action)) throw runtimeErrorUsage();
+  try {
+    if (action === 'ack') {
+      if (actionArgs.length !== 1) throw runtimeErrorUsage();
+      const result = await acknowledgeFn({ cursor: parseNonNegativeInteger(actionArgs[0], 'cursor') });
+      writeOutput(`${JSON.stringify(result)}\n`);
+      return;
+    }
+    if (action === 'resolve' || action === 'reopen') {
+      if (actionArgs.length !== 1 || !/^[a-f0-9]{64}$/.test(actionArgs[0])) throw runtimeErrorUsage();
+      const result = await (action === 'resolve' ? resolveFn : reopenFn)({ fingerprint: actionArgs[0] });
+      writeOutput(`${JSON.stringify(result)}\n`);
+      return;
+    }
+    if (action === 'compact') {
+      if (actionArgs.length !== 0) throw runtimeErrorUsage();
+      writeOutput(`${JSON.stringify(await compactFn())}\n`);
+      return;
+    }
+  let afterCursor = 0;
+  let limit = 100;
+  for (let index = 0; index < actionArgs.length; index += 1) {
+    const arg = actionArgs[index];
+    if (arg === '--after-cursor') {
+      afterCursor = parseNonNegativeInteger(requireValue(actionArgs, (index += 1), '--after-cursor'), '--after-cursor');
+      continue;
+    }
+    if (arg === '--limit') {
+      limit = parsePositiveInteger(requireValue(actionArgs, (index += 1), '--limit'), '--limit');
+      continue;
+    }
+    throw Object.assign(new Error(`unknown diagnostics runtime-errors option: ${arg}`), { exitCode: 2 });
+  }
+  const snapshot = await readSnapshotFn({ afterCursor, limit });
+  writeOutput(`${JSON.stringify(snapshot)}\n`);
+  } catch (error) {
+    if (error?.exitCode === 2) throw error;
+    const fixed = new Error('runtime error store unavailable');
+    fixed.stack = '';
+    fixed.exitCode = 1;
+    throw fixed;
+  }
+}
+
+function runtimeErrorUsage() {
+  const error = new Error('usage: spotter diagnostics runtime-errors snapshot|ack|resolve|reopen|compact');
+  error.stack = '';
+  error.exitCode = 2;
+  return error;
+}
+
 function formatCounter(counter) {
   if (!counter || typeof counter !== 'object') return '';
   const entries = Object.entries(counter).sort(([a], [b]) => a.localeCompare(b));
@@ -155,6 +242,16 @@ function requireValue(argv, index, option) {
   return value;
 }
 
+function parseNonNegativeInteger(value, option) {
+  if (!/^(?:0|[1-9][0-9]*)$/.test(value)) throw Object.assign(new Error(`${option} requires a non-negative integer`), { exitCode: 2 });
+  return Number(value);
+}
+
+function parsePositiveInteger(value, option) {
+  if (!/^[1-9][0-9]*$/.test(value)) throw Object.assign(new Error(`${option} requires a positive integer`), { exitCode: 2 });
+  return Number(value);
+}
+
 function topCounter(counter, limit) {
   return Object.entries(counter)
     .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))

package/src/cli/factory-diagnostics.mjs

@@ -0,0 +1,178 @@
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { codexHookDiagnostics } from './codex-hook-cmd.mjs';
+import { inspectAuditorContextConfiguration } from './doctor.mjs';
+import { loadDb, localDbPath } from '../tool-db/loader.mjs';
+import { version } from '../version.mjs';
+import { readRuntimeErrorStoreStatus } from '../core/runtime-error-store.mjs';
+
+const KNOWN_MARKER_VERSIONS = new Set(['1', '2']);
+const SAFE_CONTEXT_MODES = new Set(['disabled', 'throughline']);
+const SAFE_CODEX_READINESS = new Set([
+  'configured-unverified',
+  'misconfigured',
+  'not-installed',
+  'unavailable',
+]);
+
+export async function runFactoryDiagnostics({
+  projectRoot = process.cwd(),
+  codexHookDiagnosticsFn = codexHookDiagnostics,
+  inspectAuditorContextFn = inspectAuditorContextConfiguration,
+  readRuntimeErrorStoreStatusFn = readRuntimeErrorStoreStatus,
+} = {}) {
+  const runtimeErrorStore = await readRuntimeErrorStoreStatusFn();
+  const markerResult = await readMarker(join(projectRoot, '.spotter', 'marker.json'));
+  if (markerResult.status === 'missing') return inactiveSnapshot(runtimeErrorStore);
+
+  const checks = [];
+  if (markerResult.status !== 'valid') {
+    checks.push(check('project_activation', 'unverified', markerResult.reasonCode));
+    return snapshot({ overallStatus: 'unverified', checks, runtimeErrorStore });
+  }
+
+  const marker = markerResult.value;
+  checks.push(check('project_activation', 'pass'));
+
+  const markerVersion = typeof marker.markerVersion === 'string' && KNOWN_MARKER_VERSIONS.has(marker.markerVersion)
+    ? marker.markerVersion
+    : null;
+  checks.push(markerVersion
+    ? check('marker_schema', 'pass')
+    : check('marker_schema', 'fail', 'unsupported_marker_schema'));
+
+  const contextMode = safeContextMode(marker.auditorContext);
+  if (contextMode === null) {
+    checks.push(check('throughline_context', 'fail', 'invalid_context_configuration'));
+  } else if (contextMode === 'disabled') {
+    checks.push(check('throughline_context', 'skipped', 'context_disabled'));
+  } else {
+    const context = await inspectAuditorContextFn({ projectRoot });
+    checks.push(context?.ok === true && context?.mode === 'throughline'
+      ? check('throughline_context', 'pass')
+      : check('throughline_context', 'unverified', 'context_provider_unavailable'));
+  }
+
+  const catalogs = {};
+  for (const host of ['claude', 'codex']) {
+    const result = await inspectCatalog(localDbPath(projectRoot, host));
+    catalogs[host] = result.publicStatus;
+    checks.push(check(`${host}_catalog`, result.checkStatus, result.reasonCode));
+  }
+  checks.push(Object.values(catalogs).includes('available')
+    ? check('audit_catalog_readiness', 'pass')
+    : Object.values(catalogs).includes('invalid')
+      ? check('audit_catalog_readiness', 'fail', 'catalog_invalid_schema')
+      : check('audit_catalog_readiness', 'unverified', 'no_host_catalog'));
+
+  let codexReadiness = 'unverified';
+  try {
+    const diagnostics = await codexHookDiagnosticsFn({ projectRoot });
+    if (SAFE_CODEX_READINESS.has(diagnostics?.readiness)) codexReadiness = diagnostics.readiness;
+  } catch {
+    // A safe snapshot still reports that the inspector could not establish readiness.
+  }
+  checks.push(codexReadiness === 'configured-unverified'
+    ? check('codex_hooks', 'unverified', 'trust_not_machine_verifiable')
+    : codexReadiness === 'not-installed'
+      ? check('codex_hooks', 'skipped', 'not_installed')
+      : codexReadiness === 'misconfigured'
+        ? check('codex_hooks', 'fail', 'misconfigured')
+        : check('codex_hooks', 'unverified', 'diagnostics_unavailable'));
+
+  return snapshot({
+    overallStatus: overallStatus(checks),
+    markerSchemaVersion: markerVersion,
+    throughlineContext: contextMode ?? 'unverified',
+    catalogs,
+    codexHookReadiness: codexReadiness,
+    runtimeErrorStore,
+    checks,
+  });
+}
+
+function inactiveSnapshot(runtimeErrorStore) {
+  return snapshot({
+    overallStatus: 'not_applicable',
+    runtimeErrorStore,
+    checks: [check('project_activation', 'skipped', 'project_not_activated')],
+  });
+}
+
+function snapshot({
+  overallStatus,
+  markerSchemaVersion = null,
+  throughlineContext = 'unverified',
+  catalogs = { claude: 'not_applicable', codex: 'not_applicable' },
+  codexHookReadiness = 'not_applicable',
+  runtimeErrorStore,
+  checks,
+}) {
+  return {
+    schema_version: '1.0',
+    product: 'spotter',
+    version,
+    overall_status: overallStatus,
+    marker_schema_version: markerSchemaVersion,
+    throughline_context: throughlineContext,
+    catalogs,
+    codex_hook_readiness: codexHookReadiness,
+    runtime_error_store: runtimeErrorStore,
+    checks,
+  };
+}
+
+async function readMarker(path) {
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (error) {
+    return error?.code === 'ENOENT'
+      ? { status: 'missing' }
+      : { status: 'unverified', reasonCode: 'marker_unreadable' };
+  }
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      return { status: 'unverified', reasonCode: 'marker_invalid_shape' };
+    }
+    return { status: 'valid', value };
+  } catch {
+    return { status: 'unverified', reasonCode: 'marker_invalid_json' };
+  }
+}
+
+async function inspectCatalog(path) {
+  try {
+    await access(path);
+  } catch (error) {
+    return error?.code === 'ENOENT'
+      ? { publicStatus: 'missing', checkStatus: 'skipped', reasonCode: 'catalog_missing' }
+      : { publicStatus: 'unverified', checkStatus: 'unverified', reasonCode: 'catalog_unreadable' };
+  }
+  try {
+    await loadDb(path);
+    return { publicStatus: 'available', checkStatus: 'pass' };
+  } catch {
+    return { publicStatus: 'invalid', checkStatus: 'fail', reasonCode: 'catalog_invalid_schema' };
+  }
+}
+
+function safeContextMode(config) {
+  if (config === undefined) return 'disabled';
+  return config && typeof config === 'object' && SAFE_CONTEXT_MODES.has(config.mode)
+    ? config.mode
+    : null;
+}
+
+function check(checkId, status, reasonCode) {
+  return reasonCode
+    ? { check_id: checkId, status, reason_code: reasonCode }
+    : { check_id: checkId, status };
+}
+
+function overallStatus(checks) {
+  if (checks.some((entry) => entry.status === 'fail')) return 'fail';
+  if (checks.some((entry) => entry.status === 'unverified')) return 'unverified';
+  return 'pass';
+}