throughline 0.6.3 → 0.8.0

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 });
+  }
+});

package/src/cli/observer-wait.mjs

@@ -0,0 +1,123 @@
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import {
+  OBSERVER_WAIT_SCHEMA,
+  DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS,
+  waitForObserverTurnChange,
+} from '../observer-turn-wait.mjs';
+
+const ERRORS = Object.freeze({
+  args: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_ARGS', message: 'invalid observer-wait arguments' },
+  input: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_INPUT', message: 'observer wait input is invalid' },
+  cancelled: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_CANCELLED', message: 'observer wait was cancelled' },
+  internal: { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_INTERNAL', message: 'observer wait failed' },
+});
+const PARENT_WATCH_INTERVAL_MS = 1000;
+
+export function parseArgs(argv = []) {
+  const out = { projectPath: null, afterCursor: null, timeoutSeconds: DEFAULT_OBSERVER_WAIT_TIMEOUT_SECONDS, 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', '--timeout-seconds'].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 out.timeoutSeconds = parseTimeout(value);
+  }
+  if (!out.json || !out.projectPath || !out.afterCursor) throw new TypeError('missing required option');
+  return out;
+}
+
+export async function run(argv = [], {
+  wait = waitForObserverTurnChange,
+  validateProject = assertProjectDirectory,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  processRef = process,
+  setIntervalFn = setInterval,
+  clearIntervalFn = clearInterval,
+  parentWatchIntervalMs = PARENT_WATCH_INTERVAL_MS,
+} = {}) {
+  let args;
+  try { args = parseArgs(argv); } catch { writeJson(stderr, ERRORS.args); return 1; }
+
+  try { validateProject(args.projectPath); } catch { writeJson(stderr, ERRORS.input); return 1; }
+
+  const controller = new AbortController();
+  const cleanup = installCancellation({ controller, processRef, setIntervalFn, clearIntervalFn, parentWatchIntervalMs });
+  try {
+    const result = await wait({
+      projectPath: args.projectPath,
+      afterCursor: args.afterCursor,
+      timeoutSeconds: args.timeoutSeconds,
+      signal: controller.signal,
+    });
+    writeJson(stdout, result);
+    return 0;
+  } catch (error) {
+    writeJson(stderr, mapError(error));
+    return 1;
+  } finally {
+    cleanup();
+  }
+}
+
+function parseTimeout(value) {
+  if (!/^\d+$/.test(value)) throw new TypeError('invalid timeout');
+  const timeout = Number(value);
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600) throw new TypeError('invalid timeout');
+  return timeout;
+}
+
+function assertProjectDirectory(projectPath) {
+  if (!isAbsolute(projectPath) || !statSync(projectPath).isDirectory()) {
+    throw new TypeError('project must be an absolute existing directory');
+  }
+}
+
+function installCancellation({ controller, processRef, setIntervalFn, clearIntervalFn, parentWatchIntervalMs }) {
+  const abort = () => controller.abort();
+  const parentPid = processRef.ppid;
+  processRef.on('SIGINT', abort);
+  processRef.on('SIGTERM', abort);
+  processRef.on('disconnect', abort);
+
+  let parentTimer = null;
+  if (Number.isSafeInteger(parentPid) && parentPid > 1) {
+    const checkParent = () => {
+      if (processRef.ppid !== parentPid) return abort();
+      try {
+        processRef.kill(parentPid, 0);
+      } catch (error) {
+        if (error?.code === 'ESRCH') abort();
+      }
+    };
+    parentTimer = setIntervalFn(checkParent, parentWatchIntervalMs);
+    parentTimer?.unref?.();
+  }
+
+  return () => {
+    processRef.removeListener('SIGINT', abort);
+    processRef.removeListener('SIGTERM', abort);
+    processRef.removeListener('disconnect', abort);
+    if (parentTimer !== null) clearIntervalFn(parentTimer);
+  };
+}
+
+function mapError(error) {
+  if (error?.code === 'E_OBSERVER_WAIT_CANCELLED') return ERRORS.cancelled;
+  return ERRORS.internal;
+}
+
+function writeJson(stream, value) { stream.write(`${JSON.stringify(value)}\n`); }
+
+export const _internal = { assertProjectDirectory, installCancellation, PARENT_WATCH_INTERVAL_MS };

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

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { EventEmitter, getEventListeners } from 'node:events';
+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_WAIT_SCHEMA } from '../observer-turn-wait.mjs';
+import { parseArgs, run } from './observer-wait.mjs';
+
+const REPO_ROOT = join(fileURLToPath(new URL('../..', import.meta.url)));
+const BIN_PATH = join(REPO_ROOT, 'bin/throughline.mjs');
+const AFTER = 'tlc1.after';
+
+function streams() {
+  return { stdout: { text: '', write(value) { this.text += value; } }, stderr: { text: '', write(value) { this.text += value; } } };
+}
+
+function fakeProcess({ ppid = 42, kill = () => {} } = {}) {
+  const result = new EventEmitter();
+  result.ppid = ppid;
+  result.kill = kill;
+  return result;
+}
+
+test('observer-wait strictly parses its public arguments', async () => {
+  assert.deepEqual(parseArgs(['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '1', '--json']), {
+    projectPath: '/repo', afterCursor: AFTER, timeoutSeconds: 1, json: true,
+  });
+  assert.equal(parseArgs(['--project', '/repo', '--after-cursor', AFTER, '--json']).timeoutSeconds, 3600);
+  for (const argv of [
+    ['--project', '/repo', '--project', '/repo', '--after-cursor', AFTER, '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--json', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '0', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, '--timeout-seconds', '3601', '--json'],
+    ['--project', '/repo', '--after-cursor', AFTER, 'extra', '--json'],
+    ['--project', '/repo', '--json'],
+  ]) {
+    const io = streams();
+    assert.equal(await run(argv, { ...io }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.deepEqual(JSON.parse(io.stderr.text), { schema: OBSERVER_WAIT_SCHEMA, status: 'error', code: 'E_OBSERVER_WAIT_ARGS', message: 'invalid observer-wait arguments' });
+  }
+});
+
+test('observer-wait returns each known core status as successful JSON', async () => {
+  for (const [status, throughCursor] of [['changed', 'tlc1.changed'], ['timeout', AFTER], ['resync_required', null], ['ambiguous_parent', null]]) {
+    const io = streams();
+    assert.equal(await run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io,
+      validateProject: () => {},
+      processRef: fakeProcess(),
+      setIntervalFn: () => ({ unref() {} }), clearIntervalFn: () => {},
+      wait: async () => ({ schema: OBSERVER_WAIT_SCHEMA, status, afterCursor: AFTER, throughCursor }),
+    }), 0);
+    assert.deepEqual(JSON.parse(io.stdout.text), { schema: OBSERVER_WAIT_SCHEMA, status, afterCursor: AFTER, throughCursor });
+    assert.equal(io.stderr.text, '');
+  }
+});
+
+test('observer-wait maps project, cancel, and internal failures to fixed errors without leakage', async () => {
+  for (const [dependencies, code] of [
+    [{ validateProject: () => { throw new Error('/private/project'); } }, 'E_OBSERVER_WAIT_INPUT'],
+    [{ wait: async () => { throw Object.assign(new Error('secret cursor'), { code: 'E_OBSERVER_WAIT_CANCELLED' }); } }, 'E_OBSERVER_WAIT_CANCELLED'],
+    [{ wait: async () => { throw new Error('secret /private/cursor'); } }, 'E_OBSERVER_WAIT_INTERNAL'],
+  ]) {
+    const io = streams();
+    assert.equal(await run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef: fakeProcess(),
+      setIntervalFn: () => ({ unref() {} }), clearIntervalFn: () => {}, ...dependencies,
+    }), 1);
+    assert.equal(io.stdout.text, '');
+    assert.equal(JSON.parse(io.stderr.text).code, code);
+    assert.doesNotMatch(io.stderr.text, /private|secret|cursor/i);
+  }
+});
+
+test('observer-wait cancels on signals and removes listeners and parent watcher', async () => {
+  for (const event of ['SIGINT', 'SIGTERM', 'disconnect']) {
+    const io = streams();
+    const processRef = fakeProcess();
+    let checkParent;
+    let cleared = 0;
+    const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef,
+      setIntervalFn(callback) { checkParent = callback; return { unref() {} }; },
+      clearIntervalFn() { cleared++; },
+      wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(getEventListeners(processRef, 'SIGINT').length, 1);
+    assert.equal(getEventListeners(processRef, 'SIGTERM').length, 1);
+    assert.equal(getEventListeners(processRef, 'disconnect').length, 1);
+    assert.equal(typeof checkParent, 'function');
+    processRef.emit(event);
+    assert.equal(await pending, 1);
+    assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+    assert.equal(cleared, 1);
+    assert.equal(getEventListeners(processRef, 'SIGINT').length, 0);
+    assert.equal(getEventListeners(processRef, 'SIGTERM').length, 0);
+    assert.equal(getEventListeners(processRef, 'disconnect').length, 0);
+  }
+});
+
+test('observer-wait treats changed parent or ESRCH as cancellation but not EPERM', async () => {
+  for (const [mode, kill] of [
+    ['ppid', () => {}],
+    ['esrch', () => { throw Object.assign(new Error('gone'), { code: 'ESRCH' }); }],
+  ]) {
+    const io = streams();
+    const processRef = fakeProcess({ kill });
+    let checkParent;
+    const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+      ...io, validateProject: () => {}, processRef,
+      setIntervalFn(callback) { checkParent = callback; return { unref() {} }; }, clearIntervalFn: () => {},
+      wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+    });
+    await new Promise((resolve) => setImmediate(resolve));
+    if (mode === 'ppid') processRef.ppid = 1;
+    checkParent();
+    assert.equal(await pending, 1);
+    assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+  }
+
+  const io = streams();
+  const processRef = fakeProcess({ kill: () => { throw Object.assign(new Error('denied'), { code: 'EPERM' }); } });
+  let checkParent;
+  const pending = run(['--project', '/repo', '--after-cursor', AFTER, '--json'], {
+    ...io, validateProject: () => {}, processRef,
+    setIntervalFn(callback) { checkParent = callback; return { unref() {} }; }, clearIntervalFn: () => {},
+    wait: ({ signal }) => new Promise((resolve, reject) => signal.addEventListener('abort', () => reject(Object.assign(new Error('cancelled'), { code: 'E_OBSERVER_WAIT_CANCELLED' })), { once: true })),
+  });
+  await new Promise((resolve) => setImmediate(resolve));
+  checkParent();
+  assert.equal(io.stderr.text, '');
+  processRef.emit('disconnect');
+  assert.equal(await pending, 1);
+  assert.equal(JSON.parse(io.stderr.text).code, 'E_OBSERVER_WAIT_CANCELLED');
+});
+
+test('observer-wait bin dispatch and help use the JSON-only contract', async () => {
+  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-wait --project <absolute-directory> --after-cursor <opaque> --json/);
+
+  const root = await mkdtemp(join(tmpdir(), 'throughline-observer-wait-'));
+  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-wait', '--project', project, '--after-cursor', 'invalid', '--json'], {
+      cwd: REPO_ROOT, encoding: 'utf8', timeout: 5000,
+      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 output = JSON.parse(result.stdout);
+    assert.equal(output.schema, OBSERVER_WAIT_SCHEMA);
+    assert.equal(output.status, 'resync_required');
+    assert.equal(output.throughCursor, null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/cli/recall.mjs

@@ -0,0 +1,279 @@
+/**
+ * `throughline recall` — 注入案内から辿る pull 用の DB 直参照 CLI (read-only)
+ *
+ * 注入（push）は「現在地 + 入るだけの L2」だけを運び、残りの記憶は本コマンドで
+ * 必要な時だけ取得する（オーナー裁定 2026-07-18、ADR 0016）:
+ *   - `recall --l2 --session <id> --before <ISO日時> --last <N>`
+ *       境界（strict less-than, ms 比較）より古いターンを新しい側から N 件、
+ *       L2 全文（注入と同じ行文法 + L3 参照 suffix）で出す。
+ *   - `recall --l1 --session <id> --before <ISO日時> --skip <N>`
+ *       境界から N 件（--l2 の担当分）を飛ばした先の全ターン一覧。
+ *       L1 要約があれば要約、無ければ「未要約」と明示して detail 誘導を出す。
+ *
+ * 契約:
+ *   - 範囲・境界・session は注入時に案内コマンドへ焼き込まれた値だけで決まる。
+ *     recall 側で「現在の 20 ターン窓」を再計算しない（新セッションのターン追記で
+ *     窓がスライドし、古い側が黙って欠落するため）。
+ *   - DB は read-only で開く（create / migrate / write なし）。DB が無ければ
+ *     explicit error で終了する。
+ *   - 既定 session 解決は持たない。案内コマンドが常に `--session` を運ぶ。
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { formatTime } from '../handoff-record.mjs';
+import { groupL3ByTurn, buildPartsSummary } from '../l3-summary.mjs';
+
+export function defaultRecallDbPath() {
+  return join(homedir(), '.throughline', 'throughline.db');
+}
+
+const USAGE =
+  'usage: throughline recall (--l2 --last <N> | --l1 [--skip <N>] [--last <N>]) ' +
+  '--session <id> --before <ISO8601> [--db <path>]';
+
+export function parseRecallArgs(argv) {
+  const opts = {
+    mode: null,
+    sessionId: null,
+    beforeMs: null,
+    last: null,
+    skip: 0,
+    dbPath: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--l2' || a === '--l1') {
+      if (opts.mode) throw new Error('recall: --l2 と --l1 は同時に指定できません');
+      opts.mode = a.slice(2);
+    } else if (a === '--session') {
+      opts.sessionId = argv[++i];
+    } else if (a === '--before') {
+      const raw = argv[++i];
+      const ms = Date.parse(raw ?? '');
+      if (!Number.isFinite(ms)) {
+        throw new Error(`recall: --before の日時を解釈できません: ${raw}（ISO 8601 を指定）`);
+      }
+      opts.beforeMs = ms;
+    } else if (a === '--last') {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n < 0) throw new Error('recall: --last は 0 以上の整数');
+      opts.last = n;
+    } else if (a === '--skip') {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n < 0) throw new Error('recall: --skip は 0 以上の整数');
+      opts.skip = n;
+    } else if (a === '--db') {
+      opts.dbPath = argv[++i];
+    } else {
+      throw new Error(`recall: 未知の引数: ${a}\n${USAGE}`);
+    }
+  }
+  if (!opts.mode) throw new Error(`recall: --l2 または --l1 を指定してください\n${USAGE}`);
+  if (!opts.sessionId) throw new Error(`recall: --session は必須です\n${USAGE}`);
+  if (opts.beforeMs == null) throw new Error(`recall: --before は必須です\n${USAGE}`);
+  if (opts.mode === 'l2' && opts.last == null) {
+    throw new Error(`recall: --l2 には --last <N> が必須です\n${USAGE}`);
+  }
+  return opts;
+}
+
+/**
+ * 境界より古い側の distinct ターンを新しい順に列挙する。
+ * 各要素: { originSessionId, turnNumber, turnKey, minCreatedAt }
+ */
+function listTurnsBefore(db, { sessionId, beforeMs }) {
+  const rows = db
+    .prepare(
+      `SELECT origin_session_id, turn_number, MIN(created_at) AS min_ca, MAX(created_at) AS max_ca
+       FROM bodies
+       WHERE session_id = ? AND created_at < ?
+       GROUP BY origin_session_id, turn_number
+       ORDER BY min_ca DESC`,
+    )
+    .all(sessionId, beforeMs);
+  return rows.map((r) => ({
+    originSessionId: r.origin_session_id,
+    turnNumber: r.turn_number,
+    turnKey: `${r.origin_session_id}\x00${r.turn_number}`,
+    minCreatedAt: r.min_ca,
+    maxCreatedAt: r.max_ca,
+  }));
+}
+
+function loadL3ForTurns(db, sessionId, turns) {
+  if (turns.length === 0) return [];
+  const placeholders = turns.map(() => '(?, ?, ?)').join(', ');
+  const params = turns.flatMap((t) => [sessionId, t.originSessionId, Number(t.turnNumber)]);
+  return db
+    .prepare(
+      `SELECT kind, tool_name, origin_session_id, turn_number, created_at
+       FROM details
+       WHERE (session_id, origin_session_id, turn_number) IN (VALUES ${placeholders})
+       ORDER BY created_at ASC, id ASC`,
+    )
+    .all(...params)
+    .map((r) => ({
+      kind: r.kind,
+      toolName: r.tool_name,
+      originSessionId: r.origin_session_id,
+      turnNumber: r.turn_number,
+      createdAt: r.created_at,
+    }));
+}
+
+/**
+ * --l2: 境界より古いターンを新しい側から last 件、古い順の L2 全文で描画する。
+ */
+export function renderRecallL2(db, { sessionId, beforeMs, last }) {
+  const turnsDesc = listTurnsBefore(db, { sessionId, beforeMs });
+  const selected = turnsDesc.slice(0, last).reverse(); // 古い順に戻す
+  const lines = [];
+
+  if (selected.length === 0) {
+    lines.push(`## Throughline recall (L2): 該当ターンなし（--before ${new Date(beforeMs).toISOString()} より古い L2 が DB にありません）`);
+    return { text: lines.join('\n'), turnCount: 0 };
+  }
+
+  const range = `${formatTime(selected[0].minCreatedAt)}〜${formatTime(selected[selected.length - 1].maxCreatedAt)}`;
+  lines.push(`## Throughline recall (L2): ${selected.length}ターン (${range}, 古い順)`);
+  if (selected.length < last) {
+    lines.push(`（--last ${last} のうち DB に存在するのは ${selected.length} ターンのみ）`);
+  }
+  lines.push('');
+
+  const l3ByTurn = groupL3ByTurn(loadL3ForTurns(db, sessionId, selected));
+
+  const bodyStmt = db.prepare(
+    `SELECT role, text, created_at
+     FROM bodies
+     WHERE session_id = ? AND origin_session_id = ? AND turn_number = ? AND created_at < ?
+     ORDER BY created_at ASC`,
+  );
+  for (const turn of selected) {
+    const rows = bodyStmt
+      .all(sessionId, turn.originSessionId, Number(turn.turnNumber), beforeMs)
+      .filter((r) => r.text);
+    for (let i = 0; i < rows.length; i += 1) {
+      const r = rows[i];
+      const isLast = i === rows.length - 1;
+      const partCounts = isLast ? (l3ByTurn.get(turn.turnKey)?.partCounts ?? new Map()) : new Map();
+      const suffix = buildPartsSummary(partCounts);
+      lines.push(`[${formatTime(r.created_at)}] [${r.role}]: ${r.text}${suffix}`);
+    }
+  }
+  return { text: lines.join('\n'), turnCount: selected.length };
+}
+
+/**
+ * --l1: 境界から skip 件を飛ばした先の全ターン一覧（古い順）。
+ * L1 要約があれば要約行、無ければ「未要約」と明示して detail 誘導を出す。
+ */
+export function renderRecallL1(db, { sessionId, beforeMs, skip, last = null }) {
+  const turnsDesc = listTurnsBefore(db, { sessionId, beforeMs });
+  let olderDesc = turnsDesc.slice(skip);
+  if (last != null) olderDesc = olderDesc.slice(0, last);
+  const selected = [...olderDesc].reverse(); // 古い順
+  const lines = [];
+
+  if (selected.length === 0) {
+    lines.push('## Throughline recall (L1): 該当ターンなし');
+    return { text: lines.join('\n'), turnCount: 0, summarizedCount: 0 };
+  }
+
+  const skelRows = db
+    .prepare(
+      `SELECT origin_session_id, turn_number, summary, created_at
+       FROM skeletons
+       WHERE session_id = ?
+       ORDER BY created_at ASC`,
+    )
+    .all(sessionId);
+  const skelByTurn = new Map();
+  for (const r of skelRows) {
+    const key = `${r.origin_session_id}\x00${r.turn_number}`;
+    if (!skelByTurn.has(key)) skelByTurn.set(key, []);
+    skelByTurn.get(key).push(r);
+  }
+
+  let summarizedCount = 0;
+  const bodyLines = [];
+  for (const turn of selected) {
+    const time = formatTime(turn.minCreatedAt);
+    const skels = skelByTurn.get(turn.turnKey);
+    if (skels && skels.length > 0) {
+      summarizedCount += 1;
+      for (const s of skels) {
+        if (!s.summary || s.summary === '(no content)') continue;
+        const summary = s.summary.replace(/\n+/g, ' ').trim();
+        bodyLines.push(`[${time}] ${summary}`);
+      }
+    } else {
+      bodyLines.push(`[${time}] (未要約) 全文: throughline detail ${time}`);
+    }
+  }
+
+  const range = `${formatTime(selected[0].minCreatedAt)}〜${formatTime(selected[selected.length - 1].minCreatedAt)}`;
+  lines.push(
+    `## Throughline recall (L1): 全${selected.length}ターン / 要約済み ${summarizedCount} (${range}, 古い順)`,
+  );
+  lines.push('各ターンの全文・ツール入出力: `throughline detail <時刻>` で取得可');
+  lines.push('');
+  lines.push(...bodyLines);
+  return { text: lines.join('\n'), turnCount: selected.length, summarizedCount };
+}
+
+export function runRecall(db, opts) {
+  if (opts.mode === 'l2') {
+    return renderRecallL2(db, {
+      sessionId: opts.sessionId,
+      beforeMs: opts.beforeMs,
+      last: opts.last,
+    });
+  }
+  return renderRecallL1(db, {
+    sessionId: opts.sessionId,
+    beforeMs: opts.beforeMs,
+    skip: opts.skip,
+    last: opts.last,
+  });
+}
+
+export function run(argv) {
+  let opts;
+  try {
+    opts = parseRecallArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+
+  const dbPath = opts.dbPath ?? defaultRecallDbPath();
+  if (!existsSync(dbPath)) {
+    process.stderr.write(`recall: DB がありません: ${dbPath}（recall は DB を作成しません）\n`);
+    return 1;
+  }
+
+  let db;
+  try {
+    db = new DatabaseSync(dbPath, { readOnly: true });
+  } catch (err) {
+    process.stderr.write(
+      `recall: DB を read-only で開けませんでした: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+
+  try {
+    const result = runRecall(db, opts);
+    process.stdout.write(`${result.text}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`recall: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  } finally {
+    db.close();
+  }
+}