throughline 0.1.0 → 0.2.0

package/README.md

@@ -51,7 +51,7 @@ Start any Claude Code session and your turns will begin flowing into
 
 ---
 
-## Three-layer memory model (schema v4)
+## Three-layer memory model (schema v6)
 
 | Layer | Name       | Where it lives        | Content                                                    | Cost per turn |
 | ----- | ---------- | --------------------- | ---------------------------------------------------------- | ------------- |
@@ -81,29 +81,49 @@ of tool inputs, tool outputs, and hook output captured at L3 for that turn.
 
 ---
 
-## `/clear`-safe with memory rebonding
+## Explicit handoff via `/tl`
 
-When you run `/clear`, the conversation transcript is discarded, but the SQLite
-database is untouched. On the next session start:
+Inheritance is **opt-in**, not automatic. When you want the next session to
+pick up where this one left off, type `/tl` in the current session before you
+`/clear` or open a new chat. Without `/tl`, new sessions start fresh — no
+memory is carried over.
 
-1. `SessionStart` hook fires with a new `session_id`
-2. Throughline finds the previous session in the same project
-3. It **rebonds** all `skeletons` / `bodies` / `details` rows from the previous
-   session into the new session (via `UPDATE session_id = ?`) inside a
-   `BEGIN IMMEDIATE` transaction
-4. A handover banner is injected:
-   `## Throughline: セッション記憶（N ターン引き継ぎ）`
-
-Each row keeps its **origin_session_id**, so memories accumulate through chains
-of `/clear` rather than being lost or overwritten:
+The `/tl` slash command writes a **handoff baton** (the current `session_id`)
+into the `handoff_batons` table. On the next `SessionStart`, the hook reads the
+baton, and if it is less than **1 hour old**, merges that session's memory
+into the new session using a deterministic `UPDATE session_id = ?` inside a
+`BEGIN IMMEDIATE` transaction. The baton is consumed (deleted) atomically with
+the merge, so it cannot fire twice.
 
 ```
-S1 (4 turns) -- /clear --> S2 (merges S1, adds 3 turns) -- /clear --> S3 (merges S2, adds 5 turns)
-                           origin=S1×4                                origin=S1×4, S2×3, S3×5
+Session A (type /tl)  -----------> baton written
+                                       |
+                      /clear           |
+                         |             ▼
+                      Session B  ---- reads baton, merges A into B, deletes baton ---->
+                         |
+                      (type /tl again to hand off further)
 ```
 
-No time-window heuristic, no PID guessing, no ancestor walking. Just a
-deterministic UPDATE inside a SQLite transaction.
+Why explicit baton instead of auto-inherit:
+
+- **Zero false positives.** A parallel window, a VSCode restart, or a genuine
+  new task in the same repo won't accidentally inherit the previous session's
+  memory. Only an explicit `/tl` triggers inheritance.
+- **VSCode extension compatibility.** The `SessionStart` hook's `source` field
+  is rewritten to `"startup"` by the Claude Code VSCode extension even after
+  `/clear` (see [issue #49937](https://github.com/anthropics/claude-code/issues/49937)),
+  so source-based detection is unreliable. A user-driven baton sidesteps this.
+- **Deterministic.** No time-window heuristic, no PID guessing, no ancestor
+  walking. The user declares intent; the hook carries it out.
+
+Each merged row keeps its `origin_session_id`, so repeated `/tl` handoffs
+accumulate memory through chains:
+
+```
+S1 (4 turns) --/tl,/clear--> S2 (merges S1, adds 3 turns) --/tl,/clear--> S3 (merges S2, adds 5 turns)
+                             origin=S1×4                                  origin=S1×4, S2×3, S3×5
+```
 
 ---
 
@@ -165,8 +185,16 @@ you open the folder. Drop an equivalent config into your own project's
 | `throughline status`                           | Print DB statistics (sessions, skeletons, bodies, details)   |
 | `throughline --version`                        | Print the installed version                                  |
 
+Slash commands (invoked by the user in Claude Code):
+
+| Command       | What it does                                                      |
+| ------------- | ----------------------------------------------------------------- |
+| `/tl`         | Write a handoff baton so the next session inherits this one       |
+| `/sc-detail <time>` | Retrieve L2 body text and L3 tool I/O for a past turn       |
+
 Hook subcommands (invoked by Claude Code, not by humans):
-`session-start` (SessionStart), `process-turn` (Stop).
+`session-start` (SessionStart), `process-turn` (Stop),
+`prompt-submit` (UserPromptSubmit — detects `/tl` and writes baton).
 
 ### `throughline detail` — for AI, not humans
 
@@ -210,16 +238,17 @@ plain `.mjs` files.
     └── <session_id>.json     Per-session activity state for the monitor
 ```
 
-Schema v5:
+Schema v6:
 
 - `sessions` — one row per `session_id`, with `project_path` and `merged_into`
 - `skeletons` — L1 one-liners, keyed by `(session_id, origin_session_id, turn, role)`
 - `bodies` — L2 verbatim text (user + assistant), same key shape
 - `details` — L3 records with `kind` column (`tool_input` / `tool_output` / `system` / `image`) and `source_id` for idempotent re-processing
+- `handoff_batons` — one row per `project_path`, holding the `session_id` that `/tl` has nominated to hand off. Consumed and deleted by the next `SessionStart` if within the 1-hour TTL.
 - `injection_log` — audit trail of injection events
 
-All tables carry an `origin_session_id` so rebonded rows keep their lineage
-after a `/clear` chain.
+All memory tables carry an `origin_session_id` so rebonded rows keep their
+lineage across a chain of `/tl` handoffs.
 
 ---
 
@@ -287,9 +316,15 @@ unchanged here.
 
 **Database got corrupted / want a clean slate**
 Delete `~/.throughline/throughline.db` (and the `-shm` / `-wal` companion files)
-and `~/.throughline/state/*.json`. A fresh database with schema v4 is created on
+and `~/.throughline/state/*.json`. A fresh database with schema v6 is created on
 the next hook fire.
 
+**New session didn't inherit memory from the previous one**
+This is the designed behavior — inheritance requires an explicit `/tl` in the
+previous session. If you forgot to type it before `/clear`, the memory is still
+in SQLite but won't auto-inject. You can still retrieve specific turns with
+`/sc-detail <time>`.
+
 ---
 
 ## Development
@@ -297,7 +332,7 @@ the next hook fire.
 ```bash
 git clone https://github.com/kitepon-rgb/Throughline.git
 cd Throughline
-npm link                              # Put `throughline` on PATH
+npm link                              # Put `throughline` on PATH (dev only)
 throughline install --project         # Register hooks for this repo only
 node --test src/turn-processor.test.mjs src/session-merger.test.mjs
 ```
@@ -316,7 +351,8 @@ the folder in VS Code.
 ## Design docs
 
 - [`docs/L1_L2_L3_REDESIGN.md`](docs/L1_L2_L3_REDESIGN.md) — **current design
-  spec** for the L1/L2/L3 differential layer model (schema v4). Authoritative.
+  spec** for the L1/L2/L3 differential layer model (schema v4 base + v5 L3
+  classification extension). Authoritative.
 - [`docs/PUBLIC_RELEASE_PLAN.md`](docs/PUBLIC_RELEASE_PLAN.md) — public release
   plan (CLI surface, package.json layout, § 0 fallback rule)
 - [`docs/archive/`](docs/archive/) — superseded design documents kept for

package/bin/throughline.mjs

@@ -32,6 +32,9 @@ switch (cmd) {
   case 'session-start':
     await import('../src/session-start.mjs');
     break;
+  case 'prompt-submit':
+    await import('../src/prompt-submit.mjs');
+    break;
   case 'monitor':
     await import('../src/token-monitor.mjs');
     break;
@@ -74,5 +77,6 @@ Usage:
 Hook subcommands (called by Claude Code):
   throughline session-start   SessionStart hook
   throughline process-turn    Stop hook
+  throughline prompt-submit   UserPromptSubmit hook (/tl baton writer)
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/baton.mjs

@@ -0,0 +1,83 @@
+/**
+ * baton.mjs — 引き継ぎバトン管理
+ *
+ * バトン方式の設計 (docs/INHERITANCE_ON_CLEAR_ONLY.md):
+ *   - ユーザーが旧セッションで /tl スラッシュコマンドを打つ → UserPromptSubmit hook が
+ *     baton テーブルに (project_path, session_id, created_at) を INSERT OR REPLACE
+ *   - 新セッションの SessionStart hook が baton を消費:
+ *     TTL 1 時間以内 かつ session_id が自分自身でない → 前任として merge
+ *     期限切れ or 自己指名 → 破棄
+ *   - 消費は atomic (BEGIN IMMEDIATE トランザクション内で SELECT + DELETE)
+ *
+ * なぜバトン方式か:
+ *   - VSCode 拡張では SessionStart payload の source が /clear 後も "startup" に潰される
+ *     ため source 値だけで /clear を識別できない (GitHub issue #49937)
+ *   - 時間差ヒューリスティック (案 D) は誤爆の可能性があり、ユーザー明示の意思表示を
+ *     引き継ぎ発火の唯一の条件とする方が決定論的
+ */
+
+/**
+ * バトン TTL (ミリ秒)。ユーザーが /tl を打ってから新セッション開始までの猶予。
+ * 超過したバトンは consumeBaton で破棄される（merge されない）。
+ */
+export const BATON_TTL_MS = 60 * 60 * 1000; // 1 時間
+
+/**
+ * 現在セッション (= /tl を発動したセッション) を次回 SessionStart で merge 対象に指名する。
+ * 同 project_path の既存バトンは上書きされる (INSERT OR REPLACE)。最新意図のみ有効。
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{ projectPath: string, sessionId: string, now?: number }} params
+ */
+export function writeBaton(db, { projectPath, sessionId, now = Date.now() }) {
+  db.prepare(
+    `INSERT OR REPLACE INTO handoff_batons (project_path, session_id, created_at)
+     VALUES (?, ?, ?)`,
+  ).run(projectPath, sessionId, now);
+}
+
+/**
+ * 同 project_path のバトンを読み出して削除する (atomic)。
+ *
+ * 戻り値:
+ *   - { sessionId, ageMs }   : バトン存在 かつ TTL 以内
+ *   - { sessionId: null, skipReason: 'expired', ageMs }  : TTL 超過で破棄
+ *   - { sessionId: null, skipReason: 'missing' }          : バトン無し
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{ projectPath: string, now?: number, ttlMs?: number }} params
+ * @returns {{ sessionId: string | null, ageMs?: number, skipReason?: 'expired' | 'missing' }}
+ */
+export function consumeBaton(db, { projectPath, now = Date.now(), ttlMs = BATON_TTL_MS }) {
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    const row = db
+      .prepare(
+        `SELECT session_id, created_at FROM handoff_batons WHERE project_path = ?`,
+      )
+      .get(projectPath);
+
+    if (!row) {
+      db.exec('COMMIT');
+      return { sessionId: null, skipReason: 'missing' };
+    }
+
+    db.prepare('DELETE FROM handoff_batons WHERE project_path = ?').run(projectPath);
+    const ageMs = now - row.created_at;
+
+    if (ageMs > ttlMs) {
+      db.exec('COMMIT');
+      return { sessionId: null, skipReason: 'expired', ageMs };
+    }
+
+    db.exec('COMMIT');
+    return { sessionId: row.session_id, ageMs };
+  } catch (err) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}

package/src/baton.test.mjs

@@ -0,0 +1,99 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { writeBaton, consumeBaton, BATON_TTL_MS } from './baton.mjs';
+
+function makeDb() {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE handoff_batons (
+      project_path TEXT    PRIMARY KEY,
+      session_id   TEXT    NOT NULL,
+      created_at   INTEGER NOT NULL
+    );
+  `);
+  return db;
+}
+
+test('BATON_TTL_MS default is 1 hour', () => {
+  assert.equal(BATON_TTL_MS, 60 * 60 * 1000);
+});
+
+test('writeBaton: inserts a fresh baton', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  const row = db.prepare('SELECT * FROM handoff_batons').get();
+  assert.equal(row.project_path, '/proj');
+  assert.equal(row.session_id, 'S1');
+  assert.equal(row.created_at, 1000);
+});
+
+test('writeBaton: overwrites previous baton for same project_path', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S2', now: 2000 });
+  const rows = db.prepare('SELECT * FROM handoff_batons').all();
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].session_id, 'S2');
+  assert.equal(rows[0].created_at, 2000);
+});
+
+test('writeBaton: separate project_paths coexist', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/a', sessionId: 'A', now: 1000 });
+  writeBaton(db, { projectPath: '/b', sessionId: 'B', now: 1000 });
+  const rows = db.prepare('SELECT * FROM handoff_batons ORDER BY project_path').all();
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].project_path, '/a');
+  assert.equal(rows[1].project_path, '/b');
+});
+
+test('consumeBaton: returns sessionId and deletes when within TTL', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  const result = consumeBaton(db, {
+    projectPath: '/proj',
+    now: 1000 + 30 * 60 * 1000, // 30 min後
+    ttlMs: BATON_TTL_MS,
+  });
+  assert.equal(result.sessionId, 'S1');
+  assert.equal(result.ageMs, 30 * 60 * 1000);
+
+  const rows = db.prepare('SELECT * FROM handoff_batons').all();
+  assert.equal(rows.length, 0, 'baton should be deleted after consumption');
+});
+
+test('consumeBaton: returns expired when age exceeds TTL, still deletes', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/proj', sessionId: 'S1', now: 1000 });
+  const result = consumeBaton(db, {
+    projectPath: '/proj',
+    now: 1000 + 2 * 60 * 60 * 1000, // 2 時間後
+    ttlMs: BATON_TTL_MS,
+  });
+  assert.equal(result.sessionId, null);
+  assert.equal(result.skipReason, 'expired');
+  assert.ok(result.ageMs > BATON_TTL_MS);
+
+  const rows = db.prepare('SELECT * FROM handoff_batons').all();
+  assert.equal(rows.length, 0, 'expired baton should still be deleted');
+});
+
+test('consumeBaton: returns missing when no baton exists', () => {
+  const db = makeDb();
+  const result = consumeBaton(db, { projectPath: '/proj', now: 1000 });
+  assert.equal(result.sessionId, null);
+  assert.equal(result.skipReason, 'missing');
+});
+
+test('consumeBaton: scopes per project_path (does not cross-consume)', () => {
+  const db = makeDb();
+  writeBaton(db, { projectPath: '/a', sessionId: 'A', now: 1000 });
+  const result = consumeBaton(db, { projectPath: '/b', now: 1000 });
+  assert.equal(result.sessionId, null);
+  assert.equal(result.skipReason, 'missing');
+
+  // /a のバトンは残っているはず
+  const rows = db.prepare("SELECT * FROM handoff_batons WHERE project_path = '/a'").all();
+  assert.equal(rows.length, 1);
+});

package/src/cli/install.mjs

@@ -19,6 +19,7 @@ import { homedir } from 'node:os';
 const SC_COMMANDS = [
   'throughline process-turn',
   'throughline session-start',
+  'throughline prompt-submit',
   // 旧コマンド（アンインストール時に除去する）
   'throughline inject-context',
   'throughline capture-tool',
@@ -35,6 +36,9 @@ const SC_HOOKS = {
   Stop: {
     hooks: [{ type: 'command', command: 'throughline process-turn' }],
   },
+  UserPromptSubmit: {
+    hooks: [{ type: 'command', command: 'throughline prompt-submit' }],
+  },
 };
 
 function resolveSettingsPath(args) {
@@ -102,8 +106,9 @@ export async function run(args = []) {
   console.log(`  ${settingsPath}`);
   console.log('');
   console.log('有効な hooks:');
-  console.log('  SessionStart → throughline session-start  (セッション記録・記憶張り替え・L1/L2 注入)');
-  console.log('  Stop         → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
+  console.log('  SessionStart     → throughline session-start  (セッション記録・バトン消費・引き継ぎ注入)');
+  console.log('  Stop             → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
+  console.log('  UserPromptSubmit → throughline prompt-submit  (/tl バトン書き込み)');
   console.log('');
   console.log('  アンインストール: throughline uninstall');
 }

package/src/db.mjs

@@ -9,7 +9,7 @@ import { join } from 'path';
 
 const DB_DIR = join(homedir(), '.throughline');
 const DB_PATH = join(DB_DIR, 'throughline.db');
-const CURRENT_VERSION = 5;
+const CURRENT_VERSION = 6;
 
 let _db = null;
 
@@ -177,6 +177,20 @@ function initSchema(db) {
     `);
   }
 
+  // v5 → v6: handoff_batons テーブル追加（/tl スラッシュコマンドによる明示的引き継ぎ指名用）
+  // - project_path ごとに最新 1 件のみ (PRIMARY KEY)
+  // - SessionStart で読み出し、TTL 以内なら merge して DELETE
+  // - docs/INHERITANCE_ON_CLEAR_ONLY.md 参照: 案 D (時間差) 撤去、バトン方式へ移行
+  if (version < 6) {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS handoff_batons (
+        project_path TEXT    PRIMARY KEY,
+        session_id   TEXT    NOT NULL,
+        created_at   INTEGER NOT NULL
+      );
+    `);
+  }
+
   if (version < CURRENT_VERSION) {
     db.exec(`PRAGMA user_version = ${CURRENT_VERSION}`);
   }

package/src/prompt-submit.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit hook — /tl スラッシュコマンド検出 + バトン書き込み
+ *
+ * stdin: { session_id, cwd, prompt, hook_event_name, ... }
+ *
+ * 動作:
+ *   - prompt が /tl (単独 or /tl ... 形式) で始まっていればバトンを書き込んで終了
+ *   - それ以外は何もせず exit 0（プロンプトはそのまま Claude に渡る）
+ *   - 本 hook は注入を一切行わない (SessionStart の引き継ぎ注入と二重にならないため)
+ *
+ * 設計背景: docs/INHERITANCE_ON_CLEAR_ONLY.md バトン方式
+ */
+
+import { getDb } from './db.mjs';
+import { writeBaton } from './baton.mjs';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+function logBaton(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'baton-write.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(`[prompt-submit:log] ${msg}\n`);
+  }
+}
+
+/**
+ * プロンプトが /tl バトン発動コマンドか判定する。
+ * 許容: "/tl", "/tl\n", "/tl 何か" (前後空白は trim 済み前提)
+ */
+export function isBatonCommand(prompt) {
+  if (typeof prompt !== 'string') return false;
+  const trimmed = prompt.trim();
+  if (trimmed === '/tl') return true;
+  if (trimmed.startsWith('/tl ') || trimmed.startsWith('/tl\n')) return true;
+  return false;
+}
+
+async function main() {
+  let raw = '';
+  await new Promise((resolve) => {
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', resolve);
+  });
+
+  const payload = JSON.parse(raw);
+  const { session_id, cwd, prompt } = payload;
+
+  if (!isBatonCommand(prompt)) {
+    process.exit(0);
+    return;
+  }
+
+  if (!session_id) {
+    process.stderr.write('[prompt-submit] missing session_id in payload\n');
+    process.exit(0);
+    return;
+  }
+
+  const projectPath = cwd ?? process.cwd();
+  const db = getDb();
+  const now = Date.now();
+
+  writeBaton(db, { projectPath, sessionId: session_id, now });
+
+  logBaton({
+    ts: new Date(now).toISOString(),
+    session_id,
+    project_path: projectPath,
+  });
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : 'unknown';
+  process.stderr.write(`[prompt-submit] error: ${msg}\n`);
+  process.exit(1);
+});

package/src/session-merger.mjs

@@ -2,10 +2,13 @@
  * session-merger.mjs — 記憶張り替え + merged_into チェーン解決
  *
  * 用途:
- *   - SessionStart hook: mergePredecessorInto で前任セッションの L1/L2/L3 を新セッションに張り替える
- *   - Stop / PostToolUse hook: resolveMergeTarget で「入力 session_id → 実書き込み先」を解決
+ *   - SessionStart hook: バトンで指名された旧セッションを mergeSpecificPredecessor で新セッションに張り替え
+ *   - Stop hook: resolveMergeTarget で「入力 session_id → 実書き込み先」を解決
  *
- * 設計背景: docs/SESSION_LINKING_DESIGN.md
+ * 設計背景: docs/SESSION_LINKING_DESIGN.md, docs/INHERITANCE_ON_CLEAR_ONLY.md (バトン方式採用)
+ *
+ * 旧実装 (案 D: 時間差ヒューリスティック / 自動前任選択) は撤去済み。
+ * 引き継ぎはユーザーが /tl を打って書いたバトンによる明示的指名のみで発火する。
  */
 
 const MAX_CHAIN_DEPTH = 10;
@@ -16,8 +19,6 @@ const MAX_CHAIN_DEPTH = 10;
  * @param {import('node:sqlite').DatabaseSync} db
  * @param {string} sessionId
  * @returns {{ target: string, origin: string }}
- *   target: 実書き込み先 session_id（合流先）
- *   origin: 入力 session_id そのもの（INSERT 時の origin_session_id に使う）
  */
 export function resolveMergeTarget(db, sessionId) {
   const origin = sessionId;
@@ -46,43 +47,53 @@ export function resolveMergeTarget(db, sessionId) {
 }
 
 /**
- * 同一プロジェクト内の最新非合流セッションを新セッションに張り替える。
+ * バトンで指名された特定の旧セッションを新セッションに張り替える。
  *
  * 実行順序（BEGIN IMMEDIATE トランザクション内）:
- *   1. 前任候補 SELECT（同 project_path, session_id != new, merged_into IS NULL, 最新 updated_at）
+ *   1. 前任の妥当性チェック（存在する / 自分自身ではない / 既に合流済みでない / created_at が古い）
  *   2. skeletons / details / bodies の session_id を new に UPDATE
- *      （bodies は schema v4 で追加された L2 テーブル。v3 DB でも UPDATE は no-op で害なし）
  *   3. 前任 sessions.merged_into = new
  *   4. 新セッション sessions.updated_at = now
  *
  * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ newSessionId: string, projectPath: string }} params
- * @returns {{ merged: boolean, predecessorId?: string, rowCounts?: { sk: number, dt: number, bd: number } }}
+ * @param {{ newSessionId: string, predecessorId: string, now?: number }} params
+ * @returns {{
+ *   merged: boolean,
+ *   predecessorId?: string,
+ *   rowCounts?: { sk: number, dt: number, bd: number },
+ *   skipReason?: 'self_handoff' | 'predecessor_not_found' | 'already_merged' | 'predecessor_not_older',
+ * }}
  */
-export function mergePredecessorInto(db, { newSessionId, projectPath }) {
+export function mergeSpecificPredecessor(db, { newSessionId, predecessorId, now = Date.now() }) {
+  if (newSessionId === predecessorId) {
+    return { merged: false, skipReason: 'self_handoff' };
+  }
+
   db.exec('BEGIN IMMEDIATE');
   try {
-    // 時系列単調制約: 前任は新セッションより created_at が古いものに限る。
-    // これにより merge chain は厳密に時系列順となり、循環参照が構造的に発生不可能になる。
-    // (同時刻に複数 SessionStart が発火しても、自分自身より新しいセッションは選ばない)
     const pred = db
-      .prepare(
-        `SELECT session_id FROM sessions
-         WHERE lower(project_path) = lower(?)
-           AND session_id != ?
-           AND merged_into IS NULL
-           AND created_at < (SELECT created_at FROM sessions WHERE session_id = ?)
-         ORDER BY updated_at DESC
-         LIMIT 1`,
-      )
-      .get(projectPath, newSessionId, newSessionId);
+      .prepare('SELECT session_id, created_at, merged_into FROM sessions WHERE session_id = ?')
+      .get(predecessorId);
 
     if (!pred) {
       db.exec('COMMIT');
-      return { merged: false };
+      return { merged: false, skipReason: 'predecessor_not_found' };
+    }
+    if (pred.merged_into) {
+      db.exec('COMMIT');
+      return { merged: false, skipReason: 'already_merged' };
     }
 
-    const predecessorId = pred.session_id;
+    const self = db
+      .prepare('SELECT created_at FROM sessions WHERE session_id = ?')
+      .get(newSessionId);
+
+    // 時系列単調制約: 前任は新セッションより created_at が古いこと。
+    // バトンが自分より新しい session を指していたら（異常データ）merge しない。
+    if (self && pred.created_at >= self.created_at) {
+      db.exec('COMMIT');
+      return { merged: false, skipReason: 'predecessor_not_older' };
+    }
 
     const sk = db
       .prepare('UPDATE skeletons SET session_id = ? WHERE session_id = ?')
@@ -90,14 +101,12 @@ export function mergePredecessorInto(db, { newSessionId, projectPath }) {
     const dt = db
       .prepare('UPDATE details SET session_id = ? WHERE session_id = ?')
       .run(newSessionId, predecessorId);
-    // bodies は schema v4 以降のみ存在。v3 DB では 0 changes で害なし
     let bd = { changes: 0 };
     try {
       bd = db
         .prepare('UPDATE bodies SET session_id = ? WHERE session_id = ?')
         .run(newSessionId, predecessorId);
     } catch (err) {
-      // bodies テーブルが未作成の場合は無視（schema v3 DB 互換）
       if (!/no such table/i.test(err.message || '')) throw err;
     }
 
@@ -106,7 +115,7 @@ export function mergePredecessorInto(db, { newSessionId, projectPath }) {
       predecessorId,
     );
     db.prepare('UPDATE sessions SET updated_at = ? WHERE session_id = ?').run(
-      Date.now(),
+      now,
       newSessionId,
     );
 

package/src/session-merger.test.mjs

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { DatabaseSync } from 'node:sqlite';
-import { resolveMergeTarget, mergePredecessorInto } from './session-merger.mjs';
+import { resolveMergeTarget, mergeSpecificPredecessor } from './session-merger.mjs';
 
 function makeDb() {
   const db = new DatabaseSync(':memory:');
@@ -81,7 +81,7 @@ test('resolveMergeTarget: detects cycle and throws', () => {
   assert.throws(() => resolveMergeTarget(db, 'A'), /cycle detected/);
 });
 
-test('mergePredecessorInto: picks older predecessor and moves rows', () => {
+test('mergeSpecificPredecessor: moves rows from named predecessor to new session', () => {
   const db = makeDb();
   insertSession(db, 'old', 100);
   db.prepare(
@@ -90,7 +90,12 @@ test('mergePredecessorInto: picks older predecessor and moves rows', () => {
   ).run();
   insertSession(db, 'new', 200);
 
-  const result = mergePredecessorInto(db, { newSessionId: 'new', projectPath: '/proj' });
+  const result = mergeSpecificPredecessor(db, {
+    newSessionId: 'new',
+    predecessorId: 'old',
+    now: 200,
+  });
+
   assert.equal(result.merged, true);
   assert.equal(result.predecessorId, 'old');
   assert.equal(result.rowCounts.sk, 1);
@@ -102,50 +107,76 @@ test('mergePredecessorInto: picks older predecessor and moves rows', () => {
   assert.equal(oldRow.merged_into, 'new');
 });
 
-test('mergePredecessorInto: does NOT pick a session newer than self (cycle prevention)', () => {
+test('mergeSpecificPredecessor: self-handoff is refused', () => {
+  const db = makeDb();
+  insertSession(db, 'A', 100);
+
+  const result = mergeSpecificPredecessor(db, {
+    newSessionId: 'A',
+    predecessorId: 'A',
+    now: 100,
+  });
+
+  assert.equal(result.merged, false);
+  assert.equal(result.skipReason, 'self_handoff');
+});
+
+test('mergeSpecificPredecessor: predecessor not in sessions table', () => {
+  const db = makeDb();
+  insertSession(db, 'new', 200);
+
+  const result = mergeSpecificPredecessor(db, {
+    newSessionId: 'new',
+    predecessorId: 'nonexistent',
+    now: 200,
+  });
+
+  assert.equal(result.merged, false);
+  assert.equal(result.skipReason, 'predecessor_not_found');
+});
+
+test('mergeSpecificPredecessor: predecessor already merged into third session', () => {
+  const db = makeDb();
+  insertSession(db, 'old', 100, 'middle');
+  insertSession(db, 'middle', 150);
+  insertSession(db, 'new', 200);
+
+  const result = mergeSpecificPredecessor(db, {
+    newSessionId: 'new',
+    predecessorId: 'old',
+    now: 200,
+  });
+
+  assert.equal(result.merged, false);
+  assert.equal(result.skipReason, 'already_merged');
+});
+
+test('mergeSpecificPredecessor: refuses predecessor with created_at >= self', () => {
   const db = makeDb();
-  // new session created at t=100
   insertSession(db, 'new', 100);
-  // another session was created LATER at t=200 (e.g. a parallel window that started after)
   insertSession(db, 'newer', 200);
 
-  const result = mergePredecessorInto(db, { newSessionId: 'new', projectPath: '/proj' });
-  assert.equal(result.merged, false, 'should not merge a newer session into an older one');
+  const result = mergeSpecificPredecessor(db, {
+    newSessionId: 'new',
+    predecessorId: 'newer',
+    now: 100,
+  });
 
-  const newerRow = db
-    .prepare('SELECT merged_into FROM sessions WHERE session_id = ?')
-    .get('newer');
-  assert.equal(newerRow.merged_into, null);
+  assert.equal(result.merged, false);
+  assert.equal(result.skipReason, 'predecessor_not_older');
 });
 
-test('mergePredecessorInto: chronological monotonicity prevents cycles across 3 sessions', () => {
+test('mergeSpecificPredecessor: updates new session updated_at to provided now', () => {
   const db = makeDb();
-  // Sessions created in order: A (t=100), B (t=200), C (t=300)
-  insertSession(db, 'A', 100);
-  insertSession(db, 'B', 200);
-  insertSession(db, 'C', 300);
-
-  // Simulate SessionStart firing for B first, then C, then (accidentally) A again
-  mergePredecessorInto(db, { newSessionId: 'B', projectPath: '/proj' });
-  // B should have absorbed A
-  assert.equal(
-    db.prepare('SELECT merged_into FROM sessions WHERE session_id = ?').get('A').merged_into,
-    'B',
-  );
-
-  mergePredecessorInto(db, { newSessionId: 'C', projectPath: '/proj' });
-  // C should have absorbed B (A is already merged, so not a candidate)
-  assert.equal(
-    db.prepare('SELECT merged_into FROM sessions WHERE session_id = ?').get('B').merged_into,
-    'C',
-  );
-
-  // Re-firing SessionStart for A must not create a cycle (A cannot absorb newer B or C)
-  const redundant = mergePredecessorInto(db, { newSessionId: 'A', projectPath: '/proj' });
-  assert.equal(redundant.merged, false);
-
-  // Verify no cycle: resolveMergeTarget from any node terminates at C
-  assert.equal(resolveMergeTarget(db, 'A').target, 'C');
-  assert.equal(resolveMergeTarget(db, 'B').target, 'C');
-  assert.equal(resolveMergeTarget(db, 'C').target, 'C');
+  insertSession(db, 'old', 100);
+  insertSession(db, 'new', 200);
+
+  mergeSpecificPredecessor(db, {
+    newSessionId: 'new',
+    predecessorId: 'old',
+    now: 500,
+  });
+
+  const newRow = db.prepare('SELECT updated_at FROM sessions WHERE session_id = ?').get('new');
+  assert.equal(newRow.updated_at, 500);
 });

package/src/session-start.mjs

@@ -1,23 +1,40 @@
 #!/usr/bin/env node
 /**
- * SessionStart hook — セッション登録 + 前任記憶の張り替え + 引き継ぎ注入
+ * SessionStart hook — セッション登録 + バトン消費 + 引き継ぎ注入
  *
  * stdin: { session_id, source, cwd, transcript_path, hook_event_name }
  *
- * 【実機確認 (2026-04-15)】
- *   SessionStart は /clear 後も source="startup" で発火する。
- *   (Windows + VSCode 拡張では source="clear" は来ないが hook 自体は発火)
- *   source に依存せず、毎回「前任の張り替え候補」を探して合流させる。
+ * 【引き継ぎ条件 (バトン方式)】
+ *   ユーザーが旧セッションで /tl スラッシュコマンドを打つと UserPromptSubmit hook が
+ *   baton テーブルに session_id を書き込む。本 SessionStart hook はそれを TTL 1 時間以内
+ *   なら消費して merge + 引き継ぎヘッダ付き L1+L2 を stdout 注入する。
+ *   バトンが無ければ / 期限切れなら何も引き継がない（docs/INHERITANCE_ON_CLEAR_ONLY.md 参照）。
  *
  * 役割:
  *   1. sessions テーブルに新セッションを INSERT OR IGNORE
- *   2. 同プロジェクト内の最新非合流セッションを新セッションに張り替え (session-merger)
+ *   2. バトン消費 + 指名された前任を merge (session-merger.mjs)
  *   3. 合流成立なら L1+L2 を「引き継ぎヘッダ」付きで stdout 注入
+ *   4. 判定結果を ~/.throughline/logs/inheritance-decision.log に記録
  */
 
 import { getDb } from './db.mjs';
-import { mergePredecessorInto } from './session-merger.mjs';
+import { consumeBaton } from './baton.mjs';
+import { mergeSpecificPredecessor, resolveMergeTarget } from './session-merger.mjs';
 import { buildResumeContext } from './resume-context.mjs';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+function logDecision(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'inheritance-decision.log');
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    process.stderr.write(`[session-start:decision-log] ${msg}\n`);
+  }
+}
 
 async function main() {
   let raw = '';
@@ -30,7 +47,7 @@ async function main() {
   });
 
   const payload = JSON.parse(raw);
-  const { session_id, cwd } = payload;
+  const { session_id, cwd, source } = payload;
 
   if (!session_id) throw new Error('Missing session_id in SessionStart payload');
 
@@ -44,10 +61,31 @@ async function main() {
      VALUES (?, ?, 'active', ?, ?)`,
   ).run(session_id, projectPath, now, now);
 
-  // 2. 前任の張り替え
-  const mergeResult = mergePredecessorInto(db, {
-    newSessionId: session_id,
-    projectPath,
+  // 2. バトン消費
+  const baton = consumeBaton(db, { projectPath, now });
+
+  let mergeResult = { merged: false, skipReason: 'no_baton' };
+  if (baton.sessionId) {
+    // バトンが指す session が既に他と merge 済みなら、その合流先末端を前任とする
+    const { target: predecessorId } = resolveMergeTarget(db, baton.sessionId);
+    mergeResult = mergeSpecificPredecessor(db, {
+      newSessionId: session_id,
+      predecessorId,
+      now,
+    });
+  }
+
+  logDecision({
+    ts: new Date(now).toISOString(),
+    source: source ?? null,
+    session_id,
+    project_path: projectPath,
+    baton_session_id: baton.sessionId ?? null,
+    baton_age_ms: baton.ageMs ?? null,
+    baton_skip_reason: baton.skipReason ?? null,
+    merged: mergeResult.merged,
+    merge_skip_reason: mergeResult.skipReason ?? null,
+    predecessor_id: mergeResult.predecessorId ?? null,
   });
 
   // 3. 合流成立なら引き継ぎヘッダ付きで注入