throughline 0.4.12 → 0.6.0

package/src/spike-transcript-writer.test.mjs

@@ -0,0 +1,298 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spikeInject, generateSpikeTracer } from './spike-transcript-writer.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,
+      kind TEXT,
+      source_id TEXT
+    );
+  `);
+  return db;
+}
+
+function seedSession(db, { newSessionId = 'NEW', originId = 'ORIG' } = {}) {
+  db.prepare(
+    `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+     VALUES (?, '/repo', 'active', 1, 2)`,
+  ).run(newSessionId);
+  // 2 user / 2 assistant turn を新 session 配下に origin_session_id=ORIG で配置
+  // (handoff-record は inheritance mode で origin != current を recent bodies に拾う)
+  const rows = [
+    { turn: 1, role: 'user', text: 'こんにちは。tracer 検証だ', createdAt: 1000 },
+    { turn: 2, role: 'assistant', text: '了解です。テスト用ターン 1', createdAt: 1100 },
+    { turn: 3, role: 'user', text: '続きを書け', createdAt: 1200 },
+    { turn: 4, role: 'assistant', text: '最後のアシスタント発話 (tracer 受け取り側)', createdAt: 1300 },
+  ];
+  for (const r of rows) {
+    db.prepare(
+      `INSERT INTO bodies (session_id, origin_session_id, turn_number, role, text, token_count, created_at)
+       VALUES (?, ?, ?, ?, ?, 1, ?)`,
+    ).run(newSessionId, originId, r.turn, r.role, r.text, r.createdAt);
+  }
+  return rows;
+}
+
+function makeTempJsonl() {
+  const dir = mkdtempSync(join(tmpdir(), 'spike-writer-test-'));
+  return join(dir, 'session.jsonl');
+}
+
+test('generateSpikeTracer returns 8 hex chars', () => {
+  const t = generateSpikeTracer();
+  assert.match(t, /^[0-9a-f]{8}$/);
+  assert.notEqual(t, generateSpikeTracer()); // 衝突しない (実質)
+});
+
+test('spikeInject: returns skipReason when no recentBodies', () => {
+  const db = makeDb();
+  db.prepare(
+    `INSERT INTO sessions (session_id, project_path, status, created_at, updated_at)
+     VALUES ('NEW', '/repo', 'active', 1, 2)`,
+  ).run();
+  const target = makeTempJsonl();
+  const result = spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer: 'abcd1234',
+  });
+  assert.equal(result.appended, 0);
+  assert.equal(result.skipReason, 'no_record_or_empty_l2');
+  assert.equal(result.tracer, null);
+  assert.equal(result.tracerAppendedAt, null);
+});
+
+test('spikeInject: appends bodies, embeds tracer in last assistant only', () => {
+  const db = makeDb();
+  seedSession(db);
+  const target = makeTempJsonl();
+  const tracer = 'deadbeef';
+
+  const result = spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer,
+  });
+  assert.equal(result.appended, 4);
+  assert.equal(result.parentUuidStart, null); // empty file 起点
+  assert.equal(result.tracer, tracer);
+  assert.equal(result.tracerAppendedAt, 3); // index of last assistant
+
+  const lines = readFileSync(target, 'utf8').split('\n').filter((l) => l.trim());
+  assert.equal(lines.length, 4);
+
+  const parsed = lines.map((l) => JSON.parse(l));
+  // 順序 (古い順): user → assistant → user → assistant
+  assert.deepEqual(parsed.map((o) => o.type), ['user', 'assistant', 'user', 'assistant']);
+  // tracer は最後の assistant のみ
+  const lastAssistant = parsed[3];
+  assert.match(lastAssistant.message.content[0].text, /\[spike-tracer: deadbeef\]$/);
+  // 中間の assistant には tracer が無い
+  const midAssistant = parsed[1];
+  assert.doesNotMatch(midAssistant.message.content[0].text, /spike-tracer/);
+  // user 行にも無い
+  for (const u of [parsed[0], parsed[2]]) {
+    assert.doesNotMatch(u.message.content[0].text, /spike-tracer/);
+  }
+});
+
+test('spikeInject: omits tracer entirely when tracer=null', () => {
+  const db = makeDb();
+  seedSession(db);
+  const target = makeTempJsonl();
+
+  const result = spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer: null,
+  });
+  assert.equal(result.appended, 4);
+  assert.equal(result.tracer, null);
+  assert.equal(result.tracerAppendedAt, null);
+
+  const content = readFileSync(target, 'utf8');
+  assert.doesNotMatch(content, /spike-tracer/);
+});
+
+test('spikeInject: chains from last uuid when target has preexisting lines', () => {
+  const db = makeDb();
+  seedSession(db);
+  const target = makeTempJsonl();
+  const preexisting = { type: 'attachment', uuid: 'pre-attachment-uuid', parentUuid: null };
+  writeFileSync(target, JSON.stringify(preexisting) + '\n', 'utf8');
+
+  const result = spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer: 'cafef00d',
+  });
+  assert.equal(result.parentUuidStart, 'pre-attachment-uuid');
+
+  const lines = readFileSync(target, 'utf8').split('\n').filter((l) => l.trim());
+  // 1 件目 (preexisting) は preserve、2 件目が最初の spike user
+  const firstSpike = JSON.parse(lines[1]);
+  assert.equal(firstSpike.parentUuid, 'pre-attachment-uuid');
+  // chain は spike 内で繋がる
+  const secondSpike = JSON.parse(lines[2]);
+  assert.equal(secondSpike.parentUuid, firstSpike.uuid);
+});
+
+test('spikeInject: defaults assistant model to a real Claude model name', () => {
+  const db = makeDb();
+  seedSession(db);
+  const target = makeTempJsonl();
+  spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer: 'aabbccdd',
+  });
+  const lines = readFileSync(target, 'utf8').split('\n').filter((l) => l.trim());
+  const firstAssistant = JSON.parse(lines[1]); // index 1 = first assistant in [user, assistant, user, assistant]
+  assert.equal(firstAssistant.message.model, 'claude-opus-4-7', 'Phase 0-5 retry: real model name not fake');
+});
+
+test('spikeInject: assistantModel override is honored', () => {
+  const db = makeDb();
+  seedSession(db);
+  const target = makeTempJsonl();
+  spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW',
+    cwd: '/repo',
+    version: '2.1.x',
+    gitBranch: 'main',
+    tracer: '11223344',
+    assistantModel: 'claude-overridden-model',
+  });
+  const lines = readFileSync(target, 'utf8').split('\n').filter((l) => l.trim());
+  const firstAssistant = JSON.parse(lines[1]);
+  assert.equal(firstAssistant.message.model, 'claude-overridden-model');
+});
+
+test('spikeInject: writes Claude Code-compatible shape (top-level fields)', () => {
+  const db = makeDb();
+  seedSession(db, { newSessionId: 'NEW-SESSION' });
+  const target = makeTempJsonl();
+
+  spikeInject({
+    db,
+    targetJsonlPath: target,
+    newSessionId: 'NEW-SESSION',
+    cwd: '/repo',
+    version: '2.1.145',
+    gitBranch: 'main',
+    tracer: '00000000',
+  });
+
+  const lines = readFileSync(target, 'utf8').split('\n').filter((l) => l.trim());
+  const u = JSON.parse(lines[0]);
+  // user turn の必須 14 フィールド (Plan §6 リバース結果より)
+  for (const k of [
+    'parentUuid',
+    'isSidechain',
+    'promptId',
+    'type',
+    'message',
+    'uuid',
+    'timestamp',
+    'permissionMode',
+    'userType',
+    'entrypoint',
+    'cwd',
+    'sessionId',
+    'version',
+    'gitBranch',
+  ]) {
+    assert.ok(k in u, `user line missing field: ${k}`);
+  }
+  assert.equal(u.type, 'user');
+  assert.equal(u.sessionId, 'NEW-SESSION');
+  assert.equal(u.version, '2.1.145');
+  assert.equal(u.message.role, 'user');
+
+  const a = JSON.parse(lines[1]);
+  // assistant turn の必須 13 フィールド
+  for (const k of [
+    'parentUuid',
+    'isSidechain',
+    'message',
+    'requestId',
+    'type',
+    'uuid',
+    'timestamp',
+    'userType',
+    'entrypoint',
+    'cwd',
+    'sessionId',
+    'version',
+    'gitBranch',
+  ]) {
+    assert.ok(k in a, `assistant line missing field: ${k}`);
+  }
+  assert.equal(a.type, 'assistant');
+  assert.equal(a.message.role, 'assistant');
+  assert.ok(a.message.usage);
+});

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,
+  };
+}