throughline 0.4.10 → 0.4.12

package/src/cli/codex-hook.mjs

@@ -71,36 +71,11 @@ function suppressExperimentalWarnings() {
   });
 }
 
-export function codexContextOutput(text, eventName = 'UserPromptSubmit') {
-  return JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName,
-      additionalContext: text,
-    },
-  });
-}
-
-function renderAutoRefreshContext({ usage, decision, threadId, eventName = 'UserPromptSubmit' }) {
-  const tokens = Number(usage?.tokens);
-  const contextWindowSize = Number(usage?.contextWindowSize);
-  const ratio = Number(decision?.ratio);
-  const percent = Number.isFinite(ratio) ? `${(ratio * 100).toFixed(1)}%` : 'unknown';
-  const timing =
-    eventName === 'PostToolUse'
-      ? 'Before continuing the current tool loop, run the installed $throughline workflow now.'
-      : 'Before answering the user prompt, run the installed $throughline workflow now.';
-  return [
-    '[throughline] Codex context refresh threshold reached for this current session.',
-    `Thread: ${threadId}`,
-    `Usage: ${Number.isFinite(tokens) ? tokens : 'unknown'} / ${Number.isFinite(contextWindowSize) ? contextWindowSize : 'unknown'} (${percent}); threshold ${(decision.threshold * 100).toFixed(0)}%.`,
-    '',
-    timing,
-    'Execute exactly:',
-    'throughline trim --execute --host codex --all --json',
-    '',
-    'Report only the execution status, whether rollback/inject were sent, durable evidence if present, and the selected memory session; then continue from the refreshed context.',
-    'This trigger was computed from the current Codex rollout token_count, not from token-monitor output.',
-  ].join('\n');
+function codexAutoRefreshDisabledResult() {
+  return {
+    status: 'skipped',
+    reason: 'codex_auto_refresh_disabled',
+  };
 }
 
 async function captureCodexHookSession({
@@ -236,20 +211,20 @@ export async function runCodexStopHook({
   ensureMonitorTask = null,
   buildMonitorUsage = null,
   runAutoRefresh = null,
+  autoRefreshStateStore = null,
 } = {}) {
-  const [{ runCodexAutoRefresh }, capturedState] = await Promise.all([
-    import('../codex-auto-refresh.mjs'),
-    captureCodexHookSession({
-      args,
-      payload,
-      env,
-      db,
-      writeMonitorState,
-      ensureMonitorTask,
-      buildMonitorUsage,
-      summarize: true,
-    }),
-  ]);
+  void runAutoRefresh;
+  void autoRefreshStateStore;
+  const capturedState = await captureCodexHookSession({
+    args,
+    payload,
+    env,
+    db,
+    writeMonitorState,
+    ensureMonitorTask,
+    buildMonitorUsage,
+    summarize: true,
+  });
 
   if (capturedState.status !== 'ok') {
     return {
@@ -261,28 +236,6 @@ export async function runCodexStopHook({
     };
   }
 
-  let autoRefresh = null;
-  try {
-    autoRefresh = await (runAutoRefresh ?? runCodexAutoRefresh)({
-      db: capturedState.db,
-      threadId: capturedState.identity.codexThreadId,
-      codexThreadIdSource: capturedState.identity.codexThreadIdSource,
-      codexHome: capturedState.codexHome,
-      projectPath: capturedState.captured.projectPath ?? capturedState.projectPath,
-      sessionId: capturedState.captured.sessionId,
-      usage: capturedState.usage,
-      command: env.THROUGHLINE_CODEX_APP_SERVER_BIN ?? process.env.THROUGHLINE_CODEX_APP_SERVER_BIN ?? 'codex',
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : 'unknown';
-    autoRefresh = {
-      status: 'error',
-      reason: 'auto_refresh_failed',
-      message: msg,
-    };
-    process.stderr.write(`[codex-hook:auto-refresh] ${msg}\n`);
-  }
-
   return {
     status: 'ok',
     reason: 'codex_rollout_captured',
@@ -290,7 +243,7 @@ export async function runCodexStopHook({
     captured: capturedState.captured,
     summarized: capturedState.summarized,
     monitorState: capturedState.monitorState,
-    autoRefresh,
+    autoRefresh: codexAutoRefreshDisabledResult(),
   };
 }
 
@@ -302,6 +255,7 @@ export async function runCodexUserPromptSubmitHook({
   writeMonitorState = null,
   ensureMonitorTask = null,
   buildMonitorUsage = null,
+  autoRefreshStateStore = null,
 } = {}) {
   return runCodexContextRefreshInstructionHook({
     eventName: 'UserPromptSubmit',
@@ -312,6 +266,7 @@ export async function runCodexUserPromptSubmitHook({
     writeMonitorState,
     ensureMonitorTask,
     buildMonitorUsage,
+    autoRefreshStateStore,
   });
 }
 
@@ -323,6 +278,7 @@ export async function runCodexPostToolUseHook({
   writeMonitorState = null,
   ensureMonitorTask = null,
   buildMonitorUsage = null,
+  autoRefreshStateStore = null,
 } = {}) {
   return runCodexContextRefreshInstructionHook({
     eventName: 'PostToolUse',
@@ -333,6 +289,7 @@ export async function runCodexPostToolUseHook({
     writeMonitorState,
     ensureMonitorTask,
     buildMonitorUsage,
+    autoRefreshStateStore,
   });
 }
 
@@ -345,20 +302,20 @@ async function runCodexContextRefreshInstructionHook({
   writeMonitorState = null,
   ensureMonitorTask = null,
   buildMonitorUsage = null,
+  autoRefreshStateStore = null,
 } = {}) {
-  const [{ evaluateCodexAutoRefreshUsage }, capturedState] = await Promise.all([
-    import('../codex-auto-refresh.mjs'),
-    captureCodexHookSession({
-      args,
-      payload,
-      env,
-      db,
-      writeMonitorState,
-      ensureMonitorTask,
-      buildMonitorUsage,
-      summarize: false,
-    }),
-  ]);
+  void eventName;
+  void autoRefreshStateStore;
+  const capturedState = await captureCodexHookSession({
+    args,
+    payload,
+    env,
+    db,
+    writeMonitorState,
+    ensureMonitorTask,
+    buildMonitorUsage,
+    summarize: false,
+  });
 
   if (capturedState.status !== 'ok') {
     return {
@@ -371,41 +328,13 @@ async function runCodexContextRefreshInstructionHook({
     };
   }
 
-  const decision = evaluateCodexAutoRefreshUsage(capturedState.usage);
-  if (!decision.shouldRefresh) {
-    return {
-      status: 'ok',
-      reason: 'codex_rollout_captured',
-      codexThreadIdSource: capturedState.identity.codexThreadIdSource,
-      captured: capturedState.captured,
-      monitorState: capturedState.monitorState,
-      autoRefreshPrompt: {
-        status: 'skipped',
-        reason: decision.reason,
-        decision,
-      },
-    };
-  }
-
-  const context = renderAutoRefreshContext({
-    usage: capturedState.usage,
-    decision,
-    threadId: capturedState.identity.codexThreadId,
-    eventName,
-  });
   return {
     status: 'ok',
     reason: 'codex_rollout_captured',
     codexThreadIdSource: capturedState.identity.codexThreadIdSource,
     captured: capturedState.captured,
     monitorState: capturedState.monitorState,
-    autoRefreshPrompt: {
-      status: 'ready',
-      reason: 'threshold_reached',
-      decision,
-      context,
-      output: codexContextOutput(context, eventName),
-    },
+    autoRefreshPrompt: codexAutoRefreshDisabledResult(),
   };
 }
 
@@ -475,10 +404,8 @@ export async function run(argv = []) {
 
 export const _internal = {
   codexHomeFromTranscriptPath,
-  codexContextOutput,
   parseArgs,
   parsePayload,
-  renderAutoRefreshContext,
   resolveCodexHookThreadIdentity,
 };
 

package/src/cli/codex-hook.test.mjs

@@ -117,7 +117,7 @@ test('codex-hook stop captures rollout using Codex stdin payload fields', async
     assert.equal(monitorState.usage.source, 'codex-rollout-token-count');
     assert.equal(result.monitorState.sessionId, `codex:${threadId}`);
     assert.equal(result.autoRefresh.status, 'skipped');
-    assert.equal(result.autoRefresh.reason, 'below_threshold');
+    assert.equal(result.autoRefresh.reason, 'codex_auto_refresh_disabled');
     assert.equal(monitorTaskCwd, project);
   } finally {
     db.close();
@@ -126,12 +126,12 @@ test('codex-hook stop captures rollout using Codex stdin payload fields', async
   }
 });
 
-test('codex-hook stop runs auto refresh when verified usage reaches 75%', async () => {
+test('codex-hook stop captures only and does not auto refresh at 75%', async () => {
   const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
   const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
   const db = makeDb();
-  let autoRefreshArgs = null;
+  let runAutoRefreshCalled = false;
   try {
     const rolloutPath = writeRollout(codexHome, {
       id: threadId,
@@ -161,7 +161,7 @@ test('codex-hook stop runs auto refresh when verified usage reaches 75%', async
       ensureMonitorTask: () => {},
       writeMonitorState: () => {},
       runAutoRefresh: async (args) => {
-        autoRefreshArgs = args;
+        runAutoRefreshCalled = true;
         return {
           status: 'refreshed-live',
           reason: 'rollback_and_inject_sent_live',
@@ -170,16 +170,9 @@ test('codex-hook stop runs auto refresh when verified usage reaches 75%', async
     });
 
     assert.equal(result.status, 'ok');
-    assert.equal(result.autoRefresh.status, 'refreshed-live');
-    assert.equal(autoRefreshArgs.threadId, threadId);
-    assert.equal(autoRefreshArgs.codexThreadIdSource, 'payload:session_id');
-    assert.equal(autoRefreshArgs.codexHome, codexHome);
-    assert.equal(autoRefreshArgs.projectPath, project);
-    assert.equal(autoRefreshArgs.sessionId, `codex:${threadId}`);
-    assert.equal(autoRefreshArgs.usage.tokens, 240_000);
-    assert.equal(autoRefreshArgs.usage.contextWindowSize, 258400);
-    assert.equal(autoRefreshArgs.usage.estimated, false);
-    assert.equal(autoRefreshArgs.command, 'codex');
+    assert.equal(result.autoRefresh.status, 'skipped');
+    assert.equal(result.autoRefresh.reason, 'codex_auto_refresh_disabled');
+    assert.equal(runAutoRefreshCalled, false);
   } finally {
     db.close();
     rmSync(codexHome, { recursive: true, force: true });
@@ -187,7 +180,7 @@ test('codex-hook stop runs auto refresh when verified usage reaches 75%', async
   }
 });
 
-test('codex-hook user-prompt-submit injects current-session throughline instruction at 75%', async () => {
+test('codex-hook user-prompt-submit does not inject auto-refresh instruction at 75%', async () => {
   const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
   const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
@@ -227,14 +220,9 @@ test('codex-hook user-prompt-submit injects current-session throughline instruct
     });
 
     assert.equal(result.status, 'ok');
-    assert.equal(result.autoRefreshPrompt.status, 'ready');
-    assert.equal(result.autoRefreshPrompt.reason, 'threshold_reached');
-    assert.match(result.autoRefreshPrompt.context, /Before answering the user prompt/);
-    assert.match(result.autoRefreshPrompt.context, /throughline trim --execute --host codex --all --json/);
-    assert.match(result.autoRefreshPrompt.context, /current Codex rollout token_count/);
-    const output = JSON.parse(result.autoRefreshPrompt.output);
-    assert.equal(output.hookSpecificOutput.hookEventName, 'UserPromptSubmit');
-    assert.match(output.hookSpecificOutput.additionalContext, /installed \$throughline workflow/);
+    assert.equal(result.autoRefreshPrompt.status, 'skipped');
+    assert.equal(result.autoRefreshPrompt.reason, 'codex_auto_refresh_disabled');
+    assert.equal(result.autoRefreshPrompt.output, undefined);
     assert.equal(result.captured.sessionId, `codex:${threadId}`);
     assert.equal(monitorState.sessionId, `codex:${threadId}`);
   } finally {
@@ -244,6 +232,71 @@ test('codex-hook user-prompt-submit injects current-session throughline instruct
   }
 });
 
+test('codex-hook prompt and tool hooks both stay quiet when auto-refresh is disabled', async () => {
+  const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
+  const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+  const db = makeDb();
+  const autoRefreshStateStore = makeMemoryAutoRefreshStateStore();
+  try {
+    const rolloutPath = writeRollout(codexHome, {
+      id: threadId,
+      cwd: project,
+      events: [
+        event('user_message', { message: 'hook request' }),
+        event('task_started'),
+        turnContext({ model: 'gpt-5.5', cwd: project }),
+        event('agent_message', { message: 'hook answer' }),
+        event('task_complete'),
+        tokenCountEvent({
+          inputTokens: 240_000,
+          outputTokens: 67,
+          contextWindow: 258400,
+        }),
+      ],
+    });
+
+    const first = await runCodexUserPromptSubmitHook({
+      payload: {
+        session_id: threadId,
+        transcript_path: rolloutPath,
+        cwd: project,
+        prompt: 'next user prompt',
+      },
+      env: {},
+      db,
+      ensureMonitorTask: () => {},
+      writeMonitorState: () => {},
+      autoRefreshStateStore,
+    });
+    const second = await runCodexPostToolUseHook({
+      payload: {
+        session_id: threadId,
+        transcript_path: rolloutPath,
+        cwd: project,
+        hook_event_name: 'PostToolUse',
+        tool_name: 'exec_command',
+      },
+      env: {},
+      db,
+      ensureMonitorTask: () => {},
+      writeMonitorState: () => {},
+      autoRefreshStateStore,
+    });
+
+    assert.equal(first.autoRefreshPrompt.status, 'skipped');
+    assert.equal(first.autoRefreshPrompt.reason, 'codex_auto_refresh_disabled');
+    assert.equal(first.autoRefreshPrompt.output, undefined);
+    assert.equal(second.autoRefreshPrompt.status, 'skipped');
+    assert.equal(second.autoRefreshPrompt.reason, 'codex_auto_refresh_disabled');
+    assert.equal(second.autoRefreshPrompt.output, undefined);
+  } finally {
+    db.close();
+    rmSync(codexHome, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('codex-hook user-prompt-submit stays quiet below 75%', async () => {
   const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
@@ -281,7 +334,7 @@ test('codex-hook user-prompt-submit stays quiet below 75%', async () => {
 
     assert.equal(result.status, 'ok');
     assert.equal(result.autoRefreshPrompt.status, 'skipped');
-    assert.equal(result.autoRefreshPrompt.reason, 'below_threshold');
+    assert.equal(result.autoRefreshPrompt.reason, 'codex_auto_refresh_disabled');
     assert.equal(result.autoRefreshPrompt.output, undefined);
   } finally {
     db.close();
@@ -290,7 +343,7 @@ test('codex-hook user-prompt-submit stays quiet below 75%', async () => {
   }
 });
 
-test('codex-hook post-tool-use injects current-session throughline instruction at 75%', async () => {
+test('codex-hook post-tool-use does not inject auto-refresh instruction at 75%', async () => {
   const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
   const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
   const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
@@ -327,13 +380,9 @@ test('codex-hook post-tool-use injects current-session throughline instruction a
     });
 
     assert.equal(result.status, 'ok');
-    assert.equal(result.autoRefreshPrompt.status, 'ready');
-    assert.equal(result.autoRefreshPrompt.reason, 'threshold_reached');
-    assert.match(result.autoRefreshPrompt.context, /Before continuing the current tool loop/);
-    assert.match(result.autoRefreshPrompt.context, /throughline trim --execute --host codex --all --json/);
-    const output = JSON.parse(result.autoRefreshPrompt.output);
-    assert.equal(output.hookSpecificOutput.hookEventName, 'PostToolUse');
-    assert.match(output.hookSpecificOutput.additionalContext, /installed \$throughline workflow/);
+    assert.equal(result.autoRefreshPrompt.status, 'skipped');
+    assert.equal(result.autoRefreshPrompt.reason, 'codex_auto_refresh_disabled');
+    assert.equal(result.autoRefreshPrompt.output, undefined);
   } finally {
     db.close();
     rmSync(codexHome, { recursive: true, force: true });
@@ -380,6 +429,59 @@ test('codex-hook stop reports camelCase payload thread id source', async () => {
   }
 });
 
+test('codex-hook stop ignores auto-refresh backoff store while disabled', async () => {
+  const codexHome = mkdtempSync(join(tmpdir(), 'tl-codex-hook-home-'));
+  const project = mkdtempSync(join(tmpdir(), 'tl-codex-hook-project-'));
+  const threadId = '019dfaba-f87e-7f41-a144-d5ca7c6dd7f9';
+  const db = makeDb();
+  const autoRefreshStateStore = makeMemoryAutoRefreshStateStore();
+  try {
+    const rolloutPath = writeRollout(codexHome, {
+      id: threadId,
+      cwd: project,
+      events: [
+        event('user_message', { message: 'hook request' }),
+        event('task_started'),
+        turnContext({ model: 'gpt-5.5', cwd: project }),
+        event('agent_message', { message: 'hook answer' }),
+        event('task_complete'),
+        tokenCountEvent({
+          inputTokens: 240_000,
+          outputTokens: 67,
+          contextWindow: 258400,
+        }),
+      ],
+    });
+
+    const result = await runCodexStopHook({
+      payload: {
+        session_id: threadId,
+        transcript_path: rolloutPath,
+        cwd: project,
+      },
+      env: {},
+      db,
+      ensureMonitorTask: () => {},
+      writeMonitorState: () => {},
+      autoRefreshStateStore,
+      runAutoRefresh: async (args) => {
+        assert.fail('runAutoRefresh should not be called while Codex auto-refresh is disabled');
+        return {
+          status: 'skipped',
+          reason: 'auto_refresh_backoff',
+        };
+      },
+    });
+
+    assert.equal(result.status, 'ok');
+    assert.equal(result.autoRefresh.reason, 'codex_auto_refresh_disabled');
+  } finally {
+    db.close();
+    rmSync(codexHome, { recursive: true, force: true });
+    rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('codex-hook stop skips cleanly when Codex thread id is unavailable', async () => {
   const db = makeDb();
   try {
@@ -458,3 +560,16 @@ function tokenCountEvent({ inputTokens, outputTokens, contextWindow }) {
     },
   });
 }
+
+function makeMemoryAutoRefreshStateStore() {
+  const states = new Map();
+  return {
+    read(threadId) {
+      const state = states.get(threadId);
+      return state ? structuredClone(state) : null;
+    },
+    write(threadId, state) {
+      states.set(threadId, structuredClone(state));
+    },
+  };
+}

package/src/cli/codex-resume.mjs

@@ -5,6 +5,7 @@ import {
   renderCodexNewThreadHandoff,
   toCodexDeveloperMessageItem,
 } from '../codex-handoff.mjs';
+import { sameProjectPath } from '../project-path.mjs';
 
 const FORMATS = new Set(['text', 'handoff', 'item-json']);
 
@@ -75,16 +76,15 @@ function parseArgs(args) {
 }
 
 function findLatestCodexSessionId(db, projectPath) {
-  const row = db
+  const rows = db
     .prepare(
-      `SELECT session_id
+      `SELECT session_id, project_path
        FROM sessions
-       WHERE lower(project_path) = lower(?)
-         AND session_id LIKE 'codex:%'
-       ORDER BY updated_at DESC
-       LIMIT 1`,
+       WHERE session_id LIKE 'codex:%'
+       ORDER BY updated_at DESC`,
     )
-    .get(projectPath);
+    .all();
+  const row = rows.find((candidate) => sameProjectPath(candidate.project_path, projectPath));
   return row?.session_id ?? null;
 }
 

package/src/cli/codex-summarize.mjs

@@ -5,6 +5,7 @@ import {
   pickOldestUnsummarizedTurn,
 } from '../turn-processor.mjs';
 import { summarizeToL1 } from '../haiku-summarizer.mjs';
+import { sameProjectPath } from '../project-path.mjs';
 
 function parseArgs(args) {
   const out = {
@@ -51,16 +52,15 @@ function parseArgs(args) {
 }
 
 function findLatestCodexSessionId(db, projectPath) {
-  const row = db
+  const rows = db
     .prepare(
-      `SELECT session_id
+      `SELECT session_id, project_path
        FROM sessions
-       WHERE lower(project_path) = lower(?)
-         AND session_id LIKE 'codex:%'
-       ORDER BY updated_at DESC
-       LIMIT 1`,
+       WHERE session_id LIKE 'codex:%'
+       ORDER BY updated_at DESC`,
     )
-    .get(projectPath);
+    .all();
+  const row = rows.find((candidate) => sameProjectPath(candidate.project_path, projectPath));
   return row?.session_id ?? null;
 }
 

package/src/cli/handoff-preview.mjs

@@ -1,6 +1,7 @@
 import { getDb } from '../db.mjs';
 import { buildHandoffRecord } from '../handoff-record.mjs';
 import { toThroughlineHandoffBlock } from '../codex-handoff.mjs';
+import { sameProjectPath } from '../project-path.mjs';
 
 function parseArgs(args) {
   const out = {
@@ -33,15 +34,14 @@ function parseArgs(args) {
 }
 
 function findLatestSessionId(db, projectPath) {
-  const row = db
+  const rows = db
     .prepare(
-      `SELECT session_id
+      `SELECT session_id, project_path
        FROM sessions
-       WHERE lower(project_path) = lower(?)
-       ORDER BY updated_at DESC
-       LIMIT 1`,
+       ORDER BY updated_at DESC`,
     )
-    .get(projectPath);
+    .all();
+  const row = rows.find((candidate) => sameProjectPath(candidate.project_path, projectPath));
   return row?.session_id ?? null;
 }
 

package/src/cli/help.test.mjs

@@ -47,7 +47,9 @@ test('CLI help exposes guided Codex handoff and guarded execute semantics', () =
   for (const command of CODEX_HELP_COMMANDS) {
     assert.match(result.stdout, new RegExp(command.replaceAll('-', '\\-')));
   }
-  assert.match(result.stdout, /Guided read-only fresh-thread handoff start plan/);
+  assert.match(result.stdout, /Fresh-thread Codex handoff start plan/);
+  assert.match(result.stdout, /Use --execute to/);
+  assert.match(result.stdout, /--open-host auto\|vscode\|cli\|none/);
   assert.match(result.stdout, /throughline trim --execute/);
   assert.match(result.stdout, /injectable DB memory/);
   assert.match(result.stdout, /matching/);

package/src/cli/install.mjs

@@ -11,7 +11,7 @@
  * script path で登録する。
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, unlinkSync, rmSync, realpathSync } from 'node:fs';
 import { join, dirname, resolve, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -62,22 +62,58 @@ function quoteCommandPath(p) {
   return /\s/.test(p) ? `"${p.replace(/"/g, '\\"')}"` : p;
 }
 
+function safeRealpath(p, realpath = realpathSync.native) {
+  try {
+    return realpath(p);
+  } catch {
+    return null;
+  }
+}
+
+export function resolveCodexHookNodePath({
+  env = process.env,
+  execPath = process.execPath,
+  platform = process.platform,
+  exists = existsSync,
+  realpath = realpathSync.native,
+} = {}) {
+  const execRealpath = safeRealpath(execPath, realpath);
+  const pathEnv = env.PATH || env.Path || '';
+  const dirs = pathEnv.split(delimiter).filter(Boolean);
+  const names = platform === 'win32'
+    ? ['node.exe', 'node.cmd', 'node.bat', 'node']
+    : ['node'];
+
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (!exists(candidate)) continue;
+      const candidateRealpath = safeRealpath(candidate, realpath);
+      if (execRealpath && candidateRealpath && candidateRealpath === execRealpath) {
+        return candidate;
+      }
+    }
+  }
+
+  return execPath;
+}
+
 export function buildCodexStopHookCommand({
-  nodePath = process.execPath,
+  nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
 } = {}) {
   return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook stop`;
 }
 
 export function buildCodexUserPromptSubmitHookCommand({
-  nodePath = process.execPath,
+  nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
 } = {}) {
   return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook user-prompt-submit`;
 }
 
 export function buildCodexPostToolUseHookCommand({
-  nodePath = process.execPath,
+  nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
 } = {}) {
   return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook post-tool-use`;
@@ -490,8 +526,8 @@ export async function run(args = []) {
   console.log('  Stop             → throughline process-turn   (L1 要約 + L2 本文保存 + L3 詳細保存)');
   console.log('  UserPromptSubmit → throughline prompt-submit  (/tl & /clear バトン書き込み)');
   if (codex) {
-    console.log(`  Codex UserPromptSubmit → ${buildCodexUserPromptSubmitHookCommand()} (75% 到達時に current session へ $throughline 指示を注入)`);
-    console.log(`  Codex PostToolUse      → ${buildCodexPostToolUseHookCommand()} (tool loop 中も 75% 到達時に $throughline 指示を注入)`);
+    console.log(`  Codex UserPromptSubmit → ${buildCodexUserPromptSubmitHookCommand()} (capture / monitor state only; auto refresh disabled)`);
+    console.log(`  Codex PostToolUse      → ${buildCodexPostToolUseHookCommand()} (capture / monitor state only; auto refresh disabled)`);
     console.log(`  Codex Stop             → ${buildCodexStopHookCommand()} (Codex rollout capture + L1 要約)`);
   }
   console.log('');