oh-my-codex 0.14.0 → 0.14.2

package/src/scripts/__tests__/postinstall.test.ts

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import { writeUserInstallStamp } from "../../cli/update.js";
+import {
+  isGlobalInstallLifecycle,
+  runPostinstall,
+} from "../postinstall.js";
+
+describe("isGlobalInstallLifecycle", () => {
+  it("accepts npm_config_global=true", () => {
+    assert.equal(isGlobalInstallLifecycle({ npm_config_global: "true" }), true);
+  });
+
+  it("accepts npm_config_location=global", () => {
+    assert.equal(isGlobalInstallLifecycle({ npm_config_location: "global" }), true);
+  });
+
+  it("rejects local installs", () => {
+    assert.equal(isGlobalInstallLifecycle({ npm_config_global: "false" }), false);
+  });
+});
+
+describe("runPostinstall", () => {
+  it("runs interactive setup only for bumped global installs", async () => {
+    const root = await mkdtemp(join(tmpdir(), "omx-postinstall-"));
+    const stampPath = join(root, ".codex", ".omx", "install-state.json");
+    const logs: string[] = [];
+    let setupCalls = 0;
+
+    try {
+      const result = await runPostinstall({
+        env: { npm_config_global: "true" },
+        getCurrentVersion: async () => "0.14.1",
+        isInteractive: () => true,
+        log: (message) => logs.push(message),
+        readStamp: async () => ({
+          installed_version: "0.14.0",
+          setup_completed_version: "0.14.0",
+          updated_at: "2026-04-20T00:00:00.000Z",
+        }),
+        runSetup: async () => {
+          setupCalls += 1;
+        },
+        writeStamp: async (stamp) => writeUserInstallStamp(stamp, stampPath),
+      });
+
+      assert.equal(result.status, "setup-ran");
+      assert.equal(setupCalls, 1);
+      assert.match(logs.join("\n"), /Launching interactive setup/);
+
+      const stamp = JSON.parse(await readFile(stampPath, "utf-8")) as {
+        installed_version: string;
+        setup_completed_version: string;
+      };
+      assert.equal(stamp.installed_version, "0.14.1");
+      assert.equal(stamp.setup_completed_version, "0.14.1");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("records the installed version and prints a hint when no TTY is available", async () => {
+    const root = await mkdtemp(join(tmpdir(), "omx-postinstall-"));
+    const stampPath = join(root, ".codex", ".omx", "install-state.json");
+    const logs: string[] = [];
+    let setupCalls = 0;
+
+    try {
+      const result = await runPostinstall({
+        env: { npm_config_global: "true" },
+        getCurrentVersion: async () => "0.14.1",
+        isInteractive: () => false,
+        log: (message) => logs.push(message),
+        readStamp: async () => ({
+          installed_version: "0.14.0",
+          setup_completed_version: "0.14.0",
+          updated_at: "2026-04-20T00:00:00.000Z",
+        }),
+        runSetup: async () => {
+          setupCalls += 1;
+        },
+        writeStamp: async (stamp) => writeUserInstallStamp(stamp, stampPath),
+      });
+
+      assert.equal(result.status, "hinted");
+      assert.equal(setupCalls, 0);
+      assert.match(logs.join("\n"), /Run `omx setup` \(interactive\) or `omx update`/);
+
+      const stamp = JSON.parse(await readFile(stampPath, "utf-8")) as {
+        installed_version: string;
+        setup_completed_version: string;
+      };
+      assert.equal(stamp.installed_version, "0.14.1");
+      assert.equal(stamp.setup_completed_version, "0.14.0");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("skips local installs", async () => {
+    let setupCalls = 0;
+    const result = await runPostinstall({
+      env: { npm_config_global: "false" },
+      getCurrentVersion: async () => "0.14.1",
+      isInteractive: () => true,
+      runSetup: async () => {
+        setupCalls += 1;
+      },
+    });
+
+    assert.equal(result.status, "noop-local");
+    assert.equal(setupCalls, 0);
+  });
+
+  it("does not rerun setup when the installed version matches the saved stamp", async () => {
+    let setupCalls = 0;
+    const result = await runPostinstall({
+      env: { npm_config_global: "true" },
+      getCurrentVersion: async () => "0.14.1",
+      isInteractive: () => true,
+      readStamp: async () => ({
+        installed_version: "0.14.1",
+        setup_completed_version: "0.14.1",
+        updated_at: "2026-04-20T00:00:00.000Z",
+      }),
+      runSetup: async () => {
+        setupCalls += 1;
+      },
+    });
+
+    assert.equal(result.status, "noop-same-version");
+    assert.equal(setupCalls, 0);
+  });
+
+  it("warns and exits cleanly when setup fails", async () => {
+    const warnings: string[] = [];
+    const result = await runPostinstall({
+      env: { npm_config_global: "true" },
+      getCurrentVersion: async () => "0.14.1",
+      isInteractive: () => true,
+      readStamp: async () => ({
+        installed_version: "0.14.0",
+        setup_completed_version: "0.14.0",
+        updated_at: "2026-04-20T00:00:00.000Z",
+      }),
+      runSetup: async () => {
+        throw new Error("boom");
+      },
+      warn: (message) => warnings.push(message),
+      writeStamp: async () => {},
+    });
+
+    assert.equal(result.status, "setup-failed");
+    assert.match(warnings.join("\n"), /non-fatal error: boom/);
+  });
+
+  it("runs interactive setup from the npm install prefix instead of the package dir or INIT_CWD", async () => {
+    const installRoot = await mkdtemp(join(tmpdir(), "omx-postinstall-install-root-"));
+    const packageRoot = await mkdtemp(join(tmpdir(), "omx-postinstall-package-root-"));
+    const initCwd = await mkdtemp(join(tmpdir(), "omx-postinstall-init-cwd-"));
+    const originalCwd = process.cwd();
+    const scopeFile = join(installRoot, ".omx", "setup-scope.json");
+    const packageScopeFile = join(packageRoot, ".omx", "setup-scope.json");
+    const initCwdScopeFile = join(initCwd, ".omx", "setup-scope.json");
+
+    try {
+      process.chdir(packageRoot);
+
+      const result = await runPostinstall({
+        env: {
+          npm_config_global: "true",
+          npm_config_prefix: installRoot,
+          INIT_CWD: initCwd,
+        },
+        getCurrentVersion: async () => "0.14.1",
+        isInteractive: () => true,
+        readStamp: async () => ({
+          installed_version: "0.14.0",
+          setup_completed_version: "0.14.0",
+          updated_at: "2026-04-20T00:00:00.000Z",
+        }),
+        runSetup: async () => {
+          await mkdir(join(process.cwd(), ".omx"), { recursive: true });
+          await writeFile(
+            join(process.cwd(), ".omx", "setup-scope.json"),
+            JSON.stringify({ scope: "project" }),
+          );
+        },
+        writeStamp: async () => {},
+      });
+
+      assert.equal(result.status, "setup-ran");
+      assert.equal(process.cwd(), packageRoot);
+      assert.equal(
+        JSON.parse(await readFile(scopeFile, "utf-8")).scope,
+        "project",
+      );
+      await assert.rejects(() => readFile(packageScopeFile, "utf-8"));
+      await assert.rejects(() => readFile(initCwdScopeFile, "utf-8"));
+    } finally {
+      process.chdir(originalCwd);
+      await rm(installRoot, { recursive: true, force: true });
+      await rm(packageRoot, { recursive: true, force: true });
+      await rm(initCwd, { recursive: true, force: true });
+    }
+  });
+});

package/src/scripts/codex-native-hook.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { mkdir, readFile, readdir, writeFile } from "fs/promises";
 import { join, resolve } from "path";
+import { pathToFileURL } from "url";
 import { readModeState, readModeStateForSession, updateModeState } from "../modes/base.js";
 import {
   listActiveSkills,
@@ -9,7 +10,12 @@ import {
 } from "../state/skill-active.js";
 import { readSubagentSessionSummary } from "../subagents/tracker.js";
 import { resolveCanonicalTeamStateRoot } from "../team/state-root.js";
-import { readUsableSessionState, reconcileNativeSessionStart } from "../hooks/session.js";
+import {
+  isSessionStateUsable,
+  readSessionState,
+  readUsableSessionState,
+  reconcileNativeSessionStart,
+} from "../hooks/session.js";
 import {
   appendTeamEvent,
   readTeamLeaderAttention,
@@ -43,6 +49,7 @@ import {
 import type { HookEventEnvelope } from "../hooks/extensibility/types.js";
 import { dispatchHookEvent } from "../hooks/extensibility/dispatcher.js";
 import { reconcileHudForPromptSubmit } from "../hud/reconcile.js";
+import { shellEscapeSingle } from "../hud/tmux.js";
 import { onSessionStart as buildWikiSessionStartContext } from "../wiki/lifecycle.js";
 import { readAutoresearchCompletionStatus, readAutoresearchModeState } from "../autoresearch/skill-validation.js";
 import { shouldContinueRun } from "../runtime/run-loop.js";
@@ -56,6 +63,7 @@ import {
   type TriageStateFile,
 } from "../hooks/triage-state.js";
 import { isPendingDeepInterviewQuestionEnforcement } from "../question/deep-interview.js";
+import { resolveOmxCliEntryPath } from "../utils/paths.js";
 
 type CodexHookEventName =
   | "SessionStart"
@@ -203,15 +211,26 @@ function readPromptText(payload: CodexHookPayload): string {
 function sanitizePayloadForHookContext(
   payload: CodexHookPayload,
   hookEventName: CodexHookEventName,
+  canonicalSessionId = "",
 ): CodexHookPayload {
-  if (hookEventName !== "UserPromptSubmit") return payload;
-
   const sanitized = { ...payload };
-  delete sanitized.prompt;
-  delete sanitized.input;
-  delete sanitized.user_prompt;
-  delete sanitized.userPrompt;
-  delete sanitized.text;
+
+  if (hookEventName === "UserPromptSubmit") {
+    delete sanitized.prompt;
+    delete sanitized.input;
+    delete sanitized.user_prompt;
+    delete sanitized.userPrompt;
+    delete sanitized.text;
+    return sanitized;
+  }
+
+  if (hookEventName === "Stop") {
+    delete sanitized.stop_hook_active;
+    delete sanitized.stopHookActive;
+    delete sanitized.sessionId;
+    sanitized.session_id = canonicalSessionId.trim() || safeString(payload.session_id ?? payload.sessionId).trim();
+  }
+
   return sanitized;
 }
 
@@ -219,13 +238,14 @@ function buildBaseContext(
   cwd: string,
   payload: CodexHookPayload,
   hookEventName: CodexHookEventName,
+  canonicalSessionId = "",
 ): Record<string, unknown> {
   return {
     cwd,
     project_path: cwd,
     transcript_path: safeString(payload.transcript_path ?? payload.transcriptPath) || null,
     source: safeString(payload.source),
-    payload: sanitizePayloadForHookContext(payload, hookEventName),
+    payload: sanitizePayloadForHookContext(payload, hookEventName, canonicalSessionId),
   };
 }
 
@@ -264,17 +284,28 @@ async function readActiveRalphState(
   stateDir: string,
   preferredSessionId?: string,
 ): Promise<Record<string, unknown> | null> {
-  const sessionInfo = await readUsableSessionState(resolve(stateDir, "..", ".."));
-  const currentOmxSessionId = safeString(sessionInfo?.session_id).trim();
+  const cwd = resolve(stateDir, "..", "..");
+  const [rawSessionInfo, usableSessionInfo] = await Promise.all([
+    readSessionState(cwd),
+    readUsableSessionState(cwd),
+  ]);
+  const currentOmxSessionId = safeString(usableSessionInfo?.session_id).trim();
+  const staleCurrentSessionId = rawSessionInfo && !isSessionStateUsable(rawSessionInfo, cwd)
+    ? safeString(rawSessionInfo.session_id).trim()
+    : "";
   const sessionCandidates = [...new Set([
     safeString(preferredSessionId).trim(),
     currentOmxSessionId,
   ].filter(Boolean))];
 
+  // Ralph Stop stays authoritative-scope-only once the Stop payload is session-bound.
+  // That is intentionally stricter than generic state MCP reads: do not scan sibling
+  // session scopes or fall back to root when a current/explicit session is in play.
   for (const sessionId of sessionCandidates) {
-    const sessionScoped = await readJsonIfExists(
-      join(stateDir, "sessions", sessionId, "ralph-state.json"),
-    );
+    if (staleCurrentSessionId && sessionId === staleCurrentSessionId) {
+      continue;
+    }
+    const sessionScoped = await readStopSessionPinnedState("ralph-state.json", cwd, sessionId);
     if (sessionScoped?.active === true && shouldContinueRun(sessionScoped)) {
       return sessionScoped;
     }
@@ -287,17 +318,6 @@ async function readActiveRalphState(
     return direct;
   }
 
-  const sessionsRoot = join(stateDir, "sessions");
-  if (!existsSync(sessionsRoot)) return null;
-  const entries = await readdir(sessionsRoot, { withFileTypes: true }).catch(() => []);
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const candidate = await readJsonIfExists(join(sessionsRoot, entry.name, "ralph-state.json"));
-    if (candidate?.active === true && shouldContinueRun(candidate)) {
-      return candidate;
-    }
-  }
-
   return null;
 }
 
@@ -399,32 +419,55 @@ function resolveSessionOwnerPid(payload: CodexHookPayload): number {
   return process.pid;
 }
 
-async function ensureOmxGitignoreEntry(cwd: string): Promise<{ changed: boolean; gitignorePath?: string }> {
-  let repoRoot = "";
+function tryReadGitValue(cwd: string, args: string[]): string | null {
   try {
-    repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    const value = execFileSync("git", args, {
       cwd,
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
       windowsHide: true,
     }).trim();
+    return value || null;
   } catch {
-    return { changed: false };
+    return null;
   }
+}
+
+function isPathIgnoredByGit(cwd: string, path: string): boolean {
+  try {
+    execFileSync("git", ["check-ignore", "-q", path], {
+      cwd,
+      stdio: ["ignore", "ignore", "ignore"],
+      windowsHide: true,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureOmxLocalIgnoreEntry(cwd: string): Promise<{ changed: boolean; excludePath?: string }> {
+  const repoRoot = tryReadGitValue(cwd, ["rev-parse", "--show-toplevel"]);
   if (!repoRoot) return { changed: false };
+  if (isPathIgnoredByGit(repoRoot, ".omx/")) {
+    return { changed: false };
+  }
 
-  const gitignorePath = join(repoRoot, ".gitignore");
-  const existing = existsSync(gitignorePath)
-    ? await readFile(gitignorePath, "utf-8")
+  const excludePathValue = tryReadGitValue(repoRoot, ["rev-parse", "--git-path", "info/exclude"]);
+  if (!excludePathValue) return { changed: false };
+  const excludePath = resolve(repoRoot, excludePathValue);
+
+  const existing = existsSync(excludePath)
+    ? await readFile(excludePath, "utf-8")
     : "";
   const lines = existing.split(/\r?\n/).map((line) => line.trim());
   if (lines.includes(".omx/")) {
-    return { changed: false, gitignorePath };
+    return { changed: false, excludePath };
   }
 
   const next = `${existing}${existing.endsWith("\n") || existing.length === 0 ? "" : "\n"}.omx/\n`;
-  await writeFile(gitignorePath, next);
-  return { changed: true, gitignorePath };
+  await writeFile(excludePath, next);
+  return { changed: true, excludePath };
 }
 
 async function buildSessionStartContext(
@@ -433,9 +476,9 @@ async function buildSessionStartContext(
 ): Promise<string | null> {
   const sections: string[] = [];
 
-  const gitignoreResult = await ensureOmxGitignoreEntry(cwd);
-  if (gitignoreResult.changed) {
-    sections.push(`Added .omx/ to ${gitignoreResult.gitignorePath} to keep local OMX state out of source control.`);
+  const localIgnoreResult = await ensureOmxLocalIgnoreEntry(cwd);
+  if (localIgnoreResult.changed) {
+    sections.push(`Added .omx/ to ${localIgnoreResult.excludePath} to keep local OMX state out of source control without mutating tracked repo ignores.`);
   }
 
   const modeSummaries: string[] = [];
@@ -523,7 +566,17 @@ async function buildSessionStartContext(
   return sections.length > 0 ? sections.join("\n\n") : null;
 }
 
-function buildAdditionalContextMessage(prompt: string, skillState?: SkillActiveState | null): string | null {
+function buildDeepInterviewQuestionBridgeInstruction(cwd: string): string {
+  const omxBin = resolveOmxCliEntryPath({ cwd }) || process.argv[1] || "omx";
+  const bridgeCommand = `${shellEscapeSingle(process.execPath)} ${shellEscapeSingle(omxBin)} question`;
+  return `Deep-interview must ask each interview round via \`omx question\`; do not fall back to \`request_user_input\` or plain-text questioning. After starting \`omx question\` in a background terminal, wait for that terminal to finish and read the JSON answer before continuing the interview. If bare \`omx question\` is unavailable in this reused session, use the current-session CLI bridge command: \`${bridgeCommand}\`. Stop remains blocked while a deep-interview question obligation is pending.`;
+}
+
+function buildAdditionalContextMessage(
+  prompt: string,
+  skillState?: SkillActiveState | null,
+  cwd: string = process.cwd(),
+): string | null {
   if (!prompt) return null;
   const promptPriorityMessage = buildPromptPriorityMessage(prompt);
   const matches = detectKeywords(prompt);
@@ -543,7 +596,7 @@ function buildAdditionalContextMessage(prompt: string, skillState?: SkillActiveS
     ? "Prompt-side `$ralph` activation seeds Ralph workflow state only; it does not invoke `omx ralph`. Use `omx ralph --prd ...` only when you explicitly want the PRD-gated CLI startup path."
     : null;
   const deepInterviewPromptActivationNote = skillState?.initialized_mode === "deep-interview"
-    ? "Deep-interview must ask each interview round via `omx question`; do not fall back to `request_user_input` or plain-text questioning. Stop remains blocked while a deep-interview question obligation is pending."
+    ? buildDeepInterviewQuestionBridgeInstruction(cwd)
     : null;
   const combinedTransitionMessage = (() => {
     if (!skillState?.transition_message) return null;
@@ -997,7 +1050,11 @@ async function buildDeepInterviewQuestionStopOutput(
   threadId: string,
 ): Promise<{ output: Record<string, unknown>; obligationId: string } | null> {
   const modeState = await readStopSessionPinnedState("deep-interview-state.json", cwd, sessionId);
-  if (!modeState || modeState.active !== true) return null;
+  if (!modeState) return null;
+
+  const questionEnforcement = safeObject(modeState.question_enforcement);
+  const hasPendingQuestionObligation = isPendingDeepInterviewQuestionEnforcement(questionEnforcement);
+  if (modeState.active !== true && !hasPendingQuestionObligation) return null;
 
   const phase = formatPhase(modeState.current_phase, "planning");
   if (TERMINAL_MODE_PHASES.has(phase.toLowerCase()) || phase === "completing") {
@@ -1013,8 +1070,7 @@ async function buildDeepInterviewQuestionStopOutput(
     if (!blocker) return null;
   }
 
-  const questionEnforcement = safeObject(modeState.question_enforcement);
-  if (!isPendingDeepInterviewQuestionEnforcement(questionEnforcement)) {
+  if (!hasPendingQuestionObligation) {
     return null;
   }
 
@@ -1148,6 +1204,7 @@ async function returnPersistentStopBlock(
   signatureValue: string,
   output: Record<string, unknown> | null,
   canonicalSessionId?: string,
+  options: { allowRepeatDuringStopHook?: boolean } = { allowRepeatDuringStopHook: true },
 ): Promise<Record<string, unknown> | null> {
   return await maybeReturnRepeatableStopOutput(
     payload,
@@ -1155,7 +1212,7 @@ async function returnPersistentStopBlock(
     buildRepeatableStopSignature(payload, signatureKind, signatureValue, canonicalSessionId),
     output,
     canonicalSessionId,
-    { allowRepeatDuringStopHook: true },
+    options,
   );
 }
 
@@ -1438,6 +1495,7 @@ async function buildStopHookOutput(
         safeString(ultraworkOutput.stopReason),
         ultraworkOutput,
         canonicalSessionId,
+        { allowRepeatDuringStopHook: false },
       );
     }
 
@@ -1587,19 +1645,37 @@ export async function dispatchCodexNativeHook(
   const nativeSessionId = safeString(payload.session_id ?? payload.sessionId).trim();
   const threadId = safeString(payload.thread_id ?? payload.threadId).trim();
   const turnId = safeString(payload.turn_id ?? payload.turnId).trim();
-  let canonicalSessionId = safeString((await readUsableSessionState(cwd))?.session_id).trim();
+  const currentSessionState = await readUsableSessionState(cwd);
+  let canonicalSessionId = safeString(currentSessionState?.session_id).trim();
+  let resolvedNativeSessionId = nativeSessionId;
 
   if (hookEventName === "SessionStart" && nativeSessionId) {
     const sessionState = await reconcileNativeSessionStart(cwd, nativeSessionId, {
       pid: options.sessionOwnerPid ?? resolveSessionOwnerPid(payload),
     });
     canonicalSessionId = safeString(sessionState.session_id).trim();
+    resolvedNativeSessionId = safeString(sessionState.native_session_id).trim() || nativeSessionId;
   } else if (!canonicalSessionId) {
-    canonicalSessionId = safeString((await readUsableSessionState(cwd))?.session_id).trim();
+    canonicalSessionId = safeString(currentSessionState?.session_id).trim();
+  }
+
+  if (hookEventName === "Stop") {
+    const stopCanonicalSessionId = await resolveInternalSessionIdForPayload(
+      cwd,
+      readPayloadSessionId(payload),
+    );
+    if (stopCanonicalSessionId) {
+      canonicalSessionId = stopCanonicalSessionId;
+    }
+    if (canonicalSessionId && safeString(currentSessionState?.session_id).trim() === canonicalSessionId) {
+      resolvedNativeSessionId =
+        safeString(currentSessionState?.native_session_id).trim() || resolvedNativeSessionId;
+    }
   }
 
   const eventSessionId = canonicalSessionId || nativeSessionId || undefined;
   const sessionIdForState = canonicalSessionId || nativeSessionId;
+  let outputJson: Record<string, unknown> | null = null;
 
   if (hookEventName === "UserPromptSubmit") {
     const prompt = readPromptText(payload);
@@ -1684,10 +1760,10 @@ export async function dispatchCodexNativeHook(
   }
 
   if (omxEventName) {
-    const baseContext = buildBaseContext(cwd, payload, hookEventName!);
-    if (nativeSessionId) {
-      baseContext.native_session_id = nativeSessionId;
-      baseContext.codex_session_id = nativeSessionId;
+    const baseContext = buildBaseContext(cwd, payload, hookEventName!, canonicalSessionId);
+    if (resolvedNativeSessionId) {
+      baseContext.native_session_id = resolvedNativeSessionId;
+      baseContext.codex_session_id = resolvedNativeSessionId;
     }
     if (canonicalSessionId) {
       baseContext.omx_session_id = canonicalSessionId;
@@ -1705,11 +1781,10 @@ export async function dispatchCodexNativeHook(
     await dispatchHookEvent(event, { cwd });
   }
 
-  let outputJson: Record<string, unknown> | null = null;
   if (hookEventName === "SessionStart" || hookEventName === "UserPromptSubmit") {
     const additionalContext = hookEventName === "SessionStart"
       ? await buildSessionStartContext(cwd, canonicalSessionId || nativeSessionId)
-      : (buildAdditionalContextMessage(readPromptText(payload), skillState) ?? triageAdditionalContext);
+      : (buildAdditionalContextMessage(readPromptText(payload), skillState, cwd) ?? triageAdditionalContext);
     if (additionalContext) {
       outputJson = {
         hookSpecificOutput: {
@@ -1742,6 +1817,14 @@ interface NativeHookCliReadResult {
   parseError: Error | null;
 }
 
+export function isCodexNativeHookMainModule(
+  moduleUrl: string,
+  argv1: string | undefined,
+): boolean {
+  if (!argv1) return false;
+  return moduleUrl === pathToFileURL(argv1).href;
+}
+
 async function readStdinJson(): Promise<NativeHookCliReadResult> {
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) {
@@ -1786,7 +1869,7 @@ export async function runCodexNativeHookCli(): Promise<void> {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isCodexNativeHookMainModule(import.meta.url, process.argv[1])) {
   runCodexNativeHookCli().catch((error) => {
     process.stderr.write(
       `[omx] codex-native-hook failed: ${

package/src/scripts/postinstall-bootstrap.js

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const distScriptPath = join(__dirname, "..", "..", "dist", "scripts", "postinstall.js");
+
+if (!existsSync(distScriptPath)) {
+  process.exit(0);
+}
+
+const moduleUrl = pathToFileURL(distScriptPath).href;
+try {
+  const postinstallModule = await import(moduleUrl);
+  if (typeof postinstallModule.main === "function") {
+    await postinstallModule.main();
+  }
+} catch (error) {
+  console.warn(
+    `[omx] Postinstall bootstrap skipped after a non-fatal error: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}