throughline 0.5.0 → 0.6.0

package/{docs/RAG → rag}/INDEX.md

@@ -7,17 +7,17 @@ This directory accumulates third-party specifications relevant to Throughline's
 ## Folder layout
 
 ```text
-docs/RAG/
+rag/
 ├── INDEX.md (this file — synthesized findings, paths forward)
-└── _raw/                       (verbatim spec extracts, kept close to source wording)
-    ├── 01-hooks/
-    │   └── hooks-reference-extract.md      ← Claude Code hooks reference
-    ├── 02-messages-api/
-    │   └── messages-api-extract.md         ← Anthropic Messages API spec
-    ├── 03-settings/
-    │   └── sessions-extract.md             ← /clear, /compact, /resume behavior
-    └── 04-skills/
-        └── initialUserMessage-investigation.md ← deep-dive on the killer field
+├── 01-hooks/
+│   ├── raw/hooks-reference-extract.md      ← Claude Code hooks reference
+│   └── raw/session-end-reasons.md          ← SessionEnd reason enum + timeout 1.5s (2026-07-11 fetch)
+├── 02-messages-api/
+│   └── raw/messages-api-extract.md         ← Anthropic Messages API spec
+├── 03-settings/
+│   └── raw/sessions-extract.md             ← /clear, /compact, /resume behavior
+└── 04-skills/
+    └── raw/initialUserMessage-investigation.md ← deep-dive on the killer field
 ```
 
 ---
@@ -33,7 +33,7 @@ docs/RAG/
 ### Finding 1: `additionalContext` is a system reminder, not a user message
 
 > "Claude Code wraps the string in a system reminder and inserts it into the conversation at the point where the hook fired. Claude reads the reminder on the next model request, but it **does not appear as a chat message** in the interface."
-> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#what-additionalcontext-actually-does-critical)
+> — [Hooks reference](01-hooks/raw/hooks-reference-extract.md#what-additionalcontext-actually-does-critical)
 
 → システムリマインダ = ブリーフィング扱い。モデルが「他人事」と感じる構造的原因。
 
@@ -41,13 +41,13 @@ docs/RAG/
 
 > "any non-JSON text written to stdout is added as context"
 > "Claude Code wraps the string in a system reminder"
-> — [Hooks reference](_raw/01-hooks/hooks-reference-extract.md#stdout)
+> — [Hooks reference](01-hooks/raw/hooks-reference-extract.md#stdout)
 
 → 現行 Throughline v0.4.12 の stdout 注入はこの経路。`additionalContext` と同じカテゴリ = 同じ「他人事」問題。
 
 ### Finding 3: `initialUserMessage` exists in the schema, but is **HEADLESS-ONLY**
 
-Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation.md#the-critical-constraint-from-openclaude-source-comment):
+Verified via [openclaude source](04-skills/raw/initialUserMessage-investigation.md#the-critical-constraint-from-openclaude-source-comment):
 
 ```text
 // SessionStart hooks can emit initialUserMessage — the first user turn for
@@ -56,19 +56,19 @@ Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation
 
 → Interactive mode (`/clear` シナリオ) では発火しない。我々の問題には使えない。
 
-**2026-05-24 実機確認**: real Claude Code (v2.1.145) で `~/.throughline/initial-user-message-test.flag` を立てて SessionStart hook を JSON 出力モードに切り替え、`hookSpecificOutput.initialUserMessage` に 8 hex tracer 入りメッセージを乗せて `/clear` 後の cleared-me に「過去発話の tracer を message history だけ見て返して」と尋ねた。ラン (2) 13:33 tracer `9220a79c` (session `0979ad20-…`) → モデル応答 **「ない」**。openclaude のソースコメントが real CC でも妥当であることを実機で確認。詳細: [docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md §6 Phase 0-6](../THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md#phase-0-6--hookspecificoutputinitialusermessage-経路-spike)
+**2026-05-24 実機確認**: real Claude Code (v2.1.145) で `~/.throughline/initial-user-message-test.flag` を立てて SessionStart hook を JSON 出力モードに切り替え、`hookSpecificOutput.initialUserMessage` に 8 hex tracer 入りメッセージを乗せて `/clear` 後の cleared-me に「過去発話の tracer を message history だけ見て返して」と尋ねた。ラン (2) 13:33 tracer `9220a79c` (session `0979ad20-…`) → モデル応答 **「ない」**。openclaude のソースコメントが real CC でも妥当であることを実機で確認。詳細: [docs/10_transcript_injection_plan.md §6 Phase 0-6](../docs/10_transcript_injection_plan.md#phase-0-6--hookspecificoutputinitialusermessage-経路-spike)
 
 ### Finding 4: Messages API treats all messages[] entries equally
 
 > "When creating a new Message, you specify the prior conversational turns with the messages parameter, and the model then generates the next Message in the conversation."
-> — [Messages API](_raw/02-messages-api/messages-api-extract.md#no-differentiation-between-real--synthetic-messages-key)
+> — [Messages API](02-messages-api/raw/messages-api-extract.md#no-differentiation-between-real--synthetic-messages-key)
 
 → もし messages[] に synthetic な過去 turn を入れられれば、モデルは「本物」と区別できない。問題は CC が messages[] を hook から制御させていないこと。
 
 ### Finding 5: `/clear` preserves the JSONL but resets in-memory state
 
 > "/clear: start fresh with an empty context. The previous conversation is saved and resumable"
-> — [Sessions](_raw/03-settings/sessions-extract.md#clear-behavior-key)
+> — [Sessions](03-settings/raw/sessions-extract.md#clear-behavior-key)
 
 → CC は in-memory state を一次ソースに messages[] を構築。JSONL を外から書き換えても in-memory には反映されない (= Phase 0 / Phase 0-5 で実測確認済み)。
 
@@ -82,6 +82,10 @@ Verified via [openclaude source](_raw/04-skills/initialUserMessage-investigation
 
 [anthropics/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md) は SessionStart hook の `hookSpecificOutput` の `additionalContext` も `initialUserMessage` も触れていない。Plugin 開発者向けの公式チュートリアルですら触れない = どちらも primary 経路として推奨されていない可能性。
 
+### Finding 8: SessionEnd has a `clear` reason; built-in `/clear` never reaches UserPromptSubmit (2026-07-11)
+
+SessionEnd reason enum: `clear|resume|logout|prompt_input_exit|bypass_permissions_disabled|other`、default timeout 1.5s（/clear にも適用）— [session-end-reasons.md](01-hooks/raw/session-end-reasons.md)。実測: ビルトイン /clear はどのクライアントでも UserPromptSubmit に届かない（同一セッション /tl 対照実験 ×2 + VSCode 2.1.207）。VSCode は `source:"clear"` を送るが Desktop 2.1.205 は `source:"startup"`（クライアント実装差・バージョン交絡棄却済み）。→ Desktop の /clear 検知は SessionEnd(reason='clear') が唯一の hook 経路候補（実機検証は [docs/12](../docs/12_desktop_clear_handoff_plan.md) A Phase 1）。
+
 ---
 
 ## Throughline 仮説の見直し

package/src/baton.mjs

@@ -1,7 +1,7 @@
 /**
  * baton.mjs — 引き継ぎバトン管理
  *
- * バトン方式の設計 (docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md):
+ * バトン方式の設計 (docs/02_clear_auto_handoff_plan.md):
  *   - 新仕様では `/clear` 自動引継ぎがデフォルト ON。バトンは「/clear 自動引継ぎを
  *     使わずに明示的に引き継ぎたい」ユーザーのための逃げ道。
  *   - ユーザーが旧セッションで `/tl` スラッシュコマンドを打つ → UserPromptSubmit hook が
@@ -14,7 +14,7 @@
  *       "startup" に潰される問題 (#49937) に対する明示意思マーカーとして導入。
  *       2026-05-08 時点で Claude Code 2.1.128 で source='clear' は reliable に
  *       なったため auto path 中心の設計に変わったが、明示意思の signal として
- *       baton 仕組み自体は残す。詳細は docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md。
+ *       baton 仕組み自体は残す。詳細は docs/02_clear_auto_handoff_plan.md。
  */
 
 /**

package/src/db.mjs

@@ -180,7 +180,7 @@ function initSchema(db) {
   // v5 → v6: handoff_batons テーブル追加（/tl スラッシュコマンドによる明示的引き継ぎ指名用）
   // - project_path ごとに最新 1 件のみ (PRIMARY KEY)
   // - SessionStart で読み出し、TTL 以内なら merge して DELETE
-  // - docs/INHERITANCE_ON_CLEAR_ONLY.md 参照: 案 D (時間差) 撤去、バトン方式へ移行
+  // - docs/03_inheritance_on_clear_only.md 参照: 案 D (時間差) 撤去、バトン方式へ移行
   if (version < 6) {
     db.exec(`
       CREATE TABLE IF NOT EXISTS handoff_batons (
@@ -203,7 +203,7 @@ function initSchema(db) {
   }
 
   // v7 → v8: handoff_batons から memo_text 列を drop。
-  // 新仕様 (docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md) で memo 廃止:
+  // 新仕様 (docs/02_clear_auto_handoff_plan.md) で memo 廃止:
   //   - /clear 自動引継ぎ (SessionStart source='clear') + /tl baton (memo なし) の 2 経路に
   //   - 注入は L1 + L2 + L3 refs のみ
   //   - save-inflight CLI / updateBatonMemo 関数も併せて削除

package/src/hook-entrypoints.test.mjs

@@ -370,6 +370,108 @@ test('process-turn subprocess stores L2 bodies and L3 details in an isolated DB'
   }
 });
 
+test('process-turn subprocess backfills all completed logical turns from a multi-turn JSONL', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const transcriptPath = join(project, 'transcript.jsonl');
+  try {
+    writeFileSync(
+      transcriptPath,
+      [
+        { type: 'user', message: { role: 'user', content: [{ type: 'text', text: 'first request' }] } },
+        { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'first answer' }] } },
+        { type: 'user', message: { role: 'user', content: [{ type: 'text', text: 'second request' }] } },
+        { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'second answer' }] } },
+      ].map((entry) => JSON.stringify(entry)).join('\n'),
+      'utf8',
+    );
+    const result = runNode([join(REPO_ROOT, 'src/turn-processor.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ session_id: 'multi-turn-session', cwd: project, transcript_path: transcriptPath }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const db = openDb(home);
+    assert.deepEqual(
+      db.prepare('SELECT role, text FROM bodies ORDER BY turn_number, role').all().map((row) => ({ ...row })),
+      [
+        { role: 'assistant', text: 'first answer' },
+        { role: 'user', text: 'first request' },
+        { role: 'assistant', text: 'second answer' },
+        { role: 'user', text: 'second request' },
+      ],
+    );
+    db.close();
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('session-start backfills a derived predecessor transcript without a state file', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const predecessorId = 'missing-stop-predecessor';
+  const derivedPath = join(
+    home,
+    '.claude',
+    'projects',
+    `-${project.replace(/[/.]/g, '-').replace(/^-+/, '')}`,
+    `${predecessorId}.jsonl`,
+  );
+  try {
+    mkdirSync(dirname(derivedPath), { recursive: true });
+    writeFileSync(
+      derivedPath,
+      [
+        { type: 'user', message: { role: 'user', content: [{ type: 'text', text: 'predecessor question' }] } },
+        { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'predecessor answer' }] } },
+      ].map((entry) => JSON.stringify(entry)).join('\n'),
+      'utf8',
+    );
+    const baton = runNode([join(REPO_ROOT, 'src/prompt-submit.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ session_id: predecessorId, cwd: project, prompt: '/clear' }),
+    });
+    assert.equal(baton.status, 0, baton.stderr);
+    const db = openDb(home);
+    db.prepare(
+      `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+       VALUES (?, ?, 'active', 1, 1)`,
+    ).run(predecessorId, project);
+    db.close();
+
+    const started = runNode([join(REPO_ROOT, 'src/session-start.mjs')], {
+      home,
+      cwd: project,
+      input: JSON.stringify({ session_id: 'new-session', cwd: project, source: 'startup' }),
+    });
+    assert.equal(started.status, 0, started.stderr);
+    const after = openDb(home);
+    assert.deepEqual(
+      after
+        .prepare('SELECT session_id, origin_session_id, role, text FROM bodies ORDER BY turn_number, role')
+        .all()
+        .map((row) => ({ ...row })),
+      [
+        { session_id: 'new-session', origin_session_id: predecessorId, role: 'assistant', text: 'predecessor answer' },
+        { session_id: 'new-session', origin_session_id: predecessorId, role: 'user', text: 'predecessor question' },
+      ],
+    );
+    after.close();
+    const backfillLog = readFileSync(join(home, '.throughline', 'logs', 'backfill.log'), 'utf8')
+      .split('\n')
+      .filter((line) => line)
+      .map((line) => JSON.parse(line));
+    assert.ok(backfillLog.some((entry) => entry.hook === 'session-start'));
+    assert.equal(existsSync(join(home, '.throughline', 'state', `${predecessorId}.json`)), false);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 // ---- Phase 0-5 spike (UserPromptSubmit) ----
 
 function seedMergedSession(home, sessionId, originId = 'orig-sess') {

package/src/package-files.test.mjs

@@ -12,6 +12,7 @@ test('npm package files include Claude and Codex agent surfaces', () => {
     '.claude/commands/',
     '.codex-sidecar.yml',
     'docs/',
+    'rag/',
     'CHANGELOG.md',
     'README.md',
     'LICENSE',

package/src/prompt-submit.mjs

@@ -20,9 +20,9 @@
  *     行を chain-reachable (= 直前の attachment uuid を parent に取る) で append する。
  *     SessionStart 経路の spike (chain (a) = orphan) ではモデルに届かなかったため、
  *     UserPromptSubmit 経路で chain (b) を成立させて再検証する。
- *     docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md Phase 0-5 参照。
+ *     docs/10_transcript_injection_plan.md Phase 0-5 参照。
  *
- * 設計背景: docs/INHERITANCE_ON_CLEAR_ONLY.md バトン方式
+ * 設計背景: docs/03_inheritance_on_clear_only.md バトン方式
  */
 
 import { getDb } from './db.mjs';

package/src/resume-context.mjs

@@ -4,7 +4,7 @@
  * 呼び出し元:
  *   - session-start.mjs (auto path / baton path どちらでも同じ注入)
  *
- * 設計 (docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md):
+ * 設計 (docs/02_clear_auto_handoff_plan.md):
  *   - 注入順: ヘッダ + 読み方 → 現在地アンカー → L1 要約 → L2 本文（一番下）
  *   - 「現在地」アンカーは直前の user / assistant turn をヘッダ直下に再掲して
  *     最初の注意を最新ターンに固定する。L2 末尾アンカーは補強として残す。

package/src/session-merger.mjs

@@ -5,7 +5,7 @@
  *   - SessionStart hook: バトンで指名された旧セッションを mergeSpecificPredecessor で新セッションに張り替え
  *   - Stop hook: resolveMergeTarget で「入力 session_id → 実書き込み先」を解決
  *
- * 設計背景: docs/SESSION_LINKING_DESIGN.md, docs/INHERITANCE_ON_CLEAR_ONLY.md (バトン方式採用)
+ * 設計背景: docs/archive/SESSION_LINKING_DESIGN.md, docs/03_inheritance_on_clear_only.md (バトン方式採用)
  *
  * 旧実装 (案 D: 時間差ヒューリスティック / 自動前任選択) は撤去済み。
  * 引き継ぎはユーザーが /tl を打って書いたバトンによる明示的指名のみで発火する。

package/src/session-start.mjs

@@ -4,7 +4,7 @@
  *
  * stdin: { session_id, source, cwd, transcript_path, hook_event_name }
  *
- * 【引き継ぎ条件 (2 経路)】 docs/THROUGHLINE_CLEAR_AUTO_HANDOFF_PLAN.md
+ * 【引き継ぎ条件 (2 経路)】 docs/02_clear_auto_handoff_plan.md
  *
  *   1. baton path: ユーザーが旧セッションで `/tl` を打つと UserPromptSubmit hook が
  *      handoff_batons に session_id を書く。本 hook が TTL 1 時間以内に消費して
@@ -28,7 +28,9 @@
 import { getDb } from './db.mjs';
 import { consumeBaton } from './baton.mjs';
 import { mergeSpecificPredecessor, resolveMergeTarget } from './session-merger.mjs';
+import { backfillBodies, deriveTranscriptPath, logBackfill } from './turn-backfill.mjs';
 import { buildResumeContext } from './resume-context.mjs';
+import { readAllSessionStates } from './state-file.mjs';
 import { ensureMonitorTaskFile } from './vscode-task.mjs';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
@@ -37,7 +39,7 @@ import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 
 // SPIKE ONLY — Phase 0-2 / 0-4 検証用。marker file 削除で無効化される。
-// docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md §3 Phase 0-2 参照。
+// docs/10_transcript_injection_plan.md §3 Phase 0-2 参照。
 const SPIKE_MARKER_PATH = join(homedir(), '.throughline', 'spike-inject.flag');
 
 // Phase 0-6: initialUserMessage が interactive モードで効くか実機検証する experimental switch。
@@ -175,6 +177,63 @@ export async function run() {
   //    Phase 0-6: initialUserMessage test flag 存在時は JSON 出力に切り替え、
   //    initialUserMessage が interactive モードで messages[] に乗るか実機検証する。
   if (mergeResult.merged) {
+    const predecessorId = mergeResult.predecessorId;
+    // /clear 直前ターンの取りこぼしを注入前に回収する。前任の transcript path は project path
+    // から決定的に導出する — state ファイルは Stop 不発の前任（まさに回収したい事例）では存在しないため補助。
+    const derivedTranscriptPath = deriveTranscriptPath(projectPath, predecessorId);
+    const stateTranscriptPath = readAllSessionStates().find(
+      (state) => state.sessionId === predecessorId,
+    )?.transcriptPath;
+    const predecessorTranscriptPath = existsSync(derivedTranscriptPath)
+      ? derivedTranscriptPath
+      : stateTranscriptPath && existsSync(stateTranscriptPath)
+        ? stateTranscriptPath
+        : null;
+
+    if (predecessorTranscriptPath) {
+      try {
+        const backfill = backfillBodies(db, {
+          targetSessionId: session_id,
+          originSessionId: predecessorId,
+          transcriptPath: predecessorTranscriptPath,
+          now,
+        });
+        logBackfill({
+          ts: new Date(now).toISOString(),
+          hook: 'session-start',
+          session_id,
+          target: session_id,
+          origin: predecessorId,
+          transcript_path: predecessorTranscriptPath,
+          groups: backfill.groups,
+          inserted_turns: backfill.insertedTurns,
+          skipped_existing: backfill.skippedExisting,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[session-start:backfill] ${message}\n`);
+        logBackfill({
+          ts: new Date(now).toISOString(),
+          hook: 'session-start',
+          session_id,
+          target: session_id,
+          origin: predecessorId,
+          transcript_path: predecessorTranscriptPath,
+          error: message,
+        });
+      }
+    } else {
+      logBackfill({
+        ts: new Date(now).toISOString(),
+        hook: 'session-start',
+        session_id,
+        target: session_id,
+        origin: predecessorId,
+        transcript_path: null,
+        skip_reason: 'no_transcript_path',
+      });
+    }
+
     const text = buildResumeContext(db, {
       sessionId: session_id,
       isInheritance: true,
@@ -210,7 +269,7 @@ export async function run() {
 
   // 5. SPIKE: marker file あり + merge 成立 + transcript_path あり の 3 条件で
   //    L2 を user/assistant role 付きで transcript_path にも append する。
-  //    本実装ではない (docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md Phase 0-2)。
+  //    本実装ではない (docs/10_transcript_injection_plan.md Phase 0-2)。
   //
   //    tracer: 末尾 assistant 行に stdout 注入には含まれない一意トークンを付与する。
   //    次の /clear 後に Claude が tracer を再現できれば JSONL 経路はモデル可視。

package/src/spike-transcript-writer.mjs

@@ -1,7 +1,7 @@
 /**
  * SPIKE ONLY — Phase 0-2 / 0-4 検証用。本実装ではない。
  *
- * docs/THROUGHLINE_TRANSCRIPT_INJECTION_PLAN.md Phase 0-2 で
+ * docs/10_transcript_injection_plan.md Phase 0-2 で
  * 「`/clear` 直後の SessionStart hook 内で transcript_path に L2 を user/assistant
  *  role 付きで append すると、Claude が次の short prompt の文脈として読むか」を実機検証する。
  *

package/src/state-file.mjs

@@ -5,7 +5,7 @@
  * 書き手: turn-processor (Claude Stop), codex-hook (Codex Stop)
  * 読み手: token-monitor
  *
- * 設計判断 (docs/PUBLIC_RELEASE_PLAN.md §4.5/4.6):
+ * 設計判断 (docs/04_public_release_plan.md §4.5/4.6):
  *   - ファイル単位分割で last-writer-wins 問題を解消
  *   - updatedAt ベースで stale 判定（短命 hook process の PID には依存しない）
  *   - projectPath は path.resolve → / → 末尾 / 除去 → Windows lowercase で正規化

package/src/token-monitor.mjs

@@ -9,7 +9,7 @@
  *
  * VS Code の分割ターミナルなどで常時起動しておく。
  *
- * 設計: docs/PUBLIC_RELEASE_PLAN.md §4.5/4.6
+ * 設計: docs/04_public_release_plan.md §4.5/4.6
  *   - 状態ファイルはセッション単位 (~/.throughline/state/<session_id>.json)
  *   - setInterval (1s) + mtime 差分検知で更新を捕捉
  *   - updatedAt 降順ソート、先頭行を ▶ でハイライト

package/src/transcript-reader.mjs

@@ -54,22 +54,93 @@ export function readTranscript(transcriptPath) {
     // user / assistant エントリのみ対象
     if (entry.type !== 'user' && entry.type !== 'assistant') continue;
 
+    // subagent の sidechain エントリは主会話ではないので除外。現行 CC は主 transcript に
+    // 書かない（400 transcript 実測ゼロ件）が、将来変更への安価な防御 (docs/12 B-1)
+    if (entry.isSidechain === true) continue;
+
     const msg = entry.message;
     if (!msg || !msg.role || msg.content == null) continue;
 
     const text = extractText(msg.content);
     if (!text) continue;
 
+    const ts = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : NaN;
     turns.push({
       role: msg.role,
       content: text,
       turn_number: turns.length,
+      timestamp: Number.isNaN(ts) ? null : ts,
     });
   }
 
   return turns;
 }
 
+/**
+ * assistant テキスト断片が API 通知（junk）かを判定する。
+ * junk が論理ターン群の最終断片になると、通知を本文として保存し実回答を捨てる
+ * ことになるため、代表選択から除外する (docs/12 B-1 refuter 修正3)。
+ * パターンは実測で bodies に混入した通知に限定し、prefix 固定で偽陽性を避ける。
+ * @param {string} text
+ */
+export function isJunkAssistantText(text) {
+  if (typeof text !== 'string') return false;
+  return (
+    text.startsWith("You've hit your session limit") ||
+    text.startsWith("You've reached your") ||
+    text.startsWith('API Error')
+  );
+}
+
+/**
+ * transcript を論理ターン群に分解する。
+ *
+ * 論理ターン群 = user テキストエントリ 1 件 + それに続く assistant テキスト断片群。
+ * 途中割り込み（plan 拒否・AskUserQuestion 応答等）は tool_result 内に埋まり
+ * readTranscript には不可視のため、1 群が複数 Stop・複数断片を含むのは日常パターン。
+ *
+ * representative = 群内最後の非 junk 断片。この index が bodies の turn_number になる
+ * （user 行・assistant 行とも同じ turn_number で保存する現行規約と同じ）。
+ * 全断片が junk の群、断片ゼロの群（assistant 本文が transcript に無い B-2 ケース）は
+ * 返さない。
+ *
+ * @param {string} transcriptPath
+ * @returns {Array<{
+ *   user: {content: string, timestamp: number|null, turn_number: number},
+ *   fragments: Array<{index: number, content: string, timestamp: number|null}>,
+ *   representative: {index: number, content: string, timestamp: number|null},
+ * }>}
+ */
+export function getLogicalTurnGroups(transcriptPath) {
+  const turns = readTranscript(transcriptPath);
+  const raw = [];
+  let current = null;
+  for (const t of turns) {
+    if (t.role === 'user') {
+      if (current) raw.push(current);
+      current = { user: t, fragments: [] };
+    } else if (t.role === 'assistant' && current) {
+      current.fragments.push({ index: t.turn_number, content: t.content, timestamp: t.timestamp });
+    }
+  }
+  if (current) raw.push(current);
+
+  const groups = [];
+  for (const g of raw) {
+    if (g.fragments.length === 0) continue;
+    let representative = null;
+    for (let i = g.fragments.length - 1; i >= 0; i--) {
+      if (!isJunkAssistantText(g.fragments[i].content)) {
+        representative = g.fragments[i];
+        break;
+      }
+    }
+    if (!representative) continue; // 全断片 junk
+    groups.push({ user: g.user, fragments: g.fragments, representative });
+  }
+  return groups;
+}
+
 /**
  * ANSI エスケープシーケンスを除去する。
  * ツール出力（特に Bash）にしばしば含まれる色コードを剥がす。

package/src/turn-backfill.mjs

@@ -0,0 +1,131 @@
+/**
+ * turn-backfill.mjs — transcript 全体走査による L2 回収の共通ルーチン
+ *
+ * 従来の「Stop ごとに最後の 1 ペアのみ保存」は、Stop の空振り・不発が bodies の
+ * 永久穴になった（実測欠落率 Desktop 27% / VSCode 41%、docs/12 §6）。
+ * 本ルーチンは transcript の全論理ターン群を走査し、未捕捉の完了ターンを回収する。
+ * turn-processor（毎 Stop）と session-start（マージ直後の前任回収）が共用する。
+ *
+ * 設計は docs/12 Workstream B-1（refuter 修正 1/3/4/5 適用済み）:
+ *   - 群レベル dedup: 群の**どの断片 index も** bodies に無い群だけ挿入する。
+ *     部分捕捉済み群への再挿入は「同一 user 発話の重複ペア」を量産する
+ *     （実測: 全 DB で 110 群が該当）ため、代表断片の差し替え回収はしない。
+ *   - 代表断片 = 群内最後の非 junk 断片（getLogicalTurnGroups 側で選択済み）。
+ *   - created_at は transcript エントリの timestamp。now を使うと一括回収行が
+ *     同一ミリ秒に潰れ、created_at 順ソート（handoff-record の L2 窓・現在地アンカー）
+ *     の会話順が tie で不定化するため。timestamp 欠損時のみ now。
+ *   - INSERT は 1 トランザクション（fsync 1 回、turn-processor の details と同型）。
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { getLogicalTurnGroups } from './transcript-reader.mjs';
+
+/**
+ * バックフィル回収実績を ~/.throughline/logs/backfill.log に 1 行 JSON で記録する。
+ * @param {object} entry
+ */
+export function logBackfill(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'backfill.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(`[backfill-log] ${msg}\n`);
+  }
+}
+
+/**
+ * Claude Code の project-dir munging から session transcript path を決定的に導出する。
+ * macOS/Linux の Claude Code 規約を mirror する。Windows では呼び出し側が state file の
+ * transcriptPath に fallback する。
+ * @param {string} projectPath
+ * @param {string} sessionId
+ * @returns {string}
+ */
+export function deriveTranscriptPath(projectPath, sessionId) {
+  const mungedProjectPath = `-${String(projectPath).replace(/[/.]/g, '-').replace(/^-+/, '')}`;
+  return join(homedir(), '.claude', 'projects', mungedProjectPath, `${sessionId}.jsonl`);
+}
+
+/**
+ * transcript の未捕捉完了ターンを bodies へ回収する。
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {object} opts
+ * @param {string} opts.targetSessionId 書き込み先 session_id（merge 済みなら合流先）
+ * @param {string} opts.originSessionId transcript を所有する origin session_id
+ * @param {string|null|undefined} opts.transcriptPath
+ * @param {number} opts.now timestamp 欠損時の fallback epoch ms
+ * @returns {{groups: number, insertedTurns: number, skippedExisting: number, lastTurnNumber: number|null}}
+ */
+export function backfillBodies(db, { targetSessionId, originSessionId, transcriptPath, now }) {
+  const groups = getLogicalTurnGroups(transcriptPath);
+  if (groups.length === 0) {
+    return { groups: 0, insertedTurns: 0, skippedExisting: 0, lastTurnNumber: null };
+  }
+
+  const existing = new Set(
+    db
+      .prepare('SELECT DISTINCT turn_number FROM bodies WHERE origin_session_id = ?')
+      .all(originSessionId)
+      .map((r) => r.turn_number),
+  );
+
+  const insertBody = db.prepare(
+    `INSERT OR IGNORE INTO bodies
+       (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  );
+
+  let insertedTurns = 0;
+  let skippedExisting = 0;
+
+  db.exec('BEGIN');
+  try {
+    for (const g of groups) {
+      // 群のいずれかの断片 index が既に bodies にある = 部分捕捉済み群。
+      // 代表差し替えは重複ペアを生むので回収しない (refuter 修正1)。
+      if (g.fragments.some((f) => existing.has(f.index))) {
+        skippedExisting++;
+        continue;
+      }
+      const turnNumber = g.representative.index;
+      const assistantAt = g.representative.timestamp ?? now;
+      const userAt = g.user.timestamp ?? assistantAt;
+
+      insertBody.run(
+        targetSessionId,
+        originSessionId,
+        turnNumber,
+        'user',
+        g.user.content,
+        Math.round(g.user.content.length / 4),
+        userAt,
+      );
+      insertBody.run(
+        targetSessionId,
+        originSessionId,
+        turnNumber,
+        'assistant',
+        g.representative.content,
+        Math.round(g.representative.content.length / 4),
+        assistantAt,
+      );
+      insertedTurns++;
+    }
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+
+  return {
+    groups: groups.length,
+    insertedTurns,
+    skippedExisting,
+    lastTurnNumber: groups[groups.length - 1].representative.index,
+  };
+}