throughline 0.8.8 → 0.8.9

package/CHANGELOG.md

@@ -10,6 +10,25 @@ 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
@@ -1191,7 +1210,8 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.8...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

package/docs/04_public_release_plan.md

@@ -143,7 +143,8 @@ schema v4 で PostToolUse (`capture-tool`) は廃止、L2/L3 は Stop 内で一
 | **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) |
 | **公開済み (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) |
-| **release準備 (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公開 (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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/cli/doctor.mjs

@@ -32,6 +32,7 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
   isThroughlineCodexPostToolUseCommand,
   isThroughlineCodexStopCommand,
@@ -576,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,

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);
@@ -126,8 +127,8 @@ function eventStatus({ hooks, legacyHooks, featureEnabled, expectedCommand, time
   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.timeout === timeout &&
-    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 } = {}) {

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';
 
@@ -202,6 +202,48 @@ 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: () => ({

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: {

package/src/cli/install.test.mjs

@@ -8,7 +8,9 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  isEquivalentCodexHookCommand,
   isThroughlineCodexHookCommand,
+  parseCodexHookCommand,
   resolveCodexHookNodePath,
   run,
   resolveThroughlineOnPath,
@@ -580,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) {