throughline 0.8.7 → 0.8.9

package/CHANGELOG.md

@@ -10,6 +10,39 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.8.9] — 2026-08-02
+
+### Fixed
+
+- Codex hook diagnosis no longer depends on the caller's `PATH`. The expected
+  hook command is rebuilt per invocation, and `resolveCodexHookNodePath` returns
+  the PATH form of Node when one is on `PATH` and `process.execPath` otherwise.
+  Comparing that string against the registered command classified a correctly
+  installed hook as a legacy command whenever the two representations differed,
+  so `doctor --codex` reported "legacy command needs reinstall" and
+  `factory-diagnostics` reported `codex_hooks` as `not_ready` for every scheduled
+  run started from a minimal environment. Hook commands are now compared by
+  parsed identity — same Node executable by realpath, same CLI script by
+  realpath, same event — so a hook registered as `/opt/homebrew/bin/node` still
+  matches an expectation resolved to `/opt/homebrew/Cellar/node/<ver>/bin/node`.
+  Hooks pointing at a different Throughline installation, a different event, or
+  the legacy PATH-resolved form remain flagged for reinstall, and paths whose
+  realpath cannot be resolved are never treated as equivalent.
+
+## [0.8.8] — 2026-08-02
+
+### Fixed
+
+- Codex hook installation now writes the supported `timeout` field in seconds
+  for UserPromptSubmit, PostToolUse, and Stop. The previously emitted
+  `timeoutSec` field was ignored by Codex, leaving all three hooks at the
+  600-second default.
+- Reinstall canonicalizes existing Throughline-managed hooks by command
+  identity, replacing legacy `timeoutSec` entries while preserving unrelated
+  Codex hooks. Doctor reports the effective `timeout` field and explicitly
+  flags the legacy key for reinstall; factory diagnostics no longer classify
+  the ignored key as ready.
+
 ## [0.8.7] — 2026-07-20
 
 ### Fixed
@@ -1177,7 +1210,9 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.7...HEAD
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.9...HEAD
+[0.8.9]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.8...v0.8.9
+[0.8.8]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.7...v0.8.8
 [0.8.7]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.6...v0.8.7
 [0.8.6]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.5...v0.8.6
 [0.8.5]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.4...v0.8.5

package/README.ja.md

@@ -14,6 +14,16 @@
 > **Claude Code のコンテキスト消費を約 90% 削減しつつ、記憶はほぼそのまま残す。**
 > 「時間の新旧」ではなく **「コンテンツの種類」** で会話を分離する。人間が読みたいテキストは残し、機械が出力したツール I/O は SQLite に退避する。同じ判断、同じ文脈、9 割軽量。
 
+[kitepon.dev](https://kitepon.dev/)を運営する[クオ（@QLyun35332）](https://x.com/QLyun35332)が
+開発・メンテナンスしています。
+
+## 所有境界
+
+本repositoryはdatabase、migration、capture契約、release、diagnosticsを所有します。
+製品横断の導入とhost統合は、kitepon.devの製品開発を支える内部基盤
+[dotagents](https://github.com/kitepon-rgb/dotagents)が担当します。
+MarkItDownは別区分の第三者CLIです。
+
 ## 30 秒で始める
 
 ```bash

package/README.md

@@ -14,6 +14,16 @@
 > **Cut ~90% of Claude Code's context usage while keeping nearly all the memory.**
 > Throughline separates conversation by **type, not time** — humans-readable text stays, machine-generated tool output retires to SQLite. Same decisions, same context, 90% lighter.
 
+Built and maintained by [Quo](https://x.com/QLyun35332) at [kitepon.dev](https://kitepon.dev/en).
+
+## Ownership boundary
+
+This repository owns the database, migrations, capture contracts, release, and
+diagnostics. Cross-product installation and host integration are handled by
+[dotagents](https://github.com/kitepon-rgb/dotagents), the internal development
+toolchain behind kitepon.dev's products.
+MarkItDown is a separately managed third-party CLI.
+
 ## In 30 seconds
 
 ```bash

package/docs/04_public_release_plan.md

@@ -142,7 +142,9 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **npm 公開 (v0.6.3): Codex diagnostics ready 集約 + Windows bounded observer** | 3 managed Codex hooks が canonical `ready` のとき hook summary / Codex connector を `ready` とし、未検査 Claude connector は明示 `unverified` のまま Codex-only overall から除外する。Windows runtime-error observer は、既存 state の使用前検証と新規 file の ACL 付与・read-back を維持しつつ、同一 mutation 内の重複 PowerShell ACL 検証を除いた。公開commit `fc83ddf`、CI `29284655280`（9/9 green）、npm `throughline@0.6.3`、tag / GitHub Release、npm shasum `4f3fcd2598a75f026358dae7f3eb3165242b580b` を2026-07-14に確認した |
 | **npm 公開 (v0.8.4): Codex handoff host境界の明示化** | `$throughline` skillは現在のCodex UI surfaceからDesktop／VS Code／CLIを選び、`--open-host`を明示する。shell／永続PTYの継承環境はsurface判定に使わない。`codex-handoff-start`は互換の`openHost`を残し、requested / resolved hostをJSONとtextで報告する。古いVS Code由来PTY事故形と配布skillをfocused testで固定し、Claude-facing hook／`/tl`／baton／resume契約は変更しない。公開commit `5b840b6`、CI run `29721583754` 9/9 green、npm `latest` 0.8.4、shasum `1f2c39a22e45f3e02e8739ee5fd6ceefc6a71034`、tag / GitHub Release、registry由来global install、配置skill一致、`doctor --codex` exit 0を2026-07-20に確認した。判断証拠は [ADR 0017](adr/0017-codex-handoff-host-boundary.md) |
 | **npm公開 (v0.8.6): 製品所有DB migration入口** | `throughline migrate --json` は既存DBだけをproduction migrationで現行schemaへ移行し、versioned bounded JSONを返す。DB不在は作らず`not_applicable`、現行は`already_current`、future schemaと失敗は非0。`factory-diagnostics`のread-only契約は維持する。0.8.5はdry-run後に別作業の未コミット文書が混入したためdeprecateし、同一runtimeをclean worktreeから0.8.6として再公開した。設計判断は [ADR 0018](adr/0018-product-owned-database-migration.md) |
-| **release準備 (v0.8.7): Windows CI release latency** | completed-turn receiptの256件境界fixtureと実ACL検証を分離し、production mutationのPowerShellはdistinct state transitionだけに限定する。temporary ACL失敗時の旧store保持とdirectory／lock／final storeのnative ACL testを維持する。CIは9 matrixのままevent／ref単位concurrency、unit test 5分SLO／8分timeoutとする。設計判断は [ADR 0020](adr/0020-windows-ci-release-latency.md) |
+| **公開済み (v0.8.7): Windows CI release latency** | completed-turn receiptの256件境界fixtureと実ACL検証を分離し、production mutationのPowerShellはdistinct state transitionだけに限定する。temporary ACL失敗時の旧store保持とdirectory／lock／final storeのnative ACL testを維持する。CIは9 matrixのままevent／ref単位concurrency、unit test 5分SLO／8分timeoutとする。設計判断は [ADR 0020](adr/0020-windows-ci-release-latency.md) |
+| **npm公開 (v0.8.8): Codex hook timeout key修理** | Codex `hooks.json` の3 managed hookは秒単位の正規key `timeout`を30／30／300で書く。無視される旧`timeoutSec` entryは次回global installでcommand identityにより置換し、doctorは旧形式を要再install、factory diagnosticsはnot readyとする。Claude hooksとObserver wait deadline APIは変更しない。npm `latest` として2026-08-02T00:43Zに公開済み。tag / GitHub Releaseは未作成（要作成） |
+| **release準備 (v0.8.9): Codex hook診断のPATH非依存化** | 期待hook commandのnode表記は呼び出し元の`PATH`で変わるため、登録済みcommandとの文字列比較では最小PATH（launchd factory reporter等）から正規登録が「legacy command」と誤判定され、`codex_hooks`が恒常的に`not_ready`になっていた。比較を解析済みidentity（node実体realpath＋CLI script realpath＋event）へ変更する。別install／別event／旧PATH解決型／realpath未解決は従来どおり要再install扱い。hooks.json の書式と Claude-facing hook は変更しない |
 | **未リリース: Codex current-session 75% trigger** | Codex 自動発火を token-monitor に依存させず、global install が Codex `UserPromptSubmit` / `PostToolUse` hooks も登録する。hook は当該 Codex session の rollout `token_count` を直接読み、verified 75% 以上なら同じ user turn または tool loop 継続前に `$throughline` workflow 実行指示を `additionalContext` で注入する。Stop hook の guarded auto-refresh は残す。`~/.codex/config.toml` は旧 `codex_hooks = true` に加えて現行 `hooks = true` も有効化する |
 | **グローバル E2E 検証** | 2026-04-17 別ディレクトリから `throughline doctor` 全緑を確認 |
 

package/docs/05_codex_first_roadmap.md

@@ -456,9 +456,9 @@ Phase 5 implementation status (2026-05-06):
   - 修正: Caveat の Codex Stop hook は `async: false` で登録され、nested `codex exec` smoke で Stop -> 次 turn 注入まで確認済みだった。Throughline は Claude Stop と同じ発想で Codex Stop も `async: true` にしていたため、Codex 側だけ Caveat と同じ同期 hook に寄せた。既に `async: true` で登録済みの Throughline Codex Stop hook も次回 `throughline install` で `async: false` に更新される。
   - 再実測: `npm install -g .` -> `throughline install` 後、`~/.codex/hooks.json` の Throughline Codex Stop は `async: false` になり、Caveat / Spotter hooks は保持された。`codex exec --json -C /home/kite/projects/Throughline "Reply exactly: TL_CODEX_SYNC_STOP_SMOKE_20260506"` で child thread `019dfd4f-93ff-7522-8f89-bd1e1996c8d7` が作られ、直後の `throughline doctor --codex` で latest DB session が `codex:019dfd4f-93ff-7522-8f89-bd1e1996c8d7` に進んだ。Codex Stop hook の自然 capture は同期登録で確認済み。
   - 追加修正: Caveat の Codex hook は bare `caveat` ではなく絶対 node + installed CLI script path で登録されていた。Throughline も Codex App Server / VSCode host の PATH 差分を避けるため、旧 bare `throughline codex-hook stop` を次回 install で絶対 node + `bin/throughline.mjs codex-hook stop` に置換する。`doctor --codex` は Codex hook feature / Throughline Stop hook command / legacy bare command を診断表示する。
-  - 絶対パス型の再実測: `npm install -g .` -> `throughline install` 後、`~/.codex/hooks.json` の Stop 先頭は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`、`timeoutSec: 300` になり、Caveat / Spotter hooks は 2 番目以降に保持された。`doctor --codex` は `Codex hooks feature: enabled` / `Codex Stop hook: registered` を表示した。`codex exec --json -C /home/kite/projects/Throughline "Reply exactly: TL_CODEX_ABSOLUTE_STOP_SMOKE_20260506"` で child thread `019dfd5e-1248-7c11-8ddc-97e1b0701e10` が作られ、直後の `throughline doctor --codex` で latest DB session が `codex:019dfd5e-1248-7c11-8ddc-97e1b0701e10` に進んだ。
+  - 絶対パス型の再実測: `npm install -g .` -> `throughline install` 後、`~/.codex/hooks.json` の Stop 先頭は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`になり、Caveat / Spotter hooks は 2 番目以降に保持された。2026-08-02 correction: 当時記録した`timeoutSec: 300`はCodexに無視される誤keyで、v0.8.8から正規の`timeout: 300`へ修正した。`doctor --codex` は `Codex hooks feature: enabled` / `Codex Stop hook: registered` を表示した。`codex exec --json -C /home/kite/projects/Throughline "Reply exactly: TL_CODEX_ABSOLUTE_STOP_SMOKE_20260506"` で child thread `019dfd5e-1248-7c11-8ddc-97e1b0701e10` が作られ、直後の `throughline doctor --codex` で latest DB session が `codex:019dfd5e-1248-7c11-8ddc-97e1b0701e10` に進んだ。
   - 追加確認: current VSCode-origin parent thread `019dfd38-c530-71c3-b7b8-180bdd3054bc` は hook shape 変更前に開始していたため、変更後の自然 Stop smoke としては不適格。assistant final 後に rollout は `task_complete` まで進んだが latest DB session は exec child のままだった。次に VSCode-origin を見る場合は、hook shape 変更後に新しく開始した Codex session で確認する。
-  - 最終確認: hook shape 変更後に新しく開始した VSCode-origin Codex session で 1 turn 完了後、`throughline doctor --codex` を実行した。`current Codex thread` は `019dfd62-9a9d-7211-bf91-89d8e3fc908e`、`latest DB session` は `codex:019dfd62-9a9d-7211-bf91-89d8e3fc908e` で一致し、`Codex hooks feature: enabled`、`Codex Stop hook: registered`、command は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`、`timeoutSec: 300` だった。VSCode-origin の自然 Stop hook による DB capture も解決済みとして扱う。
+  - 最終確認: hook shape 変更後に新しく開始した VSCode-origin Codex session で 1 turn 完了後、`throughline doctor --codex` を実行した。`current Codex thread` は `019dfd62-9a9d-7211-bf91-89d8e3fc908e`、`latest DB session` は `codex:019dfd62-9a9d-7211-bf91-89d8e3fc908e` で一致し、`Codex hooks feature: enabled`、`Codex Stop hook: registered`、command は `/usr/bin/node /home/kite/projects/Throughline/bin/throughline.mjs codex-hook stop`、`async: false`だった。2026-08-02 correction: 当時の`timeoutSec: 300`は無効で、v0.8.8の再install後は`timeout: 300`を正とする。VSCode-origin の自然 Stop hookによるDB captureの証拠自体は維持する。
   - historical 2026-05-07 correction: 以下の Codex trim smoke は live app-server primitive の履歴として残す。ただし 2026-05-06 incident 後、restart / reconnect 越しの durable context trim 成功とは一時的に扱わず、`$throughline` / Codex Stop hook の automatic mutation を止めていた。
   - 2026-05-10 UX 修正: bare `$throughline` は `doctor --codex` / `trim --dry-run --all` / `trim --preflight --all` を AI に順番実行させる説明 surface でも、`trim --execute --host codex --all` を直接実行する current-thread refresh でもなく、`throughline codex-handoff-start --execute --open-host <current-codex-surface>` による app-server 新スレッド handoff とする。current surfaceはCodex UI contextから明示し、current-thread rollback / inject は明示要求時だけ使う。
   - memory contract 修正: Codex guarded trim でも注入 memory は元の `/tl` 思想を正とする。古い turn は L1 summaries、直近 20 turn は L2 full bodies、L3 は reference only で、L3 bodies / tool payloads は注入しない。rollout source は rollback candidate と app-server turn-count 補正の根拠であり、Throughline DB memory がある場合に rollout active work preview を注入 memory として使わない。DB memory が無い execute は rollout preview を注入せず、mutation 前に拒否する。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [
@@ -9,12 +9,19 @@
     "context-compression",
     "llm"
   ],
-  "author": "kitepon",
+  "author": {
+    "name": "Quo / クオ at kitepon.dev",
+    "url": "https://kitepon.dev/"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kitepon-rgb/Throughline.git"
   },
+  "bugs": {
+    "url": "https://github.com/kitepon-rgb/Throughline/issues"
+  },
+  "homepage": "https://github.com/kitepon-rgb/Throughline#readme",
   "bin": {
     "throughline": "bin/throughline.mjs"
   },

package/src/cli/doctor.mjs

@@ -32,6 +32,7 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
   isThroughlineCodexPostToolUseCommand,
   isThroughlineCodexStopCommand,
@@ -480,6 +481,31 @@ function summarizeHookTrust(hooks, { hooksFeatureEnabled, codexHooksFeatureEnabl
   };
 }
 
+function hasLegacyCodexHookTimeout(hook) {
+  return Object.hasOwn(hook, 'timeoutSec');
+}
+
+function describeCodexHookRegistration(hooks, legacyCommandHooks, expectedTimeout) {
+  if (hooks.length === 0) return 'not registered';
+  if (legacyCommandHooks.length > 0) return 'legacy command needs reinstall';
+  if (hooks.some(hasLegacyCodexHookTimeout)) return 'legacy timeout key needs reinstall';
+  if (hooks.length !== 1) return 'configuration needs reinstall';
+  const hook = hooks[0];
+  return hook.type === 'command' && hook.timeout === expectedTimeout && hook.async === false
+    ? 'registered'
+    : 'configuration needs reinstall';
+}
+
+function printCodexHookDetails(hook) {
+  console.log(`    command:             ${hook.command}`);
+  console.log(`    async:               ${hook.async === false ? 'false' : String(hook.async)}`);
+  console.log(`    timeout:             ${hook.timeout ?? '(default: 600)'}`);
+  if (hasLegacyCodexHookTimeout(hook)) {
+    console.log(`    legacy timeoutSec:   ${hook.timeoutSec} (ignored by Codex; reinstall required)`);
+  }
+  console.log(`    trusted:             ${hook.throughlineDoctorTrusted ? 'yes' : 'no'}`);
+}
+
 function readCodexHookDiagnosis(codexHome) {
   const hooksPath = join(codexHome, 'hooks.json');
   const configPath = join(codexHome, 'config.toml');
@@ -551,13 +577,17 @@ function readCodexHookDiagnosis(codexHome) {
   );
   const stopHooks = listHooksWithTrust(parsed, 'Stop', 'stop', hooksPath, out.trustedStateKeys);
   out.managedPromptHooks = promptHooks.filter(h => isThroughlineCodexHookCommand(h.command));
-  out.legacyManagedPromptHooks = out.managedPromptHooks.filter(h => h.command !== expectedPromptCommand);
+  out.legacyManagedPromptHooks = out.managedPromptHooks.filter(
+    h => !isEquivalentCodexHookCommand(h.command, expectedPromptCommand),
+  );
   out.managedPostToolUseHooks = postToolUseHooks.filter(h => isThroughlineCodexPostToolUseCommand(h.command));
   out.legacyManagedPostToolUseHooks = out.managedPostToolUseHooks.filter(
-    h => h.command !== expectedPostToolUseCommand,
+    h => !isEquivalentCodexHookCommand(h.command, expectedPostToolUseCommand),
   );
   out.managedStopHooks = stopHooks.filter(h => isThroughlineCodexStopCommand(h.command));
-  out.legacyManagedStopHooks = out.managedStopHooks.filter(h => h.command !== expectedStopCommand);
+  out.legacyManagedStopHooks = out.managedStopHooks.filter(
+    h => !isEquivalentCodexHookCommand(h.command, expectedStopCommand),
+  );
   out.managedHookTrust = summarizeHookTrust(
     [
       ...out.managedPromptHooks,
@@ -599,47 +629,29 @@ function runCodexDiagnosis({
   console.log(`  CODEX_HOME:            ${codexHome}`);
   console.log(`  Codex hooks feature:   ${hookDiagnosis.featureEnabled ? 'enabled' : 'not enabled'}`);
   console.log(`  Codex hook trust:      ${hookDiagnosis.managedHookTrust.status}`);
-  console.log(`  Codex UserPrompt hook: ${
-    hookDiagnosis.managedPromptHooks.length === 0
-      ? 'not registered'
-      : hookDiagnosis.legacyManagedPromptHooks.length > 0
-        ? 'legacy command needs reinstall'
-        : 'registered'
-  }`);
+  console.log(`  Codex UserPrompt hook: ${describeCodexHookRegistration(
+    hookDiagnosis.managedPromptHooks,
+    hookDiagnosis.legacyManagedPromptHooks,
+    30,
+  )}`);
   if (hookDiagnosis.managedPromptHooks.length > 0) {
-    const h = hookDiagnosis.managedPromptHooks[0];
-    console.log(`    command:             ${h.command}`);
-    console.log(`    async:               ${h.async === false ? 'false' : String(h.async)}`);
-    console.log(`    timeoutSec:          ${h.timeoutSec ?? '(default)'}`);
-    console.log(`    trusted:             ${h.throughlineDoctorTrusted ? 'yes' : 'no'}`);
+    printCodexHookDetails(hookDiagnosis.managedPromptHooks[0]);
   }
-  console.log(`  Codex PostTool hook:   ${
-    hookDiagnosis.managedPostToolUseHooks.length === 0
-      ? 'not registered'
-      : hookDiagnosis.legacyManagedPostToolUseHooks.length > 0
-        ? 'legacy command needs reinstall'
-        : 'registered'
-  }`);
+  console.log(`  Codex PostTool hook:   ${describeCodexHookRegistration(
+    hookDiagnosis.managedPostToolUseHooks,
+    hookDiagnosis.legacyManagedPostToolUseHooks,
+    30,
+  )}`);
   if (hookDiagnosis.managedPostToolUseHooks.length > 0) {
-    const h = hookDiagnosis.managedPostToolUseHooks[0];
-    console.log(`    command:             ${h.command}`);
-    console.log(`    async:               ${h.async === false ? 'false' : String(h.async)}`);
-    console.log(`    timeoutSec:          ${h.timeoutSec ?? '(default)'}`);
-    console.log(`    trusted:             ${h.throughlineDoctorTrusted ? 'yes' : 'no'}`);
+    printCodexHookDetails(hookDiagnosis.managedPostToolUseHooks[0]);
   }
-  console.log(`  Codex Stop hook:       ${
-    hookDiagnosis.managedStopHooks.length === 0
-      ? 'not registered'
-      : hookDiagnosis.legacyManagedStopHooks.length > 0
-        ? 'legacy command needs reinstall'
-        : 'registered'
-  }`);
+  console.log(`  Codex Stop hook:       ${describeCodexHookRegistration(
+    hookDiagnosis.managedStopHooks,
+    hookDiagnosis.legacyManagedStopHooks,
+    300,
+  )}`);
   if (hookDiagnosis.managedStopHooks.length > 0) {
-    const h = hookDiagnosis.managedStopHooks[0];
-    console.log(`    command:             ${h.command}`);
-    console.log(`    async:               ${h.async === false ? 'false' : String(h.async)}`);
-    console.log(`    timeoutSec:          ${h.timeoutSec ?? '(default)'}`);
-    console.log(`    trusted:             ${h.throughlineDoctorTrusted ? 'yes' : 'no'}`);
+    printCodexHookDetails(hookDiagnosis.managedStopHooks[0]);
   }
   console.log(`  VSCode monitor task:   ${monitorTaskDiagnosis.status}`);
   if (monitorTaskDiagnosis.path) {
@@ -1024,6 +1036,8 @@ export const _internal = {
   buildCodexContextRefreshDiagnosis,
   readCodexHostPrimitiveDiagnosis,
   readCodexHookDiagnosis,
+  describeCodexHookRegistration,
+  printCodexHookDetails,
   readVsCodeMonitorTaskDiagnosis,
   isPidAlive,
   findLatestJsonlInSameDir,

package/src/cli/doctor.test.mjs

@@ -19,8 +19,42 @@ const {
   runTrimDiagnosis,
   buildCodexContextRefreshDiagnosis,
   readCodexHostPrimitiveDiagnosis,
+  describeCodexHookRegistration,
+  printCodexHookDetails,
 } = _internal;
 
+test('Codex hook diagnosis requires reinstall for legacy timeoutSec key', () => {
+  const legacy = { type: 'command', command: 'canonical', timeoutSec: 300, async: false };
+  assert.equal(
+    describeCodexHookRegistration([legacy], [], 300),
+    'legacy timeout key needs reinstall',
+  );
+  assert.equal(
+    describeCodexHookRegistration([{ type: 'command', command: 'canonical', timeout: 300, async: false }], [], 300),
+    'registered',
+  );
+});
+
+test('Codex hook diagnosis prints timeout and exposes ignored legacy key', () => {
+  const lines = [];
+  const originalLog = console.log;
+  console.log = (line) => lines.push(line);
+  try {
+    printCodexHookDetails({
+      command: 'canonical',
+      timeout: 300,
+      timeoutSec: 30,
+      async: false,
+      throughlineDoctorTrusted: true,
+    });
+  } finally {
+    console.log = originalLog;
+  }
+  const output = lines.join('\n');
+  assert.match(output, /timeout:\s+300/);
+  assert.match(output, /legacy timeoutSec:\s+30 \(ignored by Codex; reinstall required\)/);
+});
+
 // ─── parseArgs ──────────────────────────────────────────────────────
 
 test('parseArgs: 引数なしは session null', () => {
@@ -345,7 +379,7 @@ test('readCodexHookDiagnosis detects Codex prompt and Stop hooks', () => {
                   {
                     type: 'command',
                     command: '/usr/bin/node /pkg/bin/throughline.mjs codex-hook user-prompt-submit',
-                    timeoutSec: 30,
+                    timeout: 30,
                     async: false,
                   },
                 ],
@@ -357,7 +391,7 @@ test('readCodexHookDiagnosis detects Codex prompt and Stop hooks', () => {
                   {
                     type: 'command',
                     command: '/usr/bin/node /pkg/bin/throughline.mjs codex-hook post-tool-use',
-                    timeoutSec: 30,
+                    timeout: 30,
                     async: false,
                   },
                 ],
@@ -369,7 +403,7 @@ test('readCodexHookDiagnosis detects Codex prompt and Stop hooks', () => {
                   {
                     type: 'command',
                     command: 'throughline codex-hook stop',
-                    timeoutSec: 300,
+                    timeout: 300,
                     async: true,
                   },
                 ],

package/src/cli/factory-diagnostics.mjs

@@ -7,6 +7,7 @@ import { buildFactoryDiagnostics } from '../factory-diagnostics.mjs';
 import { findCodexThreadCandidate, defaultCodexHome } from '../codex-thread-index.mjs';
 import { resolveCodexThreadIdentity } from '../codex-thread-identity.mjs';
 import { CURRENT_VERSION } from '../db.mjs';
+import { isEquivalentCodexHookCommand } from './install.mjs';
 import { _internal as doctorInternal } from './doctor.mjs';
 
 const require = createRequire(import.meta.url);
@@ -122,12 +123,12 @@ function hasFactoryDatabaseShape(db) {
   return bodiesUnique;
 }
 
-function eventStatus({ hooks, legacyHooks, featureEnabled, expectedCommand, timeoutSec }) {
+function eventStatus({ hooks, legacyHooks, featureEnabled, expectedCommand, timeout }) {
   if (hooks.length === 0) return featureEnabled ? 'not_ready' : 'not_applicable';
   if (!featureEnabled || legacyHooks.length > 0 || hooks.length !== 1) return 'not_ready';
   const hook = hooks[0];
-  return hook.type === 'command' && hook.command === expectedCommand && hook.timeoutSec === timeoutSec &&
-    hook.async === false ? 'ready' : 'not_ready';
+  return hook.type === 'command' && isEquivalentCodexHookCommand(hook.command, expectedCommand) &&
+    hook.timeout === timeout && hook.async === false ? 'ready' : 'not_ready';
 }
 
 export function inspectFactoryHooks({ codexHome = defaultCodexHome(), readHooks = doctorInternal.readCodexHookDiagnosis } = {}) {
@@ -143,21 +144,21 @@ export function inspectFactoryHooks({ codexHome = defaultCodexHome(), readHooks
         legacyHooks: diagnosis.legacyManagedPromptHooks,
         featureEnabled: diagnosis.featureEnabled,
         expectedCommand: diagnosis.expectedPromptCommand,
-        timeoutSec: 30,
+        timeout: 30,
       }),
       postToolUse: eventStatus({
         hooks: diagnosis.managedPostToolUseHooks,
         legacyHooks: diagnosis.legacyManagedPostToolUseHooks,
         featureEnabled: diagnosis.featureEnabled,
         expectedCommand: diagnosis.expectedPostToolUseCommand,
-        timeoutSec: 30,
+        timeout: 30,
       }),
       stop: eventStatus({
         hooks: diagnosis.managedStopHooks,
         legacyHooks: diagnosis.legacyManagedStopHooks,
         featureEnabled: diagnosis.featureEnabled,
         expectedCommand: diagnosis.expectedStopCommand,
-        timeoutSec: 300,
+        timeout: 300,
       }),
     };
     const values = Object.values(events);

package/src/cli/factory-diagnostics.test.mjs

@@ -1,7 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { DatabaseSync } from 'node:sqlite';
-import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -166,11 +166,11 @@ test('factory-diagnostics hook inspection rejects corrupt and false-ready shapes
       expectedPromptCommand: 'prompt',
       expectedPostToolUseCommand: 'post',
       expectedStopCommand: 'stop',
-      managedPromptHooks: [{ type: 'command', command: 'prompt', timeoutSec: 30, async: true }],
+      managedPromptHooks: [{ type: 'command', command: 'prompt', timeout: 30, async: true }],
       legacyManagedPromptHooks: [],
-      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeoutSec: 30, async: false }],
+      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeout: 30, async: false }],
       legacyManagedPostToolUseHooks: [],
-      managedStopHooks: [{ type: 'command', command: 'stop', timeoutSec: 300, async: false }],
+      managedStopHooks: [{ type: 'command', command: 'stop', timeout: 300, async: false }],
       legacyManagedStopHooks: [],
     }),
   });
@@ -188,11 +188,11 @@ test('factory-diagnostics hook inspection summarizes every canonical ready event
       expectedPromptCommand: 'prompt',
       expectedPostToolUseCommand: 'post',
       expectedStopCommand: 'stop',
-      managedPromptHooks: [{ type: 'command', command: 'prompt', timeoutSec: 30, async: false }],
+      managedPromptHooks: [{ type: 'command', command: 'prompt', timeout: 30, async: false }],
       legacyManagedPromptHooks: [],
-      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeoutSec: 30, async: false }],
+      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeout: 30, async: false }],
       legacyManagedPostToolUseHooks: [],
-      managedStopHooks: [{ type: 'command', command: 'stop', timeoutSec: 300, async: false }],
+      managedStopHooks: [{ type: 'command', command: 'stop', timeout: 300, async: false }],
       legacyManagedStopHooks: [],
     }),
   });
@@ -202,6 +202,72 @@ test('factory-diagnostics hook inspection summarizes every canonical ready event
   assert.equal(result.reason, 'hooks_inspected');
 });
 
+test('factory-diagnostics hook inspection: 最小 PATH 由来の node 別表記を not_ready にしない', () => {
+  // launchd の factory reporter は PATH に /opt/homebrew/bin を持たないため、期待値の
+  // node が PATH symlink ではなく実体表記になる。同一 node を指す限り ready を維持する。
+  const dir = mkdtempSync(join(tmpdir(), 'tl-factory-hook-'));
+  try {
+    mkdirSync(join(dir, 'bin'));
+    mkdirSync(join(dir, 'cellar'));
+    const realNode = join(dir, 'cellar', 'node');
+    const pathNode = join(dir, 'bin', 'node');
+    const script = join(dir, 'throughline.mjs');
+    writeFileSync(realNode, '');
+    writeFileSync(script, '');
+    symlinkSync(realNode, pathNode);
+    const registered = (event) => `${pathNode} ${script} codex-hook ${event}`;
+    const expected = (event) => `${realNode} ${script} codex-hook ${event}`;
+
+    const result = inspectFactoryHooks({
+      readHooks: () => ({
+        configExists: true,
+        configReadable: true,
+        hooksExists: true,
+        hooksReadable: true,
+        featureEnabled: true,
+        expectedPromptCommand: expected('user-prompt-submit'),
+        expectedPostToolUseCommand: expected('post-tool-use'),
+        expectedStopCommand: expected('stop'),
+        managedPromptHooks: [{ type: 'command', command: registered('user-prompt-submit'), timeout: 30, async: false }],
+        legacyManagedPromptHooks: [],
+        managedPostToolUseHooks: [{ type: 'command', command: registered('post-tool-use'), timeout: 30, async: false }],
+        legacyManagedPostToolUseHooks: [],
+        managedStopHooks: [{ type: 'command', command: registered('stop'), timeout: 300, async: false }],
+        legacyManagedStopHooks: [],
+      }),
+    });
+
+    assert.deepEqual(result.events, { userPromptSubmit: 'ready', postToolUse: 'ready', stop: 'ready' });
+    assert.equal(result.status, 'ready');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('factory-diagnostics hook inspection rejects legacy timeoutSec keys', () => {
+  const result = inspectFactoryHooks({
+    readHooks: () => ({
+      configExists: true,
+      configReadable: true,
+      hooksExists: true,
+      hooksReadable: true,
+      featureEnabled: true,
+      expectedPromptCommand: 'prompt',
+      expectedPostToolUseCommand: 'post',
+      expectedStopCommand: 'stop',
+      managedPromptHooks: [{ type: 'command', command: 'prompt', timeoutSec: 30, async: false }],
+      legacyManagedPromptHooks: [],
+      managedPostToolUseHooks: [{ type: 'command', command: 'post', timeoutSec: 30, async: false }],
+      legacyManagedPostToolUseHooks: [],
+      managedStopHooks: [{ type: 'command', command: 'stop', timeoutSec: 300, async: false }],
+      legacyManagedStopHooks: [],
+    }),
+  });
+
+  assert.deepEqual(result.events, { userPromptSubmit: 'not_ready', postToolUse: 'not_ready', stop: 'not_ready' });
+  assert.equal(result.status, 'not_ready');
+});
+
 function createFactorySchema(db) {
   db.exec(`
     PRAGMA user_version = 9;

package/src/cli/install.mjs

@@ -163,6 +163,62 @@ export function isThroughlineCodexPostToolUseCommand(command) {
   );
 }
 
+const CODEX_HOOK_EVENTS = new Set(['stop', 'user-prompt-submit', 'post-tool-use']);
+
+function tokenizeCommand(command) {
+  const tokens = [];
+  const pattern = /"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g;
+  let match;
+  while ((match = pattern.exec(command)) !== null) {
+    // quoteCommandPath は `"` だけを escape する。Windows path の `\` は温存する。
+    if (match[1] !== undefined) tokens.push(match[1].replace(/\\"/g, '"'));
+    else if (match[2] !== undefined) tokens.push(match[2]);
+    else tokens.push(match[3]);
+  }
+  return tokens;
+}
+
+/**
+ * 絶対パス型の Codex hook command を {nodePath, scriptPath, event} へ分解する。
+ * 旧 PATH 解決型 (`throughline codex-hook stop`) など、この形でないものは null。
+ */
+export function parseCodexHookCommand(command) {
+  if (typeof command !== 'string') return null;
+  const tokens = tokenizeCommand(command.replace(/^&\s+/, ''));
+  if (tokens.length !== 4) return null;
+  const [nodePath, scriptPath, subcommand, event] = tokens;
+  if (subcommand !== 'codex-hook' || !CODEX_HOOK_EVENTS.has(event)) return null;
+  if (!scriptPath.endsWith('throughline.mjs')) return null;
+  return { nodePath, scriptPath, event };
+}
+
+/**
+ * 登録済み hook command が期待値と同じ実行体を指すかを判定する。
+ *
+ * node の表記は呼び出し元の PATH で変わる (`resolveCodexHookNodePath` は PATH 上に
+ * 同一 node があればその表記を、無ければ `process.execPath` を返す)。launchd の
+ * ような最小 PATH から診断すると `/opt/homebrew/bin/node` で登録された正規 hook が
+ * `/opt/homebrew/Cellar/node/<ver>/bin/node` と文字列比較され、正しい登録が legacy
+ * と誤判定される。実体 (realpath) の同一性で比較してこれを防ぐ。realpath を解決
+ * できない場合は同一とみなさない。
+ */
+export function isEquivalentCodexHookCommand(actual, expected, { realpath = realpathSync.native } = {}) {
+  if (typeof actual !== 'string' || typeof expected !== 'string') return false;
+  if (actual === expected) return true;
+  const left = parseCodexHookCommand(actual);
+  const right = parseCodexHookCommand(expected);
+  if (!left || !right || left.event !== right.event) return false;
+  return isSameExecutablePath(left.scriptPath, right.scriptPath, realpath) &&
+    isSameExecutablePath(left.nodePath, right.nodePath, realpath);
+}
+
+function isSameExecutablePath(a, b, realpath) {
+  if (a === b) return true;
+  const left = safeRealpath(a, realpath);
+  const right = safeRealpath(b, realpath);
+  return left !== null && right !== null && left === right;
+}
+
 function createCodexHooks() {
   return {
     UserPromptSubmit: {
@@ -170,7 +226,7 @@ function createCodexHooks() {
         {
           type: 'command',
           command: buildCodexUserPromptSubmitHookCommand(),
-          timeoutSec: 30,
+          timeout: 30,
           async: false,
           statusMessage: null,
         },
@@ -181,7 +237,7 @@ function createCodexHooks() {
         {
           type: 'command',
           command: buildCodexPostToolUseHookCommand(),
-          timeoutSec: 30,
+          timeout: 30,
           async: false,
           statusMessage: null,
         },
@@ -192,7 +248,7 @@ function createCodexHooks() {
         {
           type: 'command',
           command: buildCodexStopHookCommand(),
-          timeoutSec: 300,
+          timeout: 300,
           async: false,
           statusMessage: null,
         },

package/src/cli/install.test.mjs

@@ -8,7 +8,9 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
+  parseCodexHookCommand,
   resolveCodexHookNodePath,
   run,
   resolveThroughlineOnPath,
@@ -120,19 +122,21 @@ test('global install registers Codex session hooks and enables hooks features',
       .find(h => h.command === expectedStopCommand);
     assert.ok(codexHook, 'Codex Stop should have absolute throughline.mjs codex-hook stop');
     assert.equal(codexHook.async, false, 'Codex Stop hook should be synchronous for Codex');
-    assert.equal(codexHook.timeoutSec, 300, 'Codex Stop hook should allow summarizer time');
+    assert.equal(codexHook.timeout, 300, 'Codex Stop hook should allow summarizer time');
     const promptHook = hooks.hooks.UserPromptSubmit
       .flatMap(g => g.hooks ?? [])
       .find(h => h.command === expectedPromptCommand);
     assert.ok(promptHook, 'Codex UserPromptSubmit should have absolute throughline.mjs codex-hook user-prompt-submit');
     assert.equal(promptHook.async, false, 'Codex UserPromptSubmit hook should be synchronous for capture/monitor state');
-    assert.equal(promptHook.timeoutSec, 30, 'Codex UserPromptSubmit hook should be short');
+    assert.equal(promptHook.timeout, 30, 'Codex UserPromptSubmit hook should be short');
     const postToolUseHook = hooks.hooks.PostToolUse
       .flatMap(g => g.hooks ?? [])
       .find(h => h.command === expectedPostToolUseCommand);
     assert.ok(postToolUseHook, 'Codex PostToolUse should have absolute throughline.mjs codex-hook post-tool-use');
     assert.equal(postToolUseHook.async, false, 'Codex PostToolUse hook should be synchronous for capture/monitor state');
-    assert.equal(postToolUseHook.timeoutSec, 30, 'Codex PostToolUse hook should be short');
+    assert.equal(postToolUseHook.timeout, 30, 'Codex PostToolUse hook should be short');
+    const managedHooks = [codexHook, promptHook, postToolUseHook];
+    assert.doesNotMatch(JSON.stringify(managedHooks), /timeoutSec/);
     const config = readFileSync(join(home.dir, '.codex', 'config.toml'), 'utf8');
     assert.match(config, /^\[features\]\ncodex_hooks = true/m);
     assert.match(config, /^hooks = true/m);
@@ -245,7 +249,7 @@ test('global install preserves existing Codex hooks and is idempotent', async ()
                 {
                   type: 'command',
                   command: '/usr/bin/node /home/kite/.npm-global/bin/caveat codex-hook stop',
-                  timeoutSec: 5,
+                  timeout: 5,
                   async: false,
                   statusMessage: null,
                 },
@@ -287,7 +291,7 @@ test('global install preserves existing Codex hooks and is idempotent', async ()
   }
 });
 
-test('global install updates existing Throughline Codex hook shapes', async () => {
+test('global install replaces legacy timeoutSec Throughline Codex hook shapes', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {
     home.restore();
@@ -356,19 +360,22 @@ test('global install updates existing Throughline Codex hook shapes', async () =
       .filter(h => h.command === expectedStopCommand);
     assert.equal(codexHooks.length, 1);
     assert.equal(codexHooks[0].async, false);
-    assert.equal(codexHooks[0].timeoutSec, 300);
+    assert.equal(codexHooks[0].timeout, 300);
+    assert.equal(Object.hasOwn(codexHooks[0], 'timeoutSec'), false);
     const promptHooks = hooks.hooks.UserPromptSubmit
       .flatMap(g => g.hooks ?? [])
       .filter(h => h.command === expectedPromptCommand);
     assert.equal(promptHooks.length, 1);
     assert.equal(promptHooks[0].async, false);
-    assert.equal(promptHooks[0].timeoutSec, 30);
+    assert.equal(promptHooks[0].timeout, 30);
+    assert.equal(Object.hasOwn(promptHooks[0], 'timeoutSec'), false);
     const postToolUseHooks = hooks.hooks.PostToolUse
       .flatMap(g => g.hooks ?? [])
       .filter(h => h.command === expectedPostToolUseCommand);
     assert.equal(postToolUseHooks.length, 1);
     assert.equal(postToolUseHooks[0].async, false);
-    assert.equal(postToolUseHooks[0].timeoutSec, 30);
+    assert.equal(postToolUseHooks[0].timeout, 30);
+    assert.equal(Object.hasOwn(postToolUseHooks[0], 'timeoutSec'), false);
     assert.equal(
       hooks.hooks.Stop.flatMap(g => g.hooks ?? []).filter(h => h.command === 'throughline codex-hook stop').length,
       0,
@@ -426,7 +433,7 @@ test('global uninstall removes only Throughline-managed Codex hook', async () =>
         {
           type: 'command',
           command: '/usr/bin/node /home/kite/.npm-global/bin/caveat codex-hook stop',
-          timeoutSec: 5,
+          timeout: 5,
           async: false,
           statusMessage: null,
         },
@@ -575,6 +582,65 @@ test('resolveCodexHookNodePath: falls back to process execPath when PATH node is
   assert.equal(result, execPath);
 });
 
+test('parseCodexHookCommand: 絶対パス型を分解し、旧 PATH 解決型と別コマンドは null', () => {
+  assert.deepEqual(
+    parseCodexHookCommand('/opt/homebrew/bin/node /pkg/bin/throughline.mjs codex-hook stop'),
+    { nodePath: '/opt/homebrew/bin/node', scriptPath: '/pkg/bin/throughline.mjs', event: 'stop' },
+  );
+  assert.deepEqual(
+    parseCodexHookCommand('& "C:\\node.exe" "C:\\pkg\\bin\\throughline.mjs" codex-hook post-tool-use'),
+    { nodePath: 'C:\\node.exe', scriptPath: 'C:\\pkg\\bin\\throughline.mjs', event: 'post-tool-use' },
+  );
+  assert.equal(parseCodexHookCommand('throughline codex-hook stop'), null);
+  assert.equal(parseCodexHookCommand('/bin/node /pkg/bin/throughline.mjs codex-hook rewind'), null);
+  assert.equal(parseCodexHookCommand('/bin/node /pkg/bin/other.mjs codex-hook stop'), null);
+});
+
+test('isEquivalentCodexHookCommand: 同一 node 実体を指す別表記を legacy と誤判定しない', () => {
+  // launchd の最小 PATH から診断すると expected 側だけ Cellar 実体表記になる。
+  const registered = '/opt/homebrew/bin/node /pkg/bin/throughline.mjs codex-hook user-prompt-submit';
+  const expected = '/opt/homebrew/Cellar/node/26.5.0/bin/node /pkg/bin/throughline.mjs codex-hook user-prompt-submit';
+  const realpath = (p) => (p.endsWith('node') ? '/real/node' : p);
+  assert.equal(isEquivalentCodexHookCommand(registered, expected, { realpath }), true);
+});
+
+test('isEquivalentCodexHookCommand: 別 install / 別 event / 旧形式は同一とみなさない', () => {
+  const realpath = (p) => p;
+  assert.equal(
+    isEquivalentCodexHookCommand(
+      '/bin/node /old/bin/throughline.mjs codex-hook stop',
+      '/bin/node /new/bin/throughline.mjs codex-hook stop',
+      { realpath },
+    ),
+    false,
+  );
+  assert.equal(
+    isEquivalentCodexHookCommand(
+      '/bin/node /pkg/bin/throughline.mjs codex-hook stop',
+      '/bin/node /pkg/bin/throughline.mjs codex-hook post-tool-use',
+      { realpath },
+    ),
+    false,
+  );
+  assert.equal(
+    isEquivalentCodexHookCommand(
+      'throughline codex-hook stop',
+      '/bin/node /pkg/bin/throughline.mjs codex-hook stop',
+      { realpath },
+    ),
+    false,
+  );
+  // realpath を解決できない時は同一とみなさない（暗黙の緩和をしない）
+  assert.equal(
+    isEquivalentCodexHookCommand(
+      '/a/node /pkg/bin/throughline.mjs codex-hook stop',
+      '/b/node /pkg/bin/throughline.mjs codex-hook stop',
+      { realpath: (p) => { throw new Error(`missing: ${p}`); } },
+    ),
+    false,
+  );
+});
+
 test('install is idempotent: second run keeps exactly one tl.md and one hook entry', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {