throughline 0.12.6 → 0.12.8

package/CHANGELOG.md

@@ -10,6 +10,24 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.12.8] — 2026-10-04
+
+### 変更
+
+- runtime errorの送信を有効にした端末は、未受領の記録が無くても、受け口へ最後に届いた版と今の版が違う時に、`runtime_errors`と`resolutions`が空のreportを1回送る（[ADR 0030](docs/adr/0030-report-installed-version-once.md)）。reportは`installed_version`を持つので、受け口は記録が出ていない端末の版も分かる。届いた後は、版が変わるまで送らない。reportの形、署名、送る時機と間隔は変えない。送信を有効にしていない端末（既定）と、収集が無効な端末は、今までどおり何も送らない。
+- 0.12.7以前は、未受領の記録が無ければ通信しなかった。更新した端末で何も起きなければ、受け口は古い版を持ち続けていた。
+
+## [0.12.7] — 2026-10-04
+
+### 修正
+
+- Claude Stop hookで、transcriptのファイルが無い会話を`HOOK_PROCESS_TURN_FAILED`（Claude Stop hook processing failed・high）として数えていた不具合を直す（[ADR 0029](docs/adr/0029-stop-flush-barrier-absent-transcript.md)）。Claude Codeを`--no-session-persistence`で起動すると、hookへ`transcript_path`は渡るが、ファイルは最後まで作られない。保存する元が無いので、Stopは期限（2秒）まで待った後、`~/.throughline/logs/backfill.log`に`skipped: "transcript_absent"`を1行残して終了code 0で終わる。ファイルがあるのに完了が見えない時と、`transcript_path`がpayloadに無い時は、今までどおり失敗として数える。
+- BellTeamコンテナ（0.12.6）で2026-10-04に2回起きた失敗は、transcriptがディスクに無い1会話のStopだった。Claude Code 2.1.289を`--no-session-persistence`で動かして、同じ文面の失敗を再現した。その2回の会話がこの引数で起動されたことを示す記録は無い。
+
+### 変更
+
+- `~/.throughline/logs/hook-failures.log`に、Stopが失敗した会話の`session_id`と`transcript_path`を足す。理由の文面だけでは、どの会話のStopかを端末の他の記録から探すことになるため。端末内にだけ残し、外へは送らない。
+
 ## [0.12.6] — 2026-10-04
 
 ### 修正
@@ -1603,7 +1621,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.12.6...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.12.8...HEAD
+[0.12.8]: https://github.com/kitepon/Throughline/compare/v0.12.7...v0.12.8
+[0.12.7]: https://github.com/kitepon/Throughline/compare/v0.12.6...v0.12.7
 [0.12.6]: https://github.com/kitepon/Throughline/compare/v0.12.5...v0.12.6
 [0.12.5]: https://github.com/kitepon/Throughline/compare/v0.12.4...v0.12.5
 [0.12.4]: https://github.com/kitepon/Throughline/compare/v0.12.3...v0.12.4

package/README.md

@@ -890,7 +890,7 @@ once with `npm install --global throughline@latest`, then run
 | `throughline runtime-errors compact --json`    | Remove only acknowledged, resolved aggregates after retention; open or unacknowledged records remain |
 | `throughline runtime-errors report-enable --credential-file <path> --json` | Opt in to sending aggregates to the receiver named in that credential file; sending is disabled by default |
 | `throughline runtime-errors report-disable --json` | Stop sending aggregates |
-| `throughline runtime-errors report --json`     | Send unacknowledged aggregates once now; exits 0 only for `sent` or `nothing_pending` |
+| `throughline runtime-errors report --json`     | Send unacknowledged aggregates once now (or an empty report when the receiver has not seen this version yet); exits 0 only for `sent` or `nothing_pending` |
 | `throughline runtime-errors report-status --json` | Read the last attempt time and fixed result code without exposing the receiver, credential, or paths |
 | `throughline handoff-preview --session <id>`   | Print a Codex-facing `throughline_handoff` JSON projection    |
 | `throughline handoff-context (--session <id> \| --project <path>) --json` | Print the SessionStart inheritance context without moving memory rows. Project mode selects the newest captured session with dialogue, supports `--disclosure silent`, and returns `empty` when no dialogue exists. Session mode may add a project-bound supplement inside the same 9,500-character budget |
@@ -948,8 +948,10 @@ throughline runtime-errors report-status --json
 ```
 
 Once enabled, the Claude and Codex hook entry points start a detached sender at
-most once per hour, and only contact the receiver when unacknowledged records
-exist; the hooks do not wait for it. The body carries the public snapshot fields
+most once per hour; the hooks do not wait for it. It contacts the receiver when
+unacknowledged records exist, or once after the installed version changed (a
+report with empty `runtime_errors` and `resolutions`, so the receiver learns the
+version; see [ADR 0030](docs/adr/0030-report-installed-version-once.md)). The body carries the public snapshot fields
 only (fixed error code, template, count, timestamps, version, resolutions). The
 secret is never transmitted: the body is signed with
 `HMAC-SHA256(secret, ts + "\n" + SHA-256(body))`, redirects are not followed,

package/docs/adr/0012-claude-stop-transcript-flush-barrier.md

@@ -23,6 +23,7 @@ turn後に現行parserで読むとlatest logical groupは1件だった。Claude
 3. latest user groupを必須にし、過去の同文assistantや前turnを一致として採用しない。
    （2026-10-03 [ADR 0026](0026-stop-flush-barrier-next-user.md)で、Stop直後に次のuser行が届いた時の未捕捉の1つ前のgroupだけを例外にした。）
 4. deadlineまで一致しなければ明示errorと`HOOK_PROCESS_TURN_FAILED`を返し、completionなしへ丸めない。
+   （2026-10-04 [ADR 0029](0029-stop-flush-barrier-absent-transcript.md)で、deadlineまでtranscriptのファイル自体が無い時だけ、失敗に数えず`transcript_absent`として見送ることにした。）
 5. markerを持たない旧Claude hostは既存one-shot transcript parser契約を維持する。
 6. Claude Stop hookの`async: true`、DB schema、receipt wire、Observer cursorは変更しない。
 

package/docs/adr/0025-runtime-error-reporting.md

@@ -38,7 +38,7 @@ BugHub は、端末に入る CLI 製品が自分の分だけを送る受け口
 7. 送る時機は hook 入口。`process-turn`・`session-start`・`prompt-submit`・`codex-hook` の開始時に、
    送信が有効で、次に試してよい時刻を過ぎていれば、切り離した子 process を1つ起こす。
    hook の終了は待たせない。子 process が store lock の下で時刻を先に書くので、同時に起きても送るのは1つ。
-   未受領の記録が無ければ通信しない。間隔は1時間。credential や report の形で断られた時は24時間空ける。
+   未受領の記録が無ければ通信しない（2026-10-04 [ADR 0030](0030-report-installed-version-once.md)で、受け口へ届いた版と今の版が違う時だけ、空の report を1回送ることにした）。間隔は1時間。credential や report の形で断られた時は24時間空ける。
    `throughline runtime-errors report --json` は間隔を待たずに1回送る。
 8. 送信の状態（最後に試した時刻・結果の固定 code・次の時刻）は `runtime-errors.report.state.json` に持ち、
    `runtime-errors report-status --json` で読む。宛先・credential・path は出さない。

package/docs/adr/0029-stop-flush-barrier-absent-transcript.md

@@ -0,0 +1,62 @@
+# ADR 0029: transcript のファイルが無い Claude Stop は、hook 処理の失敗に数えない
+
+日付: 2026-10-04
+
+## Context
+
+ADR 0012 の flush barrier は、Stop payload の `last_assistant_message` が transcript に見えるまで最大2秒待ち、
+見えなければ `HOOK_PROCESS_TURN_FAILED`（`Throughline Claude Stop hook processing failed`、severity `high`）で
+明示失敗する。
+
+2026-10-04、BellTeam コンテナ（0.12.6）で、前日に解決登録した `HOOK_PROCESS_TURN_FAILED` が再発した。
+00:36:19.037Z と 00:36:24.188Z の2回で、理由はどちらも
+`Claude Stop transcript completion was not visible before deadline`。
+
+失敗した会話は `/tmp` で 00:35:39Z から 00:36:24Z まで動いた Claude Code（2.1.289）の1会話。
+SessionStart と UserPromptSubmit の hook は `transcript_path` を受け取っているが、その path に
+ファイルは無い。`~/.claude/history.jsonl` にもこの会話の入力は残っていない。
+前日までに同じ内容の会話が5回 `/tmp` で動いていて、その時は transcript が残り、Stop は同じ実行で保存している。
+
+同じ端末で、Claude Code を `-p --input-format stream-json --no-session-persistence` で1 turn 動かして再現した。
+Stop payload には `transcript_path` と `last_assistant_message` が渡るが、ファイルは最後まで作られず、
+Stop は応答の 2.08 秒後に同じ文面で失敗した。payload に、保存しない起動であることを示す項目は無い。
+`--no-session-persistence` を外した同じ会話は、同じ Stop で 1 turn を保存した。
+
+Throughline が保存する本文の正本は transcript だけ（ADR 0012 Decision 2）。transcript が作られない会話には、
+保存する元が無い。これは host を起動した側の指定で、Throughline の修理では直らない。
+`HOOK_PROCESS_TURN_FAILED` の回数からは、保存できたはずの会話を落としたのか、保存する元が無かったのかを
+区別できない。
+
+## Decision
+
+1. flush barrier は、期限まで待っても完了が見えず、かつ `transcript_path` のファイルが存在しない時、
+   `transcript_absent` を返す。失敗にしない。
+2. 存在の確認は期限に達した時だけ行う。遅れて書かれる transcript は、今までどおり期限まで待つ。
+3. ファイルが存在するのに完了が見えない時は、今までどおり明示失敗して `HOOK_PROCESS_TURN_FAILED` を数える
+   （ADR 0012 Decision 4）。`transcript_path` が payload に無い時も、ファイルが無いことを確かめられないので
+   失敗のままにする。
+4. `transcript_absent` の Stop は、`~/.throughline/logs/backfill.log` に
+   `{"hook":"stop","session_id":…,"transcript_path":…,"skipped":"transcript_absent"}` を1行残し、
+   終了 code 0 で終わる。DB・state file・完了受領には何も書かない。runtime error store にも数えない。
+5. hook が失敗した時の `hook-failures.log`（ADR 0027）に、Stop の `session_id` と `transcript_path` を足す。
+   今回は理由の文面だけが残り、どの会話の Stop かを他の記録から探すことになった。
+   このログは端末内にだけ置き、外へは送らない。
+
+## Consequences
+
+- transcript を残さない起動（`--no-session-persistence`）の会話は、Throughline の記憶に入らない。
+  見送った Stop は `backfill.log` で数えられる。
+- その会話の Stop hook は、今までと同じく期限（2秒）まで待ってから終わる。
+- host が transcript の置き場を変え、hook に渡す path にファイルが無くなった場合も、失敗としては数えなくなる。
+  その時は `backfill.log` に `transcript_absent` が並び、`inserted_turns` が出なくなる。
+- 期限の後に初めてファイルが作られる会話は、その Stop では保存されない。同じ会話の次の Stop が、
+  未捕捉の turn をまとめて保存する（backfill）。最後の turn で起きた時は保存されない。
+- `HOOK_PROCESS_TURN_FAILED` の fingerprint は変わらない。過去の回数は移さない。
+
+## 確認できていないこと
+
+- 2026-10-04 の2回の会話を、誰がどの引数で起動したかは特定できていない。確かめたのは、その会話の
+  transcript がディスクに無いことと、`--no-session-persistence` で起動した会話が同じ文面で失敗すること。
+  transcript が後から消された可能性は、記録からは否定できない。
+- `--no-session-persistence` 以外に、path は渡るがファイルが作られない起動の仕方があるかは調べていない。
+- 実測は Linux の Claude Code 2.1.289 だけ。macOS と Windows では確かめていない。

package/docs/adr/0030-report-installed-version-once.md

@@ -0,0 +1,48 @@
+# ADR 0030: 未受領の記録が無くても、受け口へ届いた版と今の版が違う時は、空の report を1回送る
+
+日付: 2026-10-04
+
+## Context
+
+ADR 0025 Decision 7 は、未受領の記録（runtime error と解決記録）が無ければ通信しないと決めている。
+report は毎回 `installed_version` を持つが、記録が無い端末からは report が出ない。
+
+BugHub は 2026-10-04 から、工場の report を送らない端末について、製品の report の `installed_version` と
+`observed_at` を端末の導入版として表示する。受け口は `runtime_errors` と `resolutions` が空の report も受ける
+（BugHub の担当が確認。同じ端末×製品は1分に1回まで）。
+
+BellTeam コンテナは工場の report を送らない。0.12.7 へ更新して未解決が0件になった後は、
+次に runtime error か解決記録が出るまで report が出ず、BugHub の導入版は「未確認」のままになる。
+更新した端末で何も起きなければ、受け口は古い版を持ち続ける。
+
+オーナーは 2026-10-04 に、エラーが無い時にも版を知らせる report を送ってよいか、送るなら
+版が変わった時に1回だけか・1時間ごとかを選び、「版が変わった時に1回だけ送る」と決めた。
+
+## Decision
+
+1. 送信の状態（`runtime-errors.report.state.json`）に、受け口が受領した最後の report の版
+   `last_reported_version` を持つ。書くのは、report が `sent`（ADR 0025 Decision 6 の受領がそろった時）に
+   なった時だけ。記録を載せた report でも、空の report でも同じ。
+2. 未受領の記録が無い時、`last_reported_version` が今の版と同じなら、今までどおり通信しない（`nothing_pending`）。
+   違う時（版を上げた・下げた後、この項目を持たない旧版の state）は、`runtime_errors` と `resolutions` が
+   空の report を1回送る。
+3. 空の report の形は ADR 0025 と同じ。項目は `schema_version`・`report_id`・`product_id`・
+   `installed_version`・`observed_at`・空の `runtime_errors`・空の `resolutions`。wire の版は変えない。
+   署名、redirect を追わないこと、受領の確認も同じ。
+4. 送るのは、今までどおり `report-enable` で明示して有効にし、収集も有効な端末だけ。
+   送信が無効な端末と収集が無効な端末は、版も送らない。
+5. 送る時機と間隔は変えない（hook 入口、1時間、断られた時は ADR 0025 の間隔）。
+   断られた時と届いたか分からない時は `last_reported_version` を書かず、次の送信でもう一度送る。
+6. `runtime-errors report --json` の結果は `sent`（`runtime_errors: 0`・`resolutions: 0`）。
+   `report-status` の項目は変えない。
+
+## Consequences
+
+- 送信を有効にした端末は、0.12.8 へ上げた後に1回、その後は版が変わるたびに1回、空の report を送る。
+  受け口には、端末がその版で動いた時刻が1つ届く。
+- 版が同じ間は、記録が無ければ通信しない。端末が動いているかどうかは、この report からは分からない。
+- 版を上げた後、次の送信の時刻（最長1時間）と、その後の最初の hook までは届かない。
+  急ぐ時は `runtime-errors report --json` を回す。
+- 0.12.7 以前へ戻すと、旧版は state を書き直す時に `last_reported_version` を落とす。
+  再び上げた時に、もう1回送る。
+- 既定の利用者（送信を有効にしていない端末）の動作は変わらない。

package/package.json

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

package/src/hook-failure-log.mjs

@@ -36,6 +36,13 @@ export function logHookFailure(code, error, { home, now = Date.now(), stderr = p
     name: error instanceof Error ? error.name : typeof error,
     message: message.slice(0, HOOK_FAILURE_MESSAGE_LIMIT),
   };
+  // どの会話の失敗かを残す（errorが `hookContext` を持つ時）。回数と文面だけでは、失敗した会話を
+  // 端末の他の記録から探すことになる。
+  const context = error?.hookContext;
+  if (typeof context?.session_id === 'string' && context.session_id) entry.session_id = context.session_id;
+  if (typeof context?.transcript_path === 'string' && context.transcript_path) {
+    entry.transcript_path = context.transcript_path;
+  }
   // 外部 CLI の失敗は、message が終了 code だけになる。理由（reason）と CLI の stderr の末尾も残す
   // （CLI は先頭に起動情報を出し、失敗の理由は末尾に出す）。
   if (typeof error?.reason === 'string' && error.reason) entry.reason = error.reason;

package/src/hook-failure-log.test.mjs

@@ -41,6 +41,26 @@ test('logHookFailureは、外部CLIの失敗の理由とstderrの末尾を残す
   }
 });
 
+test('logHookFailureは、どの会話の失敗かを残す', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-hook-failure-log-'));
+  try {
+    const withContext = new Error('with context');
+    withContext.hookContext = { session_id: 'session-a', transcript_path: '/claude/projects/-tmp/session-a.jsonl' };
+    logHookFailure('HOOK_PROCESS_TURN_FAILED', withContext, { home });
+    // 文字列でない値と空文字は残さない（payloadを読む前の失敗では、手がかりがまだ無い）。
+    const withoutContext = new Error('without context');
+    withoutContext.hookContext = { session_id: '', transcript_path: undefined };
+    logHookFailure('HOOK_PROCESS_TURN_FAILED', withoutContext, { home });
+    const [first, second] = readFileSync(hookFailureLogPath({ home }), 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+    assert.equal(first.session_id, 'session-a');
+    assert.equal(first.transcript_path, '/claude/projects/-tmp/session-a.jsonl');
+    assert.equal('session_id' in second, false);
+    assert.equal('transcript_path' in second, false);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('logHookFailureは、長い文面を上限で切る', () => {
   const home = mkdtempSync(join(tmpdir(), 'tl-hook-failure-log-'));
   try {

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

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -70,6 +70,51 @@ test('top-level hook owners record one fixed aggregate per failure without repla
   assert.equal(store.records.find((record) => record.error_code === 'HOOK_PROCESS_TURN_FAILED').count, 2);
 });
 
+test('Claude Stopで、transcriptのファイルが無い会話は失敗に数えず、ファイルがあって完了が見えない時だけ数える', () => {
+  const { root, env } = createEnabledEnvironment('throughline-runtime-stop-absent-');
+  const storePath = defaultRuntimeErrorStorePath(env);
+  const stop = (payload) => spawnSync(process.execPath, [BIN, 'process-turn'], {
+    env, cwd: root, input: JSON.stringify(payload), encoding: 'utf8',
+  });
+  const readLog = (name) => readFileSync(join(root, '.throughline', 'logs', name), 'utf8')
+    .trim().split('\n').map((line) => JSON.parse(line));
+
+  // `--no-session-persistence` のClaude Code（2.1.289で実測）: pathは渡るが、ファイルは作られない。
+  const absentPath = join(root, 'never-written.jsonl');
+  const absent = stop({
+    session_id: 'a1b2c3d4-0000-4000-8000-000000000001', transcript_path: absentPath, cwd: root,
+    hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: 'PROBE_OK',
+  });
+  assert.equal(absent.status, 0, absent.stderr);
+  assert.equal(absent.stderr, '');
+  assert.equal(existsSync(storePath), false, 'an absent transcript must not be counted as a hook failure');
+  assert.equal(existsSync(join(root, '.throughline', 'logs', 'hook-failures.log')), false);
+  assert.deepEqual(readLog('backfill.log').map(({ ts, ...entry }) => entry), [{
+    hook: 'stop',
+    session_id: 'a1b2c3d4-0000-4000-8000-000000000001',
+    target: 'a1b2c3d4-0000-4000-8000-000000000001',
+    origin: 'a1b2c3d4-0000-4000-8000-000000000001',
+    transcript_path: absentPath,
+    skipped: 'transcript_absent',
+  }]);
+
+  // ファイルはあるのに、Stopが渡した応答がそこに無い。保存できなかった会話なので、失敗のまま数える。
+  const presentPath = join(root, 'present.jsonl');
+  writeFileSync(presentPath, JSON.stringify({ type: 'user', message: { role: 'user', content: 'request' } }) + '\n');
+  const present = stop({
+    session_id: 'a1b2c3d4-0000-4000-8000-000000000002', transcript_path: presentPath, cwd: root,
+    hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: 'PROBE_OK',
+  });
+  assert.equal(present.status, 1);
+  assert.match(present.stderr, /not visible before deadline/);
+  const store = JSON.parse(readFileSync(storePath, 'utf8'));
+  assert.deepEqual(store.records.map((record) => [record.error_code, record.count]), [['HOOK_PROCESS_TURN_FAILED', 1]]);
+  const [failure] = readLog('hook-failures.log');
+  assert.equal(failure.code, 'HOOK_PROCESS_TURN_FAILED');
+  assert.equal(failure.session_id, 'a1b2c3d4-0000-4000-8000-000000000002');
+  assert.equal(failure.transcript_path, presentPath);
+});
+
 function makeBin(dir, name, body) {
   const script = join(dir, `${name}.mjs`);
   writeFileSync(script, body);

package/src/runtime-error-report.mjs

@@ -131,22 +131,30 @@ export async function reportRuntimeErrors(options = {}) {
 
   // 記録が無効な端末でも次の時刻は書く。書かないと、hookのたびに送信processが起きる。
   const outcome = isRuntimeErrorCollectionEnabled({ env })
-    ? await sendPendingRecords({ env, nowMs, fetchImpl, storeOptions, credentialFile: config.reporting.credential_file })
+    ? await sendPendingRecords({
+      env, nowMs, fetchImpl, storeOptions,
+      credentialFile: config.reporting.credential_file,
+      lastReportedVersion: claimed.last_reported_version,
+    })
     : result('collection_disabled');
   updateState(lockOptions, (state) => ({
     ...state,
     last_result: outcome.status,
     last_success_at: outcome.status === 'sent' ? new Date(nowMs).toISOString() : state.last_success_at,
+    last_reported_version: outcome.status === 'sent' ? PACKAGE_VERSION : state.last_reported_version,
     next_attempt_at: new Date(nowMs + (LONG_BACKOFF_STATUSES.has(outcome.status)
       ? REPORT_REJECTED_BACKOFF_MS : REPORT_INTERVAL_MS)).toISOString(),
   }));
   return outcome;
 }
 
-async function sendPendingRecords({ env, nowMs, fetchImpl, storeOptions, credentialFile }) {
+async function sendPendingRecords({ env, nowMs, fetchImpl, storeOptions, credentialFile, lastReportedVersion }) {
   const acknowledged = readRuntimeErrorSnapshot({ ...storeOptions, limit: 1 }).cursor.acknowledged_through;
   const snapshot = readRuntimeErrorSnapshot({ ...storeOptions, afterCursor: acknowledged });
-  if (snapshot.runtime_errors.length === 0 && snapshot.resolutions.length === 0) {
+  // 未受領の記録が無くても、受け口へ最後に届いた版と今の版が違う時は、記録が空のreportを1回送る
+  // （ADR 0030）。受け口は installed_version を端末の導入版として持つ。届いた後は、版が変わるまで送らない。
+  if (snapshot.runtime_errors.length === 0 && snapshot.resolutions.length === 0 &&
+    lastReportedVersion === PACKAGE_VERSION) {
     return result('nothing_pending', { acknowledged_through: acknowledged });
   }
 
@@ -321,6 +329,7 @@ function emptyState() {
     last_result: null,
     last_success_at: null,
     next_attempt_at: null,
+    last_reported_version: null,
   };
 }
 
@@ -332,6 +341,9 @@ function normalizeState(value) {
     if (isCanonicalTimestamp(value[key])) state[key] = value[key];
   }
   if (RESULT_STATUSES.has(value.last_result)) state.last_result = value.last_result;
+  if (typeof value.last_reported_version === 'string' && /^[0-9A-Za-z.+-]{1,64}$/.test(value.last_reported_version)) {
+    state.last_reported_version = value.last_reported_version;
+  }
   return state;
 }
 

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

@@ -393,6 +393,76 @@ test('runtime error report: background runs respect the interval, explicit runs
   }
 });
 
+test('runtime error report: with nothing pending, the installed version is reported once and again only after it changes', async () => {
+  const { root, env } = createEnvironment();
+  const installed = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  let reply = (entry) => accept(entry);
+  const receiver = await startReceiver((entry) => reply(entry));
+  const statePath = defaultRuntimeErrorReportStatePath(env);
+  const readState = () => JSON.parse(readFileSync(statePath, 'utf8'));
+  try {
+    setRuntimeErrorCollectionEnabled(true, { env });
+    setRuntimeErrorReportingEnabled(true, { env, credentialFile: writeCredential(root, receiver.url) });
+
+    // 断られた時は届いた版として覚えない。次の送信でもう一度送る。
+    reply = () => ({ status: 429, body: { error: 'rate_limited' } });
+    assert.equal((await reportRuntimeErrors({ env, now: NOW })).status, 'rate_limited');
+    assert.equal(readState().last_reported_version, null);
+
+    // 記録が1件も無い端末（0.12.7以前から上げた直後のstateも同じ）: 版と時刻だけのreportを1回送る。
+    reply = (entry) => accept(entry);
+    const first = await reportRuntimeErrors({ env, now: NOW + 1000 });
+    assert.equal(first.status, 'sent');
+    assert.equal(first.runtime_errors, 0);
+    assert.equal(first.resolutions, 0);
+    assert.equal(receiver.requests.length, 2);
+    const sent = receiver.requests[1];
+    assert.equal(sent.signatureValid, true);
+    assert.deepEqual(sent.report, {
+      schema_version: '1.0',
+      report_id: first.report_id,
+      product_id: 'throughline',
+      installed_version: installed,
+      observed_at: new Date(NOW + 1000).toISOString(),
+      runtime_errors: [],
+      resolutions: [],
+    });
+    assert.equal(readState().last_reported_version, installed);
+    assert.equal(readRuntimeErrorSnapshot({ env }).cursor.acknowledged_through, 0);
+
+    // 同じ版のままなら、記録が無い間は通信しない。
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 2000 })).status, 'nothing_pending');
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 2 * REPORT_INTERVAL_MS, background: true })).status, 'nothing_pending');
+    assert.equal(receiver.requests.length, 2);
+
+    // 記録を送ったreportも、その版を届けたことになる。
+    observeRuntimeError({ code: 'HOOK_CODEX_FAILED' }, { env });
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 3 * REPORT_INTERVAL_MS })).status, 'sent');
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 3 * REPORT_INTERVAL_MS + 1000 })).status, 'nothing_pending');
+    assert.equal(receiver.requests.length, 3);
+
+    // 版が変わった（最後に届いた版が今の版と違う）時は、もう1回だけ送る。
+    writeFileSync(statePath, JSON.stringify({ ...readState(), last_reported_version: '0.0.1' }));
+    const afterUpdate = await reportRuntimeErrors({ env, now: NOW + 4 * REPORT_INTERVAL_MS });
+    assert.equal(afterUpdate.status, 'sent');
+    assert.deepEqual(receiver.requests[3].report.runtime_errors, []);
+    assert.equal(receiver.requests[3].report.installed_version, installed);
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 4 * REPORT_INTERVAL_MS + 1000 })).status, 'nothing_pending');
+    assert.equal(receiver.requests.length, 4);
+
+    // 記録を無効にした端末と、送信を無効にした端末は、版も送らない。
+    writeFileSync(statePath, JSON.stringify({ ...readState(), last_reported_version: '0.0.1' }));
+    setRuntimeErrorCollectionEnabled(false, { env });
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 5 * REPORT_INTERVAL_MS })).status, 'collection_disabled');
+    setRuntimeErrorCollectionEnabled(true, { env });
+    setRuntimeErrorReportingEnabled(false, { env });
+    assert.equal((await reportRuntimeErrors({ env, now: NOW + 6 * REPORT_INTERVAL_MS })).status, 'reporting_disabled');
+    assert.equal(receiver.requests.length, 4);
+  } finally {
+    await receiver.close();
+  }
+});
+
 test('runtime error report: an unsafe or malformed credential file is never used', { skip: process.platform === 'win32' }, async () => {
   const { root, env } = createEnvironment();
   let calls = 0;

package/src/turn-processor.mjs

@@ -44,6 +44,7 @@ import { summarizeToL1 } from './haiku-summarizer.mjs';
 import { ensureMonitorTaskFile } from './vscode-task.mjs';
 import { readLatestUsage } from './transcript-usage.mjs';
 import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
 import { logHookFailure } from './hook-failure-log.mjs';
 import { writeCompletedTurnReceipt } from './completed-turn-receipts.mjs';
@@ -69,6 +70,10 @@ const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
  *
  * markerとtranscriptの本文は、前後の空白を除いて比べる（ADR 0027）。Claude Codeはmarkerを
  * `.trim()` して渡すので、本文が空白や改行で始まる（終わる）turnは、そのままでは一致しない。
+ *
+ * 期限まで待ってもtranscriptのファイル自体が無い時は、失敗にせず `transcript_absent` を返す
+ * （ADR 0029）。Claude Codeを `--no-session-persistence` で起動すると、hookへ `transcript_path` は
+ * 渡るが、ファイルは最後まで作られない。ファイルがあるのに完了が見えない時は、今までどおり失敗にする。
  */
 export async function waitForClaudeStopTranscriptFlush({
   transcriptPath,
@@ -78,6 +83,7 @@ export async function waitForClaudeStopTranscriptFlush({
   readCompletion,
   readCompletions = readLatestLogicalTurnCompletions,
   isTurnCaptured = () => true,
+  transcriptExists = existsSync,
   now = Date.now,
   wait = delay,
 }) {
@@ -106,6 +112,9 @@ export async function waitForClaudeStopTranscriptFlush({
     }
     const remaining = deadline - now();
     if (remaining <= 0) {
+      if (typeof transcriptPath === 'string' && transcriptPath && !transcriptExists(transcriptPath)) {
+        return { status: 'transcript_absent' };
+      }
       throw new Error('Claude Stop transcript completion was not visible before deadline');
     }
     await wait(Math.min(intervalMs, remaining));
@@ -212,7 +221,20 @@ function buildL2ForSummary(userTurn, assistantTurn) {
   return parts.join('\n\n');
 }
 
+/** 失敗した時に hook-failures.log へ残す、どの会話のStopだったかの手がかり。 */
+let failureContext = {};
+
 export async function run() {
+  try {
+    await processStop();
+  } catch (err) {
+    // 失敗を記録するのは呼び出し側（bin/throughline.mjs と下の直接実行）。errorに手がかりを持たせて渡す。
+    if (err instanceof Error) err.hookContext = failureContext;
+    throw err;
+  }
+}
+
+async function processStop() {
   if (process.env.THROUGHLINE_IN_HAIKU_SUBPROCESS === '1') {
     process.exit(0);
   }
@@ -229,6 +251,7 @@ export async function run() {
   const payload = parseHookPayload(raw || '{}', { env: process.env });
   const { session_id, transcript_path, cwd, last_assistant_message } = payload;
   if (!session_id) throw new Error('Missing session_id in Stop payload');
+  failureContext = { session_id, transcript_path };
 
   // VSCode で開かれたプロジェクトに .vscode/tasks.json を自動プロビジョニングする。
   // 2 回目以降は冪等性チェックで即 return するので毎ターン走っても安全。
@@ -245,11 +268,24 @@ export async function run() {
   const { target, origin } = resolveMergeTarget(db, session_id);
 
   if (hostAdapterForSessionId(session_id).waitsForStopTranscriptFlush) {
-    await waitForClaudeStopTranscriptFlush({
+    const flush = await waitForClaudeStopTranscriptFlush({
       transcriptPath: transcript_path,
       lastAssistantMessage: last_assistant_message,
       isTurnCaptured: (fragmentTurnNumbers) => isLogicalTurnCaptured(db, origin, fragmentTurnNumbers),
     });
+    if (flush.status === 'transcript_absent') {
+      // 保存する元が無い。失敗には数えず、どの会話のStopを見送ったかを端末内に残す（ADR 0029）。
+      logBackfill({
+        ts: new Date().toISOString(),
+        hook: 'stop',
+        session_id,
+        target,
+        origin,
+        transcript_path,
+        skipped: 'transcript_absent',
+      });
+      process.exit(0);
+    }
   }
 
   // Stop hook 時点で state ファイルを更新 → token-monitor の「アクティブ行」判定が

package/src/turn-processor.test.mjs

@@ -222,6 +222,7 @@ test('Claude Stop flush barrierはmarker不一致をdeadlineで明示失敗す
       timeoutMs: 30,
       intervalMs: 10,
       readCompletion: () => ({ userTurnNumber: 4, assistantTurnNumber: null, assistantContent: null }),
+      transcriptExists: () => true,
       now: () => elapsed,
       wait: async (milliseconds) => { elapsed += milliseconds; },
     }),
@@ -230,6 +231,49 @@ test('Claude Stop flush barrierはmarker不一致をdeadlineで明示失敗す
   assert.equal(elapsed, 30);
 });
 
+test('Claude Stop flush barrierは、期限までtranscriptのファイルが無い時だけtranscript_absentを返す', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'throughline-stop-absent-'));
+  const transcriptPath = join(root, 'never-written.jsonl');
+  let elapsed = 0;
+  const clock = { now: () => elapsed, wait: async (milliseconds) => { elapsed += milliseconds; } };
+  try {
+    // `--no-session-persistence` のClaude Code: pathは渡るが、ファイルは最後まで作られない。期限までは待つ。
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'PROBE_OK', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), { status: 'transcript_absent' });
+    assert.equal(elapsed, 30, 'a transcript that is written late must still get the whole deadline');
+
+    // 待っている間にファイルが作られ、完了が見えた時は、今までどおり採用する。
+    elapsed = 0;
+    let reads = 0;
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'late answer', timeoutMs: 100, intervalMs: 10, ...clock,
+      readCompletions: () => {
+        reads++;
+        if (reads < 3) return { latest: null, previous: null };
+        return { latest: { userTurnNumber: 0, assistantTurnNumber: 1, assistantContent: 'late answer', fragmentTurnNumbers: [1] }, previous: null };
+      },
+    }), { status: 'ready', userTurnNumber: 0, assistantTurnNumber: 1 });
+
+    // ファイルはあるのに完了が見えない時は、失敗のまま。
+    writeFileSync(transcriptPath, JSON.stringify({ type: 'user', message: { role: 'user', content: 'request' } }), 'utf8');
+    elapsed = 0;
+    await assert.rejects(waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'PROBE_OK', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), /not visible before deadline/);
+
+    // pathが渡らないpayloadは、ファイルが無いことを確かめられない。失敗のまま。
+    for (const missingPath of [undefined, null, '']) {
+      elapsed = 0;
+      await assert.rejects(waitForClaudeStopTranscriptFlush({
+        transcriptPath: missingPath, lastAssistantMessage: 'PROBE_OK', 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({