throughline 0.16.4 → 0.16.5

package/CHANGELOG.md

@@ -10,6 +10,29 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.16.5] — 2026-10-08
+
+### 修正
+
+- Codexのhookが、道具を1回使うたびに、その会話のL3（`details`）を全部消して入れ直していたのを直す（[ADR 0042](docs/adr/0042-codex-capture-writes-only-changed-tail.md)）。DBにある行とrolloutの行を先頭から本文まで比べ、最初に食い違った行から後ろだけを書く。取り込んだ後の中身と並びは、全部入れ直した時と同じ。
+  - Windowsの端末で、L3が3,552行・約1.47億字（rolloutは288MB）の会話のhookが、1回でWALへ152.9MBを書いていた。その端末の`throughline.db-wal`は12.8GBまで伸びていた（DB本体は230MB）。本物のDBの写しで測ると、変化の無いhookは0.3MB、89行が増えたhookは12.5MBになる。
+- `getDb()`が`PRAGMA journal_size_limit`を64MBに設定する。WALが使い直された後の最初のcommitで、ファイルを64MBまで切り詰める。今までは、一度伸びたWALは中身が空になっても縮まなかった。
+
+### 変更
+
+- rolloutに時刻の無いL3の行は、最初に取り込んだ時刻のまま残る。今までは、取り込むたびにその時の時刻へ変わっていた。
+- `codex-capture --json`の結果へ、`keptDetails`・`writtenDetails`・`removedDetails`を足す。
+
+### 変わらない事
+
+- schema（v12）。`bodies`（L2）と`skeletons`（L1）の扱い。
+- Claude Code・Grok・Cursorの取り込み。
+
+### 確認していない範囲
+
+- 複数のCodexの会話が同時に動く本物の端末で、WALが伸びなくなるか。公開の後に端末で読む。
+- hookは今までどおり毎回rolloutの全体を読む。上の会話では約1.1秒かかる。Codexの画面での待ちとして見えているかは調べていない。
+
 ## [0.16.4] — 2026-10-07
 
 ### 変更
@@ -1959,7 +1982,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.4...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.5...HEAD
+[0.16.5]: https://github.com/kitepon/Throughline/compare/v0.16.4...v0.16.5
 [0.16.4]: https://github.com/kitepon/Throughline/compare/v0.16.3...v0.16.4
 [0.16.3]: https://github.com/kitepon/Throughline/compare/v0.16.2...v0.16.3
 [0.16.2]: https://github.com/kitepon/Throughline/compare/v0.16.1...v0.16.2

package/docs/adr/0042-codex-capture-writes-only-changed-tail.md

@@ -0,0 +1,62 @@
+# ADR 0042: Codex の取り込みは、L3 の変わった所から後ろだけを書く。WAL の大きさに上限を置く
+
+日付: 2026-10-08
+
+## Context
+
+Codex の hook（UserPromptSubmit・PostToolUse・Stop・PreCompact）は、毎回 `captureCodexRolloutToDb` を呼ぶ。
+0.16.4 までは、その会話の `bodies` と `details` を全部消し、rollout を読み直した結果を全部入れ直していた。
+PostToolUse は道具を1回使うたびに走るので、会話が長いほど、1回の hook が会話全体と同じ量を WAL へ書く。
+
+2026-10-08 に Windows の端末で次の状態を見た。
+
+- `throughline.db` は 230MB。`throughline.db-wal` は 12.8GB。
+- Codex の会話1つが、L3 に 3,552 行・約 1.47 億字を持つ（rollout は 288MB）。
+- その会話の hook を、本物の DB の写しへ当てて測ると、1回で WAL へ 152.9MB を書いた。rollout に変化が無い時も同じ量を書く。
+- hook が続く間、44 秒で wal-index が約 600MB 分伸びた。
+
+WAL は、checkpoint が全部を本体へ書き戻し、読んでいる接続が無い時にだけ、先頭から使い直される。1回の
+hook が百数十 MB を書き、別の会話の hook が続けて来ると、使い直す隙が出来ず、WAL は伸び続ける。また、
+SQLite の既定（`journal_size_limit = -1`）では、一度伸びた WAL のファイルは、中身が空になっても縮まない。
+
+rollout は追記で伸びる。普通の hook の間で変わるのは、L3 の末尾の数行だけ。
+
+## Decision
+
+1. `captureCodexRolloutToDb` は、`details` を次の形で書く。
+   - DB にある行（`id` の順）と、rollout から作った行を、先頭から1行ずつ比べる。
+   - 比べるのは `origin_session_id`・`turn_number`・`tool_name`・`kind`・`source_id`・`token_count`・`created_at` と、
+     `input_text`・`output_text` の本文。本文は SQLite の中で比べる（`input_text IS ? AND output_text IS ?`）。
+   - 最初に食い違った行から後ろを消し、rollout の同じ位置から後ろを入れる。食い違いが無ければ、増えた行だけを入れる。
+2. 比べる前に、rollout から作った行を、DB に入る形へ揃える。同じ `source_id` の2件目は
+   `uq_details_source` と `INSERT OR IGNORE` が捨てるので、先に除く。
+3. rollout に時刻が無い行は、取り込んだ時刻が `created_at` に入る。その行は `created_at` を比べず、
+   最初に取り込んだ時刻のまま残す。0.16.4 までは、取り込むたびにその時の時刻へ変わっていた。
+4. `bodies` は、今までどおり全部消して入れ直す。会話の本文は小さい（上の会話で 98 行・約 7.7 万字）。
+   `skeletons`（L1）の扱いも変えない。
+5. `getDb()` は、開いた接続へ `PRAGMA journal_size_limit = 67108864`（64MB）を設定する。WAL が使い直された
+   後の最初の commit で、SQLite がファイルを 64MB まで切り詰める。切り詰めに失敗しても、SQLite はその
+   失敗を無視して書き込みを続ける。
+6. `captureCodexRolloutToDb` の結果へ、`keptDetails`・`writtenDetails`・`removedDetails` を足す。
+
+## Consequences
+
+- 取り込んだ後の `details` の中身と並び（`id` の順）は、全部入れ直した時と同じになる。3 の `created_at` だけが違う。
+- 変わっていない行の `id` は、hook をまたいで変わらなくなる。0.16.4 までは、毎回新しい `id` になっていた。
+- 上の会話の写しで測ると、変化の無い hook が WAL へ書く量は 152.9MB から 0.3MB になる。89 行が増えた hook は 12.5MB。
+- hook は、今までどおり毎回 rollout の全体を読む。上の会話では、読むのに約 1.1 秒、比べるのに約 0.3 秒かかる。
+  本文を比べるために、DB にあるその会話の L3 を毎回読む。書く量は減るが、読む量は減らない。
+- rollout の途中の行が変わった時（rollback の後など）は、その行から後ろを入れ直す。先頭の行が変われば、
+  今までと同じく全部を入れ直す。
+- 同じ会話の hook が2つ同時に走った時は、後で commit した方の rollout の読み取りが残る。今までと同じ。
+- すでに伸びている WAL は、この版の接続が、使い直された WAL へ最初に commit した時に縮む。それまでは元の大きさのまま。
+- `journal_size_limit` は接続ごとの設定で、DB には残らない。読み取り専用の接続（`openReadOnlyDb`）には設定しない。
+- schema は変えない（v12 のまま）。
+
+## 確認していない範囲
+
+- WAL が使い直されない状態（checkpoint が終わる前に次の書き込みが来る状態）が、この版で実際に起きなくなるか。
+  書く量が減った分、起きにくくなるが、本物の端末で複数の会話が同時に動いた時の WAL の大きさは、公開の後に読む。
+- rollout を毎回全部読む時間が、Codex の画面で道具の後の待ちとして見えているか。
+- Claude Code・Grok・Cursor の取り込みは、ターンごとに `INSERT OR IGNORE` で足す形で、この変更の対象ではない。
+  これらの host の長い会話での書く量は測っていない。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "type": "module",
   "description": "Persistent memory hooks for Claude Code, Codex, Grok, and Cursor (/clear-safe context compression)",
   "keywords": [

package/src/codex-capture.mjs

@@ -58,6 +58,7 @@ export function captureCodexRolloutToDb(
     now,
   });
 
+  let detailSync = null;
   db.exec('BEGIN IMMEDIATE');
   try {
     db.prepare(
@@ -80,19 +81,12 @@ export function captureCodexRolloutToDb(
       }
     }
     db.prepare('DELETE FROM bodies WHERE session_id = ?').run(sessionId);
-    db.prepare('DELETE FROM details WHERE session_id = ?').run(sessionId);
 
     const insertBody = db.prepare(
       `INSERT INTO bodies
          (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
        VALUES (?, ?, ?, ?, ?, ?, ?)`,
     );
-    const insertDetail = db.prepare(
-      `INSERT OR IGNORE INTO details
-         (session_id, origin_session_id, turn_number, tool_name, input_text, output_text,
-          token_count, created_at, kind, source_id)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    );
 
     for (const row of rows) {
       insertBody.run(
@@ -105,20 +99,7 @@ export function captureCodexRolloutToDb(
         row.createdAt,
       );
     }
-    for (const row of detailRows) {
-      insertDetail.run(
-        row.sessionId,
-        row.originSessionId,
-        row.turnNumber,
-        row.toolName,
-        row.inputText,
-        row.outputText,
-        row.tokenCount,
-        row.createdAt,
-        row.kind,
-        row.sourceId,
-      );
-    }
+    detailSync = syncDetailRows(db, sessionId, detailRows, now);
 
     db.exec('COMMIT');
   } catch (err) {
@@ -137,10 +118,100 @@ export function captureCodexRolloutToDb(
     capturedTurns: parsed.activeTurnCount,
     capturedRows: rows.length,
     capturedDetails: detailRows.length,
+    keptDetails: detailSync.kept,
+    writtenDetails: detailSync.inserted,
+    removedDetails: detailSync.removed,
     stats: parsed.stats,
   };
 }
 
+/**
+ * L3 (details) を rollout の今の中身へ合わせる。変わっていない先頭の行はそのまま残し、
+ * 最初に食い違った行から後ろだけを消して入れ直す (ADR 0042)。
+ *
+ * hook は道具を1回使うたびに走る。会話の全行を消して入れ直すと、長い会話では1回の hook が
+ * 会話全体と同じ量を WAL へ書く。rollout は追記で伸びるので、普通は末尾の数行だけが変わる。
+ *
+ * 残った行の並び (id の順) は、全部入れ直した時と同じになる。食い違いは本文まで比べて決める。
+ */
+function syncDetailRows(db, sessionId, detailRows, now) {
+  const wanted = dropIgnoredDuplicates(detailRows);
+  const existing = db
+    .prepare(
+      `SELECT id, origin_session_id, turn_number, tool_name, kind, source_id, token_count, created_at
+         FROM details WHERE session_id = ? ORDER BY id`,
+    )
+    .all(sessionId);
+  const sameText = db.prepare(
+    'SELECT 1 AS same FROM details WHERE id = ? AND input_text IS ? AND output_text IS ?',
+  );
+
+  let kept = 0;
+  while (kept < existing.length && kept < wanted.length) {
+    const have = existing[kept];
+    const want = wanted[kept];
+    if (!sameDetailColumns(have, want, now)) break;
+    if (!sameText.get(have.id, want.inputText, want.outputText)) break;
+    kept++;
+  }
+
+  if (kept < existing.length) {
+    db.prepare('DELETE FROM details WHERE session_id = ? AND id >= ?').run(sessionId, existing[kept].id);
+  }
+
+  const insertDetail = db.prepare(
+    `INSERT OR IGNORE INTO details
+       (session_id, origin_session_id, turn_number, tool_name, input_text, output_text,
+        token_count, created_at, kind, source_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  for (const row of wanted.slice(kept)) {
+    insertDetail.run(
+      row.sessionId,
+      row.originSessionId,
+      row.turnNumber,
+      row.toolName,
+      row.inputText,
+      row.outputText,
+      row.tokenCount,
+      row.createdAt,
+      row.kind,
+      row.sourceId,
+    );
+  }
+
+  return { kept, removed: existing.length - kept, inserted: wanted.length - kept };
+}
+
+// uq_details_source (session_id, origin_session_id, source_id) は、同じ source_id の2件目を
+// INSERT OR IGNORE で捨てる。DB に入る並びと比べるため、入れる前に同じ形へ揃える。
+function dropIgnoredDuplicates(detailRows) {
+  const seen = new Set();
+  const rows = [];
+  for (const row of detailRows) {
+    if (row.sourceId !== null) {
+      const key = `${row.originSessionId}\0${row.sourceId}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+function sameDetailColumns(have, want, now) {
+  return (
+    have.origin_session_id === want.originSessionId &&
+    have.turn_number === want.turnNumber &&
+    have.tool_name === want.toolName &&
+    have.kind === want.kind &&
+    have.source_id === want.sourceId &&
+    have.token_count === want.tokenCount &&
+    // rollout に時刻が無い行は取り込んだ時刻が入る。その行は最初に取り込んだ時刻のまま残す。
+    (have.created_at === want.createdAt || want.createdAt === now)
+  );
+}
+
 function bodyTurnTexts(rows) {
   const turns = new Map();
   for (const row of rows) {

package/src/codex-capture.test.mjs

@@ -459,6 +459,158 @@ test('同じ会話の再captureはL1を保持し、ユーザー本文が変わ
   }
 });
 
+// 本物の schema と同じく、同じ source_id の2件目を INSERT OR IGNORE が捨てる DB。
+function makeDbWithSourceIndex() {
+  const db = makeDb();
+  db.exec(`CREATE UNIQUE INDEX uq_details_source
+             ON details(session_id, origin_session_id, source_id) WHERE source_id IS NOT NULL`);
+  return db;
+}
+
+function detailSnapshot(db) {
+  return db
+    .prepare(
+      `SELECT origin_session_id, turn_number, tool_name, input_text, output_text, token_count,
+              created_at, kind, source_id
+         FROM details ORDER BY id`,
+    )
+    .all();
+}
+
+function toolCall(callId, input, output) {
+  return [
+    responseItem({ type: 'function_call', call_id: callId, name: 'shell', arguments: input }),
+    responseItem({ type: 'function_call_output', call_id: callId, output }),
+  ];
+}
+
+test('同じ会話の再captureは、変わっていないL3の行を書き直さず、増えた行だけを足す', () => {
+  const db = makeDbWithSourceIndex();
+  const home = mkdtempSync(join(tmpdir(), 'tl-codex-incr-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));
+  const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+  try {
+    const head = [
+      event('task_started'), event('user_message', { message: '作業を続ける' }),
+      ...toolCall('call-1', '{"cmd":"pwd"}', '/work'),
+      ...toolCall('call-2', '{"cmd":"ls"}', 'a\nb'),
+    ];
+    const rollout = writeRollout(home, { id: threadId, cwd: project, events: head });
+    const first = captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 1 });
+    assert.deepEqual([first.keptDetails, first.writtenDetails, first.removedDetails], [0, 4, 0]);
+    const idsBefore = db.prepare('SELECT id FROM details ORDER BY id').all().map((row) => row.id);
+
+    // 道具をもう1回使った後の hook。前の4行はそのまま残り、2行だけ増える。
+    writeRolloutRows(rollout, [sessionMeta(threadId, project), ...head, ...toolCall('call-3', '{"cmd":"date"}', 'now')]);
+    const second = captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 2 });
+    assert.deepEqual([second.keptDetails, second.writtenDetails, second.removedDetails], [4, 2, 0]);
+    const idsAfter = db.prepare('SELECT id FROM details ORDER BY id').all().map((row) => row.id);
+    assert.deepEqual(idsAfter.slice(0, 4), idsBefore);
+    assert.equal(idsAfter.length, 6);
+    assert.ok(idsAfter[4] > idsBefore[3]);
+
+    // 何も増えていない hook は、L3 を1行も書かない。
+    const third = captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 3 });
+    assert.deepEqual([third.keptDetails, third.writtenDetails, third.removedDetails], [6, 0, 0]);
+    assert.deepEqual(db.prepare('SELECT id FROM details ORDER BY id').all().map((row) => row.id), idsAfter);
+  } finally {
+    db.close(); rmSync(home, { recursive: true, force: true }); rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('L3の再captureは、どの変わり方でも、全部入れ直した時と同じ中身と並びになる', () => {
+  const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+  const turn = (message, ...items) => [
+    event('task_started'), event('user_message', { message }), ...items.flat(), event('task_complete'),
+  ];
+  const orphanOutput = (output) => responseItem({ type: 'function_call_output', output });
+  const base = [
+    ...turn('1つ目', toolCall('call-1', '{"cmd":"pwd"}', '/work'), [orphanOutput('aaaa')]),
+    ...turn('2つ目', toolCall('call-2', '{"cmd":"ls"}', 'file-a'), toolCall('call-3', '{"cmd":"date"}', 'now')),
+  ];
+  const cases = {
+    // 末尾へ足されただけ。前の6行は残る。
+    '末尾へ行が増えた': { next: [...base, ...turn('3つ目', toolCall('call-4', '{"cmd":"id"}', 'kite'))], kept: 7 },
+    // 同じ source_id・同じ長さで、本文だけが違う。その行から後ろを入れ直す。
+    '途中の行の本文が同じ長さで変わった': {
+      next: [
+        ...turn('1つ目', toolCall('call-1', '{"cmd":"pwd"}', '/WORK'), [orphanOutput('aaaa')]),
+        ...turn('2つ目', toolCall('call-2', '{"cmd":"ls"}', 'file-a'), toolCall('call-3', '{"cmd":"date"}', 'now')),
+      ],
+      kept: 1,
+    },
+    // source_id の無い行は、本文でしか区別できない。
+    'source_idの無い行の本文が変わった': {
+      next: [
+        ...turn('1つ目', toolCall('call-1', '{"cmd":"pwd"}', '/work'), [orphanOutput('bbbb')]),
+        ...turn('2つ目', toolCall('call-2', '{"cmd":"ls"}', 'file-a'), toolCall('call-3', '{"cmd":"date"}', 'now')),
+      ],
+      kept: 2,
+    },
+    // 出力が後から届いた（NULL だった所へ入る形ではなく、行が増える）。
+    '途中へ行が差し込まれた': {
+      next: [
+        ...turn('1つ目', toolCall('call-1', '{"cmd":"pwd"}', '/work'), toolCall('call-1b', '{"cmd":"x"}', 'y'), [orphanOutput('aaaa')]),
+        ...turn('2つ目', toolCall('call-2', '{"cmd":"ls"}', 'file-a'), toolCall('call-3', '{"cmd":"date"}', 'now')),
+      ],
+      kept: 2,
+    },
+    // rollback で最後のターンが消えた。
+    '最後のターンが巻き戻された': { next: [...base, event('thread_rolled_back', { num_turns: 1 })], kept: 3 },
+    // 同じ call_id がもう一度出た。2件目は捨てられるので、並びは変わらない。
+    '同じsource_idがもう一度出た': {
+      next: [
+        ...turn('1つ目', toolCall('call-1', '{"cmd":"pwd"}', '/work'), [orphanOutput('aaaa')]),
+        ...turn('2つ目', toolCall('call-2', '{"cmd":"ls"}', 'file-a'), toolCall('call-2', '{"cmd":"ls"}', 'file-a'),
+          toolCall('call-3', '{"cmd":"date"}', 'now')),
+      ],
+      kept: 7,
+    },
+    '全部無くなった': { next: [...turn('1つ目')], kept: 0 },
+  };
+
+  for (const [name, { next, kept }] of Object.entries(cases)) {
+    const home = mkdtempSync(join(tmpdir(), 'tl-codex-incr-'));
+    const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));
+    const db = makeDbWithSourceIndex();
+    const fresh = makeDbWithSourceIndex();
+    try {
+      const rollout = writeRollout(home, { id: threadId, cwd: project, events: base });
+      captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 1 });
+      assert.equal(detailSnapshot(db).length, 7, name);
+
+      writeRolloutRows(rollout, [sessionMeta(threadId, project), ...next]);
+      const again = captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 2 });
+      captureCodexRolloutToDb(fresh, { threadId, codexHome: home, projectPath: project, now: 2 });
+
+      assert.deepEqual(detailSnapshot(db), detailSnapshot(fresh), name);
+      assert.equal(again.keptDetails, kept, name);
+    } finally {
+      db.close(); fresh.close();
+      rmSync(home, { recursive: true, force: true }); rmSync(project, { recursive: true, force: true });
+    }
+  }
+});
+
+test('rolloutに時刻の無いL3の行は、再captureしても最初に取り込んだ時刻のまま残る', () => {
+  const db = makeDbWithSourceIndex();
+  const home = mkdtempSync(join(tmpdir(), 'tl-codex-incr-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-project-'));
+  const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+  try {
+    const untimed = { type: 'response_item', payload: { type: 'function_call', call_id: 'call-1', name: 'shell', arguments: '{}' } };
+    writeRollout(home, { id: threadId, cwd: project, events: [
+      event('task_started'), event('user_message', { message: '作業を続ける' }), untimed,
+    ] });
+    captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 1000 });
+    const again = captureCodexRolloutToDb(db, { threadId, codexHome: home, projectPath: project, now: 2000 });
+    assert.equal(again.keptDetails, 1);
+    assert.equal(db.prepare('SELECT created_at FROM details').get().created_at, 1000);
+  } finally {
+    db.close(); rmSync(home, { recursive: true, force: true }); rmSync(project, { recursive: true, force: true });
+  }
+});
+
 function writeRollout(home, { id, cwd, events }) {
   const dir = join(home, 'sessions', '2026', '05', '06');
   mkdirSync(dir, { recursive: true });

package/src/db-contention.test.mjs

@@ -52,6 +52,50 @@ test('getDb configures a bounded SQLite busy timeout for concurrent hook process
   }
 });
 
+test('getDbは、膨らんだWALを次の書き込みで上限まで切り詰める', () => {
+  const home = mkdtempSync(join(tmpdir(), 'throughline-db-wal-limit-'));
+  try {
+    const env = { ...process.env, HOME: home, USERPROFILE: home };
+    // 上限を持たない接続で、checkpoint を止めたまま WAL を膨らませ、そのまま閉じずに終わる。
+    const grow = spawnSync(process.execPath, ['--input-type=module', '-e', `
+      import { statSync } from 'node:fs';
+      import { DatabaseSync } from 'node:sqlite';
+      import { getDb, DB_PATH, WAL_SIZE_LIMIT_BYTES } from ${JSON.stringify(DB_MODULE_URL)};
+      getDb().close();
+      const db = new DatabaseSync(DB_PATH);
+      db.exec('PRAGMA wal_autocheckpoint = 0');
+      db.exec('CREATE TABLE filler (id INTEGER PRIMARY KEY, body TEXT)');
+      const insert = db.prepare('INSERT INTO filler (body) VALUES (?)');
+      const body = 'x'.repeat(1024 * 1024);
+      while (statSync(DB_PATH + '-wal').size <= WAL_SIZE_LIMIT_BYTES + 8 * 1024 * 1024) insert.run(body);
+      db.exec('DELETE FROM filler');
+      console.log(JSON.stringify({ wal: statSync(DB_PATH + '-wal').size, limit: WAL_SIZE_LIMIT_BYTES }));
+      process.exit(0);
+    `], { env, encoding: 'utf8' });
+    assert.equal(grow.status, 0, grow.stderr);
+    const grown = JSON.parse(grow.stdout);
+    assert.ok(grown.wal > grown.limit, `WAL が膨らんでいない: ${grow.stdout}`);
+
+    // 製品の入口で開いた接続が、checkpoint の後の最初の書き込みで切り詰める。
+    const shrink = spawnSync(process.execPath, ['--input-type=module', '-e', `
+      import { statSync } from 'node:fs';
+      import { getDb, DB_PATH } from ${JSON.stringify(DB_MODULE_URL)};
+      const db = getDb();
+      const limit = db.prepare('PRAGMA journal_size_limit').get().journal_size_limit;
+      db.exec('PRAGMA wal_checkpoint(PASSIVE)');
+      db.prepare("INSERT INTO sessions (session_id, project_path, status, created_at, updated_at) VALUES ('wal-limit', '/tmp', 'active', 1, 1)").run();
+      console.log(JSON.stringify({ limit, wal: statSync(DB_PATH + '-wal').size }));
+      process.exit(0);
+    `], { env, encoding: 'utf8' });
+    assert.equal(shrink.status, 0, shrink.stderr);
+    const shrunk = JSON.parse(shrink.stdout);
+    assert.equal(shrunk.limit, grown.limit);
+    assert.ok(shrunk.wal <= grown.limit, `WAL が上限を超えたまま: ${shrink.stdout}`);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('getDb reuses an existing WAL database while another process owns the writer lock', async () => {
   const home = mkdtempSync(join(tmpdir(), 'throughline-db-contention-'));
   const env = { ...process.env, HOME: home, USERPROFILE: home };

package/src/db.mjs

@@ -10,6 +10,9 @@ import { join } from 'path';
 const DB_DIR = join(homedir(), '.throughline');
 export const DB_PATH = join(DB_DIR, 'throughline.db');
 export const DB_BUSY_TIMEOUT_MS = 5_000;
+// WAL が checkpoint で巻き戻った後、次の書き込みでファイルをこの大きさまで切り詰める (ADR 0042)。
+// 既定 (-1) は切り詰めないので、一度膨らんだ WAL は中身が空でも元の大きさのまま残る。
+export const WAL_SIZE_LIMIT_BYTES = 64 * 1024 * 1024;
 export const CURRENT_VERSION = 12;
 
 let _db = null;
@@ -485,6 +488,7 @@ export function getDb() {
     db.exec(`PRAGMA busy_timeout = ${DB_BUSY_TIMEOUT_MS}`);
     settleFirstRead(db);
     ensureWalJournalMode(db);
+    db.exec(`PRAGMA journal_size_limit = ${WAL_SIZE_LIMIT_BYTES}`);
     db.exec('PRAGMA foreign_keys = ON');
     initSchema(db);
     _db = db;