throughline 0.5.0 → 0.6.1

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/phase0-spotter-contract.test.mjs

@@ -0,0 +1,280 @@
+import assert from 'node:assert/strict';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import { DatabaseSync } from 'node:sqlite';
+
+import { captureCodexRolloutToDb } from './codex-capture.mjs';
+import { runCodexUserPromptSubmitHook } from './cli/codex-hook.mjs';
+import { findCodexThreadCandidate } from './codex-thread-index.mjs';
+
+const THREAD_ID = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+
+function makeCaptureDb() {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE sessions (
+      session_id TEXT PRIMARY KEY,
+      project_path TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      merged_into TEXT
+    );
+    CREATE TABLE skeletons (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      origin_session_id TEXT,
+      turn_number INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+    CREATE TABLE bodies (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      origin_session_id TEXT NOT NULL,
+      turn_number INTEGER NOT NULL,
+      role TEXT NOT NULL,
+      text TEXT NOT NULL,
+      token_count INTEGER,
+      created_at INTEGER NOT NULL
+    );
+    CREATE TABLE details (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      origin_session_id TEXT,
+      turn_number INTEGER,
+      tool_name TEXT NOT NULL,
+      input_text TEXT,
+      output_text TEXT,
+      token_count INTEGER NOT NULL DEFAULT 0,
+      created_at INTEGER NOT NULL,
+      kind TEXT,
+      source_id TEXT
+    );
+  `);
+  return db;
+}
+
+function event(type, payload = {}) {
+  return {
+    timestamp: '2026-07-13T00:00:00.000Z',
+    type: 'event_msg',
+    payload: { type, ...payload },
+  };
+}
+
+function developerMemory(text = '## Throughline: Active Work Context\ninternal memory') {
+  return {
+    timestamp: '2026-07-13T00:00:01.000Z',
+    type: 'response_item',
+    payload: {
+      type: 'message',
+      role: 'developer',
+      content: [{ type: 'input_text', text }],
+    },
+  };
+}
+
+function toolInput() {
+  return {
+    timestamp: '2026-07-13T00:00:01.000Z',
+    type: 'response_item',
+    payload: {
+      type: 'function_call',
+      name: 'exec_command',
+      arguments: '{"cmd":"pwd"}',
+      call_id: 'call_inflight',
+    },
+  };
+}
+
+function writeRollout(home, { cwd, id = THREAD_ID, events = [] }) {
+  const dir = join(home, 'sessions', '2026', '07', '13');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `rollout-2026-07-13T00-00-00-${id}.jsonl`);
+  const rows = [
+    {
+      timestamp: '2026-07-13T00:00:00.000Z',
+      type: 'session_meta',
+      payload: { id, cwd, source: 'vscode', cli_version: '0.128.0-alpha.1' },
+    },
+    ...events,
+  ];
+  writeFileSync(path, `${rows.map((row) => JSON.stringify(row)).join('\n')}\n`);
+  return path;
+}
+
+test('Phase 0: capture projection preserves one completed user/assistant pair and its Codex origin identity', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-phase0-capture-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-phase0-capture-project-'));
+  const db = makeCaptureDb();
+  try {
+    writeRollout(home, {
+      cwd: project,
+      events: [
+        event('user_message', { message: 'completed user request' }),
+        event('task_started'),
+        event('agent_message', { message: 'completed assistant response' }),
+        event('task_complete'),
+        developerMemory(),
+      ],
+    });
+
+    const result = captureCodexRolloutToDb(db, { threadId: THREAD_ID, codexHome: home, projectPath: project });
+    assert.equal(result.status, 'captured');
+    assert.deepEqual(
+      db
+        .prepare('SELECT origin_session_id, turn_number, role, text FROM bodies ORDER BY id')
+        .all()
+        .map((row) => ({ ...row })),
+      [
+        { origin_session_id: `codex:${THREAD_ID}`, turn_number: 1, role: 'user', text: 'completed user request' },
+        {
+          origin_session_id: `codex:${THREAD_ID}`,
+          turn_number: 1,
+          role: 'assistant',
+          text: 'completed assistant response',
+        },
+      ],
+      'audit projection candidates are completed conversation pairs only',
+    );
+  } finally {
+    db.close();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Phase 0: read-only WAL audit harness sees committed data during a writer transaction without writing DB sidecars', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-phase0-wal-'));
+  const path = join(dir, 'throughline.db');
+  const writer = new DatabaseSync(path);
+  let reader;
+  try {
+    writer.exec('PRAGMA journal_mode = WAL; CREATE TABLE audit_probe (value TEXT); INSERT INTO audit_probe VALUES (\'committed\');');
+    writer.exec("BEGIN IMMEDIATE; UPDATE audit_probe SET value = 'uncommitted';");
+
+    const before = snapshotSqliteFiles(path);
+    reader = new DatabaseSync(path, { readOnly: true });
+    assert.equal(reader.prepare('SELECT value FROM audit_probe').get().value, 'committed');
+    assert.throws(() => reader.exec("INSERT INTO audit_probe VALUES ('forbidden')"));
+    assert.deepEqual(snapshotSqliteFiles(path), before, 'audit reader must not modify DB, -wal, or -shm');
+  } finally {
+    reader?.close();
+    writer.exec('ROLLBACK');
+    writer.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('Phase 0: Spotter child environment prevents Throughline Codex hook re-entry before any capture side effect', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-phase0-spotter-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-phase0-spotter-project-'));
+  try {
+    writeRollout(home, {
+      cwd: project,
+      events: [
+        event('user_message', { message: 'must not be captured from Spotter child' }),
+        event('task_started'),
+        event('agent_message', { message: 'must not be captured from Spotter child' }),
+        event('task_complete'),
+      ],
+    });
+
+    for (const childEnv of ['SPOTTER_PARENT_PID', 'SPOTTER_BACKEND', 'SPOTTER_CHILD_BACKEND']) {
+      const db = makeCaptureDb();
+      let monitorWrites = 0;
+      let taskEnsures = 0;
+      try {
+        const result = await runCodexUserPromptSubmitHook({
+          args: { codexThreadId: THREAD_ID, codexHome: home, projectPath: project },
+          env: { [childEnv]: '1' },
+          db,
+          ensureMonitorTask: () => {
+            taskEnsures++;
+          },
+          writeMonitorState: () => {
+            monitorWrites++;
+          },
+          buildMonitorUsage: () => null,
+        });
+
+        assert.equal(result.status, 'skipped', childEnv);
+        assert.equal(result.reason, 'spotter_child_backend', childEnv);
+        assert.equal(taskEnsures, 0, childEnv);
+        assert.equal(monitorWrites, 0, childEnv);
+        assert.equal(db.prepare('SELECT COUNT(*) AS count FROM bodies').get().count, 0, childEnv);
+      } finally {
+        db.close();
+      }
+    }
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Phase 0: project identity accepts a rollout under a marker root subdirectory through symlink and Windows-style case', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-phase0-identity-home-'));
+  const markerRoot = mkdtempSync(join(tmpdir(), 'tl-phase0-marker-root-'));
+  const aliasParent = mkdtempSync(join(tmpdir(), 'tl-phase0-marker-alias-'));
+  const child = join(markerRoot, 'packages', 'adapter');
+  const alias = join(aliasParent, 'spotter-link');
+  try {
+    mkdirSync(child, { recursive: true });
+    symlinkSync(markerRoot, alias);
+    assert.ok(lstatSync(alias).isSymbolicLink());
+
+    writeRollout(home, { cwd: child });
+    assert.equal(
+      findCodexThreadCandidate({ threadId: THREAD_ID, codexHome: home, projectPath: alias })?.id,
+      THREAD_ID,
+      'marker root must include rollout cwd descendants after symlink resolution',
+    );
+
+    const windowsThreadId = '019dfabb-1111-7111-8111-111111111111';
+    writeRollout(home, {
+      id: windowsThreadId,
+      cwd: 'C:\\Users\\Kite\\Developer\\Spotter\\packages\\adapter',
+    });
+    assert.equal(
+      findCodexThreadCandidate({
+        threadId: windowsThreadId,
+        codexHome: home,
+        projectPath: 'c:/users/kite/developer/spotter',
+      })?.id,
+      windowsThreadId,
+      'Windows-style path case must retain marker-root descendant identity',
+    );
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    rmSync(markerRoot, { recursive: true, force: true });
+    rmSync(aliasParent, { recursive: true, force: true });
+  }
+});
+
+function snapshotSqliteFiles(path) {
+  return [path, `${path}-wal`, `${path}-shm`].map((file) => {
+    if (!existsSync(file)) return { file, exists: false };
+    const stat = lstatSync(file);
+    return {
+      file,
+      exists: true,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      bytes: readFileSync(file).toString('hex'),
+    };
+  });
+}

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）にしばしば含まれる色コードを剥がす。