throughline 0.12.3 → 0.12.5

package/CHANGELOG.md

@@ -10,6 +10,24 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.12.5] — 2026-10-04
+
+### 修正
+
+- Claudeの応答が空白や改行で始まる（終わる）turnで、Stop hookが2秒待って`HOOK_PROCESS_TURN_FAILED`で失敗していた不具合を直す。Claude CodeはStop payloadの`last_assistant_message`を`.trim()`して渡すが、transcriptにはtrimする前の本文が残る。flush barrierは完全一致で比べていたので、transcriptが出そろっていても一致しなかった。前後の空白を除いて比べる（[ADR 0027](docs/adr/0027-stop-flush-barrier-trimmed-marker.md)）。保存する本文はtranscriptのままで変えない。
+- Macで記録された最後の`HOOK_PROCESS_TURN_FAILED`（2026-08-31）がこの形だった。その時のtranscriptでStopを再生すると、0.10.3・0.12.1・0.12.4のどれも失敗し、この版では成功する。Macに残る8月のtranscriptでは、空白で始まる応答のStopが96回あり、96回とも保存されていなかった。
+
+### 追加
+
+- hookが失敗した時の理由を、端末内の`~/.throughline/logs/hook-failures.log`へ残す。1行のJSONで、項目は`ts`・`code`・`version`・`name`・`message`（1000字まで）。SessionStart・UserPromptSubmit・Stop・Codex hookが対象。runtime errorの収集・送信の設定とは独立に書き、外へは送らない。runtime error storeは定型codeと回数だけを持つので、これまでは失敗の理由が残らず、後から原因を追えなかった。
+
+## [0.12.4] — 2026-10-04
+
+### 修正
+
+- WindowsのCursorがhookの標準入力へ付けるUTF-8 BOMをJSONとして読もうとして、SessionStart・UserPromptSubmit・Stopが失敗する不具合を直す。共有の読取処理で先頭のBOMを1つ取り除いてから解析する。JSONの文字列中のBOMは保ち、不正なJSONは引き続き失敗として扱う。Windowsの実hook入力でSessionStartの例外を再現し、3種類のhookで会話の保存と不正JSONの拒否を試験した。
+- Cursorの`transcript_path`が未指定の場合、projectのフォルダ名をCursor自身と同じ規則で作る。以前はアンダースコアやドットを残していたため、foxの`C:\Users\kite_\.cache\…`などで実際の記録フォルダを見つけられなかった。英数字以外をハイフンに置き換え、連続するハイフンと両端を整える。指定された`transcript_path`はそのまま優先する。
+
 ## [0.12.3] — 2026-10-03
 
 ### 修正
@@ -1570,7 +1588,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.12.3...HEAD
+[Unreleased]: https://github.com/kitepon/Throughline/compare/v0.12.5...HEAD
+[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
 [0.12.3]: https://github.com/kitepon/Throughline/compare/v0.12.2...v0.12.3
 [0.12.2]: https://github.com/kitepon/Throughline/compare/v0.12.1...v0.12.2
 [0.12.1]: https://github.com/kitepon/Throughline/compare/v0.12.0...v0.12.1

package/bin/throughline.mjs

@@ -237,6 +237,8 @@ switch (cmd) {
   if (code) {
     const { recordRuntimeErrorBestEffort } = await import('../src/runtime-error-store.mjs');
     recordRuntimeErrorBestEffort(code);
+    const { logHookFailure } = await import('../src/hook-failure-log.mjs');
+    logHookFailure(code, error);
   }
   throw error;
 }

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

@@ -17,6 +17,7 @@ turn後に現行parserで読むとlatest logical groupは1件だった。Claude
 
 1. Stop payloadに非空`last_assistant_message`がある場合、latest user groupの非junk assistant本文が
    その値と一致するまで短いbounded intervalでtranscriptを再読する。
+   （2026-10-04 [ADR 0027](0027-stop-flush-barrier-trimmed-marker.md)で、前後の空白を除いて比べることにした。Claude Codeはmarkerを`.trim()`して渡す。）
 2. `last_assistant_message`はcompletion identity／flush barrierにだけ使い、L2本文やreceipt digestの
    ソースにはしない。本文は従来どおりtranscriptからDBへcommitしたpairだけを使う。
 3. latest user groupを必須にし、過去の同文assistantや前turnを一致として採用しない。

package/docs/adr/0022-cursor-host-capture.md

@@ -19,6 +19,8 @@ L2 lives in `~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl` wi
 ## Decision
 
 - Detect Cursor envelope (`cursor_version` or `hook_event_name` in the Cursor event set) as host=cursor.
+- Shared hook stdin parsing accepts one leading UTF-8 BOM, as emitted by Windows Cursor. It preserves BOM characters inside JSON strings and still rejects malformed JSON.
+- When `transcript_path` is absent, derive the project folder with Cursor's `utils/workspace-paths` rule: replace non-ASCII-alphanumeric characters with `-`, collapse consecutive hyphens, and remove leading/trailing hyphens. A supplied `transcript_path` remains authoritative.
 - Normalize to the existing snake_case hook contract and prefix ids with `cursor:`. Strip optional `bc-` from cloud conversation ids when looking up transcripts.
 - Prefer payload `transcript_path`. If absent, derive the agent-transcripts path. Do not invent a Claude-shaped transcript.
 - `throughline install` upserts product hooks into `~/.cursor/hooks.json`. Keep factory / personal commands. Command is absolute `node` + `bin/throughline.mjs`. Do not write factory.json. Do not write bare `throughline`.

package/docs/adr/0027-stop-flush-barrier-trimmed-marker.md

@@ -0,0 +1,62 @@
+# ADR 0027: flush barrier は marker と本文を前後の空白を除いて比べ、hook 失敗の理由を端末内に残す
+
+日付: 2026-10-04
+
+## Context
+
+ADR 0012 の flush barrier は、Stop payload の `last_assistant_message` と transcript の本文が
+完全に一致するまで最大2秒待ち、一致しなければ `HOOK_PROCESS_TURN_FAILED` で明示失敗する。
+
+Claude Code は `last_assistant_message` を、最後の assistant message の text block を改行でつないで
+`.trim()` した値として渡す（Claude Code の実装で確認）。transcript には trim する前の本文が残る。
+本文が空白や改行で始まる（終わる）turn は、transcript が出そろっていても一致しない。
+
+Mac の runtime error store には `HOOK_PROCESS_TURN_FAILED` が 679 回あり、最後は
+2026-08-31T13:16:06.049Z だった。その turn の transcript は次の並びだった。
+
+```text
+13:16:02.150  assistant の最終行（end_turn）。本文は半角空白で始まる
+13:16:04.195  stop_hook_summary（同期 hook の終わり。Stop hook の開始は 13:16:03.9 ごろ）
+13:16:06.049  HOOK_PROCESS_TURN_FAILED（開始から 2.1 秒後。backfill.log に行は無い）
+```
+
+この transcript をその時点で切り、trim した marker で Stop を再生すると、0.10.3・0.12.1・0.12.4 の
+どれも 2.1 秒後に `Claude Stop transcript completion was not visible before deadline` で失敗した。
+Mac に残る 2026-08-02 以降の transcript では、本文が空白で始まる Stop が8月に 96 回あり、
+96 回とも backfill.log に対応する行が無かった。9月以降は、空白で始まる本文が1回も無い。
+
+原因を調べる時、失敗の理由はどこにも残っていなかった。runtime error store は外へ送れる形
+（定型 code と回数）だけを持つ（ADR 0025）。Claude の Stop hook は `async: true` なので、
+stderr は transcript の `stop_hook_summary` にも残らない。Mac の Codex hook 1151 回と
+SessionStart 38 回、main-server の 2026-07-20 の Stop 4 回は、発生時刻と回数しか分からなかった。
+
+## Decision
+
+1. flush barrier は、marker と transcript の本文を、どちらも前後の空白を除いてから比べる。
+   latest group と、ADR 0026 の1つ前の group の両方に同じ比べ方を使う。
+2. 途中の空白は比べる対象に残す。前後の空白以外が違う本文は一致させない。
+3. 空白だけの marker は、marker が無い時（ADR 0012 Decision 5）と同じに扱う。
+4. 本文の正本は transcript のまま。DB と完了受領には trim しない本文を書く（ADR 0012 Decision 2）。
+5. hook が失敗した時、理由を `~/.throughline/logs/hook-failures.log` へ1行の JSON で追記する。
+   項目は `ts`・`code`・`version`・`name`・`message`（1000 字まで）。
+6. このログは端末内にだけ置く。runtime error の収集・送信の設定とは独立に書き、外へは送らない。
+   runtime error store と report の形（ADR 0025）は変えない。
+7. ログの書き込みに失敗した時は stderr へ理由を出す。hook の終了コードは元の失敗のまま変えない。
+
+## Consequences
+
+- 本文が空白や改行で始まる（終わる）turn の L2・完了受領・L3 が、同じ Stop で書かれる。
+- 「過去の同文 answer を今回の完了と取り違えない」条件（ADR 0012 Decision 3、ADR 0026）は変わらない。
+  前後の空白だけが違う2つの本文は同文として扱うが、どちらの条件も group の位置と捕捉済みかで決まる。
+- 次に hook が失敗した時、時刻・code・版・理由が端末に残る。`runtime-errors snapshot` の回数と
+  突き合わせて原因を追える。
+- `message` には例外の文面が入る。path を含むことがあるので、ログを端末の外へ出す時は読んで確かめる。
+- ログの大きさに上限は設けていない。失敗した時だけ1行増える。
+
+## 確認できていないこと
+
+- Mac の 679 回のうち、空白が原因と確かめたのは transcript が残る 96 回と最後の1回。Stop 直後に次の入力が
+  届いた回（ADR 0026、0.12.2 で修理）と、それ以外の回の内訳は、当時の理由が残っていないので分からない。
+- Claude Code が1つの assistant message に text block を複数持たせた時、marker は block を改行でつなぎ、
+  Throughline は block をそのままつなぐ。transcript では1行に1 block で書かれていて、複数 block の行は
+  確認していない。

package/package.json

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

package/src/cli/codex-hook.mjs

@@ -1,4 +1,5 @@
 import { recordRuntimeErrorBestEffort } from '../runtime-error-store.mjs';
+import { logHookFailure } from '../hook-failure-log.mjs';
 
 function parseArgs(argv) {
   const out = {
@@ -368,6 +369,7 @@ export async function run(argv = []) {
     payload = parsePayload(await readStdin());
   } catch (err) {
     recordRuntimeErrorBestEffort('HOOK_CODEX_FAILED', { env: process.env });
+    logHookFailure('HOOK_CODEX_FAILED', err);
     const msg = err instanceof Error ? err.message : 'unknown';
     process.stderr.write(`[codex-hook] ${msg}\n`);
     process.exit(1);
@@ -381,6 +383,7 @@ export async function run(argv = []) {
         result = await requestCodexAutoHandoff({ payload });
       } catch (error) {
         recordRuntimeErrorBestEffort('HOOK_CODEX_FAILED', { env: process.env });
+        logHookFailure('HOOK_CODEX_FAILED', error);
         const code = typeof error.code === 'string' ? error.code : 'handoff_request_failed';
         result = { status: 'failed', continue: false,
           stopReason: `Throughline自動継続が失敗しました: ${code}。記憶の圧縮を停止します。` };
@@ -415,6 +418,7 @@ export async function run(argv = []) {
     process.exit(result.continue === false || result.status === 'ok' || result.status === 'skipped' ? 0 : 1);
   } catch (err) {
     recordRuntimeErrorBestEffort('HOOK_CODEX_FAILED', { env: process.env });
+    logHookFailure('HOOK_CODEX_FAILED', err);
     const msg = err instanceof Error ? err.message : 'unknown';
     if (parsed.json) {
       process.stdout.write(

package/src/hook-entrypoints.test.mjs

@@ -918,6 +918,74 @@ test('process-turn subprocess captures the completed turn when the next user ent
   }
 });
 
+test('process-turn subprocess captures a turn whose transcript text starts with whitespace', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const transcriptPath = join(project, 'transcript.jsonl');
+  const text = (role, value) => ({ type: role, message: { role, content: [{ type: 'text', text: value }] } });
+  try {
+    // Claude Codeは `last_assistant_message` を `.trim()` して渡す。transcriptの本文はそのまま保存する。
+    writeFileSync(transcriptPath, [
+      text('user', 'request'),
+      text('assistant', ' answer that starts with a space'),
+    ].map((entry) => JSON.stringify(entry)).join('\n'), 'utf8');
+    const result = runNode([join(REPO_ROOT, 'bin/throughline.mjs'), 'process-turn'], {
+      home,
+      cwd: project,
+      input: JSON.stringify({
+        session_id: 'leading-space-session',
+        cwd: project,
+        transcript_path: transcriptPath,
+        last_assistant_message: 'answer that starts with a space',
+      }),
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const db = openDb(home);
+    assert.deepEqual(
+      db.prepare('SELECT role, text FROM bodies ORDER BY turn_number, role').all().map((row) => ({ ...row })),
+      [{ role: 'assistant', text: ' answer that starts with a space' }, { role: 'user', text: 'request' }],
+    );
+    db.close();
+    assert.equal(readCompletedTurnReceiptSnapshot({ projectPath: project, env: childEnv(home) }).receipts.length, 1);
+    assert.equal(existsSync(join(home, '.throughline', 'logs', 'hook-failures.log')), false);
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a failed hook leaves its reason in the local hook failure log', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const failures = () => readFileSync(join(home, '.throughline', 'logs', 'hook-failures.log'), 'utf8')
+    .trim().split('\n').map((line) => JSON.parse(line));
+  try {
+    // 公開CLI経由（hookが実際に呼ぶ入口）と、moduleの直接起動の両方で残す。
+    const viaCli = runNode([join(REPO_ROOT, 'bin/throughline.mjs'), 'process-turn'], {
+      home, cwd: project, input: JSON.stringify({ cwd: project }),
+    });
+    assert.notEqual(viaCli.status, 0);
+    const direct = runNode([join(REPO_ROOT, 'src/session-start.mjs')], {
+      home, cwd: project, input: JSON.stringify({ cwd: project }),
+    });
+    assert.notEqual(direct.status, 0);
+
+    const entries = failures();
+    assert.deepEqual(entries.map((entry) => [entry.code, entry.name, entry.message]), [
+      ['HOOK_PROCESS_TURN_FAILED', 'Error', 'Missing session_id in Stop payload'],
+      ['HOOK_SESSION_START_FAILED', 'Error', 'Missing session_id in SessionStart payload'],
+    ]);
+    for (const entry of entries) {
+      assert.deepEqual(Object.keys(entry), ['ts', 'code', 'version', 'name', 'message']);
+      assert.match(entry.ts, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+      assert.match(entry.version, /^\d+\.\d+\.\d+$/);
+    }
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
 test('first prompt backfills a derived predecessor transcript without a state file', {
   skip: process.platform === 'win32' ? 'Windowsはstate file transcriptPath fallback契約' : undefined,
 }, () => {
@@ -1278,3 +1346,67 @@ test('Phase 0-5: /tl and /clear prompts do NOT trigger spike', () => {
     rmSync(home, { recursive: true, force: true });
   }
 });
+
+
+test('Cursor hooks accept the UTF-8 BOM emitted by Windows and capture the turn', () => {
+  const home = makeTempHome();
+  const project = makeTempProject();
+  const id = '23c59dba-f4b5-4ce7-a2de-27a2fbbb4193';
+  const transcript = join(project, 'cursor.jsonl');
+  writeFileSync(transcript, [
+    { role: 'user', message: { content: [{ type: 'text', text: 'BOM hook capture' }] } },
+    { role: 'assistant', message: { content: [{ type: 'text', text: 'Captured' }] } },
+  ].map((entry) => JSON.stringify(entry)).join('\n') + '\n');
+  try {
+    for (const [event, command] of [
+      ['sessionStart', 'session-start'],
+      ['beforeSubmitPrompt', 'prompt-submit'],
+      ['stop', 'process-turn'],
+    ]) {
+      const result = runNode([join(REPO_ROOT, 'bin/throughline.mjs'), command], {
+        home,
+        cwd: project,
+        input: '\uFEFF' + JSON.stringify({
+          conversation_id: id,
+          session_id: id,
+          hook_event_name: event,
+          cursor_version: '2026.10.01-e373342',
+          workspace_roots: [project],
+          transcript_path: transcript,
+          prompt: '/tl',
+        }),
+      });
+      assert.equal(result.status, 0, `${event}: ${result.stderr}`);
+    }
+    const db = openDb(home);
+    try {
+      assert.equal(db.prepare('SELECT session_id FROM sessions').get().session_id, `cursor:${id}`);
+      assert.equal(db.prepare('SELECT session_id FROM handoff_batons').get().session_id, `cursor:${id}`);
+      const bodies = db.prepare('SELECT role, text FROM bodies ORDER BY role').all();
+      assert.deepEqual(bodies.map((row) => [row.role, row.text]), [
+        ['assistant', 'Captured'], ['user', 'BOM hook capture'],
+      ]);
+    } finally {
+      db.close();
+    }
+  } finally {
+    rmSync(project, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a leading BOM does not hide malformed hook JSON', () => {
+  const home = makeTempHome();
+  try {
+    for (const command of ['session-start', 'prompt-submit', 'process-turn']) {
+      const result = runNode([join(REPO_ROOT, 'bin/throughline.mjs'), command], {
+        home, input: '\uFEFF{"conversation_id":',
+      });
+      assert.notEqual(result.status, 0, command);
+      assert.match(result.stderr, /SyntaxError/, command);
+    }
+    assert.equal(existsSync(join(home, '.throughline', 'throughline.db')), false);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/hook-failure-log.mjs

@@ -0,0 +1,47 @@
+/**
+ * hook-failure-log.mjs — hook 失敗の理由ログ (~/.throughline/logs/hook-failures.log)
+ *
+ * runtime error store は外へ送れる形（定型 code と回数）だけを持つ (ADR 0025)。失敗した時の
+ * 例外の文面はどこにも残らず、後から原因を追えなかった（2026-10-04、Mac と main-server の
+ * 7〜8月の失敗）。このログは理由を端末内にだけ残す。runtime error の収集・送信の設定とは
+ * 独立で、外へは送らない。
+ * 書き込み失敗は stderr に出す（黙って握りつぶさない）。
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const PACKAGE_VERSION = require('../package.json').version;
+
+export const HOOK_FAILURE_MESSAGE_LIMIT = 1000;
+
+export function hookFailureLogPath({ home = homedir() } = {}) {
+  return join(home, '.throughline', 'logs', 'hook-failures.log');
+}
+
+/**
+ * @param {string} code runtime error の定型 code（例: HOOK_PROCESS_TURN_FAILED）
+ * @param {unknown} error 失敗の原因
+ * @param {{ home?: string, now?: number, stderr?: { write: (s: string) => unknown } }} [options]
+ */
+export function logHookFailure(code, error, { home, now = Date.now(), stderr = process.stderr } = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  const entry = {
+    ts: new Date(now).toISOString(),
+    code,
+    version: PACKAGE_VERSION,
+    name: error instanceof Error ? error.name : typeof error,
+    message: message.slice(0, HOOK_FAILURE_MESSAGE_LIMIT),
+  };
+  const path = hookFailureLogPath(home === undefined ? {} : { home });
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'unknown';
+    stderr.write(`[hook-failure-log] ${msg}\n`);
+  }
+}

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

@@ -0,0 +1,49 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { HOOK_FAILURE_MESSAGE_LIMIT, hookFailureLogPath, logHookFailure } from './hook-failure-log.mjs';
+
+test('logHookFailureは、失敗の理由を1行のJSONで追記する', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-hook-failure-log-'));
+  try {
+    logHookFailure('HOOK_PROCESS_TURN_FAILED', new TypeError('first reason'), { home, now: Date.UTC(2026, 9, 4, 0, 0, 0, 5) });
+    logHookFailure('HOOK_CODEX_FAILED', 'thrown string', { home, now: Date.UTC(2026, 9, 4, 0, 0, 1) });
+    const lines = readFileSync(hookFailureLogPath({ home }), 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+    assert.equal(lines.length, 2);
+    assert.deepEqual({ ...lines[0], version: 'x' }, {
+      ts: '2026-10-04T00:00:00.005Z', code: 'HOOK_PROCESS_TURN_FAILED', version: 'x', name: 'TypeError', message: 'first reason',
+    });
+    assert.deepEqual({ ...lines[1], version: 'x' }, {
+      ts: '2026-10-04T00:00:01.000Z', code: 'HOOK_CODEX_FAILED', version: 'x', name: 'string', message: 'thrown string',
+    });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('logHookFailureは、長い文面を上限で切る', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-hook-failure-log-'));
+  try {
+    logHookFailure('HOOK_PROMPT_SUBMIT_FAILED', new Error('x'.repeat(HOOK_FAILURE_MESSAGE_LIMIT + 50)), { home });
+    const [entry] = readFileSync(hookFailureLogPath({ home }), 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+    assert.equal(entry.message.length, HOOK_FAILURE_MESSAGE_LIMIT);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('logHookFailureは、書けない時にstderrへ理由を出し、例外を投げない', () => {
+  const home = mkdtempSync(join(tmpdir(), 'tl-hook-failure-log-'));
+  try {
+    // `.throughline` をfileにして、logs directoryを作れなくする。
+    writeFileSync(join(home, '.throughline'), 'not a directory', 'utf8');
+    const written = [];
+    logHookFailure('HOOK_SESSION_START_FAILED', new Error('reason'), { home, stderr: { write: (s) => written.push(s) } });
+    assert.equal(written.length, 1);
+    assert.match(written[0], /^\[hook-failure-log\] /);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/hosts/cursor.mjs

@@ -55,8 +55,8 @@ export function isCursorEnvelope(payload) {
 
 export function encodeCursorProjectDir(projectPath) {
   if (typeof projectPath !== 'string' || projectPath.length === 0) return null;
-  const posix = projectPath.replace(/\\/g, '/').replace(/^\/+/, '');
-  const encoded = posix.replace(/:/g, '').replace(/\//g, '-');
+  // Cursor's utils/workspace-paths normalizes every non-ASCII-alphanumeric run.
+  const encoded = projectPath.replace(/[^a-zA-Z0-9]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
   return encoded.length > 0 ? encoded : null;
 }
 

package/src/hosts/cursor.test.mjs

@@ -7,8 +7,24 @@ import {
   encodeCursorProjectDir,
   isCursorEnvelope,
   normalizeHookPayload,
+  parseHookPayload,
 } from './index.mjs';
 
+test('parseHookPayload accepts one leading BOM and preserves BOM inside prompt text', () => {
+  const raw = JSON.stringify({
+    conversation_id: 'cursor-bom',
+    hook_event_name: 'beforeSubmitPrompt',
+    workspace_roots: ['/project'],
+    prompt: 'keep \uFEFF in text',
+  });
+  const expected = parseHookPayload(raw);
+  assert.deepEqual(parseHookPayload('\uFEFF' + raw), expected);
+  assert.equal(expected.session_id, 'cursor:cursor-bom');
+  assert.equal(expected.prompt, 'keep \uFEFF in text');
+  assert.throws(() => parseHookPayload('\uFEFF\uFEFF' + raw), SyntaxError);
+  assert.throws(() => parseHookPayload('\uFEFF{"conversation_id":'), SyntaxError);
+});
+
 test('isCursorEnvelope detects Cursor events and cursor_version', () => {
   assert.equal(
     isCursorEnvelope({
@@ -99,6 +115,11 @@ test('encodeCursorProjectDir matches ~/.cursor/projects slug', () => {
   );
   assert.equal(
     encodeCursorProjectDir(String.raw`C:\Users\kite_\Developer\dotagents`),
-    'C-Users-kite_-Developer-dotagents',
+    'C-Users-kite-Developer-dotagents',
+  );
+  assert.equal(
+    encodeCursorProjectDir(String.raw`C:\Users\kite_\.cache\aiterm-branch-test\steer-test`),
+    'C-Users-kite-cache-aiterm-branch-test-steer-test',
   );
+  assert.equal(encodeCursorProjectDir('/work/part_with.dot space/'), 'work-part-with-dot-space');
 });

package/src/hosts/index.mjs

@@ -2,7 +2,7 @@
  * hosts/index.mjs — host 境界の入口
  *
  * 共有 hook 入口 (session-start / prompt-submit / turn-processor) はここから
- * `normalizeHookPayload` と `hostAdapterForSessionId` だけを使い、
+ * `parseHookPayload` と `hostAdapterForSessionId` だけを使い、
  * ベンダー分岐を直接書かない。
  */
 import { hostOfSessionId, CLAUDE_HOST, CODEX_HOST, GROK_HOST, CURSOR_HOST } from './identity.mjs';
@@ -27,6 +27,11 @@ const ADAPTERS = Object.freeze({
   [CURSOR_HOST]: cursorHostAdapter,
 });
 
+/** Parse hook stdin, including the leading UTF-8 BOM emitted by Windows Cursor. */
+export function parseHookPayload(raw, options = {}) {
+  return normalizeHookPayload(JSON.parse(raw.replace(/^\uFEFF/, '')), options);
+}
+
 /**
  * hook stdin payload を Claude snake_case 契約へ正規化する。
  * Grok は camelCase wire、Cursor は hook_event_name が sessionStart 等。

package/src/prompt-submit.mjs

@@ -40,7 +40,8 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
-import { hostAdapterForSessionId, normalizeHookPayload } from './hosts/index.mjs';
+import { logHookFailure } from './hook-failure-log.mjs';
+import { hostAdapterForSessionId, parseHookPayload } from './hosts/index.mjs';
 
 // Phase 0-5 spike marker (SessionStart の spike-inject.flag とは別)
 const PROMPT_SPIKE_MARKER_PATH = join(homedir(), '.throughline', 'spike-prompt.flag');
@@ -152,7 +153,7 @@ export async function run() {
     process.stdin.on('end', resolve);
   });
 
-  const payload = normalizeHookPayload(JSON.parse(raw), { env: process.env });
+  const payload = parseHookPayload(raw, { env: process.env });
   const { session_id, cwd, prompt } = payload;
   const hostAdapter = hostAdapterForSessionId(session_id);
 
@@ -325,6 +326,7 @@ async function maybeRunPromptSpike({ payload, sessionId, projectPath }) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   run().catch((err) => {
     recordRuntimeErrorBestEffort('HOOK_PROMPT_SUBMIT_FAILED');
+    logHookFailure('HOOK_PROMPT_SUBMIT_FAILED', err);
     const msg = err instanceof Error ? err.message : 'unknown';
     process.stderr.write(`[prompt-submit] error: ${msg}\n`);
     process.exit(1);

package/src/session-start.mjs

@@ -32,7 +32,8 @@ import { logDecision } from './decision-log.mjs';
 import { existsSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
-import { hostAdapterForSessionId, NON_CLAUDE_SESSION_PREFIXES, normalizeHookPayload } from './hosts/index.mjs';
+import { logHookFailure } from './hook-failure-log.mjs';
+import { hostAdapterForSessionId, NON_CLAUDE_SESSION_PREFIXES, parseHookPayload } from './hosts/index.mjs';
 import { executeFirstPromptHandoff } from './handoff-executor.mjs';
 
 const ENV_DISABLE_AUTO_HANDOFF = 'THROUGHLINE_DISABLE_AUTO_HANDOFF';
@@ -101,7 +102,7 @@ export async function run() {
     process.stdin.on('end', resolve);
   });
 
-  const payload = normalizeHookPayload(JSON.parse(raw), { env: process.env });
+  const payload = parseHookPayload(raw, { env: process.env });
   const { session_id, cwd, source, transcript_path } = payload;
 
   if (!session_id) throw new Error('Missing session_id in SessionStart payload');
@@ -190,6 +191,7 @@ export async function run() {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   run().catch((err) => {
     recordRuntimeErrorBestEffort('HOOK_SESSION_START_FAILED');
+    logHookFailure('HOOK_SESSION_START_FAILED', err);
     process.stderr.write(`[session-start] error: ${err.message}\n`);
     process.exit(1);
   });

package/src/turn-processor.mjs

@@ -45,8 +45,9 @@ import { ensureMonitorTaskFile } from './vscode-task.mjs';
 import { readLatestUsage } from './transcript-usage.mjs';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.mjs';
+import { logHookFailure } from './hook-failure-log.mjs';
 import { writeCompletedTurnReceipt } from './completed-turn-receipts.mjs';
-import { hostAdapterForSessionId, normalizeHookPayload } from './hosts/index.mjs';
+import { hostAdapterForSessionId, parseHookPayload } from './hosts/index.mjs';
 
 /** 直近 N ターンは bodies を生で残し、それより古いものだけ L1 要約する。 */
 export const L2_WINDOW = 20;
@@ -65,6 +66,9 @@ const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, mil
  * - latest groupにassistant断片がまだ無い（次のturnは本文を書いていない）
  * - 1つ前のgroupの本文がmarkerと一致する
  * - そのturnがまだDBに捕捉されていない（捕捉済みの同文answerは、今回のStopの完了ではない）
+ *
+ * markerとtranscriptの本文は、前後の空白を除いて比べる（ADR 0027）。Claude Codeはmarkerを
+ * `.trim()` して渡すので、本文が空白や改行で始まる（終わる）turnは、そのままでは一致しない。
  */
 export async function waitForClaudeStopTranscriptFlush({
   transcriptPath,
@@ -77,7 +81,7 @@ export async function waitForClaudeStopTranscriptFlush({
   now = Date.now,
   wait = delay,
 }) {
-  if (typeof lastAssistantMessage !== 'string' || lastAssistantMessage.length === 0) {
+  if (typeof lastAssistantMessage !== 'string' || lastAssistantMessage.trim().length === 0) {
     return { status: 'marker_unavailable' };
   }
   const read = readCompletion
@@ -88,11 +92,14 @@ export async function waitForClaudeStopTranscriptFlush({
     userTurnNumber: completion.userTurnNumber,
     assistantTurnNumber: completion.assistantTurnNumber,
   });
+  const marker = lastAssistantMessage.trim();
+  const matchesMarker = (completion) =>
+    typeof completion?.assistantContent === 'string' && completion.assistantContent.trim() === marker;
   const deadline = now() + timeoutMs;
   for (;;) {
     const { latest, previous } = read() ?? { latest: null, previous: null };
-    if (latest?.assistantContent === lastAssistantMessage) return ready(latest);
-    if (previous?.assistantContent === lastAssistantMessage &&
+    if (matchesMarker(latest)) return ready(latest);
+    if (matchesMarker(previous) &&
       latest?.fragmentTurnNumbers?.length === 0 &&
       !isTurnCaptured(previous.fragmentTurnNumbers)) {
       return ready(previous);
@@ -219,7 +226,7 @@ export async function run() {
     process.stdin.on('end', resolve);
   });
 
-  const payload = normalizeHookPayload(JSON.parse(raw || '{}'), { env: process.env });
+  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');
 
@@ -418,6 +425,7 @@ export async function run() {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   run().catch((err) => {
     recordRuntimeErrorBestEffort('HOOK_PROCESS_TURN_FAILED');
+    logHookFailure('HOOK_PROCESS_TURN_FAILED', err);
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[turn-processor] error: ${msg}\n`);
     process.exit(1);

package/src/turn-processor.test.mjs

@@ -105,6 +105,53 @@ test('Claude Stop flush barrierはlatest userの遅延assistantを待ち、過
   }
 });
 
+test('Claude Stop flush barrierは、前後の空白を除いてmarkerと本文を比べる', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'throughline-stop-flush-trim-'));
+  const transcriptPath = join(root, 'transcript.jsonl');
+  const text = (role, value) => ({ type: role, message: { role, content: [{ type: 'text', text: value }] } });
+  let elapsed = 0;
+  const clock = { now: () => elapsed, wait: async (milliseconds) => { elapsed += milliseconds; } };
+  const write = (entries) => writeFileSync(
+    transcriptPath, entries.map((entry) => JSON.stringify(entry)).join('\n'), 'utf8');
+  try {
+    // 実測（2026-08-31、Mac）: 本文が空白で始まるturn。Claude Codeはmarkerを `.trim()` して渡す。
+    write([text('user', 'request'), text('assistant', ' answer with a leading space')]);
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'answer with a leading space', timeoutMs: 100, intervalMs: 10, ...clock,
+    }), { status: 'ready', userTurnNumber: 0, assistantTurnNumber: 1 });
+    assert.equal(elapsed, 0, 'a whitespace-only difference must not wait for the deadline');
+
+    write([text('user', 'request'), text('assistant', '\n\nanswer with newlines\n')]);
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'answer with newlines', timeoutMs: 100, intervalMs: 10, ...clock,
+    }), { status: 'ready', userTurnNumber: 0, assistantTurnNumber: 1 });
+
+    // 1つ前のgroupを採用する経路（ADR 0026）も同じ比べ方をする。
+    write([text('user', 'request'), text('assistant', ' answer'), text('user', 'queued request')]);
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'answer', timeoutMs: 100, intervalMs: 10,
+      isTurnCaptured: () => false, ...clock,
+    }), { status: 'ready', userTurnNumber: 0, assistantTurnNumber: 1 });
+    assert.equal(elapsed, 0);
+
+    // 空白以外が違う本文は一致させない。
+    write([text('user', 'request'), text('assistant', ' answer')]);
+    await assert.rejects(waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'another answer', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), /not visible before deadline/);
+    await assert.rejects(waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: 'ans wer', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), /not visible before deadline/);
+
+    // 空白だけのmarkerは、無いものとして扱う。
+    assert.deepEqual(await waitForClaudeStopTranscriptFlush({
+      transcriptPath, lastAssistantMessage: ' \n', timeoutMs: 30, intervalMs: 10, ...clock,
+    }), { status: 'marker_unavailable' });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('Claude Stop flush barrierは、Stop直後に次のuser行が届いても、未捕捉の完了turnを待たずに採用する', async () => {
   const root = mkdtempSync(join(tmpdir(), 'throughline-stop-flush-next-user-'));
   const transcriptPath = join(root, 'transcript.jsonl');