throughline 0.6.0 → 0.6.2

package/src/cli/auditor-context.mjs

@@ -0,0 +1,141 @@
+import {
+  AUDITOR_CONTEXT_SCHEMA,
+  deriveAuditorFreshnessExpectation,
+  readAuditorContext,
+} from '../auditor-context.mjs';
+
+const ERROR_SCHEMA = AUDITOR_CONTEXT_SCHEMA;
+const ARGS_ERROR = {
+  schema: ERROR_SCHEMA,
+  status: 'error',
+  code: 'E_AUDITOR_CONTEXT_ARGS',
+  message: 'invalid auditor-context arguments',
+};
+const INTERNAL_ERROR = {
+  schema: ERROR_SCHEMA,
+  status: 'error',
+  code: 'E_AUDITOR_CONTEXT_INTERNAL',
+  message: 'auditor context could not be read',
+};
+
+export function parseArgs(argv = []) {
+  const out = {
+    sessionId: null,
+    projectRoot: null,
+    expectedOriginSessionId: null,
+    expectedTurnNumber: null,
+    expectedUserSha256: null,
+    expectedAssistantSha256: null,
+    recentTurns: undefined,
+    maxBodyChars: undefined,
+    maxTotalChars: undefined,
+    dbPath: undefined,
+    host: null,
+    transcriptPath: null,
+    json: false,
+  };
+
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--json') {
+      out.json = true;
+      continue;
+    }
+    const value = argv[++index];
+    if (!value || value.startsWith('-')) throw new TypeError('missing option value');
+    if (arg === '--session') out.sessionId = value;
+    else if (arg === '--project') out.projectRoot = value;
+    else if (arg === '--expected-origin-session') out.expectedOriginSessionId = value;
+    else if (arg === '--expected-turn-number') out.expectedTurnNumber = parseNonNegativeInteger(value);
+    else if (arg === '--expected-user-sha256') out.expectedUserSha256 = parseSha256(value);
+    else if (arg === '--expected-assistant-sha256') out.expectedAssistantSha256 = parseSha256(value);
+    else if (arg === '--recent-turns') out.recentTurns = parsePositiveInteger(value);
+    else if (arg === '--max-body-chars') out.maxBodyChars = parsePositiveInteger(value);
+    else if (arg === '--max-total-chars') out.maxTotalChars = parsePositiveInteger(value);
+    else if (arg === '--db') out.dbPath = value;
+    else if (arg === '--host' && (value === 'claude' || value === 'codex')) out.host = value;
+    else if (arg === '--transcript') out.transcriptPath = value;
+    else throw new TypeError('unknown option');
+  }
+
+  if (
+    !out.json ||
+    !out.sessionId ||
+    !out.projectRoot ||
+    !hasFreshnessSource(out)
+  ) {
+    throw new TypeError('missing required option');
+  }
+  return out;
+}
+
+export function run(argv = [], {
+  read = readAuditorContext,
+  deriveExpectation = deriveAuditorFreshnessExpectation,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch {
+    writeJson(stderr, ARGS_ERROR);
+    return 1;
+  }
+
+  try {
+    const derived = args.host
+      ? deriveExpectation({ host: args.host, transcriptPath: args.transcriptPath, sessionId: args.sessionId })
+      : null;
+    const result = read({
+      dbPath: args.dbPath,
+      sessionId: args.sessionId,
+      projectRoot: args.projectRoot,
+      expectedOriginSessionId: derived?.expectedOriginSessionId ?? args.expectedOriginSessionId,
+      expectedTurnNumber: derived?.expectedTurnNumber ?? args.expectedTurnNumber,
+      expectedUserSha256: derived?.expectedUserSha256 ?? args.expectedUserSha256,
+      expectedAssistantSha256: derived?.expectedAssistantSha256 ?? args.expectedAssistantSha256,
+      recentTurns: args.recentTurns,
+      maxBodyChars: args.maxBodyChars,
+      maxTotalChars: args.maxTotalChars,
+    });
+    writeJson(stdout, result);
+    return 0;
+  } catch {
+    writeJson(stderr, INTERNAL_ERROR);
+    return 1;
+  }
+}
+
+function hasFreshnessSource(args) {
+  const hasTranscript = Boolean(args.host && args.transcriptPath);
+  const hasExplicitPair = Boolean(
+    args.expectedOriginSessionId &&
+    args.expectedTurnNumber !== null &&
+    args.expectedUserSha256 &&
+    args.expectedAssistantSha256
+  );
+  return hasTranscript !== hasExplicitPair;
+}
+
+function parseNonNegativeInteger(value) {
+  if (!/^\d+$/.test(value)) throw new TypeError('invalid integer');
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new TypeError('invalid integer');
+  return parsed;
+}
+
+function parsePositiveInteger(value) {
+  const parsed = parseNonNegativeInteger(value);
+  if (parsed < 1) throw new TypeError('invalid integer');
+  return parsed;
+}
+
+function parseSha256(value) {
+  if (!/^[a-fA-F0-9]{64}$/.test(value)) throw new TypeError('invalid hash');
+  return value.toLowerCase();
+}
+
+function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value)}\n`);
+}

package/src/cli/auditor-context.test.mjs

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from 'node:sqlite';
+import test from 'node:test';
+
+import { AUDITOR_CONTEXT_SCHEMA, hashAuditorBody } from '../auditor-context.mjs';
+import { run } from './auditor-context.mjs';
+
+const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const USER = 'auditor user body';
+const ASSISTANT = 'auditor assistant body';
+
+function makeDb({ originSessionId = 'origin-1' } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-auditor-cli-'));
+  const path = join(dir, 'throughline.db');
+  const db = new DatabaseSync(path);
+  db.exec(`
+    PRAGMA user_version = 8;
+    CREATE TABLE sessions (session_id TEXT PRIMARY KEY, project_path TEXT NOT NULL);
+    CREATE TABLE bodies (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, origin_session_id TEXT NOT NULL, turn_number INTEGER NOT NULL, role TEXT NOT NULL, text TEXT NOT NULL, created_at INTEGER NOT NULL);
+    INSERT INTO sessions VALUES ('session-1', '/repo');
+    INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES ('session-1', '${originSessionId}', 3, 'user', '${USER}', 1);
+    INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES ('session-1', '${originSessionId}', 3, 'assistant', '${ASSISTANT}', 2);
+  `);
+  db.close();
+  return { dir, path };
+}
+
+function args(path) {
+  return [
+    'auditor-context', '--session', 'session-1', '--project', '/repo', '--expected-origin-session', 'origin-1',
+    '--expected-turn-number', '3', '--expected-user-sha256', hashAuditorBody(USER),
+    '--expected-assistant-sha256', hashAuditorBody(ASSISTANT), '--db', path, '--json',
+  ];
+}
+
+test('auditor-context CLI prints only fresh JSON to stdout', () => {
+  const { dir, path } = makeDb();
+  try {
+    const result = spawnSync(process.execPath, [BIN_PATH, ...args(path)], { cwd: REPO_ROOT, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr, '');
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.schema, AUDITOR_CONTEXT_SCHEMA);
+    assert.equal(output.status, 'fresh');
+    assert.equal(output.turns[0].user, USER);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('auditor-context CLI transcript freshness mode derives a fresh Claude pair', () => {
+  const { dir, path } = makeDb({ originSessionId: 'session-1' });
+  const transcript = join(dir, 'claude.jsonl');
+  try {
+    writeFileSync(transcript, [
+      claudeRow('user', 'earlier request'),
+      claudeRow('assistant', 'earlier answer'),
+      claudeRow('user', USER),
+      claudeRow('assistant', ASSISTANT),
+    ].map(JSON.stringify).join('\n'));
+    const result = spawnSync(process.execPath, [
+      BIN_PATH, 'auditor-context', '--session', 'session-1', '--project', '/repo', '--host', 'claude',
+      '--transcript', transcript, '--db', path, '--json',
+    ], { cwd: REPO_ROOT, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr, '');
+    assert.equal(JSON.parse(result.stdout).status, 'fresh');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('auditor-context CLI rejects mixed and partial freshness sources with the fixed args error', () => {
+  const transcript = '/tmp/auditor-context-transcript.jsonl';
+  const base = ['--session', 's', '--project', '/p', '--json'];
+  const explicit = [
+    '--expected-origin-session', 'origin', '--expected-turn-number', '1',
+    '--expected-user-sha256', 'a'.repeat(64), '--expected-assistant-sha256', 'b'.repeat(64),
+  ];
+  const transcriptSource = ['--host', 'claude', '--transcript', transcript];
+  for (const argv of [
+    [...base, ...explicit, ...transcriptSource],
+    [...base, '--host', 'claude'],
+    [...base, '--transcript', transcript],
+    [...base, '--expected-origin-session', 'origin'],
+  ]) {
+    const stderr = { text: '', write(value) { this.text += value; } };
+    const stdout = { text: '', write(value) { this.text += value; } };
+    assert.equal(run(argv, { stdout, stderr }), 1);
+    assert.equal(stdout.text, '');
+    assert.deepEqual(JSON.parse(stderr.text), {
+      schema: AUDITOR_CONTEXT_SCHEMA, status: 'error', code: 'E_AUDITOR_CONTEXT_ARGS', message: 'invalid auditor-context arguments',
+    });
+  }
+});
+
+test('auditor-context CLI transcript parse failures use fixed JSON without leaking transcript path or body', () => {
+  const transcript = '/private/path/with-secret-body.jsonl';
+  const stderr = { text: '', write(value) { this.text += value; } };
+  const stdout = { text: '', write(value) { this.text += value; } };
+  const argv = ['--session', 's', '--project', '/p', '--host', 'codex', '--transcript', transcript, '--json'];
+  assert.equal(run(argv, {
+    deriveExpectation: () => { throw new Error(`parse failure ${transcript} ${USER}`); },
+    stdout,
+    stderr,
+  }), 1);
+  assert.equal(stdout.text, '');
+  assert.deepEqual(JSON.parse(stderr.text), {
+    schema: AUDITOR_CONTEXT_SCHEMA, status: 'error', code: 'E_AUDITOR_CONTEXT_INTERNAL', message: 'auditor context could not be read',
+  });
+  assert.doesNotMatch(stderr.text, /private|secret|auditor user|jsonl/i);
+});
+
+test('auditor-context CLI returns fixed JSON errors without raw body, hash, DB, or thrown error text', () => {
+  const stderr = { text: '', write(value) { this.text += value; } };
+  const stdout = { text: '', write(value) { this.text += value; } };
+  assert.equal(run(['--session', 'only'], { stdout, stderr }), 1);
+  assert.equal(stdout.text, '');
+  assert.deepEqual(JSON.parse(stderr.text), {
+    schema: AUDITOR_CONTEXT_SCHEMA, status: 'error', code: 'E_AUDITOR_CONTEXT_ARGS', message: 'invalid auditor-context arguments',
+  });
+
+  stderr.text = '';
+  assert.equal(run(['--session', 's', '--project', '/p', '--expected-origin-session', 'o', '--expected-turn-number', '1', '--expected-user-sha256', 'a'.repeat(64), '--expected-assistant-sha256', 'b'.repeat(64), '--json'], {
+    read: () => { throw new Error(`private ${USER} ${hashAuditorBody(USER)} /secret.db`); }, stdout, stderr,
+  }), 1);
+  assert.deepEqual(JSON.parse(stderr.text), {
+    schema: AUDITOR_CONTEXT_SCHEMA, status: 'error', code: 'E_AUDITOR_CONTEXT_INTERNAL', message: 'auditor context could not be read',
+  });
+  assert.doesNotMatch(stderr.text, /private|secret|auditor user|[a-f0-9]{64}/i);
+});
+
+test('auditor-context bin dispatch and help advertise the JSON-only command', () => {
+  const help = spawnSync(process.execPath, [BIN_PATH, '--help'], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(help.status, 0, help.stderr);
+  assert.match(help.stdout, /throughline auditor-context --session <id> --project <root>/);
+  assert.match(help.stdout, /always requires --json/);
+});
+
+function claudeRow(role, text) {
+  return { type: role, message: { role, content: [{ type: 'text', text }] } };
+}

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() {
@@ -88,6 +89,21 @@ async function captureCodexHookSession({
   buildMonitorUsage = null,
   summarize = true,
 } = {}) {
+  if (isSpotterChildEnvironment(env)) {
+    return {
+      status: 'skipped',
+      reason: 'spotter_child_backend',
+      db,
+      identity: null,
+      projectPath: null,
+      codexHome: null,
+      captured: null,
+      summarized: null,
+      monitorState: null,
+      usage: null,
+    };
+  }
+
   const [
     { getDb },
     { captureCodexRolloutToDb },
@@ -202,6 +218,11 @@ async function captureCodexHookSession({
   };
 }
 
+function isSpotterChildEnvironment(env = {}) {
+  return ['SPOTTER_PARENT_PID', 'SPOTTER_BACKEND', 'SPOTTER_CHILD_BACKEND']
+    .some((name) => typeof env?.[name] === 'string' && env[name].length > 0);
+}
+
 export async function runCodexStopHook({
   args = {},
   payload = {},
@@ -346,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);
@@ -379,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;
+  }
+}