throughline 0.6.0 → 0.6.1

package/src/auditor-context.test.mjs

@@ -0,0 +1,296 @@
+import assert from 'node:assert/strict';
+import { existsSync, lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { DatabaseSync } from 'node:sqlite';
+
+import {
+  AUDITOR_CONTEXT_SCHEMA,
+  deriveAuditorFreshnessExpectation,
+  hashAuditorBody,
+  readAuditorContext,
+} from './auditor-context.mjs';
+
+function withDb(fn, { version = 8 } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-auditor-context-'));
+  const path = join(dir, 'throughline.db');
+  const db = new DatabaseSync(path);
+  db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA user_version = ${version};
+    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
+    );
+  `);
+  try {
+    return fn({ db, path, dir });
+  } finally {
+    db.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function seedSession(db, { sessionId = 'session-1', projectPath = '/repo', pairs = [] } = {}) {
+  db.prepare('INSERT INTO sessions (session_id, project_path) VALUES (?, ?)').run(sessionId, projectPath);
+  let createdAt = 1;
+  for (const pair of pairs) {
+    for (const [role, text] of [['user', pair.user], ['assistant', pair.assistant]]) {
+      db.prepare(
+        'INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)',
+      ).run(sessionId, pair.originSessionId, pair.turnNumber, role, text, createdAt++);
+    }
+  }
+}
+
+function expected(pair) {
+  return {
+    expectedOriginSessionId: pair.originSessionId,
+    expectedTurnNumber: pair.turnNumber,
+    expectedUserSha256: hashAuditorBody(pair.user),
+    expectedAssistantSha256: hashAuditorBody(pair.assistant),
+  };
+}
+
+function read(path, pair, extra = {}) {
+  return readAuditorContext({
+    dbPath: path,
+    sessionId: 'session-1',
+    projectRoot: '/repo',
+    ...expected(pair),
+    ...extra,
+  });
+}
+
+test('readAuditorContext: returns a fresh completed pair with canonical origin identity', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 4, user: ' ask\r\n', assistant: ' answer\r\n' };
+    seedSession(db, { pairs: [pair] });
+
+    const result = read(path, pair);
+    assert.equal(result.schema, AUDITOR_CONTEXT_SCHEMA);
+    assert.equal(result.status, 'fresh');
+    assert.equal(result.reason, 'latest_pair_matched');
+    assert.deepEqual(result.turns, [
+      { originSessionId: 'origin-a', turnNumber: 4, user: 'ask', assistant: 'answer', createdAt: 2 },
+    ]);
+    assert.deepEqual(result.freshness, {
+      originSessionId: 'origin-a', turnNumber: 4, identityMatched: true, userMatched: true, assistantMatched: true,
+    });
+  });
+});
+
+test('readAuditorContext: pair identity or hash mismatch is stale', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 4, user: 'ask', assistant: 'answer' };
+    seedSession(db, { pairs: [pair] });
+
+    for (const extra of [
+      { expectedOriginSessionId: 'origin-other' },
+      { expectedTurnNumber: 5 },
+      { expectedUserSha256: hashAuditorBody('other') },
+      { expectedAssistantSha256: hashAuditorBody('other') },
+    ]) {
+      const result = read(path, pair, extra);
+      assert.equal(result.status, 'stale');
+      assert.equal(result.reason, 'latest_pair_mismatch');
+      assert.deepEqual(result.turns, []);
+    }
+  });
+});
+
+test('readAuditorContext: returns empty for no complete pair and excludes developer/L3 roles', () => {
+  withDb(({ db, path }) => {
+    seedSession(db);
+    db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+      .run('session-1', 'origin-a', 1, 'developer', 'secret developer context', 1);
+    db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+      .run('session-1', 'origin-a', 1, 'user', 'unpaired request', 2);
+    const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'unpaired request', assistant: 'missing' };
+
+    const result = read(path, pair);
+    assert.equal(result.status, 'empty');
+    assert.equal(result.reason, 'completed_pair_not_found');
+    assert.deepEqual(result.turns, []);
+  });
+});
+
+test('readAuditorContext: reports project mismatch without exposing rows', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'private', assistant: 'private reply' };
+    seedSession(db, { projectPath: '/other-project', pairs: [pair] });
+    const result = read(path, pair);
+    assert.equal(result.status, 'session_mismatch');
+    assert.equal(result.reason, 'project_mismatch');
+    assert.deepEqual(result.turns, []);
+  });
+});
+
+test('readAuditorContext: applies recent-turn, body, and total bounds from the newest pairs', () => {
+  withDb(({ db, path }) => {
+    const old = { originSessionId: 'origin-a', turnNumber: 1, user: 'old user', assistant: 'old assistant' };
+    const latest = { originSessionId: 'origin-a', turnNumber: 2, user: 'abcdef', assistant: 'uvwxyz' };
+    seedSession(db, { pairs: [old, latest] });
+    const result = read(path, latest, { recentTurns: 1, maxBodyChars: 4, maxTotalChars: 5 });
+    assert.equal(result.status, 'fresh');
+    assert.deepEqual(result.turns, [
+      { originSessionId: 'origin-a', turnNumber: 2, user: 'ef', assistant: 'xyz', createdAt: 4 },
+    ]);
+    assert.deepEqual(result.stats, { requestedTurns: 1, returnedTurns: 1, chars: 5, truncated: true });
+  });
+});
+
+test('readAuditorContext: reports schema mismatch and missing DB as exit-safe JSON states', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'u', assistant: 'a' };
+    seedSession(db, { pairs: [pair] });
+    const mismatched = read(path, pair);
+    assert.equal(mismatched.status, 'schema_mismatch');
+    assert.equal(mismatched.reason, 'unsupported_db_schema');
+  }, { version: 7 });
+
+  const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'u', assistant: 'a' };
+  const missing = read('/definitely-missing-throughline-auditor-context.db', pair);
+  assert.equal(missing.status, 'unavailable');
+  assert.equal(missing.reason, 'db_not_found');
+});
+
+test('readAuditorContext: opens a live WAL database read-only without changing DB, -wal, or -shm', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'u', assistant: 'a' };
+    seedSession(db, { pairs: [pair] });
+    db.exec('BEGIN IMMEDIATE');
+    const before = snapshotSqliteFiles(path);
+    const result = read(path, pair);
+    assert.equal(result.status, 'fresh');
+    assert.deepEqual(snapshotSqliteFiles(path), before);
+    db.exec('ROLLBACK');
+  });
+});
+
+test('readAuditorContext: classifies an exclusive database lock without exposing SQLite diagnostics', () => {
+  withDb(({ db, path }) => {
+    const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'u', assistant: 'a' };
+    seedSession(db, { pairs: [pair] });
+    db.exec('PRAGMA journal_mode = DELETE; BEGIN EXCLUSIVE');
+    try {
+      assert.throws(
+        () => read(path, pair),
+        (error) => {
+          assert.equal(error.code, 'E_AUDITOR_CONTEXT_QUERY');
+          assert.equal(error.message, 'auditor context query failed');
+          assert.equal(error.message.includes('locked'), false);
+          return true;
+        },
+      );
+    } finally {
+      db.exec('ROLLBACK');
+    }
+  });
+});
+
+test('deriveAuditorFreshnessExpectation: Claude logical groups use the latest representative fragment and session origin', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-auditor-claude-transcript-'));
+  const transcript = join(dir, 'session.jsonl');
+  try {
+    writeFileSync(transcript, [
+      claudeRow('user', 'first request'),
+      claudeRow('assistant', 'first answer'),
+      claudeRow('user', 'latest request'),
+      claudeRow('assistant', 'partial answer'),
+      claudeRow('assistant', 'latest representative answer'),
+    ].map(JSON.stringify).join('\n'));
+
+    assert.deepEqual(
+      deriveAuditorFreshnessExpectation({ host: 'claude', transcriptPath: transcript, sessionId: 'claude-session' }),
+      {
+        expectedOriginSessionId: 'claude-session',
+        expectedTurnNumber: 4,
+        expectedUserSha256: hashAuditorBody('latest request'),
+        expectedAssistantSha256: hashAuditorBody('latest representative answer'),
+      },
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('deriveAuditorFreshnessExpectation: Codex excludes current in-flight turn before deriving latest completed identity', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-auditor-codex-rollout-'));
+  const rollout = join(dir, 'rollout.jsonl');
+  try {
+    writeFileSync(rollout, [
+      codexEvent('user_message', { message: 'completed request' }),
+      codexEvent('task_started'),
+      codexEvent('agent_message', { message: 'completed answer' }),
+      codexEvent('task_complete'),
+      codexEvent('user_message', { message: 'in-flight request' }),
+      codexEvent('task_started'),
+      codexEvent('agent_message', { message: 'in-flight answer' }),
+    ].map(JSON.stringify).join('\n'));
+
+    assert.deepEqual(
+      deriveAuditorFreshnessExpectation({ host: 'codex', transcriptPath: rollout, sessionId: 'codex:thread-1' }),
+      {
+        expectedOriginSessionId: 'codex:thread-1',
+        expectedTurnNumber: null,
+        expectedUserSha256: hashAuditorBody('completed request'),
+        expectedAssistantSha256: hashAuditorBody('completed answer'),
+      },
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('readAuditorContext: Codex freshness uses exact origin and both pair hashes when turn ordinals are unstable', () => {
+  withDb(({ db, path }) => {
+    seedSession(db, {
+      sessionId: 'codex:thread-1',
+      projectPath: '/repo',
+      pairs: [{
+        originSessionId: 'codex:thread-1', turnNumber: 32,
+        user: 'completed request', assistant: 'completed answer',
+      }, {
+        originSessionId: 'codex:thread-1', turnNumber: 33,
+        user: 'transient request', assistant: 'transient answer',
+      }],
+    });
+    const result = readAuditorContext({
+      dbPath: path,
+      sessionId: 'codex:thread-1',
+      projectRoot: '/repo',
+      expectedOriginSessionId: 'codex:thread-1',
+      expectedTurnNumber: null,
+      expectedUserSha256: hashAuditorBody('completed request'),
+      expectedAssistantSha256: hashAuditorBody('completed answer'),
+    });
+    assert.equal(result.status, 'fresh');
+    assert.equal(result.freshness.turnNumber, 32);
+    assert.equal(result.turns.at(-1).turnNumber, 32);
+    assert.equal(result.turns.some((turn) => turn.turnNumber === 33), false);
+  });
+});
+
+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') };
+  });
+}
+
+function claudeRow(role, text) {
+  return { type: role, message: { role, content: [{ type: 'text', text }] } };
+}
+
+function codexEvent(type, payload = {}) {
+  return { timestamp: '2026-07-13T00:00:00.000Z', type: 'event_msg', payload: { type, ...payload } };
+}

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

@@ -88,6 +88,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 +217,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 = {},

package/src/codex-thread-index.mjs

@@ -28,7 +28,7 @@ export function listCodexThreadCandidates({
       const meta = readSessionMeta(rollout.path);
       const indexed = index.get(rollout.threadId) ?? {};
       const cwd = meta?.cwd ?? null;
-      const matchesProject = cwd ? normalizePath(cwd) === normalizedProject : false;
+      const matchesProject = cwd ? isSameProjectOrDescendant(normalizePath(cwd), normalizedProject) : false;
       return {
         id: rollout.threadId,
         threadName: indexed.thread_name ?? null,
@@ -69,7 +69,7 @@ export function findCodexThreadCandidate({
       const meta = readSessionMeta(rollout.path);
       const indexed = index.get(rollout.threadId) ?? {};
       const cwd = meta?.cwd ?? null;
-      const matchesProject = cwd ? normalizePath(cwd) === normalizedProject : false;
+      const matchesProject = cwd ? isSameProjectOrDescendant(normalizePath(cwd), normalizedProject) : false;
       return {
         id: rollout.threadId,
         threadName: indexed.thread_name ?? null,
@@ -169,6 +169,10 @@ function compareCandidates(a, b) {
 }
 
 function normalizePath(value) {
+  const raw = String(value);
+  if (/^[A-Za-z]:[\\/]/.test(raw)) {
+    return raw.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  }
   let resolved = resolve(value);
   try {
     if (existsSync(resolved)) resolved = realpathSync.native(resolved);
@@ -177,3 +181,8 @@ function normalizePath(value) {
   }
   return resolved.split(sep).join('/').replace(/\/+$/, '').toLowerCase();
 }
+
+function isSameProjectOrDescendant(candidate, root) {
+  if (!candidate || !root) return false;
+  return candidate === root || candidate.startsWith(`${root}/`);
+}