throughline 0.6.1 → 0.6.3

package/src/cli/factory-diagnostics.mjs

@@ -0,0 +1,248 @@
+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('unverified')
+          ? 'unverified'
+          : values.includes('ready')
+            ? 'ready'
+            : '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;
+  }
+}

package/src/cli/factory-diagnostics.test.mjs

@@ -0,0 +1,226 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  collectFactoryDiagnostics,
+  inspectFactoryDatabase,
+  inspectFactoryHooks,
+  parseArgs,
+  run,
+} from './factory-diagnostics.mjs';
+
+test('factory-diagnostics CLI: JSON-only contract and schema fixture', () => {
+  const output = [];
+  const exitCode = run(['--json'], {
+    stdout: { write(value) { output.push(value); } },
+    version: '0.6.1',
+    inspectThread: () => ({ status: 'ready', rolloutAvailable: true }),
+    inspectDatabase: () => ({ status: 'ready', schemaVersion: 8, handoffMemory: true }),
+    inspectHooks: () => ({
+      status: 'ready',
+      claudeStatus: 'ready',
+      events: { userPromptSubmit: 'ready', postToolUse: 'ready', stop: 'ready' },
+    }),
+  });
+
+  assert.equal(exitCode, 0);
+  assert.equal(output.length, 1);
+  const parsed = JSON.parse(output[0]);
+  assert.equal(parsed.schema, 'throughline.native_factory_diagnostics.v1');
+  assert.equal(parsed.version, '0.6.1');
+  assert.equal(parsed.readiness.restore.status, 'ready');
+  assert.equal(parsed.evidence.restoreSmoke.status, 'unverified');
+});
+
+test('factory-diagnostics CLI: invalid request is a fixed JSON error', () => {
+  const output = [];
+  const exitCode = run(['--project', '/secret/path'], {
+    stdout: { write(value) { output.push(value); } },
+  });
+
+  assert.equal(exitCode, 2);
+  assert.equal(output.length, 1);
+  const parsed = JSON.parse(output[0]);
+  assert.equal(parsed.error, 'invalid_diagnostics_request');
+  assert.doesNotMatch(output[0], /secret\/path/);
+  assert.throws(() => parseArgs([]), /usage error/);
+  assert.throws(() => parseArgs(['--json', '--json']), /usage error/);
+});
+
+test('factory-diagnostics CLI: internal failure is not reported as a usage error', () => {
+  const output = [];
+  const exitCode = run(['--json'], {
+    stdout: { write(value) { output.push(value); } },
+    inspectThread: () => { throw new Error('/secret/internal'); },
+  });
+
+  assert.equal(exitCode, 1);
+  assert.equal(JSON.parse(output[0]).error, 'diagnostics_internal_error');
+  assert.doesNotMatch(output[0], /secret|internal\//);
+});
+
+test('factory-diagnostics CLI: unverified inspection remains unverified', () => {
+  const result = collectFactoryDiagnostics({
+    version: '0.6.1',
+    inspectThread: () => ({ status: 'unverified', rolloutAvailable: false }),
+    inspectDatabase: () => ({ status: 'unverified', schemaVersion: null, handoffMemory: false }),
+    inspectHooks: () => ({ status: 'unverified', claudeStatus: 'unverified', events: {} }),
+  });
+
+  assert.equal(result.overall.status, 'unverified');
+  assert.equal(result.readiness.capture.status, 'unverified');
+  assert.equal(result.readiness.handoff.status, 'unverified');
+  assert.throws(() => parseArgs(['--bad']), /usage error/);
+});
+
+test('factory-diagnostics DB inspection is read-only and does not create an absent DB', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-factory-diagnostics-'));
+  const dbPath = join(dir, 'throughline.db');
+  const missingPath = join(dir, 'missing.db');
+  try {
+    const db = new DatabaseSync(dbPath);
+    createFactorySchema(db);
+    db.close();
+    const before = statSync(dbPath).mtimeMs;
+
+    const result = inspectFactoryDatabase({ dbPath, threadId: 'thread-1' });
+    assert.equal(result.status, 'ready');
+    assert.equal(result.handoffMemory, false);
+    assert.equal(statSync(dbPath).mtimeMs, before);
+
+    const writer = new DatabaseSync(dbPath);
+    writer.exec(`
+      INSERT INTO sessions VALUES ('codex:thread-1', '/project/a', 'active', 1, 1, NULL);
+      INSERT INTO skeletons VALUES (1, 'codex:thread-1', 1, 'assistant', 'safe', 1, 'codex:thread-1');
+    `);
+    writer.close();
+    const matching = inspectFactoryDatabase({ dbPath, threadId: 'thread-1', projectPath: '/project/a' });
+    const mismatch = inspectFactoryDatabase({ dbPath, threadId: 'thread-1', projectPath: '/project/b' });
+    assert.equal(matching.handoffMemory, true);
+    assert.equal(mismatch.handoffMemory, false);
+
+    const missing = inspectFactoryDatabase({ dbPath: missingPath });
+    assert.equal(missing.status, 'not_applicable');
+    assert.equal(existsSync(missingPath), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('factory-diagnostics DB inspection rejects version-only fake schema', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-factory-fake-schema-'));
+  const dbPath = join(dir, 'throughline.db');
+  try {
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA user_version = 8; CREATE TABLE sessions (session_id TEXT)');
+    db.close();
+    assert.equal(inspectFactoryDatabase({ dbPath }).status, 'not_ready');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('factory-diagnostics DB inspection rejects missing runtime constraints', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-factory-fake-constraint-'));
+  const dbPath = join(dir, 'throughline.db');
+  try {
+    const db = new DatabaseSync(dbPath);
+    createFactorySchema(db);
+    db.exec(`
+      DROP TABLE handoff_batons;
+      CREATE TABLE handoff_batons (project_path TEXT, session_id TEXT NOT NULL, created_at INTEGER NOT NULL);
+    `);
+    db.close();
+    assert.equal(inspectFactoryDatabase({ dbPath }).status, 'not_ready');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('factory-diagnostics hook inspection rejects corrupt and false-ready shapes', () => {
+  const corrupt = inspectFactoryHooks({
+    readHooks: () => ({ configExists: true, configReadable: false, hooksExists: true, hooksReadable: false }),
+  });
+  assert.equal(corrupt.status, 'unverified');
+
+  const malformed = inspectFactoryHooks({
+    readHooks: () => ({
+      configExists: true,
+      configReadable: true,
+      hooksExists: true,
+      hooksReadable: true,
+      featureEnabled: true,
+      expectedPromptCommand: 'prompt',
+      expectedPostToolUseCommand: 'post',
+      expectedStopCommand: 'stop',
+      managedPromptHooks: [{ type: 'command', command: 'prompt', timeoutSec: 30, async: true }],
+      legacyManagedPromptHooks: [],
+      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeoutSec: 30, async: false }],
+      legacyManagedPostToolUseHooks: [],
+      managedStopHooks: [{ type: 'command', command: 'stop', timeoutSec: 300, async: false }],
+      legacyManagedStopHooks: [],
+    }),
+  });
+  assert.equal(malformed.status, 'not_ready');
+});
+
+test('factory-diagnostics hook inspection summarizes every canonical ready event as ready', () => {
+  const result = inspectFactoryHooks({
+    readHooks: () => ({
+      configExists: true,
+      configReadable: true,
+      hooksExists: true,
+      hooksReadable: true,
+      featureEnabled: true,
+      expectedPromptCommand: 'prompt',
+      expectedPostToolUseCommand: 'post',
+      expectedStopCommand: 'stop',
+      managedPromptHooks: [{ type: 'command', command: 'prompt', timeoutSec: 30, async: false }],
+      legacyManagedPromptHooks: [],
+      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeoutSec: 30, async: false }],
+      legacyManagedPostToolUseHooks: [],
+      managedStopHooks: [{ type: 'command', command: 'stop', timeoutSec: 300, async: false }],
+      legacyManagedStopHooks: [],
+    }),
+  });
+
+  assert.deepEqual(result.events, { userPromptSubmit: 'ready', postToolUse: 'ready', stop: 'ready' });
+  assert.equal(result.status, 'ready');
+  assert.equal(result.reason, 'hooks_inspected');
+});
+
+function createFactorySchema(db) {
+  db.exec(`
+    PRAGMA user_version = 8;
+    CREATE TABLE sessions (
+      session_id TEXT PRIMARY KEY, project_path TEXT NOT NULL, status TEXT NOT NULL,
+      created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, merged_into TEXT
+    );
+    CREATE TABLE skeletons (
+      id INTEGER, session_id TEXT, turn_number INTEGER, role TEXT, summary TEXT,
+      created_at INTEGER, origin_session_id TEXT
+    );
+    CREATE TABLE bodies (
+      id INTEGER, session_id TEXT, origin_session_id TEXT, turn_number INTEGER,
+      role TEXT, text TEXT, token_count INTEGER, created_at INTEGER,
+      UNIQUE(session_id, origin_session_id, turn_number, role)
+    );
+    CREATE TABLE details (
+      id INTEGER, session_id TEXT, turn_number INTEGER, tool_name TEXT,
+      input_text TEXT, output_text TEXT, token_count INTEGER, created_at INTEGER,
+      origin_session_id TEXT, kind TEXT, source_id TEXT
+    );
+    CREATE TABLE handoff_batons (
+      project_path TEXT PRIMARY KEY, session_id TEXT NOT NULL, created_at INTEGER NOT NULL
+    );
+    CREATE UNIQUE INDEX uq_skeletons_turn_v3
+      ON skeletons(session_id, origin_session_id, turn_number, role);
+    CREATE UNIQUE INDEX uq_details_source
+      ON details(session_id, origin_session_id, source_id)
+      WHERE source_id IS NOT NULL;
+  `);
+}

package/src/cli/runtime-errors.mjs

@@ -0,0 +1,85 @@
+import {
+  acknowledgeRuntimeErrors,
+  compactRuntimeErrors,
+  getRuntimeErrorDiagnostics,
+  readRuntimeErrorSnapshot,
+  reopenRuntimeError,
+  resolveRuntimeError,
+} from '../runtime-error-store.mjs';
+
+const USAGE = 'usage: throughline runtime-errors <snapshot|diagnostics|ack|resolve|reopen|compact> [arguments] --json';
+
+export function parseArgs(argv = []) {
+  const command = argv[0];
+  if (!['snapshot', 'diagnostics', 'ack', 'resolve', 'reopen', 'compact'].includes(command)) {
+    throw new TypeError(USAGE);
+  }
+  const options = { command, json: false, afterCursor: 0, limit: 256, value: null };
+  for (let index = 1; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--json' && !options.json) {
+      options.json = true;
+    } else if (command === 'snapshot' && arg === '--after-cursor' && argv[index + 1]) {
+      options.afterCursor = parseInteger(argv[++index], '--after-cursor');
+    } else if (command === 'snapshot' && arg === '--limit' && argv[index + 1]) {
+      options.limit = parseInteger(argv[++index], '--limit');
+    } else if (['ack', 'resolve', 'reopen'].includes(command) && options.value === null && !arg.startsWith('-')) {
+      options.value = arg;
+    } else {
+      throw new TypeError(USAGE);
+    }
+  }
+  if (!options.json || (['ack', 'resolve', 'reopen'].includes(command) && options.value === null)) {
+    throw new TypeError(USAGE);
+  }
+  return options;
+}
+
+export function run(argv = [], dependencies = {}) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch {
+    process.stderr.write(`[runtime-errors] ${USAGE}\n`);
+    return 2;
+  }
+
+  try {
+    const env = dependencies.env ?? process.env;
+    let result;
+    if (options.command === 'snapshot') {
+      result = (dependencies.readSnapshot ?? readRuntimeErrorSnapshot)({
+        env,
+        afterCursor: options.afterCursor,
+        limit: options.limit,
+      });
+    } else if (options.command === 'diagnostics') {
+      result = (dependencies.getDiagnostics ?? getRuntimeErrorDiagnostics)({ env });
+    } else if (options.command === 'ack') {
+      result = (dependencies.acknowledge ?? acknowledgeRuntimeErrors)(
+        parseInteger(options.value, 'cursor'),
+        { env },
+      );
+    } else if (options.command === 'resolve') {
+      result = (dependencies.resolve ?? resolveRuntimeError)(options.value, { env });
+    } else if (options.command === 'reopen') {
+      result = (dependencies.reopen ?? reopenRuntimeError)(options.value, { env });
+    } else {
+      result = (dependencies.compact ?? compactRuntimeErrors)({ env });
+    }
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch {
+    process.stderr.write('[runtime-errors] operation_failed\n');
+    return 1;
+  }
+}
+
+function parseInteger(value, name) {
+  if (typeof value !== 'string' || !/^\d+$/.test(value)) throw new TypeError(`${name} invalid`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new TypeError(`${name} invalid`);
+  return parsed;
+}
+
+export const _internal = { USAGE };

package/src/cli/runtime-errors.test.mjs

@@ -0,0 +1,75 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseArgs, run } from './runtime-errors.mjs';
+import { defaultFactoryReporterConfigPath } from '../runtime-error-store.mjs';
+import { applyWindowsPrivateAcl } from '../windows-acl-test-helper.mjs';
+
+test('runtime-errors CLI: strict command surface accepts no raw payload options', () => {
+  assert.deepEqual(parseArgs(['snapshot', '--after-cursor', '2', '--limit', '3', '--json']), {
+    command: 'snapshot', json: true, afterCursor: 2, limit: 3, value: null,
+  });
+  assert.equal(parseArgs(['reopen', 'a'.repeat(64), '--json']).command, 'reopen');
+  for (const args of [
+    ['snapshot', '--stderr', 'secret', '--json'],
+    ['snapshot', '--path', '/Users/private', '--json'],
+    ['resolve', 'abc', '--context', 'secret', '--json'],
+    ['diagnostics'],
+  ]) assert.throws(() => parseArgs(args));
+});
+
+test('runtime-errors CLI: internal failure is fixed and does not reflect exceptions or paths', () => {
+  const writes = { stdout: '', stderr: '' };
+  const originalOut = process.stdout.write;
+  const originalErr = process.stderr.write;
+  process.stdout.write = (chunk) => { writes.stdout += chunk; return true; };
+  process.stderr.write = (chunk) => { writes.stderr += chunk; return true; };
+  try {
+    const exitCode = run(['snapshot', '--json'], {
+      readSnapshot() { throw new Error('secret /Users/private stack'); },
+    });
+    assert.equal(exitCode, 1);
+  } finally {
+    process.stdout.write = originalOut;
+    process.stderr.write = originalErr;
+  }
+  assert.equal(writes.stdout, '');
+  assert.equal(writes.stderr, '[runtime-errors] operation_failed\n');
+});
+
+test('runtime-errors CLI: snapshot and diagnostics are JSON-only and contain no state path', () => {
+  const root = mkdtempSync(join(tmpdir(), 'throughline-runtime-cli-'));
+  const env = {
+    ...process.env,
+    HOME: root,
+    USERPROFILE: root,
+    LOCALAPPDATA: root,
+    XDG_CONFIG_HOME: join(root, 'config'),
+    XDG_STATE_HOME: join(root, 'state'),
+  };
+  const configPath = defaultFactoryReporterConfigPath(env);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify({
+    schema_version: '1.0',
+    host: { id: 'test-host', profile: process.platform === 'win32' ? 'windows-native' : 'mac' },
+    collection: { enabled: true },
+    reporting: { enabled: false },
+  }));
+  applyWindowsPrivateAcl(configPath);
+  const bin = new URL('../../bin/throughline.mjs', import.meta.url);
+  for (const args of [
+    ['runtime-errors', 'snapshot', '--json'],
+    ['runtime-errors', 'diagnostics', '--json'],
+  ]) {
+    const result = spawnSync(process.execPath, [fileURLToPath(bin), ...args], { env, encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr);
+    const json = JSON.parse(result.stdout);
+    assert.equal(typeof json.schema, 'string');
+    assert.doesNotMatch(result.stdout, new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+  }
+});

package/src/cli/trim.mjs

@@ -164,11 +164,11 @@ export async function run(args) {
     } else {
       process.stdout.write(renderTrimActionReport(result) + '\n');
     }
-    process.exit(
+    process.exitCode =
       result.status === 'preflight-ready' || result.status === 'execute-durable-verified'
         ? 0
-        : 1,
-    );
+        : 1;
+    return;
   }
 
   if (parsed.json) {
@@ -177,7 +177,7 @@ export async function run(args) {
     process.stdout.write(renderTrimDryRunReport(plan) + '\n');
   }
 
-  process.exit(plan.status === 'unavailable' ? 1 : 0);
+  process.exitCode = plan.status === 'unavailable' ? 1 : 0;
 }
 
 async function runExecute(parsed, plan) {

package/src/codex-handoff-model-smoke.mjs

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawnPortableSync } from './portable-spawn-sync.mjs';
 
 export const CODEX_HANDOFF_MODEL_SMOKE_ENV = 'THROUGHLINE_EXPERIMENTAL_CODEX_HANDOFF_MODEL_SMOKE';
 export const DEFAULT_CODEX_HANDOFF_MODEL_SMOKE_TIMEOUT_MS = 120_000;
@@ -48,7 +48,7 @@ export function runCodexHandoffModelSmoke({
   assertNonEmptyString(command, 'command');
   assertPositiveInteger(timeoutMs, 'timeoutMs');
 
-  const result = spawnSync(
+  const result = spawnPortableSync(
     command,
     [
       'exec',
@@ -65,7 +65,6 @@ export function runCodexHandoffModelSmoke({
     {
       encoding: 'utf8',
       timeout: timeoutMs,
-      shell: process.platform === 'win32',
       env,
       cwd,
     },