throughline 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -10,6 +10,22 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.16.1] — 2026-10-07
+
+### 修正
+
+- Claudeのターンの途中で会話記録（transcript）のフォルダが消され、Claude Codeが残りの行だけでファイルを作り直した時、Stopのhookが`Claude Stop transcript completion was not visible before deadline`で失敗し、`HOOK_PROCESS_TURN_FAILED`を数えていたのを直す（[ADR 0038](docs/adr/0038-stop-flush-barrier-head-lost-transcript.md)）。期限まで待って、transcriptに応答だけがあり利用者の発言が1つも無い時は、失敗に数えず、`backfill.log`に`skipped: "transcript_head_lost"`を残して終わる。ファイルが残らなかった時（`transcript_absent`、[ADR 0029](docs/adr/0029-stop-flush-barrier-absent-transcript.md)）と同じ扱いにする。
+- 利用者の発言が残っているのに完了が見えない時は、今までどおり失敗に数える。
+
+### 確認した範囲
+
+- Linuxのコンテナ（0.15.5、Claude Code 2.1.292）で2026-10-07に起きた失敗の、transcriptとStopのpayloadを切り離した置き場で再生した。0.15.5は同じ文面で失敗して1回数え、この版は失敗に数えず`transcript_head_lost`を記録した。
+
+### 確認していない範囲
+
+- 同じ朝に同じ試験の道具で数えられた残り11回の失敗は、transcriptが後で消されていて、同じ形だったかを直接は見ていない。11回とも、その会話の最後のStopで起きている。
+- macOSとWindowsでは、この形の失敗を再現していない（足した試験はCIの3環境で走る）。
+
 ## [0.16.0] — 2026-10-07
 
 ### 変更
@@ -1876,7 +1892,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.0...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.16.1...HEAD
+[0.16.1]: https://github.com/kitepon/Throughline/compare/v0.16.0...v0.16.1
 [0.16.0]: https://github.com/kitepon/Throughline/compare/v0.15.5...v0.16.0
 [0.15.5]: https://github.com/kitepon/Throughline/compare/v0.15.4...v0.15.5
 [0.15.4]: https://github.com/kitepon/Throughline/compare/v0.15.3...v0.15.4

package/docs/adr/0038-stop-flush-barrier-head-lost-transcript.md

@@ -0,0 +1,53 @@
+# ADR 0038: 始まりを失った transcript の Claude Stop は、hook 処理の失敗に数えない
+
+日付: 2026-10-07
+
+## Context
+
+2026-10-07 08:24:17 JST、BellTeam コンテナ（0.15.5）で、解決登録していた `HOOK_PROCESS_TURN_FAILED` が再発した
+（7回目）。理由は `Claude Stop transcript completion was not visible before deadline`。
+
+失敗した会話は、`/tmp/ag-fvIcWA/proj` で動いた Claude Code（2.1.292）の試験用の会話。1つ目のターンの Stop は
+同じ会話の transcript を読んで 1 turn を保存している（08:23:59）。2つ目のターンの Stop が失敗した。
+
+残っていた transcript は 10 行で、最初の行は 08:24:08.262 の assistant（thinking だけ）、次が 08:24:15.621 の
+最後の応答だった。user の行は1つも無い。同じファイルの `turn_duration` は `messageCount: 29` と書いている。
+transcript を置くフォルダ（`~/.claude/projects/-tmp-ag-fvIcWA-proj`）の作成時刻は 08:24:15.744 で、
+会話の作業フォルダ（`/tmp/ag-fvIcWA/proj`）は 08:24:15.861 に消されている。
+
+会話を起動した試験の道具は、回答が端末に出た直後に端末を閉じ、transcript のフォルダと作業フォルダを消す。
+Claude Code は最後の応答の行（thinking と本文）をその後で書くので、フォルダごとファイルを作り直す。
+Stop hook は応答の後に非同期で走り、応答だけのファイルを読んだ、と読める。
+
+同じ道具は同じ朝に続けて動き、08:24〜08:33 の間に同じ文面の失敗が 12 回数えられた（7回目〜18回目）。
+transcript が残っていたのは最初の1回だけで、残りの11回は後でファイルが消されている。11回とも、
+その会話の最後の Stop で、1つ前の Stop は保存できている。
+
+ファイルが残らなかった時は ADR 0029 の `transcript_absent` になり、失敗に数えない。今回はファイルが
+作り直されていたので、ADR 0029 Decision 3（ファイルがあるのに完了が見えない時は失敗）に当たった。
+どちらも「保存する元が、会話を起動した側に消された」で、違いは Claude Code が残りを書いた時刻だけ。
+
+Throughline はターンを user の発言から数える（`readLatestLogicalTurnCompletions`）。user の発言が1つも無い
+transcript からは、どのターンも作れない。Claude Code は会話の最初に必ず user の行を書くので、
+assistant の発言があって user の発言が無い transcript は、始まりを失った物に限られる。
+
+控えた transcript と同じ Stop の payload を、切り離した置き場で再生した。0.15.5 は同じ文面で失敗し、
+`HOOK_PROCESS_TURN_FAILED` を1回数えた。
+
+## Decision
+
+1. flush barrier は、期限まで待っても完了が見えず、transcript に assistant の発言があって user の発言が
+   1つも無い時、`transcript_head_lost` を返す。失敗にしない。
+2. 確認は期限に達した時だけ行う。遅れて書かれる user の行は、今までどおり期限まで待つ。
+3. user の発言が1つでも残っている時と、発言が1つも無いファイル（書き始め）は、今までどおり明示失敗して
+   `HOOK_PROCESS_TURN_FAILED` を数える（ADR 0012 Decision 4、ADR 0029 Decision 3）。
+4. `transcript_head_lost` の Stop は、ADR 0029 Decision 4 と同じ扱いにする。`backfill.log` に
+   `{"hook":"stop",…,"skipped":"transcript_head_lost"}` を1行残し、終了 code 0 で終わる。
+   DB・state file・完了受領・runtime error store には何も書かない。
+
+## Consequences
+
+- 始まりを消された会話の最後のターンは保存されない。保存する依頼がどこにも無いので、今までも保存できていない。
+  変わるのは、失敗に数えるかどうかだけ。
+- 見送った Stop は `backfill.log` の `skipped` で数えられる。
+- transcript の途中だけが失われ、user の発言が残っている時は、今までどおり失敗に数える。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
   "description": "Persistent memory hooks for Claude Code, Codex, Grok, and Cursor (/clear-safe context compression)",
   "keywords": [

package/src/runtime-error-hook.test.mjs

@@ -98,6 +98,20 @@ test('Claude Stopで、transcriptのファイルが無い会話は失敗に数
     skipped: 'transcript_absent',
   }]);
 
+  // ターンの途中でtranscriptが消され、応答の行だけでファイルが作り直された。依頼が残っていないので、失敗に数えない（ADR 0038）。
+  const headLostPath = join(root, 'head-lost.jsonl');
+  writeFileSync(headLostPath, JSON.stringify({ type: 'assistant',
+    message: { role: 'assistant', stop_reason: 'end_turn', content: [{ type: 'text', text: 'PROBE_OK' }] } }) + '\n');
+  const headLost = stop({
+    session_id: 'a1b2c3d4-0000-4000-8000-000000000003', transcript_path: headLostPath, cwd: root,
+    hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: 'PROBE_OK',
+  });
+  assert.equal(headLost.status, 0, headLost.stderr);
+  assert.equal(existsSync(storePath), false, 'a transcript that lost its head must not be counted as a hook failure');
+  assert.equal(existsSync(join(root, '.throughline', 'logs', 'hook-failures.log')), false);
+  assert.deepEqual([readLog('backfill.log').at(-1).session_id, readLog('backfill.log').at(-1).skipped],
+    ['a1b2c3d4-0000-4000-8000-000000000003', 'transcript_head_lost']);
+
   // ファイルはあるのに、Stopが渡した応答がそこに無い。保存できなかった会話なので、失敗のまま数える。
   const presentPath = join(root, 'present.jsonl');
   writeFileSync(presentPath, JSON.stringify({ type: 'user', message: { role: 'user', content: 'request' } }) + '\n');

package/src/turn-processor.mjs

@@ -33,6 +33,7 @@
 import { getDb } from './db.mjs';
 import {
   readRawEntries,
+  readTranscript,
   readLatestLogicalTurnCompletions,
   sliceCurrentTurnEntries,
   extractDetailBlocks,
@@ -60,6 +61,12 @@ export const CLAUDE_STOP_TRANSCRIPT_FLUSH_INTERVAL_MS = 25;
 
 const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 
+/** transcript に assistant の発言だけがあり、user の発言が1つも無い（会話の始まりを失っている）。 */
+function isTranscriptHeadLost(transcriptPath) {
+  const turns = readTranscript(transcriptPath);
+  return turns.length > 0 && !turns.some(turn => turn.role === 'user');
+}
+
 /**
  * Claude Stop payloadのassistant identityがtranscriptへ永続化されるまで待つ。
  * markerは本文ソースにせず、transcript可視化のbarrierにだけ使う。
@@ -77,6 +84,10 @@ const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
  * 期限まで待ってもtranscriptのファイル自体が無い時は、失敗にせず `transcript_absent` を返す
  * （ADR 0029）。Claude Codeを `--no-session-persistence` で起動すると、hookへ `transcript_path` は
  * 渡るが、ファイルは最後まで作られない。ファイルがあるのに完了が見えない時は、今までどおり失敗にする。
+ *
+ * 期限まで待って、transcriptにassistantの発言だけがありuserの発言が1つも無い時は、失敗にせず
+ * `transcript_head_lost` を返す（ADR 0038）。ターンの途中でtranscriptが消されると、Claude Codeは
+ * 残りの行だけでファイルを作り直す。そのターンの依頼はどこにも残っていない。
  */
 export async function waitForClaudeStopTranscriptFlush({
   transcriptPath,
@@ -87,6 +98,7 @@ export async function waitForClaudeStopTranscriptFlush({
   readCompletions = readLatestLogicalTurnCompletions,
   isTurnCaptured = () => true,
   transcriptExists = existsSync,
+  transcriptHeadLost = isTranscriptHeadLost,
   now = Date.now,
   wait = delay,
 }) {
@@ -115,8 +127,9 @@ export async function waitForClaudeStopTranscriptFlush({
     }
     const remaining = deadline - now();
     if (remaining <= 0) {
-      if (typeof transcriptPath === 'string' && transcriptPath && !transcriptExists(transcriptPath)) {
-        return { status: 'transcript_absent' };
+      if (typeof transcriptPath === 'string' && transcriptPath) {
+        if (!transcriptExists(transcriptPath)) return { status: 'transcript_absent' };
+        if (transcriptHeadLost(transcriptPath)) return { status: 'transcript_head_lost' };
       }
       throw new Error('Claude Stop transcript completion was not visible before deadline');
     }
@@ -279,8 +292,8 @@ async function processStop() {
       lastAssistantMessage: last_assistant_message,
       isTurnCaptured: (fragmentTurnNumbers) => isLogicalTurnCaptured(db, origin, fragmentTurnNumbers),
     });
-    if (flush.status === 'transcript_absent') {
-      // 保存する元が無い。失敗には数えず、どの会話のStopを見送ったかを端末内に残す（ADR 0029）。
+    if (flush.status === 'transcript_absent' || flush.status === 'transcript_head_lost') {
+      // 保存する元が無い。失敗には数えず、どの会話のStopを見送ったかを端末内に残す（ADR 0029・0038）。
       logBackfill({
         ts: new Date().toISOString(),
         hook: 'stop',
@@ -288,7 +301,7 @@ async function processStop() {
         target,
         origin,
         transcript_path,
-        skipped: 'transcript_absent',
+        skipped: flush.status,
       });
       process.exit(0);
     }

package/src/turn-processor.test.mjs

@@ -274,6 +274,46 @@ test('Claude Stop flush barrierは、期限までtranscriptのファイルが無
   }
 });
 
+test('Claude Stop flush barrierは、期限までtranscriptにuserの発言が1つも無い時だけtranscript_head_lostを返す', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'throughline-stop-head-lost-'));
+  const transcriptPath = join(root, 'head-lost.jsonl');
+  let elapsed = 0;
+  const clock = { now: () => elapsed, wait: async (milliseconds) => { elapsed += milliseconds; } };
+  const line = (entry) => JSON.stringify(entry);
+  const assistant = (content) => ({ type: 'assistant', message: { role: 'assistant', stop_reason: 'end_turn', content } });
+  try {
+    // ターンの途中でtranscriptのフォルダが消され、Claude Codeが残りの行だけでファイルを作り直した形（Linux 2.1.292で実測）。
+    const tail = [
+      line(assistant([{ type: 'thinking', thinking: '' }])),
+      line(assistant([{ type: 'text', text: '最後の応答' }])),
+      line({ type: 'system', subtype: 'stop_hook_summary', hookCount: 3 }),
+      line({ type: 'ai-title', aiTitle: '題' }),
+    ];
+    writeFileSync(transcriptPath, tail.join('\n') + '\n', 'utf8');
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: '最後の応答', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), { status: 'transcript_head_lost' });
+    assert.equal(elapsed, 30, 'a user line that is written late must still get the whole deadline');
+
+    // userの発言が残っているのに完了が見えない時は、失敗のまま（保存できたはずの会話）。
+    writeFileSync(transcriptPath,
+      [line({ type: 'user', message: { role: 'user', content: '依頼' } }), ...tail].join('\n') + '\n', 'utf8');
+    elapsed = 0;
+    await assert.rejects(waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: '別の応答', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), /not visible before deadline/);
+
+    // 発言が1つも無いファイル（書き始め）は、先頭を失ったとは言えない。失敗のまま。
+    writeFileSync(transcriptPath, line({ type: 'mode', mode: 'normal' }) + '\n', 'utf8');
+    elapsed = 0;
+    await assert.rejects(waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: '最後の応答', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), /not visible before deadline/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('Claude Stop flush barrierはmarkerなし旧payloadをone-shot互換へ残す', async () => {
   let reads = 0;
   const result = await waitForClaudeStopTranscriptFlush({