throughline 0.1.0

package/src/sc-detail.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * sc-detail — /sc-detail スラッシュコマンドの実行本体
+ *
+ * 使い方:
+ *   node src/sc-detail.mjs <時刻>
+ *   node src/sc-detail.mjs <開始時刻>-<終了時刻>
+ *
+ * 時刻フォーマット: HH:MM:SS または HH:MM（秒省略可）
+ * 複数ターンが同一時刻にヒットする場合は全部返す。
+ *
+ * 出力: 指定時刻のターン（または範囲内の全ターン）の L2 (bodies) + L3 (details)
+ *       を人間可読なテキストで stdout に出力する。
+ *
+ * 注意:
+ *   - 現在の作業ディレクトリ（cwd）のプロジェクトに属するターンのみを対象にする
+ *   - session_id は merge chain 解決後の合流先（target）を使う
+ *   - 複数セッションの ID を跨いで時刻で検索するので、project_path でフィルタ必須
+ */
+
+import { getDb } from './db.mjs';
+import { DETAIL_KIND, DETAIL_KIND_VALUES } from './constants.mjs';
+
+function parseTimeArg(arg) {
+  const m = String(arg || '').trim().match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
+  if (!m) return null;
+  const [, hh, mm, ss] = m;
+  return {
+    hours: Number(hh),
+    minutes: Number(mm),
+    seconds: ss != null ? Number(ss) : null, // null = 秒指定なし（その分内すべて）
+  };
+}
+
+/**
+ * 指定時刻（HH:MM:SS）の当日タイムスタンプ（ms）を返す。
+ * 秒が null の場合は start=00, end=59 の範囲を返す（呼び出し側で使い分け）。
+ */
+function timeToUnixRange(t, baseDate = new Date()) {
+  const y = baseDate.getFullYear();
+  const mo = baseDate.getMonth();
+  const d = baseDate.getDate();
+  const secStart = t.seconds != null ? t.seconds : 0;
+  const secEnd = t.seconds != null ? t.seconds : 59;
+  const start = new Date(y, mo, d, t.hours, t.minutes, secStart, 0).getTime();
+  const end = new Date(y, mo, d, t.hours, t.minutes, secEnd, 999).getTime();
+  return { start, end };
+}
+
+function parseRangeArg(arg) {
+  const s = String(arg || '').trim();
+  if (!s.includes('-')) {
+    const t = parseTimeArg(s);
+    if (!t) return null;
+    const r = timeToUnixRange(t);
+    return { start: r.start, end: r.end };
+  }
+  const [lo, hi] = s.split('-').map((x) => x.trim());
+  const tLo = parseTimeArg(lo);
+  const tHi = parseTimeArg(hi);
+  if (!tLo || !tHi) return null;
+  const rLo = timeToUnixRange(tLo);
+  const rHi = timeToUnixRange(tHi);
+  return { start: rLo.start, end: rHi.end };
+}
+
+function formatTime(unixMs) {
+  const d = new Date(unixMs);
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mm = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  return `${hh}:${mm}:${ss}`;
+}
+
+/**
+ * コアロジック。bin/throughline.mjs などから直接呼び出せるよう、
+ * process.argv ではなく引数配列を受け取る。
+ * @param {string[]} args
+ */
+export function run(args) {
+  const arg = args[0];
+  if (!arg) {
+    process.stderr.write(
+      '使い方: throughline detail <HH:MM:SS>\n' +
+        '       throughline detail <HH:MM:SS>-<HH:MM:SS>\n',
+    );
+    process.exit(1);
+  }
+
+  const range = parseRangeArg(arg);
+  if (!range) {
+    process.stderr.write(`[sc-detail] 時刻フォーマットが無効: ${arg}\n`);
+    process.exit(1);
+  }
+
+  const db = getDb();
+  const projectPath = process.cwd();
+
+  // 指定時刻範囲内のターンを bodies から取得（project_path でフィルタ）
+  // bodies と sessions を JOIN して同プロジェクトに絞る
+  const bodyRows = db
+    .prepare(
+      `SELECT b.session_id, b.origin_session_id, b.turn_number, b.role, b.text, b.created_at
+       FROM bodies b
+       JOIN sessions s ON s.session_id = b.session_id
+       WHERE lower(s.project_path) = lower(?)
+         AND b.created_at BETWEEN ? AND ?
+       ORDER BY b.created_at ASC, b.role ASC`,
+    )
+    .all(projectPath, range.start, range.end);
+
+  if (bodyRows.length === 0) {
+    process.stdout.write(
+      `## Throughline /sc-detail\n\n指定時刻 ${arg} に該当するターンが見つかりませんでした。\n`,
+    );
+    process.exit(0);
+  }
+
+  // ターン単位でグルーピング（同じ session_id + origin + turn_number）
+  const turnKeys = new Set();
+  for (const r of bodyRows) {
+    turnKeys.add(`${r.session_id}\x00${r.origin_session_id}\x00${r.turn_number}`);
+  }
+
+  const lines = [];
+  lines.push('## Throughline /sc-detail');
+  lines.push(`指定時刻: ${arg}  対象ターン数: ${turnKeys.size}`);
+  lines.push('');
+
+  // L2 を時刻順に出力
+  lines.push('### L2 (会話本文)');
+  for (const r of bodyRows) {
+    lines.push(`[${formatTime(r.created_at)}] [${r.role}]: ${r.text}`);
+    lines.push('');
+  }
+
+  // 対応する L3 を details から 1 クエリで取得（N+1 回避のため row-value IN）
+  const turnTuples = [...turnKeys].map((k) => k.split('\x00'));
+  const placeholders = turnTuples.map(() => '(?, ?, ?)').join(', ');
+  const params = turnTuples.flatMap(([sid, origin, turn]) => [sid, origin, Number(turn)]);
+  const detailRows = db
+    .prepare(
+      `SELECT id, turn_number, kind, tool_name, input_text, output_text, created_at
+       FROM details
+       WHERE (session_id, origin_session_id, turn_number) IN (VALUES ${placeholders})
+       ORDER BY id ASC`,
+    )
+    .all(...params);
+
+  if (detailRows.length > 0) {
+    // 単一 pass で kind ごとに振り分け
+    const toolRows = [];
+    const systemRows = [];
+    const imageRows = [];
+    const legacyRows = [];
+    for (const d of detailRows) {
+      if (d.kind === DETAIL_KIND.TOOL_INPUT || d.kind === DETAIL_KIND.TOOL_OUTPUT) toolRows.push(d);
+      else if (d.kind === DETAIL_KIND.SYSTEM) systemRows.push(d);
+      else if (d.kind === DETAIL_KIND.IMAGE) imageRows.push(d);
+      else if (!DETAIL_KIND_VALUES.has(d.kind)) legacyRows.push(d);
+    }
+
+    if (toolRows.length > 0) {
+      lines.push('### L3 (ツール入出力)');
+      for (const d of toolRows) {
+        const marker = d.kind === DETAIL_KIND.TOOL_INPUT ? 'IN ' : 'OUT';
+        lines.push(`[${formatTime(d.created_at)}] ${marker} ${d.tool_name}`);
+        if (d.input_text) {
+          lines.push(`  IN:  ${d.input_text.replace(/\n/g, '\n       ')}`);
+        }
+        if (d.output_text) {
+          lines.push(`  OUT: ${d.output_text.replace(/\n/g, '\n       ')}`);
+        }
+        lines.push('');
+      }
+    }
+
+    if (systemRows.length > 0) {
+      lines.push('### L3 (システムメッセージ / hook 出力)');
+      for (const d of systemRows) {
+        lines.push(`[${formatTime(d.created_at)}] ${d.tool_name}`);
+        if (d.input_text) lines.push(`  CMD: ${d.input_text}`);
+        if (d.output_text) lines.push(`  OUT: ${d.output_text.replace(/\n/g, '\n       ')}`);
+        lines.push('');
+      }
+    }
+
+    if (imageRows.length > 0) {
+      lines.push('### L3 (画像)');
+      for (const d of imageRows) {
+        lines.push(`[${formatTime(d.created_at)}] ${d.output_text ?? '[image]'}`);
+      }
+      lines.push('');
+    }
+
+    if (legacyRows.length > 0) {
+      lines.push('### L3 (legacy)');
+      for (const d of legacyRows) {
+        lines.push(`[${formatTime(d.created_at)}] ${d.tool_name}`);
+        if (d.input_text) lines.push(`  IN:  ${d.input_text.replace(/\n/g, '\n       ')}`);
+        if (d.output_text) lines.push(`  OUT: ${d.output_text.replace(/\n/g, '\n       ')}`);
+        lines.push('');
+      }
+    }
+  } else {
+    lines.push('### L3');
+    lines.push('（該当ターンに L3 レコード無し）');
+  }
+
+  process.stdout.write(lines.join('\n') + '\n');
+  process.exit(0);
+}

package/src/session-merger.mjs

@@ -0,0 +1,127 @@
+/**
+ * session-merger.mjs — 記憶張り替え + merged_into チェーン解決
+ *
+ * 用途:
+ *   - SessionStart hook: mergePredecessorInto で前任セッションの L1/L2/L3 を新セッションに張り替える
+ *   - Stop / PostToolUse hook: resolveMergeTarget で「入力 session_id → 実書き込み先」を解決
+ *
+ * 設計背景: docs/SESSION_LINKING_DESIGN.md
+ */
+
+const MAX_CHAIN_DEPTH = 10;
+
+/**
+ * merged_into チェーンを辿って最終的な書き込み先 session_id を解決する。
+ *
+ * @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;
+  const seen = new Set();
+  let current = sessionId;
+
+  for (let depth = 0; depth < MAX_CHAIN_DEPTH; depth++) {
+    if (seen.has(current)) {
+      throw new Error(`[session-merger] merge chain cycle detected at ${current}`);
+    }
+    seen.add(current);
+
+    const row = db
+      .prepare('SELECT merged_into FROM sessions WHERE session_id = ?')
+      .get(current);
+
+    if (!row || row.merged_into === null || row.merged_into === undefined) {
+      return { target: current, origin };
+    }
+    current = row.merged_into;
+  }
+
+  throw new Error(
+    `[session-merger] merge chain depth exceeded ${MAX_CHAIN_DEPTH} from ${sessionId}`,
+  );
+}
+
+/**
+ * 同一プロジェクト内の最新非合流セッションを新セッションに張り替える。
+ *
+ * 実行順序（BEGIN IMMEDIATE トランザクション内）:
+ *   1. 前任候補 SELECT（同 project_path, session_id != new, merged_into IS NULL, 最新 updated_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 } }}
+ */
+export function mergePredecessorInto(db, { newSessionId, projectPath }) {
+  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);
+
+    if (!pred) {
+      db.exec('COMMIT');
+      return { merged: false };
+    }
+
+    const predecessorId = pred.session_id;
+
+    const sk = db
+      .prepare('UPDATE skeletons SET session_id = ? WHERE session_id = ?')
+      .run(newSessionId, predecessorId);
+    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;
+    }
+
+    db.prepare('UPDATE sessions SET merged_into = ? WHERE session_id = ?').run(
+      newSessionId,
+      predecessorId,
+    );
+    db.prepare('UPDATE sessions SET updated_at = ? WHERE session_id = ?').run(
+      Date.now(),
+      newSessionId,
+    );
+
+    db.exec('COMMIT');
+    return {
+      merged: true,
+      predecessorId,
+      rowCounts: { sk: sk.changes, dt: dt.changes, bd: bd.changes },
+    };
+  } catch (err) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}

package/src/session-merger.test.mjs

@@ -0,0 +1,151 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { resolveMergeTarget, mergePredecessorInto } from './session-merger.mjs';
+
+function makeDb() {
+  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
+    );
+  `);
+  return db;
+}
+
+function insertSession(db, id, createdAt, mergedInto = null, projectPath = '/proj') {
+  db.prepare(
+    `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at, merged_into)
+     VALUES (?, ?, 'active', ?, ?, ?)`,
+  ).run(id, projectPath, createdAt, createdAt, mergedInto);
+}
+
+test('resolveMergeTarget: unmerged session returns itself', () => {
+  const db = makeDb();
+  insertSession(db, 'A', 1);
+  const { target, origin } = resolveMergeTarget(db, 'A');
+  assert.equal(target, 'A');
+  assert.equal(origin, 'A');
+});
+
+test('resolveMergeTarget: follows chain to end', () => {
+  const db = makeDb();
+  insertSession(db, 'A', 1, 'B');
+  insertSession(db, 'B', 2, 'C');
+  insertSession(db, 'C', 3, null);
+  const { target, origin } = resolveMergeTarget(db, 'A');
+  assert.equal(target, 'C');
+  assert.equal(origin, 'A');
+});
+
+test('resolveMergeTarget: detects cycle and throws', () => {
+  const db = makeDb();
+  insertSession(db, 'A', 1, 'B');
+  insertSession(db, 'B', 2, 'C');
+  insertSession(db, 'C', 3, 'A');
+  assert.throws(() => resolveMergeTarget(db, 'A'), /cycle detected/);
+});
+
+test('mergePredecessorInto: picks older predecessor and moves rows', () => {
+  const db = makeDb();
+  insertSession(db, 'old', 100);
+  db.prepare(
+    `INSERT INTO skeletons (session_id, origin_session_id, turn_number, role, summary, created_at)
+     VALUES ('old', 'old', 1, 'user', 's', 100)`,
+  ).run();
+  insertSession(db, 'new', 200);
+
+  const result = mergePredecessorInto(db, { newSessionId: 'new', projectPath: '/proj' });
+  assert.equal(result.merged, true);
+  assert.equal(result.predecessorId, 'old');
+  assert.equal(result.rowCounts.sk, 1);
+
+  const skRow = db.prepare('SELECT session_id FROM skeletons').get();
+  assert.equal(skRow.session_id, 'new');
+
+  const oldRow = db.prepare('SELECT merged_into FROM sessions WHERE session_id = ?').get('old');
+  assert.equal(oldRow.merged_into, 'new');
+});
+
+test('mergePredecessorInto: does NOT pick a session newer than self (cycle prevention)', () => {
+  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 newerRow = db
+    .prepare('SELECT merged_into FROM sessions WHERE session_id = ?')
+    .get('newer');
+  assert.equal(newerRow.merged_into, null);
+});
+
+test('mergePredecessorInto: chronological monotonicity prevents cycles across 3 sessions', () => {
+  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');
+});

package/src/session-start.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * 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 に依存せず、毎回「前任の張り替え候補」を探して合流させる。
+ *
+ * 役割:
+ *   1. sessions テーブルに新セッションを INSERT OR IGNORE
+ *   2. 同プロジェクト内の最新非合流セッションを新セッションに張り替え (session-merger)
+ *   3. 合流成立なら L1+L2 を「引き継ぎヘッダ」付きで stdout 注入
+ */
+
+import { getDb } from './db.mjs';
+import { mergePredecessorInto } from './session-merger.mjs';
+import { buildResumeContext } from './resume-context.mjs';
+
+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 } = payload;
+
+  if (!session_id) throw new Error('Missing session_id in SessionStart payload');
+
+  const projectPath = cwd ?? process.cwd();
+  const db = getDb();
+  const now = Date.now();
+
+  // 1. sessions テーブルに INSERT OR IGNORE
+  db.prepare(
+    `INSERT OR IGNORE INTO sessions (session_id, project_path, status, created_at, updated_at)
+     VALUES (?, ?, 'active', ?, ?)`,
+  ).run(session_id, projectPath, now, now);
+
+  // 2. 前任の張り替え
+  const mergeResult = mergePredecessorInto(db, {
+    newSessionId: session_id,
+    projectPath,
+  });
+
+  // 3. 合流成立なら引き継ぎヘッダ付きで注入
+  if (mergeResult.merged) {
+    const text = buildResumeContext(db, { sessionId: session_id, isInheritance: true });
+    if (text) {
+      process.stdout.write(text + '\n');
+    }
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[session-start] error: ${err.message}\n`);
+  process.exit(1);
+});

package/src/state-file.mjs

@@ -0,0 +1,117 @@
+/**
+ * state-file.mjs — セッション単位の状態ファイル管理（共有モジュール）
+ *
+ * パス: ~/.throughline/state/<session_id>.json
+ * 書き手: turn-processor (Stop)
+ * 読み手: token-monitor
+ *
+ * 設計判断 (docs/PUBLIC_RELEASE_PLAN.md §4.5/4.6):
+ *   - ファイル単位分割で last-writer-wins 問題を解消
+ *   - PID 生存チェックで stale 削除（時間窓は使わない）
+ *   - projectPath は path.resolve → / → 末尾 / 除去 → Windows lowercase で正規化
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const STATE_DIR = join(homedir(), '.throughline', 'state');
+
+/** 状態ファイル保管ディレクトリを返す */
+export function getStateDir() {
+  return STATE_DIR;
+}
+
+/**
+ * projectPath を正規化する（書き手/読み手で同じ関数を通すのが契約）
+ * @param {string} p
+ * @returns {string}
+ */
+export function normalizeProjectPath(p) {
+  if (!p) return '';
+  let result = resolve(p).replace(/\\/g, '/');
+  if (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1);
+  if (platform() === 'win32') result = result.toLowerCase();
+  return result;
+}
+
+/**
+ * セッション状態ファイルを書く
+ * @param {{sessionId: string, projectPath: string, transcriptPath: string, pid: number}} data
+ */
+export function writeSessionState({ sessionId, projectPath, transcriptPath, pid }) {
+  if (!sessionId) throw new Error('writeSessionState: sessionId is required');
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
+  const file = join(STATE_DIR, `${sessionId}.json`);
+  const payload = {
+    sessionId,
+    projectPath: normalizeProjectPath(projectPath),
+    transcriptPath: transcriptPath ?? null,
+    pid: pid ?? process.pid,
+    updatedAt: Date.now(),
+  };
+  writeFileSync(file, JSON.stringify(payload));
+}
+
+// 活動タイムアウト（表示フィルタ / 削除）
+// 背景: Windows + VSCode の hook process tree は `Claude Code → 短命 shell → node`
+//       で process.ppid は即死する shell を指すため、PID 生存チェック案は機能しない。
+//       代替として state ファイルの updatedAt を活動信号にする。
+export const STALE_HIDE_MS = 15 * 60 * 1000;       // 15 分: 表示から隠す（次の発話で復活）
+export const STALE_DELETE_MS = 24 * 60 * 60 * 1000; // 24 時間: ファイル自体を削除
+
+/**
+ * 全セッション状態を読む。24 時間超のファイルは削除、壊れたファイルも削除する。
+ * 15 分超のファイルは「stale」フラグを付けて返す（monitor 側で隠す判断をする）。
+ * @returns {Array<{sessionId: string, projectPath: string, transcriptPath: string|null, updatedAt: number, stale: boolean}>}
+ */
+export function readAllSessionStates() {
+  if (!existsSync(STATE_DIR)) return [];
+  const now = Date.now();
+  const entries = readdirSync(STATE_DIR);
+  const results = [];
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    const file = join(STATE_DIR, name);
+    const raw = readFileSync(file, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      // JSON 破損は状態ファイル固有の冪等な状況（次ターンで再生成される）
+      process.stderr.write(`[state-file] corrupt state file ${name}, deleting: ${err.message}\n`);
+      unlinkSync(file);
+      continue;
+    }
+    const age = now - (parsed.updatedAt ?? 0);
+    if (age > STALE_DELETE_MS) {
+      // 24h 超: ハード削除（無制限蓄積防止）
+      unlinkSync(file);
+      continue;
+    }
+    parsed.stale = age > STALE_HIDE_MS;
+    results.push(parsed);
+  }
+  return results;
+}
+
+/**
+ * ファイル単位の mtime スナップショットを取る（差分検知用）
+ * @returns {Map<string, number>}
+ */
+export function snapshotStateMtimes() {
+  const result = new Map();
+  if (!existsSync(STATE_DIR)) return result;
+  for (const name of readdirSync(STATE_DIR)) {
+    if (!name.endsWith('.json')) continue;
+    // readdir と stat の間でファイルが削除される race がある。
+    // ENOENT のみ許容してそれ以外は throw（§0）
+    const file = join(STATE_DIR, name);
+    try {
+      result.set(name, statSync(file).mtimeMs);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+  }
+  return result;
+}

package/src/token-estimator.mjs

@@ -0,0 +1,16 @@
+/**
+ * テキストのトークン数を推定する。
+ *
+ * GPT-4 の平均的な比率（4文字 ≒ 1トークン）を用いたヒューリスティック実装。
+ * tiktoken への差し替えは Phase 3 で行う予定。
+ *
+ * @param {string | null | undefined} text
+ * @returns {number} 推定トークン数（整数）
+ */
+export function estimateTokens(text) {
+  if (text == null) {
+    return 0;
+  }
+
+  return Math.ceil(text.length / 4);
+}