throughline 0.6.3 → 0.8.0

package/src/completed-turn-receipts.mjs

@@ -0,0 +1,374 @@
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  chmodSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import childProcess from 'node:child_process';
+import { homedir, platform as hostPlatform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { hashAuditorBody } from './body-digest.mjs';
+import { normalizeProjectPathForCompare } from './project-path.mjs';
+
+export const COMPLETED_TURN_RECEIPT_STORE_SCHEMA = 'throughline.completed_turn_receipts.v1';
+export const COMPLETED_TURN_RECEIPT_SCHEMA_VERSION = '1.0';
+export const COMPLETED_TURN_RECEIPT_LIMIT = 256;
+
+const PRIVATE_DIRECTORY_CAPABILITY = Symbol('throughline.completed-turn-receipt-directory');
+// CI実測でPowerShellコールドスタートが3.0〜3.2秒に達しflakeしたため15秒 (run 29586852389 / 29628634501)
+const WINDOWS_ACL_TIMEOUT_MS = 15_000;
+
+export function defaultCompletedTurnReceiptStorePath(projectSha256, env = process.env) {
+  if (!isSha256(projectSha256)) throw new TypeError('projectSha256 must be a SHA-256 digest');
+  const home = env.HOME || env.USERPROFILE || homedir();
+  if (isWindows(env)) {
+    return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
+  }
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
+}
+
+/**
+ * Captures one Claude Stop completion after its L2 user/assistant pair is durable in SQLite.
+ * The pair identity is immutable: a Stop retry returns the original receipt and never consumes
+ * another sequence number.
+ */
+export function writeCompletedTurnReceipt(input, options = {}) {
+  assertExactInput(input);
+  assertExactOptions(options);
+  const normalized = normalizeInput(input);
+  return withStoreLock(normalized, options, (privateDirectory) => {
+    const store = readStore(normalized, options, privateDirectory);
+    const existing = store.receipts.find((receipt) => samePair(receipt, normalized));
+    if (existing) return { ...existing };
+
+    const receipt = {
+      schema_version: COMPLETED_TURN_RECEIPT_SCHEMA_VERSION,
+      host: 'claude',
+      project_sha256: normalized.projectSha256,
+      target_session_id: normalized.targetSessionId,
+      origin_session_id: normalized.originSessionId,
+      user_sha256: normalized.userSha256,
+      assistant_sha256: normalized.assistantSha256,
+      completed_at: normalized.completedAt,
+      sequence: store.next_sequence,
+    };
+    store.next_sequence += 1;
+    store.receipts.push(receipt);
+    if (store.receipts.length > COMPLETED_TURN_RECEIPT_LIMIT) {
+      store.receipts.splice(0, store.receipts.length - COMPLETED_TURN_RECEIPT_LIMIT);
+      store.history_floor = store.receipts[0].sequence;
+    }
+    writeStore(store, normalized, options, privateDirectory);
+    return { ...receipt };
+  });
+}
+
+/** Read-only receipt snapshot. This never creates a directory, lock, or store file. */
+export function readCompletedTurnReceiptSnapshot(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) ||
+    Object.keys(input).some((key) => !['projectPath', 'env', 'storePath'].includes(key))) {
+    throw new TypeError('completed turn receipt snapshot options are invalid');
+  }
+  const { projectPath, env = process.env, storePath } = input;
+  const projectSha256 = sha256(normalizeProjectPathForCompare(assertProjectPath(projectPath)));
+  const options = { env, storePath };
+  const path = storePathFor({ projectSha256 }, options);
+  try {
+    const info = lstatSync(path);
+    assertPrivateFile(info, env, path);
+    assertPrivateDirectory(dirname(path), env);
+    const store = JSON.parse(readFileSync(path, 'utf8'));
+    validateStore(store, projectSha256);
+    return cloneStore(store);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return emptyStore(projectSha256);
+    throw error;
+  }
+}
+
+function normalizeInput(input) {
+  return {
+    projectSha256: sha256(normalizeProjectPathForCompare(assertProjectPath(input.projectPath))),
+    targetSessionId: normalizeIdentity(input.targetSessionId, 'targetSessionId'),
+    originSessionId: normalizeIdentity(input.originSessionId, 'originSessionId'),
+    userSha256: hashAuditorBody(assertBody(input.userBody)),
+    assistantSha256: hashAuditorBody(assertBody(input.assistantBody)),
+    completedAt: normalizeCompletionTimestamp(input.completedAt),
+  };
+}
+
+function emptyStore(projectSha256) {
+  return {
+    schema: COMPLETED_TURN_RECEIPT_STORE_SCHEMA,
+    project_sha256: projectSha256,
+    next_sequence: 1,
+    history_floor: 1,
+    receipts: [],
+  };
+}
+
+function readStore(normalized, options, privateDirectory) {
+  const path = storePathFor(normalized, options);
+  try {
+    const info = lstatSync(path);
+    assertPrivateFile(info, options.env, path);
+    assertPrivateDirectoryCapability(privateDirectory, dirname(path), options.env);
+    const store = JSON.parse(readFileSync(path, 'utf8'));
+    validateStore(store, normalized.projectSha256);
+    return store;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return emptyStore(normalized.projectSha256);
+    throw error;
+  }
+}
+
+function writeStore(store, normalized, options, privateDirectory) {
+  validateStore(store, normalized.projectSha256);
+  const path = storePathFor(normalized, options);
+  const directory = dirname(path);
+  assertPrivateDirectoryCapability(privateDirectory, directory, options.env);
+  const temporary = join(directory, `.completed-turn-receipts.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(store)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    if (isWindows(options.env)) {
+      applyAndVerifyWindowsAcl(temporary, false);
+      assertPrivateFileShape(lstatSync(temporary));
+    } else {
+      chmodSync(temporary, 0o600);
+    }
+    renameSync(temporary, path);
+    assertPrivateFile(lstatSync(path), options.env, path);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function withStoreLock(normalized, options, operation) {
+  const storePath = storePathFor(normalized, options);
+  const directory = dirname(storePath);
+  ensurePrivateDirectory(directory, options.env);
+  const lockPath = `${storePath}.lock.sqlite`;
+  let created = false;
+  try {
+    writeFileSync(lockPath, '', { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    created = true;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  if (created) {
+    if (isWindows(options.env)) applyAndVerifyWindowsAcl(lockPath, false);
+    else chmodSync(lockPath, 0o600);
+  }
+  assertPrivateFile(lstatSync(lockPath), options.env, lockPath);
+  const database = new DatabaseSync(lockPath);
+  let active = false;
+  try {
+    database.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL; BEGIN IMMEDIATE');
+    active = true;
+    const result = operation(privateDirectoryCapability(directory, options.env));
+    database.exec('COMMIT');
+    active = false;
+    return result;
+  } finally {
+    if (active) { try { database.exec('ROLLBACK'); } catch {} }
+    database.close();
+  }
+}
+
+function ensurePrivateDirectory(directory, env) {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const info = lstatSync(directory);
+  assertPrivateDirectoryShape(info);
+  if (isWindows(env)) applyAndVerifyWindowsAcl(directory, true);
+  else chmodSync(directory, 0o700);
+  assertPrivateDirectory(directory, env);
+}
+
+function privateDirectoryCapability(directory, env) {
+  return Object.freeze({ directory, windows: isWindows(env), [PRIVATE_DIRECTORY_CAPABILITY]: true });
+}
+
+function assertPrivateDirectoryCapability(capability, directory, env) {
+  if (!capability || capability[PRIVATE_DIRECTORY_CAPABILITY] !== true ||
+    capability.directory !== directory || capability.windows !== isWindows(env)) {
+    assertPrivateDirectory(directory, env);
+    return;
+  }
+  assertPrivateDirectoryShape(lstatSync(directory));
+}
+
+function assertPrivateDirectory(directory, env) {
+  const info = lstatSync(directory);
+  assertPrivateDirectoryShape(info);
+  if (isWindows(env)) verifyWindowsAcl(directory, true);
+  else assertPosixOwnerMode(info, 0o700);
+}
+
+function assertPrivateFile(info, env, path) {
+  assertPrivateFileShape(info);
+  if (isWindows(env)) verifyWindowsAcl(path, false);
+  else assertPosixOwnerMode(info, 0o600);
+}
+
+function assertPrivateDirectoryShape(info) {
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('completed turn receipt directory unsafe');
+}
+
+function assertPrivateFileShape(info) {
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error('completed turn receipt store path unsafe');
+}
+
+function assertPosixOwnerMode(info, expectedMode) {
+  if ((info.mode & 0o777) !== expectedMode) throw new Error('completed turn receipt permissions unsafe');
+  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) {
+    throw new Error('completed turn receipt owner unsafe');
+  }
+}
+
+function validateStore(store, expectedProjectSha256) {
+  if (!store || typeof store !== 'object' || Array.isArray(store) ||
+    !exactKeys(store, ['schema', 'project_sha256', 'next_sequence', 'history_floor', 'receipts']) ||
+    store.schema !== COMPLETED_TURN_RECEIPT_STORE_SCHEMA ||
+    store.project_sha256 !== expectedProjectSha256 || !isSha256(store.project_sha256) ||
+    !Number.isSafeInteger(store.next_sequence) || store.next_sequence < 1 ||
+    !Number.isSafeInteger(store.history_floor) || store.history_floor < 1 || store.history_floor > store.next_sequence ||
+    !Array.isArray(store.receipts) || store.receipts.length > COMPLETED_TURN_RECEIPT_LIMIT) {
+    throw new Error('completed turn receipt store schema invalid');
+  }
+  const identities = new Set();
+  for (const [index, receipt] of store.receipts.entries()) {
+    validateReceipt(receipt, store.next_sequence);
+    const identity = receiptIdentity(receipt);
+    if (identities.has(identity) || receipt.project_sha256 !== store.project_sha256 ||
+      receipt.sequence !== store.history_floor + index) {
+      throw new Error('completed turn receipt uniqueness invalid');
+    }
+    identities.add(identity);
+  }
+  if (store.receipts.length > 0 && store.history_floor !== store.receipts[0].sequence) {
+    throw new Error('completed turn receipt history floor invalid');
+  }
+  if (store.receipts.length === 0 && store.history_floor !== store.next_sequence) {
+    throw new Error('completed turn receipt history floor invalid');
+  }
+  if (store.receipts.length > 0 && store.next_sequence !== store.history_floor + store.receipts.length) {
+    throw new Error('completed turn receipt sequence continuity invalid');
+  }
+}
+
+function validateReceipt(receipt, nextSequence) {
+  const keys = [
+    'schema_version', 'host', 'project_sha256', 'target_session_id', 'origin_session_id',
+    'user_sha256', 'assistant_sha256', 'completed_at', 'sequence',
+  ];
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt) ||
+    !exactKeys(receipt, keys) || receipt.schema_version !== COMPLETED_TURN_RECEIPT_SCHEMA_VERSION ||
+    receipt.host !== 'claude' || !isSha256(receipt.project_sha256) ||
+    !isIdentity(receipt.target_session_id) || !isIdentity(receipt.origin_session_id) ||
+    !isSha256(receipt.user_sha256) || !isSha256(receipt.assistant_sha256) ||
+    !Number.isSafeInteger(receipt.completed_at) || receipt.completed_at < 0 ||
+    !Number.isSafeInteger(receipt.sequence) || receipt.sequence < 1 || receipt.sequence >= nextSequence) {
+    throw new Error('completed turn receipt value invalid');
+  }
+}
+
+function samePair(receipt, input) {
+  return receipt.project_sha256 === input.projectSha256 &&
+    receipt.origin_session_id === input.originSessionId &&
+    receipt.user_sha256 === input.userSha256 &&
+    receipt.assistant_sha256 === input.assistantSha256;
+}
+
+function receiptIdentity(receipt) {
+  return [receipt.project_sha256, receipt.origin_session_id,
+    receipt.user_sha256, receipt.assistant_sha256].join('\0');
+}
+
+function assertBody(value) {
+  if (typeof value !== 'string') throw new TypeError('receipt body must be a string');
+  return value;
+}
+
+function normalizeIdentity(value, name) {
+  if (!isIdentity(value)) throw new TypeError(`${name} must be a non-empty string`);
+  return value;
+}
+
+function normalizeCompletionTimestamp(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new TypeError('completedAt must be a non-negative integer');
+  return value;
+}
+
+function assertProjectPath(value) {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError('projectPath must be a non-empty string');
+  return value;
+}
+
+function storePathFor(normalized, options) {
+  return options.storePath || defaultCompletedTurnReceiptStorePath(normalized.projectSha256, options.env);
+}
+
+function cloneStore(store) {
+  return {
+    schema: store.schema,
+    project_sha256: store.project_sha256,
+    next_sequence: store.next_sequence,
+    history_floor: store.history_floor,
+    receipts: store.receipts.map((receipt) => ({ ...receipt })),
+  };
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+function isSha256(value) { return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value); }
+function isIdentity(value) { return typeof value === 'string' && value.length > 0 && value.length <= 4096; }
+function exactKeys(value, keys) {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every((key) => actual.includes(key));
+}
+function assertExactInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) ||
+    !exactKeys(input, ['projectPath', 'targetSessionId', 'originSessionId', 'userBody', 'assistantBody', 'completedAt'])) {
+    throw new TypeError('completed turn receipt input is invalid');
+  }
+}
+function assertExactOptions(options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options) ||
+    Object.keys(options).some((key) => !['env', 'storePath'].includes(key))) {
+    throw new TypeError('completed turn receipt options are invalid');
+  }
+}
+function isWindows(env = process.env) { return env.OS === 'Windows_NT' || hostPlatform() === 'win32'; }
+
+function applyAndVerifyWindowsAcl(path, directory) { runWindowsAclScript(path, directory, WINDOWS_ACL_APPLY_SCRIPT); }
+function verifyWindowsAcl(path, directory) { runWindowsAclScript(path, directory, WINDOWS_ACL_VERIFY_SCRIPT); }
+function runWindowsAclScript(path, directory, script) {
+  const result = childProcess.spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    env: { ...process.env, THROUGHLINE_ACL_PATH: path, THROUGHLINE_ACL_DIRECTORY: directory ? '1' : '0' },
+    stdio: 'ignore', timeout: WINDOWS_ACL_TIMEOUT_MS, windowsHide: true,
+  });
+  if (result.status !== 0) throw new Error('Windows owner-only ACL verification failed');
+}
+
+const WINDOWS_ACL_VERIFY_SCRIPT = String.raw`
+$p=$env:THROUGHLINE_ACL_PATH; $isDir=$env:THROUGHLINE_ACL_DIRECTORY -eq '1'; $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$acl=if($isDir){[System.IO.Directory]::GetAccessControl($p)}else{[System.IO.File]::GetAccessControl($p)}
+$owner=$acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
+if($owner -ne $sid){exit 41}; $rules=@($acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])); if($rules.Count -ne 1){exit 42}
+$r=$rules[0]; if($r.IdentityReference.Value -ne $sid -or $r.AccessControlType -ne 'Allow' -or $r.IsInherited -or ($r.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::FullControl) -ne [System.Security.AccessControl.FileSystemRights]::FullControl){exit 43}
+`;
+
+const WINDOWS_ACL_APPLY_SCRIPT = String.raw`
+$p=$env:THROUGHLINE_ACL_PATH; $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$isDir=$env:THROUGHLINE_ACL_DIRECTORY -eq '1'; $acl=if($isDir){New-Object System.Security.AccessControl.DirectorySecurity}else{New-Object System.Security.AccessControl.FileSecurity}; $acl.SetAccessRuleProtection($true,$false)
+$flags=if($isDir){[System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'}else{[System.Security.AccessControl.InheritanceFlags]::None}
+$rule=New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl',$flags,[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow)
+$acl.SetOwner($sid); $acl.AddAccessRule($rule); if($isDir){[System.IO.Directory]::SetAccessControl($p,$acl)}else{[System.IO.File]::SetAccessControl($p,$acl)}
+` + WINDOWS_ACL_VERIFY_SCRIPT;

package/src/completed-turn-receipts.test.mjs

@@ -0,0 +1,186 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import {
+  COMPLETED_TURN_RECEIPT_LIMIT,
+  COMPLETED_TURN_RECEIPT_STORE_SCHEMA,
+  defaultCompletedTurnReceiptStorePath,
+  readCompletedTurnReceiptSnapshot,
+  writeCompletedTurnReceipt,
+} from './completed-turn-receipts.mjs';
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), 'throughline-completed-receipts-'));
+  return { root, storePath: join(root, 'state', 'completed-turn-receipts.json') };
+}
+
+function input(index = 1) {
+  return {
+    projectPath: '/repo', targetSessionId: 'target', originSessionId: 'origin',
+    userBody: `user ${index}`, assistantBody: `assistant ${index}`, completedAt: index,
+  };
+}
+
+test('completed turn receipt: private atomic store records only identities and hashes', () => {
+  const box = sandbox();
+  try {
+    const receipt = writeCompletedTurnReceipt(input(), { storePath: box.storePath });
+    assert.equal(receipt.schema_version, '1.0');
+    assert.equal(receipt.host, 'claude');
+    assert.equal(receipt.sequence, 1);
+    assert.match(receipt.project_sha256, /^[0-9a-f]{64}$/);
+    assert.match(receipt.user_sha256, /^[0-9a-f]{64}$/);
+    assert.match(receipt.assistant_sha256, /^[0-9a-f]{64}$/);
+    const bytes = readFileSync(box.storePath, 'utf8');
+    assert.doesNotMatch(bytes, /user 1|assistant 1|\/repo/);
+    const stored = JSON.parse(bytes);
+    assert.equal(stored.schema, COMPLETED_TURN_RECEIPT_STORE_SCHEMA);
+    assert.equal(stored.history_floor, 1);
+    assert.equal(stored.receipts.length, 1);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: same project/session/pair is idempotent and keeps its sequence', () => {
+  const box = sandbox();
+  try {
+    const first = writeCompletedTurnReceipt(input(), { storePath: box.storePath });
+    const retry = writeCompletedTurnReceipt({ ...input(), completedAt: 999 }, { storePath: box.storePath });
+    assert.deepEqual(retry, first);
+    const next = writeCompletedTurnReceipt(input(2), { storePath: box.storePath });
+    assert.equal(next.sequence, 2);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: target変更を伴う同一origin/pairの再実行は冪等', () => {
+  const box = sandbox();
+  try {
+    const first = writeCompletedTurnReceipt(input(), { storePath: box.storePath });
+    const retriedAfterMerge = writeCompletedTurnReceipt({ ...input(), targetSessionId: 'merged-target' }, { storePath: box.storePath });
+    assert.deepEqual(retriedAfterMerge, first);
+    assert.equal(retriedAfterMerge.target_session_id, 'target', 'capture時targetを保持する');
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: project digest shares realpath canonicalization with the DB projection', {
+  skip: process.platform === 'win32',
+}, () => {
+  const box = sandbox();
+  const project = join(box.root, 'project');
+  const alias = join(box.root, 'project-alias');
+  try {
+    mkdirSync(project);
+    symlinkSync(project, alias);
+    const direct = writeCompletedTurnReceipt({ ...input(), projectPath: project }, { storePath: box.storePath });
+    const viaAlias = writeCompletedTurnReceipt({ ...input(), projectPath: alias }, { storePath: box.storePath });
+    assert.deepEqual(viaAlias, direct);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: rejects symlinked store paths', { skip: process.platform === 'win32' }, () => {
+  const box = sandbox();
+  const target = join(box.root, 'target.json');
+  try {
+    mkdirSync(dirname(box.storePath), { recursive: true });
+    symlinkSync(target, box.storePath);
+    assert.throws(() => writeCompletedTurnReceipt(input(), { storePath: box.storePath }), /unsafe/);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: bounded store drops only oldest receipts', () => {
+  const box = sandbox();
+  try {
+    for (let index = 1; index <= COMPLETED_TURN_RECEIPT_LIMIT + 1; index++) {
+      writeCompletedTurnReceipt({ ...input(index), targetSessionId: `target-${index}` }, { storePath: box.storePath });
+    }
+    const stored = JSON.parse(readFileSync(box.storePath, 'utf8'));
+    assert.equal(stored.receipts.length, COMPLETED_TURN_RECEIPT_LIMIT);
+    assert.equal(stored.history_floor, 2);
+    assert.equal(stored.receipts[0].sequence, 2);
+    assert.equal(stored.receipts.at(-1).sequence, COMPLETED_TURN_RECEIPT_LIMIT + 1);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: noisy project cannot evict another project anchor', () => {
+  const box = sandbox();
+  const env = { HOME: box.root, USERPROFILE: box.root, XDG_STATE_HOME: join(box.root, 'state-home') };
+  try {
+    const quiet = writeCompletedTurnReceipt({ ...input(), projectPath: '/quiet-project' }, { env });
+    for (let index = 1; index <= COMPLETED_TURN_RECEIPT_LIMIT + 1; index++) {
+      writeCompletedTurnReceipt({ ...input(index), projectPath: '/noisy-project', targetSessionId: `target-${index}` }, { env });
+    }
+    const quietStorePath = defaultCompletedTurnReceiptStorePath(quiet.project_sha256, env);
+    const quietStore = JSON.parse(readFileSync(quietStorePath, 'utf8'));
+    assert.equal(quietStore.receipts.length, 1);
+    assert.equal(quietStore.receipts[0].sequence, 1);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: explicit store path rejects a second project', () => {
+  const box = sandbox();
+  try {
+    writeCompletedTurnReceipt({ ...input(), projectPath: '/project-a' }, { storePath: box.storePath });
+    assert.throws(
+      () => writeCompletedTurnReceipt({ ...input(), projectPath: '/project-b' }, { storePath: box.storePath }),
+      /schema invalid/,
+    );
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: read-only snapshot validates project binding and does not create missing state', () => {
+  const box = sandbox();
+  try {
+    const missing = readCompletedTurnReceiptSnapshot({ projectPath: '/missing-project', storePath: box.storePath });
+    assert.equal(missing.receipts.length, 0);
+    assert.throws(() => readFileSync(box.storePath));
+    writeCompletedTurnReceipt({ ...input(), projectPath: '/project-a' }, { storePath: box.storePath });
+    assert.throws(
+      () => readCompletedTurnReceiptSnapshot({ projectPath: '/project-b', storePath: box.storePath }),
+      /schema invalid/,
+    );
+    assert.throws(() => readCompletedTurnReceiptSnapshot({ projectPath: '/project-a', unknown: true }), /options are invalid/);
+    assert.throws(() => readCompletedTurnReceiptSnapshot({ projectPath: null }), /projectPath/);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: rejects sequence order corruption', () => {
+  const box = sandbox();
+  try {
+    writeCompletedTurnReceipt(input(1), { storePath: box.storePath });
+    writeCompletedTurnReceipt(input(2), { storePath: box.storePath });
+    const store = JSON.parse(readFileSync(box.storePath, 'utf8'));
+    [store.receipts[0], store.receipts[1]] = [store.receipts[1], store.receipts[0]];
+    writeFileSync(box.storePath, `${JSON.stringify(store)}\n`);
+    assert.throws(() => writeCompletedTurnReceipt(input(3), { storePath: box.storePath }), /uniqueness invalid/);
+  } finally {
+    rmSync(box.root, { recursive: true, force: true });
+  }
+});
+
+test('completed turn receipt: Windows path uses LocalAppData', () => {
+  const env = { OS: 'Windows_NT', USERPROFILE: 'C:\\Users\\kite', LOCALAPPDATA: 'C:\\Users\\kite\\AppData\\Local' };
+  const projectSha256 = 'a'.repeat(64);
+  assert.equal(
+    defaultCompletedTurnReceiptStorePath(projectSha256, env),
+    join(env.LOCALAPPDATA, 'throughline', 'completed-turn-receipts', `${projectSha256}.json`),
+  );
+});

package/src/db-schema.test.mjs

@@ -38,10 +38,10 @@ function indexNames(db) {
     .map((row) => row.name);
 }
 
-test('schema v8 preserves Claude-facing tables, fields, and unique indexes', async () => {
+test('schema v9 preserves Claude-facing tables, fields, and unique indexes', async () => {
   await withIsolatedDb((db) => {
     const version = db.prepare('PRAGMA user_version').get();
-    assert.equal(version.user_version, 8);
+    assert.equal(version.user_version, 9);
 
     assert.deepEqual(columnNames(db, 'sessions'), [
       'session_id',
@@ -88,6 +88,13 @@ test('schema v8 preserves Claude-facing tables, fields, and unique indexes', asy
       'session_id',
       'created_at',
     ]);
+    assert.deepEqual(columnNames(db, 'pending_handoffs'), [
+      'session_id',
+      'project_path',
+      'source',
+      'auto_predecessor_id',
+      'created_at',
+    ]);
 
     const indexes = indexNames(db);
     assert.ok(indexes.includes('uq_skeletons_turn_v3'));

package/src/db.mjs

@@ -9,7 +9,7 @@ import { join } from 'path';
 
 const DB_DIR = join(homedir(), '.throughline');
 const DB_PATH = join(DB_DIR, 'throughline.db');
-export const CURRENT_VERSION = 8;
+export const CURRENT_VERSION = 9;
 
 let _db = null;
 
@@ -215,6 +215,25 @@ function initSchema(db) {
     }
   }
 
+  // v8 → v9: pending_handoffs テーブル追加（二相ハンドオフ）。
+  // SessionStart は merge / 注入をせず intent をここに登録するだけ。
+  // 最初の UserPromptSubmit（= セッション実在の証明。幽霊 SessionStart は
+  // プロンプトを一度も発火しない）が原子的に consume して merge + 注入する。
+  // auto path (source='clear') の前任は SessionStart 時点で解決して凍結する。
+  // 幽霊の pending 行は誰にも consume されず無害に残る（行は数百バイト）。
+  // 経緯: 2026-07-17 の baton 幽霊奪取 incident（ADR 0014）。
+  if (version < 9) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS pending_handoffs (
+        session_id          TEXT    PRIMARY KEY,
+        project_path        TEXT    NOT NULL,
+        source              TEXT,
+        auto_predecessor_id TEXT,
+        created_at          INTEGER NOT NULL
+      );
+    `);
+  }
+
   if (version < CURRENT_VERSION) {
     db.exec(`PRAGMA user_version = ${CURRENT_VERSION}`);
   }

package/src/decision-log.mjs

@@ -0,0 +1,24 @@
+/**
+ * decision-log.mjs — 引き継ぎ判定ログ (~/.throughline/logs/inheritance-decision.log)
+ *
+ * 二相ハンドオフでは SessionStart (intent 登録) と UserPromptSubmit (consume + merge)
+ * の両方が判定に関与するため、共有モジュールに切り出す。各エントリは `phase` field
+ * ('session-start' | 'prompt-submit') で区別する。
+ * このログは 2026-07-17 の幽霊バトン奪取 incident の一次証拠になった実績があり、
+ * 事故調査の生命線。書き込み失敗は stderr に出す（黙って握りつぶさない）。
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export function logDecision(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'inheritance-decision.log');
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[decision-log] ${msg}\n`);
+  }
+}