oh-my-codex 0.11.13 → 0.12.1

package/dist/cli/index.js

@@ -4,7 +4,7 @@
  */
 import { execFileSync, spawn } from "child_process";
 import { basename, dirname, join } from "path";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { constants as osConstants } from "os";
 import { setup, SETUP_SCOPES } from "./setup.js";
 import { uninstall } from "./uninstall.js";
@@ -30,9 +30,10 @@ import { generateOverlay, removeSessionModelInstructionsFile, resolveSessionOrch
 import { readSessionState, writeSessionStart, writeSessionEnd, resetSessionMetrics, } from "../hooks/session.js";
 import { buildClientAttachedReconcileHookName, buildReconcileHudResizeArgs, buildRegisterClientAttachedReconcileArgs, buildRegisterResizeHookArgs, buildResizeHookName, buildResizeHookTarget, buildScheduleDelayedHudResizeArgs, buildUnregisterClientAttachedReconcileArgs, buildUnregisterResizeHookArgs, enableMouseScrolling, isMsysOrGitBash, isNativeWindows, isTmuxAvailable, } from "../team/tmux-session.js";
 import { getPackageRoot } from "../utils/package.js";
-import { codexConfigPath } from "../utils/paths.js";
+import { codexConfigPath, rememberOmxLaunchContext, resolveOmxEntryPath } from "../utils/paths.js";
 import { repairConfigIfNeeded } from "../config/generator.js";
 import { HUD_TMUX_HEIGHT_LINES } from "../hud/constants.js";
+rememberOmxLaunchContext();
 import { classifySpawnError, spawnPlatformCommandSync, } from "../utils/platform-command.js";
 import { buildHookEvent } from "../hooks/extensibility/events.js";
 import { dispatchHookEvent } from "../hooks/extensibility/dispatcher.js";
@@ -100,6 +101,7 @@ Options:
   --madmax-spark  spark model for workers + bypass approvals for leader and workers
                 (shorthand for: --spark --madmax)
   --notify-temp  Enable temporary notification routing for this run/session only
+  --tmux         Launch the interactive leader session in detached tmux
   --discord      Select Discord provider for temporary notification mode
   --slack        Select Slack provider for temporary notification mode
   --telegram     Select Telegram provider for temporary notification mode
@@ -146,6 +148,11 @@ const ALLOWED_SHELLS = new Set([
 ]);
 const WINDOWS_DETACHED_BOOTSTRAP_DELAY_MS = 2500;
 const CODEX_VERSION_FLAGS = new Set(["--version", "-V"]);
+const TMUX_EXTENDED_KEYS_MODE = "always";
+const TMUX_EXTENDED_KEYS_FALLBACK_MODE = "off";
+const TMUX_EXTENDED_KEYS_LEASE_DIR = "tmux-extended-keys";
+const TMUX_EXTENDED_KEYS_LOCK_RETRY_MS = 20;
+const TMUX_EXTENDED_KEYS_LOCK_MAX_ATTEMPTS = 100;
 const NESTED_HELP_COMMANDS = new Set([
     "ask",
     "cleanup",
@@ -258,9 +265,40 @@ export function resolveNotifyTempContract(args, env = process.env) {
 export function commandOwnsLocalHelp(command) {
     return NESTED_HELP_COMMANDS.has(command);
 }
-export function resolveCodexLaunchPolicy(env = process.env, _platform = process.platform, tmuxAvailable = isTmuxAvailable(), nativeWindows = isNativeWindows(), stdinIsTTY = Boolean(process.stdin.isTTY), stdoutIsTTY = Boolean(process.stdout.isTTY)) {
+function splitLeaderLaunchPolicyArgs(args) {
+    const remainingArgs = [];
+    let explicitPolicy;
+    let passthroughOnly = false;
+    for (const arg of args) {
+        if (passthroughOnly) {
+            remainingArgs.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            passthroughOnly = true;
+            remainingArgs.push(arg);
+            continue;
+        }
+        if (arg === "--tmux") {
+            explicitPolicy = "detached-tmux";
+            continue;
+        }
+        remainingArgs.push(arg);
+    }
+    return { explicitPolicy, remainingArgs };
+}
+export function resolveLeaderLaunchPolicyOverride(args) {
+    return splitLeaderLaunchPolicyArgs(args).explicitPolicy;
+}
+export function resolveCodexLaunchPolicy(env = process.env, _platform = process.platform, tmuxAvailable = isTmuxAvailable(), nativeWindows = isNativeWindows(), stdinIsTTY = Boolean(process.stdin.isTTY), stdoutIsTTY = Boolean(process.stdout.isTTY), explicitPolicy) {
     if (env.TMUX)
         return "inside-tmux";
+    if (explicitPolicy === "detached-tmux")
+        return tmuxAvailable ? "detached-tmux" : "direct";
+    if (explicitPolicy === "direct")
+        return "direct";
+    if (_platform === "win32")
+        return "direct";
     if (nativeWindows)
         return "direct";
     if (!stdinIsTTY || !stdoutIsTTY)
@@ -622,8 +660,9 @@ export async function launchWithHud(args) {
     const launchCwd = process.cwd();
     const parsedWorktree = parseWorktreeMode(args);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
+    const explicitLaunchPolicy = resolveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs);
     const codexHomeOverride = resolveCodexHomeForLaunch(launchCwd, process.env);
-    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, isNativeWindows());
+    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, isNativeWindows(), undefined, undefined, explicitLaunchPolicy);
     const enableNotifyFallbackAuthority = launchPolicy === "direct";
     const workerSparkModel = resolveWorkerSparkModel(notifyTempResult.passthroughArgs, codexHomeOverride);
     const normalizedArgs = normalizeCodexLaunchArgs(notifyTempResult.passthroughArgs);
@@ -661,7 +700,7 @@ export async function launchWithHud(args) {
     try {
         const repaired = await repairConfigIfNeeded(codexConfigPath(), getPackageRoot());
         if (repaired) {
-            console.log("[omx] Repaired duplicate [tui] section in config.toml.");
+            console.log("[omx] Repaired managed config.toml compatibility issue.");
         }
     }
     catch {
@@ -680,7 +719,7 @@ export async function launchWithHud(args) {
         const notifyTempContractRaw = notifyTempResult.contract.active
             ? serializeNotifyTempContract(notifyTempResult.contract)
             : null;
-        runCodex(cwd, normalizedArgs, sessionId, workerSparkModel, codexHomeOverride, notifyTempContractRaw);
+        runCodex(cwd, normalizedArgs, sessionId, workerSparkModel, codexHomeOverride, notifyTempContractRaw, explicitLaunchPolicy);
     }
     finally {
         // ── Phase 3: postLaunch ─────────────────────────────────────────────
@@ -721,7 +760,7 @@ export async function execWithOverlay(args) {
     try {
         const repaired = await repairConfigIfNeeded(codexConfigPath(), getPackageRoot());
         if (repaired) {
-            console.log("[omx] Repaired duplicate [tui] section in config.toml.");
+            console.log("[omx] Repaired managed config.toml compatibility issue.");
         }
     }
     catch {
@@ -755,11 +794,12 @@ export async function execWithOverlay(args) {
 }
 export function normalizeCodexLaunchArgs(args) {
     const parsed = parseWorktreeMode(args);
+    const launchPolicyParsed = splitLeaderLaunchPolicyArgs(parsed.remainingArgs);
     const normalized = [];
     let wantsBypass = false;
     let hasBypass = false;
     let reasoningMode = null;
-    for (const arg of parsed.remainingArgs) {
+    for (const arg of launchPolicyParsed.remainingArgs) {
         if (arg === MADMAX_FLAG) {
             wantsBypass = true;
             continue;
@@ -1050,20 +1090,191 @@ function detectDetachedSessionWindowIndex(sessionName) {
 function escapeShellDoubleQuotedValue(value) {
     return value.replace(/["\\$`]/g, "\\$&");
 }
-function buildDetachedSessionLeaderCommand(sessionName, codexCmd) {
-    const cleanupTrap = [
+function sanitizeTmuxLeaseKey(value) {
+    const cleaned = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "default";
+}
+function blockMs(ms) {
+    const delay = Math.max(1, Math.floor(ms));
+    const shared = new SharedArrayBuffer(4);
+    const view = new Int32Array(shared);
+    Atomics.wait(view, 0, 0, delay);
+}
+function tmuxExtendedKeysLeaseRoot(cwd) {
+    return join(cwd, ".omx", "state", TMUX_EXTENDED_KEYS_LEASE_DIR);
+}
+function resolveTmuxSocketPath(execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
+    encoding: "utf-8",
+})) {
+    return (execTmuxSync(["display-message", "-p", "#{socket_path}"], execFileSyncImpl) ||
+        "default");
+}
+function tmuxExtendedKeysLeasePath(cwd, socketPath) {
+    return join(tmuxExtendedKeysLeaseRoot(cwd), `${sanitizeTmuxLeaseKey(socketPath)}.json`);
+}
+function readTmuxExtendedKeysLeaseState(leasePath) {
+    if (!existsSync(leasePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(leasePath, "utf-8"));
+        if (typeof parsed.originalMode !== "string" ||
+            !Array.isArray(parsed.holders) ||
+            !parsed.holders.every((holder) => typeof holder === "string")) {
+            return null;
+        }
+        return {
+            originalMode: parsed.originalMode,
+            holders: [...parsed.holders],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeTmuxExtendedKeysLeaseState(leasePath, state) {
+    mkdirSync(dirname(leasePath), { recursive: true });
+    writeFileSync(leasePath, JSON.stringify(state, null, 2));
+}
+function withTmuxExtendedKeysLeaseLock(cwd, socketPath, run) {
+    const leaseRoot = tmuxExtendedKeysLeaseRoot(cwd);
+    mkdirSync(leaseRoot, { recursive: true });
+    const lockPath = join(leaseRoot, `${sanitizeTmuxLeaseKey(socketPath)}.lock`);
+    for (let attempt = 0; attempt < TMUX_EXTENDED_KEYS_LOCK_MAX_ATTEMPTS; attempt++) {
+        try {
+            mkdirSync(lockPath);
+            try {
+                return run();
+            }
+            finally {
+                rmSync(lockPath, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            const code = err && typeof err === "object" && "code" in err
+                ? String(err.code)
+                : "";
+            if (code !== "EEXIST")
+                throw err;
+            blockMs(TMUX_EXTENDED_KEYS_LOCK_RETRY_MS);
+        }
+    }
+    throw new Error(`timed out waiting for tmux extended-keys lease lock: ${lockPath}`);
+}
+function buildDetachedSessionLeaderCommand(cwd, sessionName, codexCmd) {
+    const wrapped = [
+        buildTmuxExtendedKeysAcquireShellSnippet(cwd),
+        "omx_detached_session_cleanup() {",
         "status=$?;",
         "trap - 0 INT TERM HUP;",
+        buildTmuxExtendedKeysReleaseShellSnippet(cwd),
         `tmux kill-session -t "${escapeShellDoubleQuotedValue(sessionName)}" >/dev/null 2>&1 || true;`,
         "exit $status;",
+        "};",
+        "trap omx_detached_session_cleanup 0 INT TERM HUP;",
+        codexCmd,
     ].join(" ");
-    const wrapped = [`trap '${cleanupTrap}' 0 INT TERM HUP;`, codexCmd].join(" ");
     return `/bin/sh -lc ${quoteShellArg(wrapped)}`;
 }
+function execTmuxSync(args, execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
+    encoding: "utf-8",
+})) {
+    return execFileSyncImpl("tmux", [...args]).trim();
+}
+export function acquireTmuxExtendedKeysLease(cwd, execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
+    encoding: "utf-8",
+})) {
+    try {
+        const socketPath = resolveTmuxSocketPath(execFileSyncImpl);
+        const leasePath = tmuxExtendedKeysLeasePath(cwd, socketPath);
+        const leaseId = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        withTmuxExtendedKeysLeaseLock(cwd, socketPath, () => {
+            const state = readTmuxExtendedKeysLeaseState(leasePath);
+            if (!state || state.holders.length === 0) {
+                const previousMode = execTmuxSync(["show-options", "-sv", "extended-keys"], execFileSyncImpl) ||
+                    TMUX_EXTENDED_KEYS_FALLBACK_MODE;
+                execTmuxSync(["set-option", "-sq", "extended-keys", TMUX_EXTENDED_KEYS_MODE], execFileSyncImpl);
+                writeTmuxExtendedKeysLeaseState(leasePath, {
+                    originalMode: previousMode,
+                    holders: [leaseId],
+                });
+                return;
+            }
+            state.holders.push(leaseId);
+            writeTmuxExtendedKeysLeaseState(leasePath, state);
+        });
+        return `${socketPath}\t${leaseId}`;
+    }
+    catch (err) {
+        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        return null;
+    }
+}
+export function releaseTmuxExtendedKeysLease(cwd, leaseHandle, execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
+    encoding: "utf-8",
+})) {
+    if (!leaseHandle.trim())
+        return;
+    const [socketPathRaw = "", leaseId = ""] = leaseHandle.split("\t");
+    const socketPath = socketPathRaw.trim() || "default";
+    if (!leaseId)
+        return;
+    try {
+        const leasePath = tmuxExtendedKeysLeasePath(cwd, socketPath);
+        withTmuxExtendedKeysLeaseLock(cwd, socketPath, () => {
+            const state = readTmuxExtendedKeysLeaseState(leasePath);
+            if (!state || state.holders.length === 0) {
+                rmSync(leasePath, { force: true });
+                return;
+            }
+            const holders = state.holders.filter((holder) => holder !== leaseId);
+            if (holders.length > 0) {
+                writeTmuxExtendedKeysLeaseState(leasePath, {
+                    originalMode: state.originalMode,
+                    holders,
+                });
+                return;
+            }
+            execTmuxSync(["set-option", "-sq", "extended-keys", state.originalMode], execFileSyncImpl);
+            rmSync(leasePath, { force: true });
+        });
+    }
+    catch (err) {
+        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+    }
+}
+function buildTmuxExtendedKeysHelperCommand(cwd, operation) {
+    const cwdLiteral = JSON.stringify(cwd);
+    const moduleUrlLiteral = JSON.stringify(import.meta.url);
+    const script = operation === "acquire"
+        ? `const mod = await import(${moduleUrlLiteral}); const lease = mod.acquireTmuxExtendedKeysLease(${cwdLiteral}); if (lease) process.stdout.write(lease);`
+        : `const mod = await import(${moduleUrlLiteral}); mod.releaseTmuxExtendedKeysLease(${cwdLiteral}, process.argv[1] ?? "");`;
+    return `${quoteShellArg(process.execPath)} --input-type=module -e ${quoteShellArg(script)}`;
+}
+function buildTmuxExtendedKeysAcquireShellSnippet(cwd) {
+    return `OMX_TMUX_EXTENDED_KEYS_LEASE=$(${buildTmuxExtendedKeysHelperCommand(cwd, "acquire")} 2>/dev/null || true);`;
+}
+function buildTmuxExtendedKeysReleaseShellSnippet(cwd) {
+    return `if [ -n "\${OMX_TMUX_EXTENDED_KEYS_LEASE:-}" ]; then ${buildTmuxExtendedKeysHelperCommand(cwd, "release")} "\${OMX_TMUX_EXTENDED_KEYS_LEASE}" >/dev/null 2>&1 || true; fi;`;
+}
+export function withTmuxExtendedKeys(cwd, run, execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
+    encoding: "utf-8",
+})) {
+    const leaseHandle = acquireTmuxExtendedKeysLease(cwd, execFileSyncImpl);
+    try {
+        return run();
+    }
+    finally {
+        if (leaseHandle)
+            releaseTmuxExtendedKeysLease(cwd, leaseHandle, execFileSyncImpl);
+    }
+}
 export function buildDetachedSessionBootstrapSteps(sessionName, cwd, codexCmd, hudCmd, workerLaunchArgs, codexHomeOverride, notifyTempContractRaw, nativeWindows = false, sessionId) {
     const detachedLeaderCmd = nativeWindows
         ? "powershell.exe"
-        : buildDetachedSessionLeaderCommand(sessionName, codexCmd);
+        : buildDetachedSessionLeaderCommand(cwd, sessionName, codexCmd);
     const newSessionArgs = [
         "new-session",
         "-d",
@@ -1197,6 +1408,13 @@ export function buildNotifyFallbackWatcherEnv(env = process.env, options = {}) {
         OMX_HUD_AUTHORITY: options.enableAuthority ? "1" : "0",
     };
 }
+export function shouldEnableNotifyFallbackWatcher(env = process.env, platform = process.platform) {
+    const toggle = String(env.OMX_NOTIFY_FALLBACK ?? "").trim();
+    if (platform === "win32") {
+        return toggle === "1";
+    }
+    return toggle !== "0";
+}
 export async function cleanupLaunchOrphanedMcpProcesses(dependencies = {}) {
     return cleanupOmxMcpProcesses([], {
         ...dependencies,
@@ -1204,6 +1422,24 @@ export async function cleanupLaunchOrphanedMcpProcesses(dependencies = {}) {
         writeLine: dependencies.writeLine ?? (() => { }),
     });
 }
+export async function reapPostLaunchOrphanedMcpProcesses(dependencies = {}) {
+    const cleanup = dependencies.cleanup ?? cleanupLaunchOrphanedMcpProcesses;
+    const writeInfo = dependencies.writeInfo ?? console.log;
+    const writeWarn = dependencies.writeWarn ?? console.warn;
+    const writeError = dependencies.writeError ?? ((line) => process.stderr.write(line));
+    try {
+        const result = await cleanup();
+        if (result.terminatedCount > 0) {
+            writeInfo(`[omx] postLaunch: reaped ${result.terminatedCount} orphaned OMX MCP process(es).`);
+        }
+        if (result.failedPids.length > 0) {
+            writeWarn(`[omx] postLaunch: failed to reap ${result.failedPids.length} orphaned OMX MCP process(es); continuing cleanup.`);
+        }
+    }
+    catch (err) {
+        writeError(`[cli/index] postLaunch MCP cleanup failed: ${err}\n`);
+    }
+}
 /**
  * preLaunch: Prepare environment before Codex starts.
  * 1. Best-effort launch-safe orphan cleanup for detached OMX MCP processes
@@ -1307,10 +1543,13 @@ ${launchAppendix}`
  * runCodex: Launch Codex CLI (blocks until exit).
  * All 3 paths (new tmux, existing tmux, no tmux) block via execSync/execFileSync.
  */
-function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, notifyTempContractRaw) {
+function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, notifyTempContractRaw, explicitLaunchPolicy) {
     const launchArgs = injectModelInstructionsBypassArgs(cwd, args, process.env, sessionModelInstructionsPath(cwd, sessionId));
     const nativeWindows = isNativeWindows();
-    const omxBin = process.argv[1];
+    const omxBin = resolveOmxEntryPath();
+    if (!omxBin) {
+        throw new Error("Unable to resolve OMX launcher path for tmux HUD bootstrap");
+    }
     const hudCmd = nativeWindows
         ? buildWindowsPromptCommand("node", [omxBin, "hud", "--watch"])
         : buildTmuxPaneCommand("node", [omxBin, "hud", "--watch"]);
@@ -1326,7 +1565,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
     const codexEnvWithNotify = notifyTempContractRaw
         ? { ...codexEnv, [OMX_NOTIFY_TEMP_CONTRACT_ENV]: notifyTempContractRaw }
         : codexEnv;
-    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, nativeWindows);
+    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, nativeWindows, undefined, undefined, explicitLaunchPolicy);
     if (isCodexVersionRequest(launchArgs)) {
         runCodexBlocking(cwd, launchArgs, codexEnvWithNotify);
         return;
@@ -1376,7 +1615,9 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
             catch { }
         }
         try {
-            runCodexBlocking(cwd, launchArgs, codexEnvWithNotify);
+            withTmuxExtendedKeys(cwd, () => {
+                runCodexBlocking(cwd, launchArgs, codexEnvWithNotify);
+            });
         }
         finally {
             const cleanupPaneIds = buildHudPaneCleanupTargets(listHudWatchPaneIdsInCurrentWindow(currentPaneId), hudPaneId, currentPaneId);
@@ -1598,6 +1839,8 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         process.stderr.write(`[cli/index] operation failed: ${err}\n`);
         // Non-fatal
     }
+    // 0. Reap MCP orphans left behind by the session that just exited.
+    await reapPostLaunchOrphanedMcpProcesses();
     // 0. Flush fallback watcher once to reduce race with fast codex exit.
     try {
         await flushNotifyFallbackOnce(cwd, { codexHomeOverride, enableAuthority: enableNotifyFallbackAuthority, sessionId });
@@ -1685,6 +1928,15 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         process.stderr.write(`[cli/index] operation failed: ${err}\n`);
         // Non-fatal: notification failures must never block session cleanup
     }
+    // 4.5. Persist team leader attention when an active leader session exits.
+    try {
+        const { markOwnedTeamsLeaderSessionStopped } = await import("../team/state.js");
+        await markOwnedTeamsLeaderSessionStopped(cwd, sessionId);
+    }
+    catch (err) {
+        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        // Non-fatal
+    }
     // 5. Dispatch native hook event (best effort)
     try {
         const durationMs = sessionStartedAt
@@ -1811,6 +2063,30 @@ function parseWatcherPidFile(content) {
         return Number.isFinite(pid) && pid > 0 ? pid : null;
     }
 }
+export async function reapStaleNotifyFallbackWatcher(pidPath, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    if (!exists(pidPath))
+        return;
+    const { readFile } = await import("fs/promises");
+    const readFileImpl = deps.readFile ?? readFile;
+    const tryKillPidImpl = deps.tryKillPid ?? tryKillPid;
+    const hasErrnoCodeImpl = deps.hasErrnoCode ?? hasErrnoCode;
+    const warn = deps.warn ?? console.warn;
+    try {
+        const prevPid = parseWatcherPidFile(await readFileImpl(pidPath, "utf-8"));
+        if (prevPid) {
+            tryKillPidImpl(prevPid, "SIGTERM");
+        }
+    }
+    catch (error) {
+        if (!hasErrnoCodeImpl(error, "ESRCH")) {
+            warn("[omx] warning: failed to stop stale notify fallback watcher", {
+                path: pidPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
 function tryKillPid(pid, signal = "SIGTERM") {
     try {
         process.kill(pid, signal);
@@ -1824,32 +2100,16 @@ function tryKillPid(pid, signal = "SIGTERM") {
     }
 }
 async function startNotifyFallbackWatcher(cwd, options = {}) {
-    if (process.env.OMX_NOTIFY_FALLBACK === "0")
-        return;
-    const { mkdir, writeFile, readFile } = await import("fs/promises");
+    const { mkdir, writeFile } = await import("fs/promises");
     const pidPath = notifyFallbackPidPath(cwd);
+    await reapStaleNotifyFallbackWatcher(pidPath);
+    if (!shouldEnableNotifyFallbackWatcher(process.env, process.platform))
+        return;
     const pkgRoot = getPackageRoot();
     const watcherScript = resolveNotifyFallbackWatcherScript(pkgRoot);
     const notifyScript = resolveNotifyHookScript(pkgRoot);
     if (!existsSync(watcherScript) || !existsSync(notifyScript))
         return;
-    // Stop stale watcher from a previous run.
-    if (existsSync(pidPath)) {
-        try {
-            const prevPid = parseWatcherPidFile(await readFile(pidPath, "utf-8"));
-            if (prevPid) {
-                tryKillPid(prevPid, "SIGTERM");
-            }
-        }
-        catch (error) {
-            if (!hasErrnoCode(error, "ESRCH")) {
-                console.warn("[omx] warning: failed to stop stale notify fallback watcher", {
-                    path: pidPath,
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-    }
     await mkdir(join(cwd, ".omx", "state"), { recursive: true }).catch((error) => {
         console.warn("[omx] warning: failed to create notify fallback watcher state directory", {
             cwd,
@@ -2003,6 +2263,8 @@ async function stopHookDerivedWatcher(cwd) {
     });
 }
 async function flushNotifyFallbackOnce(cwd, options = {}) {
+    if (!shouldEnableNotifyFallbackWatcher(process.env, process.platform))
+        return;
     const { spawnSync } = await import("child_process");
     const pkgRoot = getPackageRoot();
     const watcherScript = resolveNotifyFallbackWatcherScript(pkgRoot);