throughline 0.4.12 → 0.6.0

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,13 +28,37 @@
 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, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 
+// SPIKE ONLY — Phase 0-2 / 0-4 検証用。marker file 削除で無効化される。
+// 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。
+// flag 存在時、SessionStart hook は plain stdout の代わりに JSON 出力に切り替わり、
+// hookSpecificOutput.initialUserMessage に tracer 入りメッセージを乗せる。
+// openclaude の OSS 実装では「headless 専用」と記載されているが、real CC の挙動は未確認。
+const INITIAL_USER_MESSAGE_TEST_FLAG = join(homedir(), '.throughline', 'initial-user-message-test.flag');
+
+function logInitialUserMessageTest(entry) {
+  const path = join(homedir(), '.throughline', 'logs', 'initial-user-message-test.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:initialUserMessage-test-log] ${msg}\n`);
+  }
+}
+
 const ENV_DISABLE_AUTO_HANDOFF = 'THROUGHLINE_DISABLE_AUTO_HANDOFF';
 
 function isAutoHandoffDisabled(env) {
@@ -88,7 +112,7 @@ export async function run() {
   });
 
   const payload = JSON.parse(raw);
-  const { session_id, cwd, source } = payload;
+  const { session_id, cwd, source, transcript_path } = payload;
 
   if (!session_id) throw new Error('Missing session_id in SessionStart payload');
 
@@ -146,11 +170,137 @@ export async function run() {
     mergeResult = { merged: false, skipReason: 'auto_handoff_disabled' };
   }
 
+  // 4. 合流成立なら curated memory を stdout 注入 (L1 + L2 + L3 refs)
+  //    順序厳守: stdout flush を先に完了させてから spike 分岐へ進む。
+  //    spike が throw しても stdout は既に attachment に保存されている。
+  //
+  //    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,
+    });
+    if (existsSync(INITIAL_USER_MESSAGE_TEST_FLAG)) {
+      // TEST MODE: emit JSON with initialUserMessage tracer. Plain stdout は出さない
+      // (= 通常 Throughline 案内文無し)。テスト 1 回限定。flag を削除すれば即復帰。
+      const tracer = randomBytes(4).toString('hex');
+      const initialMessage =
+        `[initial-user-tracer: ${tracer}]\n\n` +
+        `This text is being delivered via the SessionStart hook's ` +
+        `hookSpecificOutput.initialUserMessage field. If you can quote the 8-hex ` +
+        `tracer above when asked, it means initialUserMessage IS consumed in ` +
+        `interactive mode (not headless-only as openclaude documents).`;
+      const jsonOutput = JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'SessionStart',
+          initialUserMessage: initialMessage,
+        },
+      });
+      process.stdout.write(jsonOutput + '\n');
+      logInitialUserMessageTest({
+        ts: new Date(now).toISOString(),
+        session_id,
+        tracer,
+        mode: 'json-initial-user-message-only',
+        had_resume_context: Boolean(text),
+      });
+    } else if (text) {
+      process.stdout.write(text + '\n');
+    }
+  }
+
+  // 5. SPIKE: marker file あり + merge 成立 + transcript_path あり の 3 条件で
+  //    L2 を user/assistant role 付きで transcript_path にも append する。
+  //    本実装ではない (docs/10_transcript_injection_plan.md Phase 0-2)。
+  //
+  //    tracer: 末尾 assistant 行に stdout 注入には含まれない一意トークンを付与する。
+  //    次の /clear 後に Claude が tracer を再現できれば JSONL 経路はモデル可視。
+  let spikeResult = null;
+  const spikeMarkerExists = existsSync(SPIKE_MARKER_PATH);
+  if (spikeMarkerExists && mergeResult.merged && transcript_path) {
+    try {
+      const { spikeInject, generateSpikeTracer } = await import('./spike-transcript-writer.mjs');
+      const tracer = generateSpikeTracer();
+      spikeResult = spikeInject({
+        db,
+        targetJsonlPath: transcript_path,
+        newSessionId: session_id,
+        cwd: projectPath,
+        version: payload.version ?? '2.1.145',
+        gitBranch: payload.gitBranch ?? 'main',
+        tracer,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'unknown';
+      process.stderr.write(`[spike-inject] ${msg}\n`);
+      spikeResult = { error: msg };
+    }
+  }
+
   logDecision({
     ts: new Date(now).toISOString(),
     source: source ?? null,
     session_id,
     project_path: projectPath,
+    transcript_path: transcript_path ?? null,
     triggered_path: triggeredPath,
     auto_handoff_disabled: autoDisabled,
     baton_session_id: baton.sessionId ?? null,
@@ -159,19 +309,10 @@ export async function run() {
     merged: mergeResult.merged,
     merge_skip_reason: mergeResult.skipReason ?? null,
     predecessor_id: mergeResult.predecessorId ?? null,
+    spike_marker_exists: spikeMarkerExists,
+    spike_result: spikeResult,
   });
 
-  // 4. 合流成立なら curated memory を stdout 注入 (L1 + L2 + L3 refs)
-  if (mergeResult.merged) {
-    const text = buildResumeContext(db, {
-      sessionId: session_id,
-      isInheritance: true,
-    });
-    if (text) {
-      process.stdout.write(text + '\n');
-    }
-  }
-
   process.exit(0);
 }
 

package/src/spike-transcript-writer.mjs

@@ -0,0 +1,196 @@
+/**
+ * SPIKE ONLY — Phase 0-2 / 0-4 検証用。本実装ではない。
+ *
+ * docs/10_transcript_injection_plan.md Phase 0-2 で
+ * 「`/clear` 直後の SessionStart hook 内で transcript_path に L2 を user/assistant
+ *  role 付きで append すると、Claude が次の short prompt の文脈として読むか」を実機検証する。
+ *
+ * 本実装ではない理由:
+ *   - text content のみ復元 (tool_use / tool_result / thinking は割愛)
+ *   - idempotency 簡易チェックのみ
+ *   - 本実装 (Phase 1-1) では src/transcript-writer.mjs を別途作る
+ *
+ * tracer 経路: 注入した JSONL 行が**モデルの message 履歴に乗ったか**を切り分けるため、
+ * 最終 assistant 行末尾に **stdout 注入には含まれない一意トークン** を付与する。
+ * 次の /clear 後にユーザーがその合言葉の再現を求め、Claude が答えられれば JSONL 経路は
+ * モデル可視。答えられなければ JSONL は保持されてもメッセージ履歴に乗らない (孤立 chain
+ * 等が原因)。
+ *
+ * marker file `~/.throughline/spike-inject.flag` 削除で spike は無効化される。
+ */
+
+import { readFileSync, existsSync, fsyncSync, openSync, closeSync, writeSync } from 'node:fs';
+import { randomUUID, randomBytes } from 'node:crypto';
+import { buildHandoffRecord } from './handoff-record.mjs';
+
+/**
+ * targetJsonl の末尾行の uuid を返す。chain 設計案 (b) の親決定用。
+ * file が無い / 空 / uuid 持ち行が無い場合は null を返す。
+ */
+function readLastUuid(path) {
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, 'utf8');
+  const lines = text.split('\n').filter((l) => l.trim());
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    try {
+      const o = JSON.parse(lines[i]);
+      if (typeof o.uuid === 'string') return o.uuid;
+    } catch {
+      // skip non-json line
+    }
+  }
+  return null;
+}
+
+function buildUserLine({ b, parentUuid, newSessionId, cwd, version, gitBranch }) {
+  const uuid = randomUUID();
+  const ts = new Date(b.createdAt ?? Date.now()).toISOString();
+  const obj = {
+    parentUuid,
+    isSidechain: false,
+    promptId: randomUUID(),
+    type: 'user',
+    message: {
+      role: 'user',
+      content: [{ type: 'text', text: b.text ?? '' }],
+    },
+    uuid,
+    timestamp: ts,
+    permissionMode: 'auto',
+    userType: 'external',
+    entrypoint: 'claude-vscode',
+    cwd,
+    sessionId: newSessionId,
+    version,
+    gitBranch,
+  };
+  return { uuid, line: JSON.stringify(obj) };
+}
+
+function buildAssistantLine({ b, parentUuid, newSessionId, cwd, version, gitBranch, tracer, assistantModel }) {
+  const uuid = randomUUID();
+  const ts = new Date(b.createdAt ?? Date.now()).toISOString();
+  const baseText = b.text ?? '';
+  const text = tracer ? `${baseText}\n\n[spike-tracer: ${tracer}]` : baseText;
+  const obj = {
+    parentUuid,
+    isSidechain: false,
+    message: {
+      model: assistantModel,
+      id: `msg_spike_${uuid.slice(0, 8)}`,
+      type: 'message',
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      stop_reason: 'end_turn',
+      stop_sequence: null,
+      usage: { input_tokens: 0, output_tokens: 0 },
+    },
+    requestId: `req_spike_${uuid.slice(0, 8)}`,
+    type: 'assistant',
+    uuid,
+    timestamp: ts,
+    userType: 'external',
+    entrypoint: 'claude-vscode',
+    cwd,
+    sessionId: newSessionId,
+    version,
+    gitBranch,
+  };
+  return { uuid, line: JSON.stringify(obj) };
+}
+
+/**
+ * 末尾 assistant 行に埋める tracer を生成する。8 hex (32 bit)。
+ * stdout 注入には含まれない値である必要があるため、DB body text とは無相関に乱数生成する。
+ */
+export function generateSpikeTracer() {
+  return randomBytes(4).toString('hex');
+}
+
+/**
+ * spike append. fsync 付きで JSONL に user/assistant 行を append する。
+ *
+ * @param {object} opts
+ * @param {string|null} [opts.tracer] 末尾 assistant 行に付与する一意トークン。
+ *   未指定なら付与しない (back-compat: 既存呼び出し用)。
+ * @returns {{
+ *   appended: number,
+ *   parentUuidStart: string|null,
+ *   tracer: string|null,
+ *   tracerAppendedAt: number|null,
+ *   skipReason?: string
+ * }}
+ */
+// Phase 0-5 retry: 偽モデル名 ('claude-throughline-spike') では Claude Code が messages[]
+// 構築時にフィルタしている可能性があるため、デフォルトは実在 Claude モデル名にする。
+const DEFAULT_SPIKE_ASSISTANT_MODEL = 'claude-opus-4-7';
+
+export function spikeInject({
+  db,
+  targetJsonlPath,
+  newSessionId,
+  cwd,
+  version,
+  gitBranch,
+  tracer = null,
+  assistantModel = DEFAULT_SPIKE_ASSISTANT_MODEL,
+}) {
+  const record = buildHandoffRecord(db, { sessionId: newSessionId, isInheritance: true });
+  if (!record || !record.memory?.recentBodies?.length) {
+    return {
+      appended: 0,
+      parentUuidStart: null,
+      tracer: null,
+      tracerAppendedAt: null,
+      skipReason: 'no_record_or_empty_l2',
+    };
+  }
+  const bodies = record.memory.recentBodies; // 古い順
+
+  // 末尾 assistant 行を 1 件特定 (assistant が必ず末尾とは限らないため後ろから探す)。
+  let lastAssistantIdx = -1;
+  for (let i = bodies.length - 1; i >= 0; i -= 1) {
+    if (bodies[i].role === 'assistant') {
+      lastAssistantIdx = i;
+      break;
+    }
+  }
+
+  let parentUuid = readLastUuid(targetJsonlPath);
+  const parentUuidStart = parentUuid;
+  const lines = [];
+  let tracerAppendedAt = null;
+  for (let i = 0; i < bodies.length; i += 1) {
+    const b = bodies[i];
+    const isLastAssistant = Boolean(tracer) && i === lastAssistantIdx;
+    const built = b.role === 'user'
+      ? buildUserLine({ b, parentUuid, newSessionId, cwd, version, gitBranch })
+      : buildAssistantLine({
+          b,
+          parentUuid,
+          newSessionId,
+          cwd,
+          version,
+          gitBranch,
+          tracer: isLastAssistant ? tracer : null,
+          assistantModel,
+        });
+    if (isLastAssistant) tracerAppendedAt = i;
+    lines.push(built.line);
+    parentUuid = built.uuid;
+  }
+  // sync write + fsync で hook 終了前に確実に flush
+  const fd = openSync(targetJsonlPath, 'a');
+  try {
+    writeSync(fd, lines.join('\n') + '\n');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  return {
+    appended: lines.length,
+    parentUuidStart,
+    tracer: tracer ?? null,
+    tracerAppendedAt,
+  };
+}