throughline 0.6.2 → 0.7.0

package/src/auditor-context.mjs

@@ -1,4 +1,3 @@
-import { createHash } from 'node:crypto';
 import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve, sep } from 'node:path';
@@ -6,25 +5,21 @@ import { DatabaseSync } from 'node:sqlite';
 import { buildBodyRowsFromActiveTurns } from './codex-capture.mjs';
 import { parseCodexRolloutFile } from './codex-rollout-memory.mjs';
 import { getLogicalTurnGroups } from './transcript-reader.mjs';
+import { hashAuditorBody, normalizeAuditorBody } from './body-digest.mjs';
+
+export { hashAuditorBody, normalizeAuditorBody } from './body-digest.mjs';
 
 export const AUDITOR_CONTEXT_SCHEMA = 'throughline.auditor_context.v1';
-export const AUDITOR_CONTEXT_DB_SCHEMA_VERSION = 8;
+export const AUDITOR_CONTEXT_DB_SCHEMA_VERSION = 9;
 export const DEFAULT_AUDITOR_RECENT_TURNS = 2;
 export const DEFAULT_AUDITOR_MAX_BODY_CHARS = 1200;
 export const DEFAULT_AUDITOR_MAX_TOTAL_CHARS = 4000;
+const OBSERVER_PROJECTION_BUSY_TIMEOUT_MS = 1_000;
 
 export function defaultAuditorContextDbPath() {
   return join(homedir(), '.throughline', 'throughline.db');
 }
 
-export function normalizeAuditorBody(value) {
-  return String(value ?? '').normalize('NFC').replace(/\r\n?/g, '\n').trim();
-}
-
-export function hashAuditorBody(value) {
-  return createHash('sha256').update(normalizeAuditorBody(value), 'utf8').digest('hex');
-}
-
 export function deriveAuditorFreshnessExpectation({ host, transcriptPath, sessionId } = {}) {
   assertNonEmptyString(transcriptPath, 'transcriptPath');
   assertNonEmptyString(sessionId, 'sessionId');
@@ -182,6 +177,44 @@ export function readAuditorContext({
   }
 }
 
+/** Read-only, ordered completed-pair projection for the Observer feed. */
+export function readCompletedPairProjection({
+  dbPath = defaultAuditorContextDbPath(), sessionId, projectRoot, expectedPairs,
+  maxBodyChars = DEFAULT_AUDITOR_MAX_BODY_CHARS, maxTotalChars = DEFAULT_AUDITOR_MAX_TOTAL_CHARS,
+} = {}) {
+  assertNonEmptyString(sessionId, 'sessionId');
+  assertNonEmptyString(projectRoot, 'projectRoot');
+  assertExpectedPairs(expectedPairs);
+  assertPositiveInteger(maxBodyChars, 'maxBodyChars');
+  if (!Number.isInteger(maxTotalChars) || maxTotalChars < 0) throw new TypeError('maxTotalChars must be an integer >= 0');
+  if (!existsSync(dbPath)) return { status: 'pending', reason: 'db_not_found', turns: [] };
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    db.exec(`PRAGMA busy_timeout = ${OBSERVER_PROJECTION_BUSY_TIMEOUT_MS}`);
+  } catch (cause) {
+    db?.close();
+    throw new AuditorContextError('E_AUDITOR_CONTEXT_DB_OPEN', 'auditor context DB could not be opened', { cause });
+  }
+  try {
+    const version = Number(db.prepare('PRAGMA user_version').get()?.user_version ?? 0);
+    if (version !== AUDITOR_CONTEXT_DB_SCHEMA_VERSION) throw new AuditorContextError('E_AUDITOR_CONTEXT_SCHEMA', 'auditor context DB schema is unsupported');
+    const session = db.prepare('SELECT session_id, project_path FROM sessions WHERE session_id = ?').get(sessionId);
+    if (!session) return { status: 'pending', reason: 'session_not_found', turns: [] };
+    if (!isSameProjectOrDescendant(session.project_path, projectRoot)) throw new AuditorContextError('E_AUDITOR_CONTEXT_PROJECT', 'auditor context DB project does not match');
+    const rows = db.prepare(
+      `SELECT id, origin_session_id, turn_number, role, text, created_at FROM bodies
+       WHERE session_id = ? AND role IN ('user', 'assistant') ORDER BY created_at ASC, id ASC`,
+    ).all(sessionId);
+    const matched = matchExpectedPairs(buildCompletedPairs(rows), expectedPairs);
+    if (!matched) return { status: 'pending', reason: 'pair_not_found', turns: [] };
+    return { status: 'fresh', turns: boundProjectedPairs(matched, { maxBodyChars, maxTotalChars }) };
+  } catch (cause) {
+    if (cause instanceof AuditorContextError) throw cause;
+    throw new AuditorContextError('E_AUDITOR_CONTEXT_QUERY', 'auditor context query failed', { cause });
+  } finally { db.close(); }
+}
+
 export class AuditorContextError extends Error {
   constructor(code, message, { cause } = {}) {
     super(message, { cause });
@@ -262,6 +295,35 @@ function boundCompletedPairs(pairs, { maxBodyChars, maxTotalChars }) {
   return { turns: selected, chars, truncated };
 }
 
+function matchExpectedPairs(completed, expectedPairs) {
+  const matched = [];
+  let searchStart = 0;
+  for (const expected of expectedPairs) {
+    const index = completed.findIndex((pair, pairIndex) => pairIndex >= searchStart &&
+      hashAuditorBody(pair.originSessionId) === expected.origin_sha256 &&
+      hashAuditorBody(pair.user) === expected.user_sha256 && hashAuditorBody(pair.assistant) === expected.assistant_sha256);
+    if (index < 0) return null;
+    matched.push({ ...completed[index], expected });
+    searchStart = index + 1;
+  }
+  return matched;
+}
+
+function boundProjectedPairs(pairs, { maxBodyChars, maxTotalChars }) {
+  let remaining = maxTotalChars;
+  return pairs.map((pair) => {
+    const user = tail(pair.user, Math.min(maxBodyChars, remaining));
+    remaining -= user.length;
+    const assistant = tail(pair.assistant, Math.min(maxBodyChars, remaining));
+    remaining -= assistant.length;
+    return {
+      origin_sha256: pair.expected.origin_sha256, user_sha256: pair.expected.user_sha256,
+      assistant_sha256: pair.expected.assistant_sha256, user, assistant,
+      truncated: user.length < pair.user.length || assistant.length < pair.assistant.length,
+    };
+  });
+}
+
 function emptyResult(status, reason, { sessionId, projectRoot, recentTurns, dbSchemaVersion } = {}) {
   return {
     schema: AUDITOR_CONTEXT_SCHEMA,
@@ -289,7 +351,17 @@ function emptyResult(status, reason, { sessionId, projectRoot, recentTurns, dbSc
 function canonicalProjectPath(value) {
   const raw = String(value ?? '');
   if (/^[A-Za-z]:[\\/]/.test(raw)) {
-    return raw.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+    // Windows の 8.3 短縮名 (例: RUNNER~1) を実体の長い名前へ解決してから比較形へ
+    // 正規化する。GitHub Actions は TEMP が短縮名で来るため、realpath を挟まないと
+    // 同一ディレクトリの短縮形/長形が別 project と判定される (codex-thread-index の
+    // normalizePath と同型)。存在しないパスは lexical のまま (fixture の仮パスを壊さない)。
+    let resolved = raw;
+    try {
+      if (existsSync(raw)) resolved = realpathSync.native(raw);
+    } catch {
+      // Keep the lexical Windows path when it cannot be resolved.
+    }
+    return resolved.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
   }
   let normalized = isAbsolute(raw) ? raw : resolve(raw);
   try {
@@ -328,3 +400,12 @@ function assertPositiveInteger(value, name) {
     throw new TypeError(`${name} must be an integer >= 1`);
   }
 }
+
+function assertExpectedPairs(value) {
+  if (!Array.isArray(value) || value.length < 1 || value.some((pair) => !pair || typeof pair !== 'object' ||
+    Object.keys(pair).length !== 3 || !isLowercaseSha256(pair.origin_sha256) || !isLowercaseSha256(pair.user_sha256) || !isLowercaseSha256(pair.assistant_sha256))) {
+    throw new TypeError('expectedPairs must be a non-empty SHA-256 chain');
+  }
+}
+
+function isLowercaseSha256(value) { return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value); }

package/src/auditor-context.test.mjs

@@ -1,4 +1,6 @@
 import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
 import { existsSync, lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -9,10 +11,11 @@ import {
   AUDITOR_CONTEXT_SCHEMA,
   deriveAuditorFreshnessExpectation,
   hashAuditorBody,
+  readCompletedPairProjection,
   readAuditorContext,
 } from './auditor-context.mjs';
 
-function withDb(fn, { version = 8 } = {}) {
+function withDb(fn, { version = 9 } = {}) {
   const dir = mkdtempSync(join(tmpdir(), 'tl-auditor-context-'));
   const path = join(dir, 'throughline.db');
   const db = new DatabaseSync(path);
@@ -279,6 +282,118 @@ test('readAuditorContext: Codex freshness uses exact origin and both pair hashes
   });
 });
 
+test('readCompletedPairProjection: ordered chain matches each DB pair once and preserves bounded identities', () => {
+  withDb(({ db, path }) => {
+    const pairs = [
+      { originSessionId: 'origin-a', turnNumber: 1, user: 'first user', assistant: 'first answer' },
+      { originSessionId: 'origin-b', turnNumber: 2, user: 'second user', assistant: 'second answer' },
+    ];
+    seedSession(db, { pairs });
+    db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+      .run('session-1', 'extra', 3, 'user', 'not completed by chain', 10);
+    const expectedPairs = pairs.map((pair) => ({
+      origin_sha256: hashAuditorBody(pair.originSessionId), user_sha256: hashAuditorBody(pair.user), assistant_sha256: hashAuditorBody(pair.assistant),
+    }));
+    const result = readCompletedPairProjection({ dbPath: path, sessionId: 'session-1', projectRoot: '/repo', expectedPairs, maxBodyChars: 20, maxTotalChars: 0 });
+    assert.equal(result.status, 'fresh');
+    assert.equal(result.turns.length, 2);
+    assert.ok(result.turns.every((turn) => turn.truncated && turn.user === '' && turn.assistant === ''));
+    assert.deepEqual(result.turns.map((turn) => turn.origin_sha256), expectedPairs.map((pair) => pair.origin_sha256));
+  });
+});
+
+test('readCompletedPairProjection: missing or mismatched pair returns pending without partial bodies', () => {
+  withDb(({ db, path }) => {
+    const pairs = [
+      { originSessionId: 'origin-a', turnNumber: 1, user: 'first user', assistant: 'first answer' },
+      { originSessionId: 'origin-b', turnNumber: 2, user: 'second user', assistant: 'second answer' },
+    ];
+    seedSession(db, { pairs });
+    const expectedPairs = [
+      { origin_sha256: hashAuditorBody(pairs[0].originSessionId), user_sha256: hashAuditorBody(pairs[0].user), assistant_sha256: hashAuditorBody(pairs[0].assistant) },
+      { origin_sha256: hashAuditorBody(pairs[1].originSessionId), user_sha256: hashAuditorBody(pairs[1].user), assistant_sha256: hashAuditorBody('different') },
+    ];
+    assert.deepEqual(readCompletedPairProjection({ dbPath: path, sessionId: 'session-1', projectRoot: '/repo', expectedPairs }), {
+      status: 'pending', reason: 'pair_not_found', turns: [],
+    });
+  });
+});
+
+test('readCompletedPairProjection: missing session is pending without any body', () => {
+  withDb(({ path }) => {
+    const expectedPairs = [{
+      origin_sha256: hashAuditorBody('origin'), user_sha256: hashAuditorBody('user'), assistant_sha256: hashAuditorBody('assistant'),
+    }];
+    assert.deepEqual(readCompletedPairProjection({ dbPath: path, sessionId: 'missing-session', projectRoot: '/repo', expectedPairs }), {
+      status: 'pending', reason: 'session_not_found', turns: [],
+    });
+  });
+});
+
+test('readCompletedPairProjection: bounded wait内にwriter lockが解放されれば同じpairを読む', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-observer-read-busy-'));
+  const path = join(dir, 'throughline.db');
+  const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'user', assistant: 'answer' };
+  const expectedPairs = [{
+    origin_sha256: hashAuditorBody(pair.originSessionId),
+    user_sha256: hashAuditorBody(pair.user),
+    assistant_sha256: hashAuditorBody(pair.assistant),
+  }];
+  const db = new DatabaseSync(path);
+  db.exec(`
+    PRAGMA journal_mode = DELETE;
+    PRAGMA user_version = 9;
+    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
+    );
+  `);
+  seedSession(db, { pairs: [pair] });
+  db.close();
+  const writer = spawn(process.execPath, ['--input-type=module', '-e', `
+    import { DatabaseSync } from 'node:sqlite';
+    const db = new DatabaseSync(process.argv[1]);
+    db.exec('BEGIN EXCLUSIVE');
+    process.stdout.write('ready\\n');
+    setTimeout(() => { db.exec('ROLLBACK'); db.close(); }, 200);
+  `, path], { stdio: ['ignore', 'pipe', 'pipe'] });
+  const exited = once(writer, 'exit');
+  try {
+    await once(writer.stdout, 'data');
+    const startedAt = Date.now();
+    const result = readCompletedPairProjection({
+      dbPath: path, sessionId: 'session-1', projectRoot: '/repo', expectedPairs,
+    });
+    assert.equal(result.status, 'fresh');
+    assert.deepEqual(result.turns.map((turn) => turn.origin_sha256), expectedPairs.map((entry) => entry.origin_sha256));
+    assert.ok(Date.now() - startedAt >= 100);
+    const [code] = await exited;
+    assert.equal(code, 0);
+  } finally {
+    if (writer.exitCode === null) writer.kill('SIGTERM');
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('readCompletedPairProjection: schema and project mismatch are hard failures', () => {
+  const pair = { originSessionId: 'origin-a', turnNumber: 1, user: 'user', assistant: 'answer' };
+  const expectedPairs = [{ origin_sha256: hashAuditorBody(pair.originSessionId), user_sha256: hashAuditorBody(pair.user), assistant_sha256: hashAuditorBody(pair.assistant) }];
+  withDb(({ db, path }) => {
+    seedSession(db, { projectPath: '/other', pairs: [pair] });
+    assert.throws(() => readCompletedPairProjection({ dbPath: path, sessionId: 'session-1', projectRoot: '/repo', expectedPairs }), (error) => error.code === 'E_AUDITOR_CONTEXT_PROJECT');
+  });
+  withDb(({ db, path }) => {
+    seedSession(db, { pairs: [pair] });
+    assert.throws(() => readCompletedPairProjection({ dbPath: path, sessionId: 'session-1', projectRoot: '/repo', expectedPairs }), (error) => error.code === 'E_AUDITOR_CONTEXT_SCHEMA');
+  }, { version: 7 });
+});
+
 function snapshotSqliteFiles(path) {
   return [path, `${path}-wal`, `${path}-shm`].map((file) => {
     if (!existsSync(file)) return { file, exists: false };

package/src/baton.mjs

@@ -43,16 +43,29 @@ export function writeBaton(db, { projectPath, sessionId, now = Date.now() }) {
 /**
  * 同 project_path のバトンを読み出して削除する (atomic)。
  *
+ * 適格性は `bornAt`（= 消費者セッションの誕生時刻）基準で判定する:
+ *   age = bornAt - baton.created_at
+ *   - age < 0     : バトンは消費者セッションより後に書かれた（本来の後継は
+ *                   その後に生まれる別セッション）→ **消さずに残し** skip。
+ *                   二相ハンドオフでは消費が最初のプロンプト時点まで遅延するため、
+ *                   「自分より後に書かれたバトン」を走行中セッションが横取りしない
+ *                   ためのガード。
+ *   - age > ttlMs : TTL 超過。従来どおり削除して破棄。
+ *   - それ以外    : 削除して sessionId を返す。
+ * `bornAt` 省略時は now と同値（= 従来の SessionStart 即時消費と同じ判定）。
+ *
  * 戻り値:
- *   - { sessionId, ageMs }                                : バトン存在 かつ TTL 以内
- *   - { sessionId: null, skipReason: 'expired', ageMs }   : TTL 超過で破棄
- *   - { sessionId: null, skipReason: 'missing' }          : バトン無し
+ *   - { sessionId, ageMs }                                    : バトン存在 かつ適格
+ *   - { sessionId: null, skipReason: 'expired', ageMs }       : TTL 超過で破棄
+ *   - { sessionId: null, skipReason: 'future_baton', ageMs }  : 消費者誕生より後の
+ *                                                               バトン（残置）
+ *   - { sessionId: null, skipReason: 'missing' }              : バトン無し
  *
  * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ projectPath: string, now?: number, ttlMs?: number }} params
- * @returns {{ sessionId: string | null, ageMs?: number, skipReason?: 'expired' | 'missing' }}
+ * @param {{ projectPath: string, now?: number, bornAt?: number, ttlMs?: number }} params
+ * @returns {{ sessionId: string | null, ageMs?: number, skipReason?: 'expired' | 'missing' | 'future_baton' }}
  */
-export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_TTL_MS }) {
+export function consumeBaton(db, { projectPath, now = Date.now(), bornAt = now, ttlMs = BATON_TTL_MS }) {
   db.exec('BEGIN IMMEDIATE');
   try {
     // Windows 互換: ドライブレターの大小差を吸収するため COLLATE NOCASE
@@ -67,10 +80,17 @@ export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_
       return { sessionId: null, skipReason: 'missing' };
     }
 
+    const ageMs = bornAt - row.created_at;
+
+    if (ageMs < 0) {
+      // 消費者より未来のバトンは本来の後継のために残す（削除しない）
+      db.exec('COMMIT');
+      return { sessionId: null, skipReason: 'future_baton', ageMs };
+    }
+
     db.prepare('DELETE FROM handoff_batons WHERE project_path = ? COLLATE NOCASE').run(
       projectPath,
     );
-    const ageMs = now - row.created_at;
 
     if (ageMs > ttlMs) {
       db.exec('COMMIT');

package/src/baton.test.mjs

@@ -105,3 +105,47 @@ test('consumeBaton: returns no memoText property in v8 (memo column dropped)', (
   assert.equal(result.sessionId, 'S1');
   assert.equal('memoText' in result, false, 'memoText property should be removed in v8');
 });
+
+test('consumeBaton: bornAt basis — session born after baton write consumes it', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  // セッション誕生 2000、消費 (初回プロンプト) はずっと後の 50 分後でも、
+  // TTL は誕生時刻基準なので age = 1 秒で有効
+  const result = consumeBaton(db, {
+    projectPath: '/proj',
+    now: 1000 + 50 * 60 * 1000,
+    bornAt: 2000,
+  });
+  assert.equal(result.sessionId, 'S1');
+  assert.equal(result.ageMs, 1000);
+  assert.equal(db.prepare('SELECT COUNT(*) AS c FROM handoff_batons').get().c, 0);
+});
+
+test('consumeBaton: bornAt basis — TTL measured from birth, not from consumption time', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  // 誕生が /tl の 2 時間後 → 初回プロンプトが即時でも expired
+  const result = consumeBaton(db, {
+    projectPath: '/proj',
+    now: 1000 + 2 * 60 * 60 * 1000 + 5000,
+    bornAt: 1000 + 2 * 60 * 60 * 1000,
+  });
+  assert.equal(result.sessionId, null);
+  assert.equal(result.skipReason, 'expired');
+  assert.equal(db.prepare('SELECT COUNT(*) AS c FROM handoff_batons').get().c, 0, 'expired は従来どおり削除');
+});
+
+test('consumeBaton: future_baton — baton written after consumer birth is left in place', () => {
+  const db = makeDb();
+  // 走行中セッション (誕生 1000) が初回プロンプト消費を試みる時、
+  // 誕生後 (5000) に書かれた他セッションのバトンは本来の後継のために残す
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S-later', now: 5000 });
+  const result = consumeBaton(db, { projectPath: '/proj', now: 6000, bornAt: 1000 });
+  assert.equal(result.sessionId, null);
+  assert.equal(result.skipReason, 'future_baton');
+  assert.ok(result.ageMs < 0);
+
+  const rows = db.prepare('SELECT session_id FROM handoff_batons').all();
+  assert.equal(rows.length, 1, 'future baton must NOT be deleted');
+  assert.equal(rows[0].session_id, 'S-later');
+});

package/src/body-digest.mjs

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+export function normalizeAuditorBody(value) {
+  return String(value ?? '').normalize('NFC').replace(/\r\n?/g, '\n').trim();
+}
+
+export function hashAuditorBody(value) {
+  return createHash('sha256').update(normalizeAuditorBody(value), 'utf8').digest('hex');
+}

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

@@ -20,7 +20,7 @@ function makeDb({ originSessionId = 'origin-1' } = {}) {
   const path = join(dir, 'throughline.db');
   const db = new DatabaseSync(path);
   db.exec(`
-    PRAGMA user_version = 8;
+    PRAGMA user_version = 9;
     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');

package/src/cli/factory-diagnostics.mjs

@@ -17,6 +17,7 @@ const REQUIRED_DATABASE_COLUMNS = {
   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'],
+  pending_handoffs: ['session_id', 'project_path', 'source', 'auto_predecessor_id', 'created_at'],
 };
 const REQUIRED_DATABASE_INDEXES = ['uq_skeletons_turn_v3', 'uq_details_source'];
 const REQUIRED_INDEX_SHAPES = {
@@ -163,9 +164,11 @@ export function inspectFactoryHooks({ codexHome = defaultCodexHome(), readHooks
     return {
       status: values.includes('not_ready')
         ? 'not_ready'
-        : values.includes('ready')
+        : values.includes('unverified')
           ? 'unverified'
-          : 'not_applicable',
+          : values.includes('ready')
+            ? 'ready'
+            : 'not_applicable',
       reason: 'hooks_inspected',
       events,
     };

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

@@ -116,7 +116,7 @@ test('factory-diagnostics DB inspection rejects version-only 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.exec('PRAGMA user_version = 9; CREATE TABLE sessions (session_id TEXT)');
     db.close();
     assert.equal(inspectFactoryDatabase({ dbPath }).status, 'not_ready');
   } finally {
@@ -168,9 +168,34 @@ test('factory-diagnostics hook inspection rejects corrupt and false-ready shapes
   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;
+    PRAGMA user_version = 9;
     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
@@ -192,6 +217,10 @@ function createFactorySchema(db) {
     CREATE TABLE handoff_batons (
       project_path TEXT PRIMARY KEY, session_id TEXT NOT NULL, created_at INTEGER NOT NULL
     );
+    CREATE TABLE pending_handoffs (
+      session_id TEXT PRIMARY KEY, project_path TEXT NOT NULL, source TEXT,
+      auto_predecessor_id TEXT, 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

package/src/cli/observer-read.mjs

@@ -0,0 +1,73 @@
+import { readObserverTurnPage, OBSERVER_READ_SCHEMA } from '../observer-turn-feed.mjs';
+
+const ERRORS = Object.freeze({
+  args: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_ARGS', message: 'invalid observer-read arguments' },
+  input: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_INPUT', message: 'observer read input is invalid' },
+  schema: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_DB_SCHEMA', message: 'observer read database schema is unsupported' },
+  project: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_DB_PROJECT', message: 'observer read database project does not match' },
+  io: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_DB_IO', message: 'observer read database could not be read' },
+  internal: { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_INTERNAL', message: 'observer read failed' },
+});
+
+export function parseArgs(argv = []) {
+  const out = { projectPath: null, afterCursor: undefined, throughCursor: undefined, pageToken: undefined, limit: undefined, json: false };
+  const seen = new Set();
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === '--json') {
+      if (seen.has(arg)) throw new TypeError('duplicate option');
+      seen.add(arg); out.json = true; continue;
+    }
+    if (!['--project', '--after-cursor', '--through-cursor', '--page-token', '--limit'].includes(arg) || seen.has(arg)) {
+      throw new TypeError('invalid option');
+    }
+    const value = argv[++index];
+    if (!value || value.startsWith('-')) throw new TypeError('missing option value');
+    seen.add(arg);
+    if (arg === '--project') out.projectPath = value;
+    else if (arg === '--after-cursor') out.afterCursor = value;
+    else if (arg === '--through-cursor') out.throughCursor = value;
+    else if (arg === '--page-token') out.pageToken = value;
+    else out.limit = parseLimit(value);
+  }
+  if (!out.json || !out.projectPath || (out.pageToken !== undefined && (out.afterCursor === undefined || out.throughCursor === undefined))) {
+    throw new TypeError('missing required option');
+  }
+  return out;
+}
+
+export function run(argv = [], { read = readObserverTurnPage, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let args;
+  try { args = parseArgs(argv); } catch { writeJson(stderr, ERRORS.args); return 1; }
+  try {
+    const result = read({
+      projectPath: args.projectPath,
+      ...(args.afterCursor === undefined ? {} : { afterCursor: args.afterCursor }),
+      ...(args.throughCursor === undefined ? {} : { throughCursor: args.throughCursor }),
+      ...(args.pageToken === undefined ? {} : { pageToken: args.pageToken }),
+      ...(args.limit === undefined ? {} : { limit: args.limit }),
+    });
+    writeJson(stdout, result);
+    return 0;
+  } catch (error) {
+    writeJson(stderr, mapError(error));
+    return 1;
+  }
+}
+
+function parseLimit(value) {
+  if (!/^\d+$/.test(value)) throw new TypeError('invalid limit');
+  const limit = Number(value);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new TypeError('invalid limit');
+  return limit;
+}
+
+function mapError(error) {
+  if (error?.code === 'E_AUDITOR_CONTEXT_SCHEMA') return ERRORS.schema;
+  if (error?.code === 'E_AUDITOR_CONTEXT_PROJECT') return ERRORS.project;
+  if (['E_AUDITOR_CONTEXT_DB_OPEN', 'E_AUDITOR_CONTEXT_QUERY'].includes(error?.code)) return ERRORS.io;
+  if (error instanceof TypeError) return ERRORS.input;
+  return ERRORS.internal;
+}
+
+function writeJson(stream, value) { stream.write(`${JSON.stringify(value)}\n`); }

package/src/cli/observer-read.test.mjs

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import test from 'node:test';
+import { OBSERVER_READ_SCHEMA } from '../observer-turn-feed.mjs';
+import { parseArgs, run } from './observer-read.mjs';
+
+const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const FIXED = { schema: OBSERVER_READ_SCHEMA, status: 'snapshot', turns: [], page: { complete: true, nextToken: null } };
+
+function streams() {
+  return { stdout: { text: '', write(value) { this.text += value; } }, stderr: { text: '', write(value) { this.text += value; } } };
+}
+
+test('observer-read parses each supported option once and delegates validation to read library', () => {
+  assert.deepEqual(parseArgs(['--project', '/repo', '--after-cursor', 'after', '--through-cursor', 'through', '--page-token', 'page', '--limit', '100', '--json']), {
+    projectPath: '/repo', afterCursor: 'after', throughCursor: 'through', pageToken: 'page', limit: 100, json: true,
+  });
+  const io = streams(); let input;
+  assert.equal(run(['--project', '/repo', '--json'], { ...io, read(value) { input = value; return FIXED; } }), 0);
+  assert.deepEqual(input, { projectPath: '/repo' });
+  assert.deepEqual(JSON.parse(io.stdout.text), FIXED);
+  assert.equal(io.stderr.text, '');
+});
+
+test('observer-read rejects duplicate, missing, positional, and invalid pagination arguments with fixed args error', () => {
+  for (const argv of [
+    ['--project', '/repo', '--project', '/repo', '--json'], ['--project', '/repo', '--json', '--json'],
+    ['--project', '/repo', '--page-token', 'p', '--json'], ['--project', '/repo', '--limit', '0', '--json'],
+    ['--project', '/repo', 'extra', '--json'], ['--json'],
+  ]) {
+    const io = streams();
+    assert.equal(run(argv, { ...io }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.deepEqual(JSON.parse(io.stderr.text), { schema: OBSERVER_READ_SCHEMA, status: 'error', code: 'E_OBSERVER_READ_ARGS', message: 'invalid observer-read arguments' });
+  }
+});
+
+test('observer-read keeps known states successful and maps hard failures without leakage', () => {
+  for (const status of ['snapshot', 'delta', 'thread_switched', 'host_switched', 'resync_required', 'projection_pending', 'ambiguous_parent']) {
+    const io = streams();
+    assert.equal(run(['--project', '/repo', '--json'], { ...io, read: () => ({ ...FIXED, status }) }), 0);
+    assert.equal(JSON.parse(io.stdout.text).status, status);
+    assert.equal(io.stderr.text, '');
+  }
+  for (const [error, code] of [
+    [new TypeError('/private/cursor body'), 'E_OBSERVER_READ_INPUT'],
+    [Object.assign(new Error('schema'), { code: 'E_AUDITOR_CONTEXT_SCHEMA' }), 'E_OBSERVER_READ_DB_SCHEMA'],
+    [Object.assign(new Error('project'), { code: 'E_AUDITOR_CONTEXT_PROJECT' }), 'E_OBSERVER_READ_DB_PROJECT'],
+    [Object.assign(new Error('io'), { code: 'E_AUDITOR_CONTEXT_QUERY' }), 'E_OBSERVER_READ_DB_IO'],
+    [new Error('secret /private cursor'), 'E_OBSERVER_READ_INTERNAL'],
+  ]) {
+    const io = streams();
+    assert.equal(run(['--project', '/repo', '--json'], { ...io, read: () => { throw error; } }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.equal(JSON.parse(io.stderr.text).code, code);
+    assert.doesNotMatch(io.stderr.text, /private|cursor|secret/i);
+  }
+});
+
+test('observer-read bin dispatch and help advertise 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 observer-read --project <absolute-directory> --json/);
+});
+
+test('observer-read bin dispatch returns an empty snapshot from an isolated environment', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'throughline-observer-read-'));
+  const home = join(root, 'home');
+  const state = join(root, 'state');
+  const codexHome = join(root, 'codex');
+  const project = join(root, 'project');
+  try {
+    await Promise.all([mkdir(home), mkdir(state), mkdir(codexHome), mkdir(project)]);
+    const result = spawnSync(process.execPath, [BIN_PATH, 'observer-read', '--project', project, '--json'], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      env: { ...process.env, HOME: home, USERPROFILE: home, XDG_STATE_HOME: state, CODEX_HOME: codexHome },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr, '');
+    const page = JSON.parse(result.stdout);
+    assert.equal(page.schema, OBSERVER_READ_SCHEMA);
+    assert.equal(page.status, 'snapshot');
+    assert.deepEqual(page.turns, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});