throughline 0.6.3 → 0.7.0

package/src/observer-turn-feed.test.mjs

@@ -0,0 +1,339 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, 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 { decodeObserverCursor, encodeObserverCursor, readObserverTurnPage, resolveObserverTurnFeed } from './observer-turn-feed.mjs';
+import { writeCompletedTurnReceipt } from './completed-turn-receipts.mjs';
+import { hashAuditorBody } from './body-digest.mjs';
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'tl-observer-feed-'));
+  const project = join(root, 'project'); const other = join(root, 'other'); const home = join(root, 'codex');
+  mkdirSync(project); mkdirSync(other); mkdirSync(home);
+  // LOCALAPPDATA も state へ向け、win32 (LOCALAPPDATA layout) と POSIX (XDG layout) で
+  // receipt store の実パスを一致させる (テスト内の削除・検査パスを OS 非依存にする)
+  return { root, project, other, home, receiptOptions: { env: { HOME: root, USERPROFILE: root, XDG_STATE_HOME: join(root, 'state'), LOCALAPPDATA: join(root, 'state') } } };
+}
+function writeRollout(home, project, id, events) {
+  const dir = join(home, 'sessions', '2026', '07', '15'); mkdirSync(dir, { recursive: true });
+  const path = join(dir, `rollout-2026-07-15T00-00-00-${id}.jsonl`);
+  const rows = [{ type: 'session_meta', timestamp: '2026-07-15T00:00:00.000Z', payload: { id, cwd: project } }, ...events];
+  writeFileSync(path, rows.map(JSON.stringify).join('\n'));
+  return path;
+}
+function event(type, message, timestamp) { return { type: 'event_msg', timestamp, payload: { type, ...(message === undefined ? {} : { message }) } }; }
+function completeEvents(at = '2026-07-15T00:01:00.000Z') { return [event('user_message', 'request', '2026-07-15T00:00:01.000Z'), event('task_started', undefined, '2026-07-15T00:00:02.000Z'), event('agent_message', 'answer', '2026-07-15T00:00:03.000Z'), event('task_complete', undefined, at)]; }
+function createProjectionDb(path, project, sessionId) {
+  const db = new DatabaseSync(path);
+  db.exec(`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);`);
+  db.prepare('INSERT INTO sessions (session_id, project_path) VALUES (?, ?)').run(sessionId, project);
+  return db;
+}
+function addClaudeTurn(box, db, { sessionId = 'claude-session', origin, turn, user, assistant, at }) {
+  writeCompletedTurnReceipt({
+    projectPath: box.project, targetSessionId: sessionId, originSessionId: origin,
+    userBody: user, assistantBody: assistant, completedAt: at,
+  }, box.receiptOptions);
+  if (!db) return;
+  const insert = db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)');
+  insert.run(sessionId, origin, turn, 'user', user, at * 2);
+  insert.run(sessionId, origin, turn, 'assistant', assistant, at * 2 + 1);
+}
+function rewritePageToken(token, mutate) {
+  const prefix = 'tlp1.';
+  const value = JSON.parse(Buffer.from(token.slice(prefix.length), 'base64url').toString('utf8'));
+  mutate(value);
+  return `${prefix}${Buffer.from(JSON.stringify(value), 'utf8').toString('base64url')}`;
+}
+
+test('observer feed: in-flight DB recordとStop continuationは最終task_completeまでchainを進めない', () => {
+  const box = fixture();
+  const dbPath = join(box.root, 'throughline.db');
+  let db;
+  try {
+    const id = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+    const sessionId = `codex:${id}`;
+    db = createProjectionDb(dbPath, box.project, sessionId);
+    const insert = db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, ?, ?, ?, ?)');
+    insert.run(sessionId, sessionId, 1, 'user', 'in-flight request', 1);
+    insert.run(sessionId, sessionId, 1, 'assistant', 'in-flight answer', 2);
+    writeRollout(box.home, box.project, id, completeEvents().slice(0, 3));
+    const dbAhead = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions, dbPath });
+    assert.equal(dbAhead.status, 'snapshot');
+    assert.equal(dbAhead.chain.length, 0, 'DBにpair本文があってもrollout未完了turnをcompleted feedへ出さない');
+    const emptyCursor = decodeObserverCursor(dbAhead.throughCursor);
+    assert.equal(emptyCursor.host, null);
+    assert.equal(emptyCursor.thread_sha256, null);
+    assert.equal(emptyCursor.length, 0);
+
+    writeRollout(box.home, box.project, id, completeEvents());
+    const baseline = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    writeRollout(box.home, box.project, id, [
+      ...completeEvents(),
+      event('user_message', 'continuation request', '2026-07-15T00:01:01.000Z'),
+      event('task_started', undefined, '2026-07-15T00:01:02.000Z'),
+      event('agent_message', 'Stop continuation', '2026-07-15T00:01:03.000Z'),
+    ]);
+    const beforeFinalComplete = resolveObserverTurnFeed({ projectPath: box.project, cursor: baseline.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions });
+    assert.equal(beforeFinalComplete.status, 'unchanged');
+    assert.equal(beforeFinalComplete.throughCursor, baseline.throughCursor);
+    assert.equal(beforeFinalComplete.chain.length, 1);
+
+    writeRollout(box.home, box.project, id, [
+      ...completeEvents(),
+      event('user_message', 'continuation request', '2026-07-15T00:01:01.000Z'),
+      event('task_started', undefined, '2026-07-15T00:01:02.000Z'),
+      event('agent_message', 'Stop continuation', '2026-07-15T00:01:03.000Z'),
+      event('task_complete', undefined, '2026-07-15T00:01:04.000Z'),
+    ]);
+    const afterFinalComplete = resolveObserverTurnFeed({ projectPath: box.project, cursor: baseline.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions });
+    assert.equal(afterFinalComplete.status, 'append');
+    assert.notEqual(afterFinalComplete.throughCursor, baseline.throughCursor);
+    assert.equal(afterFinalComplete.chain.length, 2);
+  } finally {
+    db?.close();
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('observer feed: same-thread append, rollback prefix change, and project separation', () => {
+  const box = fixture();
+  try {
+    const id = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+    writeRollout(box.home, box.project, id, completeEvents());
+    const first = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    writeRollout(box.home, box.project, id, [...completeEvents(), ...completeEvents('2026-07-15T00:02:00.000Z')]);
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: first.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'append');
+    writeRollout(box.home, box.project, id, [event('user_message', 'changed', '2026-07-15T00:00:01.000Z'), ...completeEvents().slice(1)]);
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: first.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'resync_required');
+    const child = join(box.project, 'child'); mkdirSync(child);
+    const childId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f7';
+    writeRollout(box.home, child, childId, completeEvents('2026-07-15T00:03:00.000Z'));
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions }).chain.at(-1).completed_at, Date.parse('2026-07-15T00:03:00.000Z'), 'root配下cwdを含む');
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.other, codexHome: box.home, receiptOptions: box.receiptOptions }).chain.length, 0, '別projectは除外');
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.other, cursor: first.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'resync_required');
+  } finally { rmSync(box.root, { recursive: true, force: true }); }
+});
+
+test('observer feed: Claude history floor, host/thread switch, cross-host tie, and opaque cursor', () => {
+  const box = fixture();
+  try {
+    const options = box.receiptOptions;
+    for (let i = 1; i <= 257; i++) writeCompletedTurnReceipt({ projectPath: box.project, targetSessionId: 'claude-session', originSessionId: `o${i}`, userBody: `u${i}`, assistantBody: `a${i}`, completedAt: i }, options);
+    const latest = resolveObserverTurnFeed({ projectPath: box.project, receiptOptions: options, codexHome: box.home });
+    const decoded = decodeObserverCursor(latest.throughCursor);
+    const beforeFloor = encodeObserverCursor({ ...decoded, history_floor: 1 });
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: beforeFloor, receiptOptions: options, codexHome: box.home }).status, 'resync_required');
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: `${latest.throughCursor}x`, receiptOptions: options, codexHome: box.home }).status, 'resync_required');
+    const oldVersion = `tlc1.${Buffer.from(JSON.stringify({ ...decoded, schema: 'throughline.observer_cursor.v0' })).toString('base64url')}`;
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: oldVersion, receiptOptions: options, codexHome: box.home }).status, 'resync_required');
+    const changedPrefix = encodeObserverCursor({ ...decoded, prefix_sha256: 'f'.repeat(64) });
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: changedPrefix, receiptOptions: options, codexHome: box.home }).status, 'resync_required');
+    assert.throws(() => encodeObserverCursor({ ...decoded, length: 0 }), /cursor invalid/);
+    assert.doesNotMatch(JSON.stringify(decoded), new RegExp(`${box.project}|claude-session|u257|a257`));
+    const id = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+    writeRollout(box.home, box.project, id, completeEvents('2026-07-15T00:03:00.000Z'));
+    const switched = resolveObserverTurnFeed({ projectPath: box.project, cursor: latest.throughCursor, receiptOptions: options, codexHome: box.home });
+    assert.equal(switched.status, 'host_switched');
+    const secondId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f8';
+    writeRollout(box.home, box.project, secondId, completeEvents('2026-07-15T00:04:00.000Z'));
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: switched.throughCursor, receiptOptions: options, codexHome: box.home }).status, 'thread_switched');
+    writeCompletedTurnReceipt({ projectPath: box.project, targetSessionId: 'claude-tie', originSessionId: 'tie', userBody: 'tu', assistantBody: 'ta', completedAt: Date.parse('2026-07-15T00:03:00.000Z') }, options);
+    // Tie the current Codex parent, not a stale earlier one.
+    writeCompletedTurnReceipt({ projectPath: box.project, targetSessionId: 'claude-tie-current', originSessionId: 'tie-current', userBody: 'tuc', assistantBody: 'tac', completedAt: Date.parse('2026-07-15T00:04:00.000Z') }, options);
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, receiptOptions: options, codexHome: box.home }).status, 'ambiguous_parent');
+  } finally { rmSync(box.root, { recursive: true, force: true }); }
+});
+
+test('observer feed: Codex pair hashes reuse DB capture role aggregation', () => {
+  const box = fixture();
+  try {
+    const id = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+    writeRollout(box.home, box.project, id, [
+      event('user_message', 'user one', '2026-07-15T00:00:01.000Z'),
+      event('task_started', undefined, '2026-07-15T00:00:02.000Z'),
+      event('user_message', 'user two', '2026-07-15T00:00:03.000Z'),
+      event('agent_message', 'assistant one', '2026-07-15T00:00:04.000Z'),
+      event('agent_message', 'assistant two', '2026-07-15T00:00:05.000Z'),
+      event('task_complete', undefined, '2026-07-15T00:00:06.000Z'),
+    ]);
+    const result = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    assert.equal(result.chain[0].user_sha256, hashAuditorBody('user one\n\nuser two'));
+    assert.equal(result.chain[0].assistant_sha256, hashAuditorBody('assistant one\n\nassistant two'));
+  } finally { rmSync(box.root, { recursive: true, force: true }); }
+});
+
+test('observer feed: prior source loss never downgrades into a switch', () => {
+  const box = fixture();
+  try {
+    const primary = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+    const backup = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f8';
+    const primaryPath = writeRollout(box.home, box.project, primary, completeEvents('2026-07-15T00:03:00.000Z'));
+    writeRollout(box.home, box.project, backup, completeEvents('2026-07-15T00:02:00.000Z'));
+    const prior = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    rmSync(primaryPath);
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: prior.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'resync_required', 'old同hostへ露出してもswitchにしない');
+    const backupPath = join(box.home, 'sessions', '2026', '07', '15', `rollout-2026-07-15T00-00-00-${backup}.jsonl`);
+    writeCompletedTurnReceipt({ projectPath: box.project, targetSessionId: 'claude', originSessionId: 'origin', userBody: 'u', assistantBody: 'a', completedAt: Date.parse('2026-07-15T00:04:00.000Z') }, box.receiptOptions);
+    rmSync(backupPath);
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: prior.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'resync_required', 'prior host消失で他hostが出てもresync');
+    const claudePrior = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    const receiptPath = join(box.root, 'state', 'throughline', 'completed-turn-receipts');
+    rmSync(receiptPath, { recursive: true, force: true });
+    assert.equal(resolveObserverTurnFeed({ projectPath: box.project, cursor: claudePrior.throughCursor, codexHome: box.home, receiptOptions: box.receiptOptions }).status, 'resync_required', 'source全消失もresync');
+  } finally { rmSync(box.root, { recursive: true, force: true }); }
+});
+
+test('observer feed: DB projection is all-or-nothing and never exposes raw session identity', () => {
+  const box = fixture();
+  const dbPath = join(box.root, 'throughline.db');
+  let db;
+  try {
+    const options = box.receiptOptions;
+    writeCompletedTurnReceipt({ projectPath: box.project, targetSessionId: 'private-session', originSessionId: 'private-origin', userBody: 'captured user', assistantBody: 'captured answer', completedAt: 1 }, options);
+    const pending = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: options, dbPath });
+    assert.equal(pending.status, 'projection_pending');
+    assert.deepEqual(pending.turns, []);
+    db = new DatabaseSync(dbPath);
+    db.exec(`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);`);
+    db.prepare('INSERT INTO sessions (session_id, project_path) VALUES (?, ?)').run('private-session', box.project);
+    db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, 1, ?, ?, ?)').run('private-session', 'private-origin', 'user', 'captured user', 1);
+    db.prepare('INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, created_at) VALUES (?, ?, 1, ?, ?, ?)').run('private-session', 'private-origin', 'assistant', 'captured answer', 2);
+    const fresh = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: options, dbPath, maxTotalChars: 0 });
+    assert.equal(fresh.status, 'snapshot');
+    assert.equal(fresh.turns.length, 1);
+    assert.equal(fresh.turns[0].truncated, true);
+    assert.doesNotMatch(JSON.stringify(fresh), /private-session|private-origin|captured user|captured answer/);
+  } finally {
+    db?.close();
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('observer read: snapshot returns only the latest bounded DB-projected turns without pagination', () => {
+  const box = fixture();
+  const dbPath = join(box.root, 'throughline.db');
+  let db;
+  try {
+    db = createProjectionDb(dbPath, box.project, 'private-claude-session');
+    for (let turn = 1; turn <= 3; turn++) {
+      addClaudeTurn(box, db, {
+        sessionId: 'private-claude-session', origin: `private-origin-${turn}`, turn,
+        user: `user-${turn}`, assistant: `assistant-${turn}`, at: turn,
+      });
+    }
+    const result = readObserverTurnPage({
+      projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions,
+      dbPath, limit: 2,
+    });
+    assert.equal(result.schema, 'throughline.observer_read.v1');
+    assert.equal(result.status, 'snapshot');
+    assert.equal(result.host, 'claude');
+    assert.equal(result.historyTruncated, true);
+    assert.deepEqual(result.page, { complete: true, nextToken: null });
+    assert.deepEqual(result.turns.map((turn) => [turn.user, turn.assistant]), [
+      ['user-2', 'assistant-2'], ['user-3', 'assistant-3'],
+    ]);
+    assert.equal(result.turns.every((turn) => turn.origin_sha256 && turn.source_sha256 && Number.isInteger(turn.completed_at)), true);
+    assert.doesNotMatch(JSON.stringify(result), /private-claude-session|private-origin/);
+    for (const limit of [0, 101, 1.5]) {
+      assert.throws(() => readObserverTurnPage({
+        projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions, dbPath, limit,
+      }), /limit must be an integer between 1 and 100/);
+    }
+  } finally {
+    db?.close();
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('observer read: delta pages keep the first through boundary while newer turns arrive', () => {
+  const box = fixture();
+  const dbPath = join(box.root, 'throughline.db');
+  let db;
+  try {
+    db = createProjectionDb(dbPath, box.project, 'claude-session');
+    addClaudeTurn(box, db, { origin: 'origin-1', turn: 1, user: 'user-1', assistant: 'assistant-1', at: 1 });
+    const baseline = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    for (let turn = 2; turn <= 4; turn++) {
+      addClaudeTurn(box, db, { origin: `origin-${turn}`, turn, user: `user-${turn}`, assistant: `assistant-${turn}`, at: turn });
+    }
+
+    const first = readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, limit: 1,
+      codexHome: box.home, receiptOptions: box.receiptOptions, dbPath,
+    });
+    assert.equal(first.status, 'delta');
+    assert.equal(first.page.complete, false);
+    assert.equal(first.turns[0].user, 'user-2');
+    assert.equal(typeof first.page.nextToken, 'string');
+    assert.doesNotMatch(first.page.nextToken, /claude-session|origin-2|user-2|assistant-2/);
+
+    addClaudeTurn(box, db, { origin: 'origin-5', turn: 5, user: 'user-5', assistant: 'assistant-5', at: 5 });
+    const second = readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, throughCursor: first.throughCursor,
+      pageToken: first.page.nextToken, limit: 1, codexHome: box.home,
+      receiptOptions: box.receiptOptions, dbPath,
+    });
+    const third = readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, throughCursor: second.throughCursor,
+      pageToken: second.page.nextToken, limit: 1, codexHome: box.home,
+      receiptOptions: box.receiptOptions, dbPath,
+    });
+    assert.equal(second.turns[0].user, 'user-3');
+    assert.equal(third.turns[0].user, 'user-4');
+    assert.deepEqual(third.page, { complete: true, nextToken: null });
+    assert.equal(JSON.stringify([first, second, third]).includes('user-5'), false);
+
+    const tamperedOffset = rewritePageToken(first.page.nextToken, (value) => { value.offset = 2; });
+    assert.throws(() => readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, throughCursor: first.throughCursor,
+      pageToken: tamperedOffset, limit: 1, codexHome: box.home,
+      receiptOptions: box.receiptOptions, dbPath,
+    }), /page token binding invalid/);
+    assert.throws(() => readObserverTurnPage({
+      projectPath: box.other, afterCursor: baseline.throughCursor, throughCursor: first.throughCursor,
+      pageToken: first.page.nextToken, limit: 1, codexHome: box.home,
+      receiptOptions: box.receiptOptions, dbPath,
+    }), /page token binding invalid/);
+  } finally {
+    db?.close();
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('observer read: a missing pair on a later page returns no partial body or continuation', () => {
+  const box = fixture();
+  const dbPath = join(box.root, 'throughline.db');
+  let db;
+  try {
+    db = createProjectionDb(dbPath, box.project, 'claude-session');
+    addClaudeTurn(box, db, { origin: 'origin-1', turn: 1, user: 'user-1', assistant: 'assistant-1', at: 1 });
+    const baseline = resolveObserverTurnFeed({ projectPath: box.project, codexHome: box.home, receiptOptions: box.receiptOptions });
+    addClaudeTurn(box, db, { origin: 'origin-2', turn: 2, user: 'user-2', assistant: 'assistant-2', at: 2 });
+    addClaudeTurn(box, null, { origin: 'origin-3', turn: 3, user: 'user-3', assistant: 'assistant-3', at: 3 });
+    const first = readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, limit: 1,
+      codexHome: box.home, receiptOptions: box.receiptOptions, dbPath,
+    });
+    const pending = readObserverTurnPage({
+      projectPath: box.project, afterCursor: baseline.throughCursor, throughCursor: first.throughCursor,
+      pageToken: first.page.nextToken, limit: 1, codexHome: box.home,
+      receiptOptions: box.receiptOptions, dbPath,
+    });
+    assert.equal(first.status, 'delta');
+    assert.equal(pending.status, 'projection_pending');
+    assert.deepEqual(pending.turns, []);
+    assert.equal(pending.throughCursor, null);
+    assert.deepEqual(pending.page, { complete: false, nextToken: null });
+  } finally {
+    db?.close();
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});

package/src/observer-turn-wait.mjs

@@ -0,0 +1,102 @@
+import { performance } from 'node:perf_hooks';
+import { resolveObserverTurnFeed } from './observer-turn-feed.mjs';
+
+export const OBSERVER_WAIT_SCHEMA = 'throughline.observer_wait.v1';
+export const DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS = 3600;
+export const MAX_OBSERVER_WAIT_TIMEOUT_SECONDS = 3600;
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+
+export class ObserverWaitCancelledError extends Error {
+  constructor() {
+    super('observer wait was cancelled');
+    this.name = 'ObserverWaitCancelledError';
+    this.code = 'E_OBSERVER_WAIT_CANCELLED';
+  }
+}
+
+/**
+ * Waits for the completed-only Observer cursor to change. The second argument
+ * is an explicit dependency boundary for deterministic tests; callers should
+ * normally omit it.
+ */
+export async function waitForObserverTurnChange({
+  projectPath,
+  afterCursor,
+  timeoutSeconds = DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS,
+  signal,
+  codexHome,
+  receiptOptions,
+} = {}, dependencies = {}) {
+  assertWaitInput({ afterCursor, timeoutSeconds, signal });
+  const resolve = dependencies.resolve ?? resolveObserverTurnFeed;
+  const now = dependencies.now ?? (() => performance.now());
+  const sleep = dependencies.sleep ?? abortableSleep;
+  const pollIntervalMs = dependencies.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+    throw new TypeError('observer wait poll interval must be positive');
+  }
+
+  throwIfAborted(signal);
+  const deadline = now() + timeoutSeconds * 1000;
+  for (;;) {
+    throwIfAborted(signal);
+    const current = await resolve({ projectPath, cursor: afterCursor, codexHome, receiptOptions });
+    throwIfAborted(signal);
+    const terminal = terminalWire(current, afterCursor);
+    if (terminal) return terminal;
+
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) return waitWire('timeout', afterCursor, afterCursor);
+    await sleep(Math.min(pollIntervalMs, remainingMs), signal);
+    throwIfAborted(signal);
+  }
+}
+
+function assertWaitInput({ afterCursor, timeoutSeconds, signal }) {
+  if (typeof afterCursor !== 'string' || afterCursor.length === 0) {
+    throw new TypeError('observer wait afterCursor is required');
+  }
+  if (!Number.isSafeInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > MAX_OBSERVER_WAIT_TIMEOUT_SECONDS) {
+    throw new TypeError('observer wait timeoutSeconds must be an integer between 1 and 3600');
+  }
+  if (signal !== undefined && (typeof signal !== 'object' || typeof signal.aborted !== 'boolean' || typeof signal.addEventListener !== 'function')) {
+    throw new TypeError('observer wait signal must be an AbortSignal');
+  }
+}
+
+function terminalWire(result, afterCursor) {
+  if (result?.status === 'resync_required') return waitWire('resync_required', afterCursor, null);
+  if (result?.status === 'ambiguous_parent') return waitWire('ambiguous_parent', afterCursor, null);
+  if (result?.status === 'unchanged') return null;
+  if (['append', 'thread_switched', 'host_switched'].includes(result?.status) && typeof result.throughCursor === 'string') {
+    return waitWire('changed', afterCursor, result.throughCursor);
+  }
+  throw new TypeError('observer wait resolver returned an invalid state');
+}
+
+function waitWire(status, afterCursor, throughCursor) {
+  return { schema: OBSERVER_WAIT_SCHEMA, status, afterCursor, throughCursor };
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw new ObserverWaitCancelledError();
+}
+
+function abortableSleep(delayMs, signal) {
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal?.removeEventListener('abort', onAbort);
+    const finish = (callback) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      callback();
+    };
+    const onAbort = () => finish(() => reject(new ObserverWaitCancelledError()));
+    const timer = setTimeout(() => finish(resolve), delayMs);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+}

package/src/observer-turn-wait.test.mjs

@@ -0,0 +1,122 @@
+import assert from 'node:assert/strict';
+import { getEventListeners } from 'node:events';
+import test from 'node:test';
+import {
+  OBSERVER_WAIT_SCHEMA,
+  ObserverWaitCancelledError,
+  waitForObserverTurnChange,
+} from './observer-turn-wait.mjs';
+
+const AFTER = 'tlc1.after';
+
+function virtualDependencies(states, { pollIntervalMs = 1000 } = {}) {
+  let nowMs = 0;
+  let resolveCalls = 0;
+  let sleepCalls = 0;
+  return {
+    dependencies: {
+      now: () => nowMs,
+      pollIntervalMs,
+      resolve: () => states[Math.min(resolveCalls++, states.length - 1)],
+      sleep: async (delayMs) => { sleepCalls++; nowMs += delayMs; },
+    },
+    counts: () => ({ resolveCalls, sleepCalls, nowMs }),
+  };
+}
+
+test('observer wait returns immediate and polled changes without exposing resolver details', async () => {
+  const immediate = virtualDependencies([{ status: 'append', throughCursor: 'tlc1.changed', chain: [{ secret: 'body' }] }]);
+  assert.deepEqual(await waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER }, immediate.dependencies), {
+    schema: OBSERVER_WAIT_SCHEMA,
+    status: 'changed',
+    afterCursor: AFTER,
+    throughCursor: 'tlc1.changed',
+  });
+  assert.deepEqual(immediate.counts(), { resolveCalls: 1, sleepCalls: 0, nowMs: 0 });
+
+  const polled = virtualDependencies([
+    { status: 'unchanged', throughCursor: AFTER },
+    { status: 'host_switched', throughCursor: 'tlc1.host' },
+  ]);
+  assert.equal((await waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1 }, polled.dependencies)).throughCursor, 'tlc1.host');
+  assert.deepEqual(polled.counts(), { resolveCalls: 2, sleepCalls: 1, nowMs: 1000 });
+});
+
+test('observer wait polls once at the deadline before returning timeout', async () => {
+  const timeout = virtualDependencies([{ status: 'unchanged' }]);
+  assert.deepEqual(await waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1 }, timeout.dependencies), {
+    schema: OBSERVER_WAIT_SCHEMA,
+    status: 'timeout',
+    afterCursor: AFTER,
+    throughCursor: AFTER,
+  });
+  assert.deepEqual(timeout.counts(), { resolveCalls: 2, sleepCalls: 1, nowMs: 1000 });
+
+  const boundary = virtualDependencies([
+    { status: 'unchanged' },
+    { status: 'thread_switched', throughCursor: 'tlc1.boundary' },
+  ]);
+  assert.equal((await waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1 }, boundary.dependencies)).status, 'changed');
+  assert.deepEqual(boundary.counts(), { resolveCalls: 2, sleepCalls: 1, nowMs: 1000 });
+});
+
+test('observer wait preserves fail-closed cursor states', async () => {
+  for (const status of ['resync_required', 'ambiguous_parent']) {
+    const box = virtualDependencies([{ status }]);
+    assert.deepEqual(await waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER }, box.dependencies), {
+      schema: OBSERVER_WAIT_SCHEMA,
+      status,
+      afterCursor: AFTER,
+      throughCursor: null,
+    });
+  }
+});
+
+test('observer wait aborts before start and between polls without starting another resolver', async () => {
+  const already = new AbortController();
+  already.abort();
+  let called = 0;
+  await assert.rejects(
+    waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER, signal: already.signal }, { resolve: () => { called++; } }),
+    (error) => error instanceof ObserverWaitCancelledError && error.code === 'E_OBSERVER_WAIT_CANCELLED',
+  );
+  assert.equal(called, 0);
+
+  const during = new AbortController();
+  const box = virtualDependencies([{ status: 'unchanged' }]);
+  box.dependencies.sleep = async () => { during.abort(); };
+  await assert.rejects(
+    waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER, signal: during.signal }, box.dependencies),
+    { code: 'E_OBSERVER_WAIT_CANCELLED' },
+  );
+  assert.equal(box.counts().resolveCalls, 1);
+});
+
+test('observer wait removes its abort listener after a pending timer is cancelled', async () => {
+  const controller = new AbortController();
+  const pending = waitForObserverTurnChange(
+    { projectPath: '/repo', afterCursor: AFTER, signal: controller.signal },
+    { resolve: () => ({ status: 'unchanged' }), pollIntervalMs: 50 },
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(getEventListeners(controller.signal, 'abort').length, 1);
+  controller.abort();
+  await assert.rejects(pending, { code: 'E_OBSERVER_WAIT_CANCELLED' });
+  assert.equal(getEventListeners(controller.signal, 'abort').length, 0);
+});
+
+test('observer wait rejects invalid public inputs and resolver states', async () => {
+  for (const input of [
+    { projectPath: '/repo' },
+    { projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 0 },
+    { projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 3601 },
+    { projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1.5 },
+    { projectPath: '/repo', afterCursor: AFTER, signal: {} },
+  ]) {
+    await assert.rejects(waitForObserverTurnChange(input, { resolve: () => ({ status: 'unchanged' }) }), TypeError);
+  }
+  await assert.rejects(
+    waitForObserverTurnChange({ projectPath: '/repo', afterCursor: AFTER }, { resolve: () => ({ status: 'projection_pending' }) }),
+    /invalid state/,
+  );
+});

package/src/pending-handoff.mjs

@@ -0,0 +1,96 @@
+/**
+ * pending-handoff.mjs — 二相ハンドオフの intent 管理 (schema v9 pending_handoffs)
+ *
+ * 背景 (ADR 0014): Claude Code は同一 project_path に対して短時間 (実測 315–488ms) に
+ * 複数の SessionStart hook を発火させることがあり、その一部は transcript を一度も
+ * 生成しない「幽霊セッション」になる。SessionStart 時点では payload・DB のどこにも
+ * 実体と幽霊を判別する情報が存在しない（transcript ファイルは本物でも hook より
+ * 数百 ms 遅れて作られる）。
+ *
+ * したがって merge / 注入は「実体の証明」= 最初の UserPromptSubmit まで遅延する:
+ *   - SessionStart:  registerPendingHandoff で intent を登録するだけ
+ *   - 最初の prompt: consumePendingHandoff → baton / auto の順で merge + 注入
+ * 幽霊はプロンプトを一度も発火しないため、pending 行が残るだけで記憶を奪えない。
+ *
+ * pending 行の created_at はセッション誕生時刻として baton TTL 判定の基準
+ * (consumeBaton の bornAt) に使う。これにより「/tl からセッション開始までの猶予 1h」
+ * という従来の TTL 意味論を、消費が初回プロンプトまで遅れても保存する。
+ */
+
+/**
+ * SessionStart から呼ぶ。intent を登録する（merge も注入もしない）。
+ * resume / compact 由来の SessionStart でも再登録してよい（INSERT OR REPLACE）。
+ * その場合 created_at は再開時刻に更新され、従来の「SessionStart 時点で消費」と
+ * 同じ適格判定が初回プロンプト時に再現される。
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{
+ *   sessionId: string,
+ *   projectPath: string,
+ *   source: string | null,
+ *   autoPredecessorId?: string | null,
+ *   now?: number,
+ * }} params
+ */
+export function registerPendingHandoff(
+  db,
+  { sessionId, projectPath, source, autoPredecessorId = null, now = Date.now() },
+) {
+  db.prepare(
+    `INSERT INTO pending_handoffs (session_id, project_path, source, auto_predecessor_id, created_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(session_id) DO UPDATE SET
+       project_path = excluded.project_path,
+       source = excluded.source,
+       auto_predecessor_id = excluded.auto_predecessor_id,
+       created_at = excluded.created_at`,
+  ).run(sessionId, projectPath, source ?? null, autoPredecessorId ?? null, now);
+}
+
+/**
+ * UserPromptSubmit から呼ぶ。自セッションの pending 行を atomic に取り出して削除する。
+ * 行が無ければ null（= newborn ではない。ハンドオフ判定はしない）。
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{ sessionId: string }} params
+ * @returns {{
+ *   sessionId: string,
+ *   projectPath: string,
+ *   source: string | null,
+ *   autoPredecessorId: string | null,
+ *   createdAt: number,
+ * } | null}
+ */
+export function consumePendingHandoff(db, { sessionId }) {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const row = db
+      .prepare(
+        `SELECT session_id, project_path, source, auto_predecessor_id, created_at
+         FROM pending_handoffs WHERE session_id = ?`,
+      )
+      .get(sessionId);
+
+    if (!row) {
+      db.exec('COMMIT');
+      return null;
+    }
+
+    db.prepare('DELETE FROM pending_handoffs WHERE session_id = ?').run(sessionId);
+    db.exec('COMMIT');
+    return {
+      sessionId: row.session_id,
+      projectPath: row.project_path,
+      source: row.source ?? null,
+      autoPredecessorId: row.auto_predecessor_id ?? null,
+      createdAt: row.created_at,
+    };
+  } catch (err) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}