throughline 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -10,6 +10,36 @@ 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
+
+- 挙動不変のOS/harness層集約リファクタ（harness用語統一campaignの分離規約）:
+  - LOCALAPPDATA / XDG_CONFIG_HOME / XDG_STATE_HOME のベースディレクトリ組み立てを
+    新設`src/os/app-dirs.mjs`へ一本化（runtime-error-store / completed-turn-receipts
+    に3重実装されていた）。
+  - hostリテラル比較（`'claude'`／`'codex'`）6ファイルを`src/hosts/identity.mjs`の
+    定数importへ統一し、「識別の唯一の正本」宣言と実装を一致させた。
+  - codex-auto-refreshの独自パス正規化を`src/os/paths.mjs`の
+    `foldPathCaseForPlatform`へ、codex-sidecarのwin32判定を同`isWin32Platform`へ委譲。
+  - `hosts/identity.mjs`の分類語をvendorからharnessへ更新（用語のみ）。
+
 ## [0.10.1] — 2026-08-23
 
 ### Changed
@@ -1290,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>
@@ -390,7 +396,7 @@ throughline handoff-context --session codex:<thread-id> --json
 成功時の`throughline.handoff_context.v1`は`schema`、`status`、`sessionId`、`context`だけを返す。
 `context`はSessionStartと同じ予算付き継承文脈で、DB作成・migration・baton消費・session merge・
 latest session推測・`sessions.merged_into`変更・L1/L2/L3 rowの所属変更は行わない。AItermは任意の
-別vendor portable forkでこの境界を使う。Observer feedはcompleted-turn projectionであり代替ではない。
+別harness portable forkでこの境界を使う。Observer feedはcompleted-turn projectionであり代替ではない。
 
 スラッシュコマンド (Claude Code 内でユーザーが叩く):
 

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>
 
@@ -834,7 +841,7 @@ local-only contracts.
 | `throughline runtime-errors reopen <fingerprint> --json` | Explicitly reopen a resolved aggregate without fabricating a new occurrence |
 | `throughline runtime-errors compact --json`    | Remove only acknowledged, resolved aggregates after retention; open or unacknowledged records remain |
 | `throughline handoff-preview --session <id>`   | Print a Codex-facing `throughline_handoff` JSON projection    |
-| `throughline handoff-context --session <id> --json` | Print the exact SessionStart inheritance context as versioned JSON without moving memory rows or changing `sessions.merged_into`; intended for local launchers that need portable cross-vendor context |
+| `throughline handoff-context --session <id> --json` | Print the exact SessionStart inheritance context as versioned JSON without moving memory rows or changing `sessions.merged_into`; intended for local launchers that need portable cross-harness context |
 | `throughline grok-continue --session <id>` | Spawn a person-facing Grok seat whose first user text is the handoff-context body. cwd is the source session `project_path`. Does not spawn without ready context. No `--rules`. macOS Terminal only |
 | `throughline codex-capture --codex-thread-id <id>` | Capture active Codex rollout turns into a `codex:<thread_id>` DB session |
 | `throughline codex-summarize --session codex:<id>` | Summarize captured Codex L2 into L1 with the Codex CLI backend |
@@ -872,7 +879,7 @@ The successful `throughline.handoff_context.v1` object contains only `schema`,
 inheritance text used by SessionStart. The command does not create or migrate a
 database, consume a baton, merge sessions, infer a latest session, change
 `sessions.merged_into`, or reassign L1/L2/L3 rows. AIterm uses this boundary for
-its optional cross-vendor portable fork; the Observer feed is a separate
+its optional cross-harness portable fork; the Observer feed is a separate
 completed-turn projection and is not a substitute.
 
 Slash commands (invoked by the user in Claude Code):

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/16_readonly_handoff_context_plan.md

@@ -4,14 +4,14 @@
 
 通常 handoff が使う `buildBudgetedResumeContext` の出力を、DB 所有権を変えずにローカルプログラムが
 取得できる read-only CLI として公開する。最初の consumer は AIterm の portable fork だが、I/F は
-特定 consumer や vendor に依存させない。
+特定 consumer や harness に依存させない。
 
 実行 ToDo、依存、状態、完了証拠の正本は Lattice plan `readonly-handoff-context` とする。
 
 ## 完了
 
 2026-08-04に`throughline@0.9.0`としてnpm、tag、GitHub Release、global installまで公開した。
-focused契約testと全回帰は729 pass／1 skip／0 fail。AIterm v0.23.0の代表cross-vendor smokeでは
+focused契約testと全回帰は729 pass／1 skip／0 fail。AIterm v0.23.0の代表cross-harness smokeでは
 Codex source memoryをClaudeへ注入し、前後でsource session、`sessions.merged_into`、L1/L2/L3 row所属が
 完全一致することを確認した。公開後の現行ドキュメント全域監査は、Latticeの終端ToDoを再openして
 README、作業者入口、配布Codex skill、docs索引、計画、CHANGELOGへ同期した。変更Markdownの

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.1",
-  "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/auditor-context.mjs

@@ -3,7 +3,7 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve, sep } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { buildBodyRowsFromActiveTurns } from './codex-capture.mjs';
-import { isCodexSessionId } from './hosts/identity.mjs';
+import { CLAUDE_HOST, CODEX_HOST, isCodexSessionId } from './hosts/identity.mjs';
 import { parseCodexRolloutFile } from './codex-rollout-memory.mjs';
 import { getLogicalTurnGroups } from './transcript-reader.mjs';
 import { hashAuditorBody, normalizeAuditorBody } from './body-digest.mjs';
@@ -24,7 +24,7 @@ export function defaultAuditorContextDbPath() {
 export function deriveAuditorFreshnessExpectation({ host, transcriptPath, sessionId } = {}) {
   assertNonEmptyString(transcriptPath, 'transcriptPath');
   assertNonEmptyString(sessionId, 'sessionId');
-  if (host === 'claude') {
+  if (host === CLAUDE_HOST) {
     const latest = getLogicalTurnGroups(transcriptPath).at(-1);
     if (!latest) return null;
     return {
@@ -34,7 +34,7 @@ export function deriveAuditorFreshnessExpectation({ host, transcriptPath, sessio
       expectedAssistantSha256: hashAuditorBody(latest.representative.content),
     };
   }
-  if (host === 'codex') {
+  if (host === CODEX_HOST) {
     const parsed = parseCodexRolloutFile(transcriptPath, { includeInFlightTurn: false });
     const rows = buildBodyRowsFromActiveTurns(parsed.activeTurns, { sessionId, now: 0 });
     const latestTurnNumber = rows.reduce((max, row) => Math.max(max, row.turnNumber), 0);

package/src/cli/auditor-context.mjs

@@ -1,3 +1,4 @@
+import { CLAUDE_HOST, CODEX_HOST } from '../hosts/identity.mjs';
 import {
   AUDITOR_CONTEXT_SCHEMA,
   deriveAuditorFreshnessExpectation,
@@ -53,7 +54,7 @@ export function parseArgs(argv = []) {
     else if (arg === '--max-body-chars') out.maxBodyChars = parsePositiveInteger(value);
     else if (arg === '--max-total-chars') out.maxTotalChars = parsePositiveInteger(value);
     else if (arg === '--db') out.dbPath = value;
-    else if (arg === '--host' && (value === 'claude' || value === 'codex')) out.host = value;
+    else if (arg === '--host' && (value === CLAUDE_HOST || value === CODEX_HOST)) out.host = value;
     else if (arg === '--transcript') out.transcriptPath = value;
     else throw new TypeError('unknown option');
   }

package/src/cli/doctor.mjs

@@ -14,6 +14,7 @@
  */
 
 import { existsSync, accessSync, readFileSync, constants, readdirSync, statSync } from 'node:fs';
+import { CODEX_HOST } from '../hosts/identity.mjs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
@@ -302,9 +303,9 @@ function runTrimDiagnosis(
 ) {
   const info = describeTrimHost(host);
   const codexIdentity =
-    info.host === 'codex' ? resolveCodexThreadIdentity({ codexThreadId: null }, env) : null;
+    info.host === CODEX_HOST ? resolveCodexThreadIdentity({ codexThreadId: null }, env) : null;
   const hostPrimitiveDiagnosis =
-    info.host === 'codex' ? readCodexHostPrimitiveDiagnosis({ env, auditRunner }) : null;
+    info.host === CODEX_HOST ? readCodexHostPrimitiveDiagnosis({ env, auditRunner }) : null;
   console.log(`${BOLD}[Trim]${RESET}\n`);
   console.log(`  host:                  ${info.host}`);
   console.log(`  default keep-recent:   ${DEFAULT_TRIM_KEEP_RECENT}`);
@@ -330,19 +331,19 @@ function runTrimDiagnosis(
   }
   console.log('');
   console.log('  dry-run command:');
-  if (info.host === 'codex' && !codexIdentity?.codexThreadId) {
+  if (info.host === CODEX_HOST && !codexIdentity?.codexThreadId) {
     console.log('    throughline trim --dry-run --host codex --codex-thread-id <id>');
     console.log('    throughline trim --preflight --host codex --codex-thread-id <id>');
-  } else if (info.host === 'codex') {
+  } else if (info.host === CODEX_HOST) {
     console.log('    throughline trim --dry-run --host codex');
     console.log('    throughline trim --preflight --host codex');
   } else {
     console.log(`    throughline trim --dry-run --host ${info.host}`);
   }
-  if (info.host === 'codex') {
+  if (info.host === CODEX_HOST) {
     console.log('    throughline trim --execute --host codex');
   }
-  if (info.host === 'codex') {
+  if (info.host === CODEX_HOST) {
     const sessionId = codexIdentity?.codexThreadId
       ? `codex:${codexIdentity.codexThreadId}`
       : 'codex:<thread-id>';

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/cli/trim.mjs

@@ -1,4 +1,5 @@
 import { runCodexTrimExecution, runCodexTrimPreflight } from '../codex-app-server.mjs';
+import { CODEX_HOST } from '../hosts/identity.mjs';
 import {
   buildCodexRolloutTrimSource,
   parseCodexRolloutFile,
@@ -122,7 +123,7 @@ export async function run(args) {
   const inflightMemo = parsed.memoStdin ? await readStdin() : null;
   const db = getDb();
   const trimSource =
-    parsed.host === 'codex' && parsed.codexThreadId
+    parsed.host === CODEX_HOST && parsed.codexThreadId
       ? buildCodexRolloutTrimSource({
           threadId: parsed.codexThreadId,
           projectPath: process.cwd(),
@@ -376,7 +377,7 @@ async function runPreflight(parsed, plan) {
 }
 
 function validateCodexAction(parsed, plan, action) {
-  if (parsed.host !== 'codex') {
+  if (parsed.host !== CODEX_HOST) {
     return {
       status: `${action}-refused`,
       reason: `${action}_requires_codex_host`,

package/src/codex-auto-refresh.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { foldPathCaseForPlatform } from './os/paths.mjs';
+import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
 import { runCodexTrimExecution } from './codex-app-server.mjs';
@@ -509,8 +510,7 @@ function normalizeProjectPath(value) {
   if (typeof value !== 'string' || value.length === 0) return '';
   let result = resolve(value).replace(/\\/g, '/');
   if (result.length > 1 && result.endsWith('/')) result = result.slice(0, -1);
-  if (platform() === 'win32') result = result.toLowerCase();
-  return result;
+  return foldPathCaseForPlatform(result);
 }
 
 function numberOrNull(value) {

package/src/codex-sidecar.mjs

@@ -1,4 +1,5 @@
 import { spawnPortableSync } from './os/portable-spawn-sync.mjs';
+import { isWin32Platform } from './os/paths.mjs';
 
 export const CODEX_SIDECAR_WORKFLOWS = Object.freeze([
   'review',
@@ -23,7 +24,7 @@ function resolveCommand({ command, env }) {
 }
 
 export function shouldShellWrapSidecarCommand(platform = process.platform) {
-  return platform === 'win32';
+  return isWin32Platform(platform);
 }
 
 export function runCodexSidecarCommand(command, args, options = {}) {

package/src/completed-turn-receipts.mjs

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { CLAUDE_HOST } from './hosts/identity.mjs';
 import {
   chmodSync,
   lstatSync,
@@ -8,12 +9,12 @@ import {
   rmSync,
   writeFileSync,
 } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { hashAuditorBody } from './body-digest.mjs';
 import { normalizeProjectPathForCompare } from './project-path.mjs';
 import { applyAndVerifyWindowsAcl, isWindows, verifyWindowsAcl } from './os/windows-acl.mjs';
+import { windowsLocalAppData, xdgStateHome } from './os/app-dirs.mjs';
 
 export const COMPLETED_TURN_RECEIPT_STORE_SCHEMA = 'throughline.completed_turn_receipts.v1';
 export const COMPLETED_TURN_RECEIPT_SCHEMA_VERSION = '1.0';
@@ -24,11 +25,10 @@ const PRIVATE_DIRECTORY_CAPABILITY = Symbol('throughline.completed-turn-receipt-
 
 export function defaultCompletedTurnReceiptStorePath(projectSha256, env = process.env) {
   if (!isSha256(projectSha256)) throw new TypeError('projectSha256 must be a SHA-256 digest');
-  const home = env.HOME || env.USERPROFILE || homedir();
   if (isWindows(env)) {
-    return join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
+    return join(windowsLocalAppData(env), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
   }
-  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
+  return join(xdgStateHome(env), 'throughline', 'completed-turn-receipts', `${projectSha256}.json`);
 }
 
 /**
@@ -273,7 +273,7 @@ function validateReceipt(receipt, nextSequence) {
   ];
   if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt) ||
     !exactKeys(receipt, keys) || receipt.schema_version !== COMPLETED_TURN_RECEIPT_SCHEMA_VERSION ||
-    receipt.host !== 'claude' || !isSha256(receipt.project_sha256) ||
+    receipt.host !== CLAUDE_HOST || !isSha256(receipt.project_sha256) ||
     !isIdentity(receipt.target_session_id) || !isIdentity(receipt.origin_session_id) ||
     !isSha256(receipt.user_sha256) || !isSha256(receipt.assistant_sha256) ||
     !Number.isSafeInteger(receipt.completed_at) || receipt.completed_at < 0 ||

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 };
   },