throughline 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -10,6 +10,22 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.10.3] — 2026-08-24
+
+### Added
+
+- Cursor を first-class hook host にする（工場 Cursor harness campaign Wave 6）。
+  - envelope は `hook_event_name=sessionStart|beforeSubmitPrompt|stop` と
+    `conversation_id` / `cursor_version`。session id は `cursor:<uuid>`。
+  - L2 は payload の `transcript_path`、無ければ
+    `~/.cursor/projects/<slug>/agent-transcripts/<id>/<id>.jsonl`。
+  - `throughline install` は `~/.cursor/hooks.json` へ絶対 `node` +
+    `bin/throughline.mjs` の sessionStart / beforeSubmitPrompt / stop を upsert
+    する。工場 hook（`cursor-*-hook`）は残す。bare `throughline` は書かない。
+  - beforeSubmitPrompt は continue のみなので、引き継ぎ注入は sessionStart の
+    `additional_context`。`/tl` 後継の自動起動はしない。
+  - Claude / Codex / Grok 契約は変えない。
+
 ## [0.10.2] — 2026-08-24
 
 ### Changed
@@ -1304,7 +1320,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.10.1...HEAD
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.10.3...HEAD
+[0.10.3]: https://github.com/kitepon-rgb/Throughline/compare/v0.10.2...v0.10.3
+[0.10.2]: https://github.com/kitepon-rgb/Throughline/compare/v0.10.1...v0.10.2
 [0.10.1]: https://github.com/kitepon-rgb/Throughline/compare/v0.10.0...v0.10.1
 [0.10.0]: https://github.com/kitepon-rgb/Throughline/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/kitepon-rgb/Throughline/compare/v0.9.0...v0.9.1

package/README.ja.md

@@ -39,8 +39,14 @@ throughline install     # hook / Codex skill / VS Code monitor task を登録
 `/clear` を経由しない新規 chat / VS Code 再起動では `/tl` で前任を指名できる。
 
 Grok Desktop も first-class host である。`throughline install` は
-`~/.grok/hooks/throughline.json` を書く。Grok の `/tl` は今の窓へ注入せず、
-Terminal に新席を立てる（詳細は下）。
+`~/.grok/hooks/throughline.json` を書く。Grok では `/tl` は今の窓へ注入せず、
+新しい Terminal 席を立てる。
+
+Cursor も first-class host である。`throughline install` は `~/.cursor/hooks.json`
+へ sessionStart / beforeSubmitPrompt / stop を upsert し、工場 hook は残す。
+capture は Cursor の `agent-transcripts` jsonl。注入は sessionStart の
+`additional_context`。`/tl` 後継の自動起動はしない。
+[ADR 0022](docs/adr/0022-cursor-host-capture.md) を正とする。
 
 <details>
 <summary><b>Grok も併用する場合</b> Grok hooks も登録される — クリックで詳細</summary>

package/README.md

@@ -43,6 +43,13 @@ Grok Desktop is also a first-class host. `throughline install` writes
 `~/.grok/hooks/throughline.json`. On Grok, `/tl` does not inject into the
 current window — it starts a new Terminal seat. See below.
 
+Cursor is also a first-class host. `throughline install` upserts
+`sessionStart` / `beforeSubmitPrompt` / `stop` into `~/.cursor/hooks.json` and
+leaves factory hooks in place. Capture reads Cursor `agent-transcripts` jsonl.
+Handoff injection uses `sessionStart` `additional_context`. `/tl` does not
+auto-launch a successor Cursor chat — the next new conversation drinks the
+baton. See [ADR 0022](docs/adr/0022-cursor-host-capture.md).
+
 <details>
 <summary><b>Also using Codex?</b> Global install registers Codex hooks too — click for details.</summary>
 

package/docs/00_overview.md

@@ -40,6 +40,7 @@
 - [ADR 0003](adr/0003-observer-completed-chain-cursor.md): Observer cursorをhost固有のcompleted pair chainとprefix検証へ束縛する。
 - [ADR 0020](adr/0020-windows-ci-release-latency.md): Windows ACL契約を維持し、境界fixtureと実ACL検証を分離する。
 - [ADR 0021](adr/0021-grok-host-capture.md): Grok を first-class hook host にし、`/tl` 後の記憶再開は `grok-continue` に固定する。
+- [ADR 0022](adr/0022-cursor-host-capture.md): Cursor を first-class hook host にし、注入は sessionStart の `additional_context`、hook は `~/.cursor/hooks.json` への upsert。
 
 Observerの公開境界は`throughline observer-read`／`throughline observer-wait`のJSON-only CLIである。
 ThroughlineはClaude Stop receiptとCodex rolloutの`task_complete`だけからcompleted cursorを構築し、

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

@@ -0,0 +1,39 @@
+# ADR 0022: Treat Cursor as a first-class Throughline host
+
+Date: 2026-08-24
+
+## Status
+
+Accepted
+
+## Context
+
+dotagents Wave 5 made Cursor a peer factory harness. Throughline still had only Claude / Codex / Grok adapters. Cursor parent sessions were not captured.
+
+Cursor hook envelope is not Claude PascalCase and not Grok camelCase. Official events are `sessionStart`, `beforeSubmitPrompt` (Claude `UserPromptSubmit` 相当), and `stop`. Common fields include `conversation_id`, `workspace_roots`, `cursor_version`, and optional `transcript_path`.
+
+L2 lives in `~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl` with role-first rows (`{role, message.content}`), not Claude `{type, message}`.
+
+`beforeSubmitPrompt` stdout is `{continue}` only. `sessionStart` may return `additional_context`. Cursor has a single `~/.cursor/hooks.json`; factory hooks already occupy that file.
+
+## Decision
+
+- Detect Cursor envelope (`cursor_version` or `hook_event_name` in the Cursor event set) as host=cursor.
+- 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`.
+- Cursor `sessionStart` of a new composer conversation is the handoff injection mouth (`additional_context`). Consume pending there. Skip `is_background_agent`. Claude ghost-SessionStart rules stay on Claude.
+- `/tl` writes a baton. Do not auto-launch a successor Cursor chat. The next new conversation's `sessionStart` drinks the baton.
+- Keep Claude, Codex, and Grok adapters unchanged. Do not mix `cursor:` rows into Claude predecessor search.
+
+## Consequences
+
+- Cursor capture / restore / `handoff-context` reuse the existing DB after hook fire exists.
+- Live injection in the same conversation after `/tl` is not a Cursor contract (no additional_context on `beforeSubmitPrompt`).
+- Factory apply-cursor-config must keep Throughline commands, matching the existing personal-hook upsert.
+
+## 現在地
+
+公式 Cursor hooks 文書（2026-08-24）とこのMacの
+`~/.cursor/projects/Users-kite-Developer-dotagents/agent-transcripts/<uuid>/<uuid>.jsonl`
+を実測した。公開後の新規 Cursor session 受入は別 H。

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "throughline",
-  "version": "0.10.2",
-  "type": "module",
-  "description": "Persistent memory hooks for Claude Code, Codex, and Grok (/clear-safe context compression)",
-  "keywords": [
-    "claude-code",
-    "codex",
-    "grok",
+    "version": "0.10.3",
+    "type": "module",
+    "description": "Persistent memory hooks for Claude Code, Codex, Grok, and Cursor (/clear-safe context compression)",
+    "keywords": [
+      "claude-code",
+      "codex",
+      "grok",
+      "cursor",
     "hooks",
     "context-compression",
     "llm"
@@ -40,7 +41,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --import ./src/test-env.mjs --test scripts/verify-release-commit.test.mjs src/*.test.mjs src/cli/*.test.mjs",
+    "test": "node --import ./src/test-env.mjs --test scripts/verify-release-commit.test.mjs src/*.test.mjs src/cli/*.test.mjs src/hosts/*.test.mjs",
     "verify:release-commit": "node scripts/verify-release-commit.mjs",
     "prepublishOnly": "npm run verify:release-commit && npm test"
   },

package/src/cli/install.mjs

@@ -11,6 +11,7 @@
  * script path で登録する。
  * Grok-facing hook も Desktop の GUI PATH に throughline が無いため、同じ絶対
  * node + CLI script path で ~/.grok/hooks/throughline.json に書く。
+ * Cursor-facing hook は ~/.cursor/hooks.json へ upsert する（工場 hook は残す）。
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
@@ -27,6 +28,7 @@ const CODEX_SKILL_NAMES = ['throughline'];
 const CODEX_HOOKS_RELATIVE_PATH = ['.codex', 'hooks.json'];
 const CODEX_CONFIG_RELATIVE_PATH = ['.codex', 'config.toml'];
 const GROK_HOOKS_RELATIVE_PATH = ['.grok', 'hooks', 'throughline.json'];
+const CURSOR_HOOKS_RELATIVE_PATH = ['.cursor', 'hooks.json'];
 
 // Throughline が管理する hook コマンド一覧
 // schema v4 以降: PostToolUse (capture-tool) は廃止。Stop 内で L2/L3 を一括処理する。
@@ -297,6 +299,16 @@ export function buildGrokHookCommand(subcommand, {
   return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} ${subcommand}`;
 }
 
+export function buildCursorHookCommand(subcommand, options = {}) {
+  return buildGrokHookCommand(subcommand, options);
+}
+
+export function isThroughlineCursorHookCommand(command) {
+  return typeof command === 'string'
+    && command.includes('throughline.mjs')
+    && /\b(session-start|prompt-submit|process-turn)\b/.test(command);
+}
+
 export function createGrokHooksFile(options = {}) {
   return {
     hooks: {
@@ -334,6 +346,74 @@ function uninstallGrokHooks() {
   return { hooksPath, removed: 1 };
 }
 
+function resolveCursorHooksPath() {
+  return join(homedir(), ...CURSOR_HOOKS_RELATIVE_PATH);
+}
+
+export function createCursorHookEntries(options = {}) {
+  return {
+    sessionStart: [
+      { command: buildCursorHookCommand('session-start', options), timeout: 10 },
+    ],
+    beforeSubmitPrompt: [
+      { command: buildCursorHookCommand('prompt-submit', options), timeout: 30 },
+    ],
+    stop: [
+      { command: buildCursorHookCommand('process-turn', options), timeout: 300 },
+    ],
+  };
+}
+
+function readCursorHooksFile(hooksPath) {
+  if (!existsSync(hooksPath)) return { version: 1, hooks: {} };
+  const parsed = JSON.parse(readFileSync(hooksPath, 'utf8'));
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${hooksPath} は object である必要があります`);
+  }
+  if (parsed.hooks == null) parsed.hooks = {};
+  if (typeof parsed.hooks !== 'object' || Array.isArray(parsed.hooks)) {
+    throw new Error(`${hooksPath} の hooks は object である必要があります`);
+  }
+  return parsed;
+}
+
+function installCursorHooks() {
+  const hooksPath = resolveCursorHooksPath();
+  mkdirSync(dirname(hooksPath), { recursive: true });
+  const current = readCursorHooksFile(hooksPath);
+  current.version = 1;
+  const wanted = createCursorHookEntries();
+  for (const [event, entries] of Object.entries(wanted)) {
+    const existing = Array.isArray(current.hooks[event]) ? current.hooks[event] : [];
+    const kept = existing.filter((entry) => !isThroughlineCursorHookCommand(entry?.command));
+    current.hooks[event] = [...kept, ...entries];
+  }
+  writeFileSync(hooksPath, `${JSON.stringify(current, null, 2)}\n`);
+  return { hooksPath };
+}
+
+function uninstallCursorHooks() {
+  const hooksPath = resolveCursorHooksPath();
+  if (!existsSync(hooksPath)) return { hooksPath, removed: 0 };
+  const current = readCursorHooksFile(hooksPath);
+  let removed = 0;
+  for (const [event, list] of Object.entries(current.hooks ?? {})) {
+    if (!Array.isArray(list)) continue;
+    const kept = list.filter((entry) => {
+      if (isThroughlineCursorHookCommand(entry?.command)) {
+        removed += 1;
+        return false;
+      }
+      return true;
+    });
+    if (kept.length > 0) current.hooks[event] = kept;
+    else delete current.hooks[event];
+  }
+  if (removed === 0) return { hooksPath, removed: 0 };
+  writeFileSync(hooksPath, `${JSON.stringify(current, null, 2)}\n`);
+  return { hooksPath, removed };
+}
+
 function installSlashCommands(commandsDir) {
   if (!existsSync(SLASH_COMMANDS_SRC)) {
     return { installed: [], skipped: 'source-missing' };
@@ -589,6 +669,7 @@ export async function run(args = []) {
     const removedCommands = uninstallSlashCommands(commandsDir);
     const codex = args.includes('--project') ? null : uninstallCodexHooks();
     const grok = args.includes('--project') ? null : uninstallGrokHooks();
+    const cursor = args.includes('--project') ? null : uninstallCursorHooks();
     const removedCodexSkills = args.includes('--project') ? [] : uninstallCodexSkills(codexSkillsDir);
     console.log('Throughline hooks を削除しました。');
     console.log(`  ${settingsPath}`);
@@ -601,6 +682,9 @@ export async function run(args = []) {
     if (grok?.removed > 0) {
       console.log(`  Grok hooks 削除: ${grok.removed} (${grok.hooksPath})`);
     }
+    if (cursor?.removed > 0) {
+      console.log(`  Cursor hooks 削除: ${cursor.removed} (${cursor.hooksPath})`);
+    }
     if (removedCodexSkills.length > 0) {
       console.log(`  Codex skills 削除: ${removedCodexSkills.join(', ')} (${codexSkillsDir})`);
     }
@@ -624,6 +708,7 @@ export async function run(args = []) {
   const { installed: installedCommands, skipped } = installSlashCommands(commandsDir);
   const codex = args.includes('--project') ? null : installCodexHooks();
   const grok = args.includes('--project') ? null : installGrokHooks();
+  const cursor = args.includes('--project') ? null : installCursorHooks();
   const codexSkills = args.includes('--project') ? { installed: [], skipped: null } : installCodexSkills(codexSkillsDir);
   const monitorTask = ensureMonitorTaskFile({
     cwd: process.cwd(),
@@ -643,6 +728,9 @@ export async function run(args = []) {
   if (grok) {
     console.log(`  ${grok.hooksPath}`);
   }
+  if (cursor) {
+    console.log(`  ${cursor.hooksPath}`);
+  }
   console.log('');
   console.log('有効な hooks:');
   console.log('  SessionStart     → throughline session-start  (セッション記録・バトン消費・引き継ぎ注入)');
@@ -656,6 +744,9 @@ export async function run(args = []) {
   if (grok) {
     console.log('  Grok SessionStart / UserPromptSubmit / Stop → ~/.grok/hooks/throughline.json');
   }
+  if (cursor) {
+    console.log('  Cursor sessionStart / beforeSubmitPrompt / stop → ~/.cursor/hooks.json（工場hookは残す）');
+  }
   console.log('');
   if (installedCommands.length > 0) {
     console.log(`slash commands を配置しました: ${installedCommands.map(n => '/' + n.replace(/\.md$/, '')).join(', ')}`);

package/src/cli/install.test.mjs

@@ -10,8 +10,10 @@ import {
   buildCodexUserPromptSubmitHookCommand,
   buildGrokHookCommand,
   createGrokHooksFile,
+  createCursorHookEntries,
   isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
+  isThroughlineCursorHookCommand,
   parseCodexHookCommand,
   resolveCodexHookNodePath,
   run,
@@ -92,6 +94,28 @@ test('global install copies Throughline slash commands to ~/.claude/commands/',
       assert.match(command, /throughline\.mjs/);
       assert.doesNotMatch(command, /^throughline /);
     }
+    const cursorHooks = JSON.parse(readFileSync(join(home.dir, '.cursor', 'hooks.json'), 'utf8'));
+    assert.equal(cursorHooks.version, 1);
+    assert.equal(
+      cursorHooks.hooks.sessionStart[0].command,
+      createCursorHookEntries().sessionStart[0].command,
+    );
+    assert.equal(
+      cursorHooks.hooks.beforeSubmitPrompt[0].command,
+      createCursorHookEntries().beforeSubmitPrompt[0].command,
+    );
+    assert.equal(
+      cursorHooks.hooks.stop[0].command,
+      createCursorHookEntries().stop[0].command,
+    );
+    for (const command of [
+      cursorHooks.hooks.sessionStart[0].command,
+      cursorHooks.hooks.beforeSubmitPrompt[0].command,
+      cursorHooks.hooks.stop[0].command,
+    ]) {
+      assert.equal(isThroughlineCursorHookCommand(command), true);
+      assert.doesNotMatch(command, /^throughline /);
+    }
   } finally {
     unsilence();
     home.restore();
@@ -192,6 +216,39 @@ test('Grok hook commands are absolute node + throughline.mjs on every platform',
   assert.equal(file.hooks.Stop[0].hooks[0].async, true);
 });
 
+test('Cursor install upserts product hooks and keeps factory commands', async () => {
+  const home = makeTempHome();
+  if (home.resolved !== home.dir) {
+    home.restore();
+    return;
+  }
+  const unsilence = silence();
+  try {
+    mkdirSync(join(home.dir, '.cursor'), { recursive: true });
+    writeFileSync(join(home.dir, '.cursor', 'hooks.json'), `${JSON.stringify({
+      version: 1,
+      hooks: {
+        sessionStart: [{ command: '/tmp/cursor-todo-gate-hook session-start', timeout: 10 }],
+      },
+    }, null, 2)}\n`);
+    await run([]);
+    const installed = JSON.parse(readFileSync(join(home.dir, '.cursor', 'hooks.json'), 'utf8'));
+    assert.equal(installed.hooks.sessionStart[0].command, '/tmp/cursor-todo-gate-hook session-start');
+    assert.equal(isThroughlineCursorHookCommand(installed.hooks.sessionStart[1].command), true);
+    assert.equal(isThroughlineCursorHookCommand(installed.hooks.beforeSubmitPrompt[0].command), true);
+    assert.equal(isThroughlineCursorHookCommand(installed.hooks.stop[0].command), true);
+    await run(['--uninstall']);
+    const after = JSON.parse(readFileSync(join(home.dir, '.cursor', 'hooks.json'), 'utf8'));
+    assert.equal(after.hooks.sessionStart.length, 1);
+    assert.equal(after.hooks.sessionStart[0].command, '/tmp/cursor-todo-gate-hook session-start');
+    assert.equal(after.hooks.beforeSubmitPrompt, undefined);
+    assert.equal(after.hooks.stop, undefined);
+  } finally {
+    unsilence();
+    home.restore();
+  }
+});
+
 test('Codex hook builders use the PowerShell call operator on Windows only', () => {
   const options = {
     nodePath: String.raw`C:\Program Files\nodejs\node.exe`,

package/src/hosts/claude.mjs

@@ -21,6 +21,7 @@ export const claudeHostAdapter = Object.freeze({
   resolveCommandPrompt({ prompt }) {
     return prompt;
   },
+  consumesHandoffAtSessionStart: false,
   afterBatonWrite() {
     return { launched: false };
   },

package/src/hosts/codex.mjs

@@ -22,6 +22,7 @@ export const codexHostAdapter = Object.freeze({
   resolveCommandPrompt({ prompt }) {
     return prompt;
   },
+  consumesHandoffAtSessionStart: false,
   afterBatonWrite() {
     return { launched: false };
   },

package/src/hosts/cursor.mjs

@@ -0,0 +1,128 @@
+/**
+ * hosts/cursor.mjs — Cursor host 境界 (envelope 正規化 + hook adapter)
+ *
+ * Cursor は Claude PascalCase でも Grok camelCase wire でもない。
+ * hook_event_name は sessionStart / beforeSubmitPrompt / stop などの
+ * Cursor envelope。session 識別は conversation_id（sessionStart では
+ * session_id と同じ）。L2 は ~/.cursor/projects/<slug>/agent-transcripts/<id>/<id>.jsonl。
+ *
+ * beforeSubmitPrompt の stdout は continue だけ（additional_context なし）。
+ * 引き継ぎ注入は sessionStart の additional_context が公式口。
+ * /tl 後継の自動起動はしない（次の新規 Cursor 会話の sessionStart が飲む）。
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  CURSOR_HOST,
+  CURSOR_SESSION_PREFIX,
+  cursorBareSessionId,
+  isCursorSessionId,
+} from './identity.mjs';
+
+const CURSOR_HOOK_EVENTS = new Set([
+  'sessionStart',
+  'sessionEnd',
+  'beforeSubmitPrompt',
+  'stop',
+  'preToolUse',
+  'postToolUse',
+  'postToolUseFailure',
+  'subagentStart',
+  'subagentStop',
+  'beforeShellExecution',
+  'afterShellExecution',
+  'beforeMCPExecution',
+  'afterMCPExecution',
+  'beforeReadFile',
+  'afterFileEdit',
+  'preCompact',
+  'afterAgentResponse',
+  'afterAgentThought',
+  'beforeTabFileRead',
+  'afterTabFileEdit',
+  'workspaceOpen',
+]);
+
+export function isCursorEnvelope(payload) {
+  if (payload === null || typeof payload !== 'object') return false;
+  if (typeof payload.cursor_version === 'string' && payload.cursor_version.length > 0) {
+    return true;
+  }
+  return typeof payload.hook_event_name === 'string'
+    && CURSOR_HOOK_EVENTS.has(payload.hook_event_name);
+}
+
+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, '-');
+  return encoded.length > 0 ? encoded : null;
+}
+
+export function deriveCursorTranscriptPath(projectPath, sessionId, { home = homedir() } = {}) {
+  const bare = cursorBareSessionId(sessionId);
+  const slug = encodeCursorProjectDir(projectPath);
+  if (!bare || !slug) return null;
+  return join(home, '.cursor', 'projects', slug, 'agent-transcripts', bare, `${bare}.jsonl`);
+}
+
+function cursorCwd(payload) {
+  if (typeof payload.cwd === 'string' && payload.cwd.length > 0) return payload.cwd;
+  const roots = payload.workspace_roots;
+  if (Array.isArray(roots) && typeof roots[0] === 'string' && roots[0].length > 0) {
+    return roots[0];
+  }
+  return undefined;
+}
+
+function cursorRawSessionId(payload) {
+  if (typeof payload.conversation_id === 'string' && payload.conversation_id.length > 0) {
+    return payload.conversation_id;
+  }
+  if (typeof payload.session_id === 'string' && payload.session_id.length > 0) {
+    return payload.session_id;
+  }
+  return null;
+}
+
+export function normalizeCursorHookPayload(payload, { home = homedir() } = {}) {
+  if (!isCursorEnvelope(payload)) return payload;
+  const rawId = cursorRawSessionId(payload);
+  const cwd = cursorCwd(payload);
+  const prefixed = rawId ? `${CURSOR_SESSION_PREFIX}${cursorBareSessionId(rawId)}` : undefined;
+  const givenTranscript = typeof payload.transcript_path === 'string' && payload.transcript_path.length > 0
+    ? payload.transcript_path
+    : null;
+  const transcriptPath = givenTranscript ?? deriveCursorTranscriptPath(cwd, prefixed, { home });
+  return {
+    ...payload,
+    session_id: prefixed,
+    cwd,
+    source: typeof payload.source === 'string' && payload.source.length > 0
+      ? payload.source
+      : 'startup',
+    prompt: payload.prompt,
+    hook_event_name: payload.hook_event_name,
+    transcript_path: transcriptPath,
+    last_assistant_message: payload.last_assistant_message ?? payload.text,
+    is_background_agent: payload.is_background_agent === true,
+  };
+}
+
+export const cursorHostAdapter = Object.freeze({
+  host: CURSOR_HOST,
+  matchesSessionId: isCursorSessionId,
+  waitsForStopTranscriptFlush: false,
+  consumesHandoffAtSessionStart: true,
+  deliverHandoffInjection({ text, stdout = process.stdout }) {
+    stdout.write(`${JSON.stringify({ additional_context: text })}\n`);
+    return { delivered: true };
+  },
+  resolveCommandPrompt({ prompt }) {
+    return prompt;
+  },
+  afterBatonWrite() {
+    return { launched: false };
+  },
+});

package/src/hosts/cursor.test.mjs

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+
+import {
+  deriveCursorTranscriptPath,
+  encodeCursorProjectDir,
+  isCursorEnvelope,
+  normalizeHookPayload,
+} from './index.mjs';
+
+test('isCursorEnvelope detects Cursor events and cursor_version', () => {
+  assert.equal(
+    isCursorEnvelope({
+      hook_event_name: 'sessionStart',
+      session_id: '7face712-ef58-40d7-b71e-b71091dfee5c',
+      workspace_roots: ['/Users/kite/Developer/dotagents'],
+    }),
+    true,
+  );
+  assert.equal(
+    isCursorEnvelope({
+      cursor_version: '1.7.2',
+      conversation_id: '7face712-ef58-40d7-b71e-b71091dfee5c',
+    }),
+    true,
+  );
+  assert.equal(
+    isCursorEnvelope({
+      session_id: 'claude-session',
+      hook_event_name: 'SessionStart',
+    }),
+    false,
+  );
+  assert.equal(
+    isCursorEnvelope({
+      sessionId: '01a00aa2-dead-beef',
+      hookEventName: 'session_start',
+    }),
+    false,
+  );
+});
+
+test('normalizeHookPayload prefixes cursor: and derives agent-transcripts path', () => {
+  const home = '/tmp/tl-home';
+  const cwd = '/Users/kite/Developer/dotagents';
+  const payload = normalizeHookPayload(
+    {
+      conversation_id: '7face712-ef58-40d7-b71e-b71091dfee5c',
+      hook_event_name: 'beforeSubmitPrompt',
+      workspace_roots: [cwd],
+      prompt: '/tl',
+      cursor_version: '1.7.2',
+    },
+    { home },
+  );
+  assert.equal(payload.session_id, 'cursor:7face712-ef58-40d7-b71e-b71091dfee5c');
+  assert.equal(payload.cwd, cwd);
+  assert.equal(payload.prompt, '/tl');
+  assert.equal(
+    payload.transcript_path,
+    join(
+      home,
+      '.cursor',
+      'projects',
+      'Users-kite-Developer-dotagents',
+      'agent-transcripts',
+      '7face712-ef58-40d7-b71e-b71091dfee5c',
+      '7face712-ef58-40d7-b71e-b71091dfee5c.jsonl',
+    ),
+  );
+  assert.equal(
+    deriveCursorTranscriptPath(cwd, 'cursor:7face712-ef58-40d7-b71e-b71091dfee5c', { home }),
+    payload.transcript_path,
+  );
+});
+
+test('normalizeHookPayload strips bc- prefix and keeps payload transcript_path', () => {
+  const home = '/tmp/tl-home';
+  const given = '/tmp/given.jsonl';
+  const payload = normalizeHookPayload(
+    {
+      conversation_id: 'bc-7face712-ef58-40d7-b71e-b71091dfee5c',
+      hook_event_name: 'stop',
+      cwd: '/Users/kite/Developer/dotagents',
+      transcript_path: given,
+      status: 'completed',
+    },
+    { home },
+  );
+  assert.equal(payload.session_id, 'cursor:7face712-ef58-40d7-b71e-b71091dfee5c');
+  assert.equal(payload.transcript_path, given);
+});
+
+test('encodeCursorProjectDir matches ~/.cursor/projects slug', () => {
+  assert.equal(
+    encodeCursorProjectDir('/Users/kite/Developer/dotagents'),
+    'Users-kite-Developer-dotagents',
+  );
+  assert.equal(
+    encodeCursorProjectDir(String.raw`C:\Users\kite_\Developer\dotagents`),
+    'C-Users-kite_-Developer-dotagents',
+  );
+});

package/src/hosts/grok.mjs

@@ -88,6 +88,7 @@ export const grokHostAdapter = Object.freeze({
     return lastUserPromptText(payload.transcript_path);
   },
   // Grok `/tl` 成功後だけ、源セッションの project_path で後継の対話 grok を立てる。
+  consumesHandoffAtSessionStart: false,
   afterBatonWrite({ trigger, sessionId, cwd, continueRun = runGrokContinue }) {
     if (trigger !== 'tl') return { launched: false };
     const code = continueRun(['--session', sessionId], { cwd });

package/src/hosts/identity.mjs

@@ -1,7 +1,7 @@
 /**
  * hosts/identity.mjs — harness (hook host) 識別の唯一の正本
  *
- * Throughline は Claude / Codex / Grok の 3 hook host を同じ SQLite に保存する。
+ * Throughline は Claude / Codex / Grok / Cursor の hook host を同じ SQLite に保存する。
  * host の見分け方は session_id prefix だけであり、その prefix 定義と判定関数を
  * このファイルに一元化する。共有コード (hook 入口・monitor・state-file・
  * predecessor 検索) は文字列リテラルを直接持たず、必ずここを参照する。
@@ -13,9 +13,11 @@
 export const CLAUDE_HOST = 'claude';
 export const CODEX_HOST = 'codex';
 export const GROK_HOST = 'grok';
+export const CURSOR_HOST = 'cursor';
 
 export const CODEX_SESSION_PREFIX = 'codex:';
 export const GROK_SESSION_PREFIX = 'grok:';
+export const CURSOR_SESSION_PREFIX = 'cursor:';
 
 /**
  * Claude session は prefix を持たない。auto handoff の前任検索 (Claude 専用) は
@@ -24,6 +26,7 @@ export const GROK_SESSION_PREFIX = 'grok:';
 export const NON_CLAUDE_SESSION_PREFIXES = Object.freeze([
   CODEX_SESSION_PREFIX,
   GROK_SESSION_PREFIX,
+  CURSOR_SESSION_PREFIX,
 ]);
 
 /**
@@ -40,14 +43,19 @@ export function isGrokSessionId(sessionId) {
   return typeof sessionId === 'string' && sessionId.startsWith(GROK_SESSION_PREFIX);
 }
 
+export function isCursorSessionId(sessionId) {
+  return typeof sessionId === 'string' && sessionId.startsWith(CURSOR_SESSION_PREFIX);
+}
+
 /**
  * session_id から hook host を返す。prefix なしは Claude。
  * @param {string} sessionId
- * @returns {'claude'|'codex'|'grok'}
+ * @returns {'claude'|'codex'|'grok'|'cursor'}
  */
 export function hostOfSessionId(sessionId) {
   if (isCodexSessionId(sessionId)) return CODEX_HOST;
   if (isGrokSessionId(sessionId)) return GROK_HOST;
+  if (isCursorSessionId(sessionId)) return CURSOR_HOST;
   return CLAUDE_HOST;
 }
 
@@ -69,3 +77,12 @@ export function grokBareSessionId(sessionId) {
     ? sessionId.slice(GROK_SESSION_PREFIX.length)
     : sessionId;
 }
+
+export function cursorBareSessionId(sessionId) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return null;
+  let bare = sessionId.startsWith(CURSOR_SESSION_PREFIX)
+    ? sessionId.slice(CURSOR_SESSION_PREFIX.length)
+    : sessionId;
+  if (bare.startsWith('bc-')) bare = bare.slice(3);
+  return bare.length > 0 ? bare : null;
+}

package/src/hosts/identity.test.mjs

@@ -3,13 +3,16 @@ import assert from 'node:assert/strict';
 
 import {
   CODEX_SESSION_PREFIX,
+  CURSOR_SESSION_PREFIX,
   GROK_SESSION_PREFIX,
   NON_CLAUDE_SESSION_PREFIXES,
   buildCodexThroughlineSessionId,
   codexSessionIdToThreadId,
+  cursorBareSessionId,
   grokBareSessionId,
   hostOfSessionId,
   isCodexSessionId,
+  isCursorSessionId,
   isGrokSessionId,
 } from './identity.mjs';
 import { hostAdapterForSessionId } from './index.mjs';
@@ -17,12 +20,14 @@ import { hostAdapterForSessionId } from './index.mjs';
 test('session prefixes are the canonical wire values', () => {
   assert.equal(CODEX_SESSION_PREFIX, 'codex:');
   assert.equal(GROK_SESSION_PREFIX, 'grok:');
-  assert.deepEqual([...NON_CLAUDE_SESSION_PREFIXES], ['codex:', 'grok:']);
+  assert.equal(CURSOR_SESSION_PREFIX, 'cursor:');
+  assert.deepEqual([...NON_CLAUDE_SESSION_PREFIXES], ['codex:', 'grok:', 'cursor:']);
 });
 
 test('hostOfSessionId maps prefixes to hosts and defaults to claude', () => {
   assert.equal(hostOfSessionId('codex:0199aa'), 'codex');
   assert.equal(hostOfSessionId('grok:0199aa'), 'grok');
+  assert.equal(hostOfSessionId('cursor:0199aa'), 'cursor');
   assert.equal(hostOfSessionId('0199aa-claude'), 'claude');
   assert.equal(hostOfSessionId(undefined), 'claude');
 });
@@ -41,25 +46,43 @@ test('grokBareSessionId strips only the grok prefix', () => {
   assert.equal(grokBareSessionId(''), null);
 });
 
-test('isCodexSessionId / isGrokSessionId reject non-strings', () => {
+test('cursorBareSessionId strips cursor: and optional bc- prefix', () => {
+  assert.equal(cursorBareSessionId('cursor:abc'), 'abc');
+  assert.equal(cursorBareSessionId('bc-abc'), 'abc');
+  assert.equal(cursorBareSessionId('cursor:bc-abc'), 'abc');
+  assert.equal(cursorBareSessionId('abc'), 'abc');
+  assert.equal(cursorBareSessionId(''), null);
+});
+
+test('isCodexSessionId / isGrokSessionId / isCursorSessionId reject non-strings', () => {
   assert.equal(isCodexSessionId(null), false);
   assert.equal(isGrokSessionId(undefined), false);
+  assert.equal(isCursorSessionId(undefined), false);
 });
 
 test('every host adapter satisfies the shared hook contract', () => {
-  for (const sessionId of ['claude-session', 'codex:t1', 'grok:t1']) {
+  for (const sessionId of ['claude-session', 'codex:t1', 'grok:t1', 'cursor:t1']) {
     const adapter = hostAdapterForSessionId(sessionId);
     assert.equal(typeof adapter.host, 'string');
     assert.equal(adapter.matchesSessionId(sessionId), true);
     assert.equal(typeof adapter.waitsForStopTranscriptFlush, 'boolean');
+    assert.equal(typeof adapter.consumesHandoffAtSessionStart, 'boolean');
     assert.equal(typeof adapter.deliverHandoffInjection, 'function');
     assert.equal(typeof adapter.resolveCommandPrompt, 'function');
     assert.equal(typeof adapter.afterBatonWrite, 'function');
   }
 });
 
-test('flush barrier applies to claude and codex sessions, not grok', () => {
+test('flush barrier applies to claude and codex sessions, not grok or cursor', () => {
   assert.equal(hostAdapterForSessionId('claude-session').waitsForStopTranscriptFlush, true);
   assert.equal(hostAdapterForSessionId('codex:t1').waitsForStopTranscriptFlush, true);
   assert.equal(hostAdapterForSessionId('grok:t1').waitsForStopTranscriptFlush, false);
+  assert.equal(hostAdapterForSessionId('cursor:t1').waitsForStopTranscriptFlush, false);
+});
+
+test('only Cursor consumes handoff at sessionStart', () => {
+  assert.equal(hostAdapterForSessionId('claude-session').consumesHandoffAtSessionStart, false);
+  assert.equal(hostAdapterForSessionId('codex:t1').consumesHandoffAtSessionStart, false);
+  assert.equal(hostAdapterForSessionId('grok:t1').consumesHandoffAtSessionStart, false);
+  assert.equal(hostAdapterForSessionId('cursor:t1').consumesHandoffAtSessionStart, true);
 });

package/src/hosts/index.mjs

@@ -5,26 +5,35 @@
  * `normalizeHookPayload` と `hostAdapterForSessionId` だけを使い、
  * ベンダー分岐を直接書かない。
  */
-import { hostOfSessionId, CLAUDE_HOST, CODEX_HOST, GROK_HOST } from './identity.mjs';
+import { hostOfSessionId, CLAUDE_HOST, CODEX_HOST, GROK_HOST, CURSOR_HOST } from './identity.mjs';
 import { claudeHostAdapter } from './claude.mjs';
 import { codexHostAdapter } from './codex.mjs';
 import { grokHostAdapter, isGrokEnvelope, normalizeGrokHookPayload } from './grok.mjs';
+import { cursorHostAdapter, isCursorEnvelope, normalizeCursorHookPayload } from './cursor.mjs';
 
 export * from './identity.mjs';
 export { isGrokEnvelope, deriveGrokChatHistoryPath, normalizeGrokHookPayload } from './grok.mjs';
+export {
+  isCursorEnvelope,
+  encodeCursorProjectDir,
+  deriveCursorTranscriptPath,
+  normalizeCursorHookPayload,
+} from './cursor.mjs';
 
 const ADAPTERS = Object.freeze({
   [CLAUDE_HOST]: claudeHostAdapter,
   [CODEX_HOST]: codexHostAdapter,
   [GROK_HOST]: grokHostAdapter,
+  [CURSOR_HOST]: cursorHostAdapter,
 });
 
 /**
  * hook stdin payload を Claude snake_case 契約へ正規化する。
- * 現状 camelCase envelope を送るのは Grok だけ (v0.10.0 / ADR 0021)。
+ * Grok は camelCase wire、Cursor は hook_event_name が sessionStart 等。
  */
 export function normalizeHookPayload(payload, options = {}) {
   if (isGrokEnvelope(payload)) return normalizeGrokHookPayload(payload, options);
+  if (isCursorEnvelope(payload)) return normalizeCursorHookPayload(payload, options);
   return payload;
 }
 

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 { NON_CLAUDE_SESSION_PREFIXES, normalizeHookPayload } from './hosts/index.mjs';
+import { hostAdapterForSessionId, NON_CLAUDE_SESSION_PREFIXES, normalizeHookPayload } from './hosts/index.mjs';
+import { executeFirstPromptHandoff } from './handoff-executor.mjs';
 
 const ENV_DISABLE_AUTO_HANDOFF = 'THROUGHLINE_DISABLE_AUTO_HANDOFF';
 
@@ -161,6 +162,28 @@ export async function run() {
     pending_registered: true,
   });
 
+  // Cursor は beforeSubmitPrompt が additional_context を持たない。
+  // 新規 composer 会話の sessionStart が公式の注入口なので、ここで第二相を実行する。
+  // Claude の幽霊 SessionStart 問題はこの host では sessionStart = 会話作成のため適用しない。
+  // クラウド / background agent は baton を奪わない。
+  const hostAdapter = hostAdapterForSessionId(session_id);
+  if (hostAdapter.consumesHandoffAtSessionStart === true && payload.is_background_agent !== true) {
+    const handoff = executeFirstPromptHandoff(db, {
+      sessionId: session_id,
+      projectPath,
+      now,
+    });
+    if (handoff.attempted && handoff.injectionText) {
+      const delivery = hostAdapter.deliverHandoffInjection({
+        payload,
+        text: handoff.injectionText,
+      });
+      if (!delivery.delivered) {
+        process.stderr.write(`[session-start] ${delivery.reason}\n`);
+      }
+    }
+  }
+
   process.exit(0);
 }
 

package/src/transcript-reader-cursor.test.mjs

@@ -0,0 +1,43 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getLogicalTurnGroups, readTranscript, sliceCurrentTurnEntries, readRawEntries } from './transcript-reader.mjs';
+
+test('readTranscript accepts Cursor agent-transcripts role-first jsonl', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'tl-cursor-transcript-'));
+  const path = join(dir, '7face712.jsonl');
+  writeFileSync(
+    path,
+    [
+      JSON.stringify({
+        role: 'user',
+        message: { content: [{ type: 'text', text: 'hello cursor' }] },
+      }),
+      JSON.stringify({
+        role: 'assistant',
+        message: { content: [{ type: 'text', text: 'captured reply' }] },
+      }),
+    ].join('\n'),
+  );
+  try {
+    const turns = readTranscript(path);
+    assert.deepEqual(
+      turns.map((t) => ({ role: t.role, content: t.content })),
+      [
+        { role: 'user', content: 'hello cursor' },
+        { role: 'assistant', content: 'captured reply' },
+      ],
+    );
+    const groups = getLogicalTurnGroups(path);
+    assert.equal(groups.length, 1);
+    assert.equal(groups[0].user.content, 'hello cursor');
+    assert.equal(groups[0].representative.content, 'captured reply');
+    const sliced = sliceCurrentTurnEntries(readRawEntries(path));
+    assert.equal(sliced.length, 2);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/transcript-reader.mjs

@@ -11,6 +11,12 @@
 import { readFileSync, existsSync } from 'fs';
 import { DETAIL_KIND } from './constants.mjs';
 
+function entryKind(entry) {
+  if (typeof entry?.type === 'string' && entry.type.length > 0) return entry.type;
+  if (typeof entry?.role === 'string' && entry.role.length > 0) return entry.role;
+  return undefined;
+}
+
 /**
  * content 配列からテキスト部分だけを結合する。
  * thinking ブロックは除外。
@@ -51,8 +57,9 @@ export function readTranscript(transcriptPath) {
       continue;
     }
 
-    // user / assistant エントリのみ対象
-    if (entry.type !== 'user' && entry.type !== 'assistant') continue;
+    // user / assistant エントリのみ対象。Claude は type、Cursor jsonl は role。
+    const kind = entryKind(entry);
+    if (kind !== 'user' && kind !== 'assistant') continue;
 
     // subagent の sidechain エントリは主会話ではないので除外。現行 CC は主 transcript に
     // 書かない（400 transcript 実測ゼロ件）が、将来変更への安価な防御 (docs/12 B-1)
@@ -60,7 +67,7 @@ export function readTranscript(transcriptPath) {
 
     const msg = entry.message;
     const grokContent = entry.content;
-    const role = msg?.role ?? entry.type;
+    const role = msg?.role ?? kind;
     const rawContent = msg?.content ?? grokContent;
     if (!role || rawContent == null) continue;
 
@@ -258,7 +265,7 @@ export function sliceCurrentTurnEntries(entries) {
   let lastAssistantTextIdx = -1;
   for (let i = entries.length - 1; i >= 0; i--) {
     const e = entries[i];
-    if (e.type !== 'assistant') continue;
+    if (entryKind(e) !== 'assistant') continue;
     const blocks = e.message?.content;
     if (!Array.isArray(blocks)) continue;
     if (blocks.some((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.length > 0)) {
@@ -272,7 +279,7 @@ export function sliceCurrentTurnEntries(entries) {
   let userTextIdx = -1;
   for (let i = lastAssistantTextIdx - 1; i >= 0; i--) {
     const e = entries[i];
-    if (e.type !== 'user') continue;
+    if (entryKind(e) !== 'user') continue;
     const blocks = e.message?.content;
     if (Array.isArray(blocks)) {
       if (blocks.some((b) => b && b.type === 'text' && typeof b.text === 'string' && b.text.length > 0)) {
@@ -319,7 +326,7 @@ export function extractDetailBlocks(turnEntries) {
   const toolNameById = new Map();
 
   for (const e of turnEntries) {
-    if (e.type === 'assistant') {
+    if (entryKind(e) === 'assistant') {
       const blocks = e.message?.content;
       if (!Array.isArray(blocks)) continue;
       for (let i = 0; i < blocks.length; i++) {
@@ -355,7 +362,7 @@ export function extractDetailBlocks(turnEntries) {
         }
         // text は扱わない
       }
-    } else if (e.type === 'user') {
+    } else if (entryKind(e) === 'user') {
       const blocks = e.message?.content;
       if (!Array.isArray(blocks)) continue;
       for (const b of blocks) {