throughline 0.12.3 → 0.12.4

package/CHANGELOG.md

@@ -10,6 +10,13 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [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 +1577,8 @@ 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.4...HEAD
+[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/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/package.json

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

package/src/hook-entrypoints.test.mjs

@@ -1278,3 +1278,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/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,7 @@ 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 { 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 +152,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);
 

package/src/session-start.mjs

@@ -32,7 +32,7 @@ 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 { 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 +101,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');

package/src/turn-processor.mjs

@@ -46,7 +46,7 @@ import { readLatestUsage } from './transcript-usage.mjs';
 import { pathToFileURL } from 'node:url';
 import { recordRuntimeErrorBestEffort } from './runtime-error-store.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;
@@ -219,7 +219,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');