oh-my-codex-pennix 0.18.13

package/dist/cli/__tests__/index.test.js

@@ -0,0 +1,3619 @@
+import { afterEach, describe, it, mock } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, readFileSync, utimesSync } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { once } from "node:events";
+import TOML from "@iarna/toml";
+import { HELP, normalizeCodexLaunchArgs, buildTmuxShellCommand, buildTmuxPaneCommand, shouldSourceTmuxPaneShellRc, buildWindowsPromptCommand, buildTmuxSessionName, resolveCliInvocation, resolveUpdateChannelArg, commandOwnsLocalHelp, resolveCodexLaunchPolicy, resolveEffectiveLeaderLaunchPolicyOverride, resolveEnvLaunchPolicyOverride, resolveLeaderLaunchPolicyOverride, classifyCodexExecFailure, resolveSignalExitCode, parseTmuxPaneSnapshot, findHudWatchPaneIds, buildHudPaneCleanupTargets, readTopLevelTomlString, upsertTopLevelTomlString, collectInheritableTeamWorkerArgs, resolveTeamWorkerLaunchArgsEnv, injectModelInstructionsBypassArgs, resolveWorkerSparkModel, resolveSetupInstallModeArg, resolveSetupMcpModeArg, resolveSetupScopeArg, resolveSetupTeamModeArg, resolveLaunchConfigRepairOptions, readPersistedSetupPreferences, readPersistedSetupScope, resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, resolveProjectLocalCodexHomeForLaunch, shouldAutoIsolateMadmaxLaunch, createMadmaxIsolatedRoot, buildMadmaxDetachedLaunchContextKey, withMadmaxDetachedContextLock, resolveOmxRootForLaunch, resolveDisposableWorktreeOmxRootForLaunch, prepareCodexHomeForLaunch, persistProjectLaunchRuntimeAuthState, persistProjectLaunchRuntimeProjectTrustState, runtimeCodexHomePath, buildDetachedSessionBootstrapSteps, buildDetachedTmuxSessionName, buildDetachedSessionFinalizeSteps, shouldAttachDetachedTmuxSession, buildDetachedSessionRollbackSteps, detectDetachedSessionWindowIndex, resolveNotifyTempContract, buildNotifyTempStartupMessages, buildNotifyFallbackWatcherEnv, shouldEnableNotifyFallbackWatcher, reapStaleNotifyFallbackWatcher, cleanupLaunchOrphanedMcpProcesses, reapPostLaunchOrphanedMcpProcesses, cleanupPostLaunchModeStateFiles, resolveBackgroundHelperLaunchMode, shouldDetachBackgroundHelper, resolveNotifyFallbackWatcherScript, resolveHookDerivedWatcherScript, resolveNotifyHookScript, buildDetachedWindowsBootstrapScript, acquireTmuxExtendedKeysLease, resolveNativeSessionName, releaseTmuxExtendedKeysLease, withTmuxExtendedKeys, serializeDetachedSessionParentEnv, buildInsideTmuxHudHookEnv, registerInsideTmuxHudResizeHook, buildDetachedHudHookEnv, registerDetachedHudLayoutReconcileHook, ensureOmxRuntimeCommandShim, omxRuntimeCommandShimPath, prependOmxRuntimeCommandShimToEnv, CODEX_SQLITE_HOME_ENV, DETACHED_TMUX_HISTORY_LIMIT, isExistingTmuxWindowTooCrampedForLaunchHud, } from "../index.js";
+import { mergeConfig, repairConfigIfNeeded } from "../../config/generator.js";
+import { ensureReusableNodeModules } from "../../utils/repo-deps.js";
+import { readAllState } from "../../hud/state.js";
+import { generateOverlay } from "../../hooks/agents-overlay.js";
+import { HUD_TMUX_HEIGHT_LINES, HUD_TMUX_MIN_LAUNCH_WINDOW_HEIGHT_LINES } from "../../hud/constants.js";
+import { createHudWatchPane as createSharedHudWatchPane, listCurrentWindowHudPaneIds } from "../../hud/tmux.js";
+import { DEFAULT_FRONTIER_MODEL, getTeamLowComplexityModel, } from "../../config/models.js";
+const testDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(testDir, "..", "..", "..");
+function normalizeDarwinTmpPath(value) {
+    return process.platform === "darwin" ? value.replaceAll("/private/var/", "/var/") : value;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function countMatches(text, pattern) {
+    return text.match(pattern)?.length ?? 0;
+}
+function expectedLowComplexityModel(codexHomeOverride) {
+    return getTeamLowComplexityModel(codexHomeOverride);
+}
+afterEach(() => {
+    mock.restoreAll();
+});
+describe("madmax state isolation", () => {
+    it("auto-isolates only madmax launch and exec invocations", () => {
+        assert.equal(shouldAutoIsolateMadmaxLaunch("launch", ["--madmax"], {}), true);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("exec", ["--madmax-spark"], {}), true);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("team", ["--madmax"], {}), false);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("launch", ["--yolo"], {}), false);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("launch", ["--madmax"], { OMX_ROOT: "/already/boxed" }), false);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("launch", ["--madmax"], { OMXBOX_ACTIVE: "1" }), false);
+        assert.equal(shouldAutoIsolateMadmaxLaunch("launch", ["--madmax"], { OMX_NO_BOX: "1" }), false);
+    });
+    it("creates a per-run OMX_ROOT registry entry without touching source .omx", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-madmax-source-"));
+        const runs = await mkdtemp(join(tmpdir(), "omx-madmax-runs-"));
+        try {
+            const runDir = createMadmaxIsolatedRoot(wd, ["--madmax"], { OMX_RUNS_DIR: runs });
+            assert.equal(runDir.startsWith(runs), true);
+            assert.equal(existsSync(join(wd, ".omx")), false);
+            const metadata = JSON.parse(await readFile(join(runDir, ".omxbox-run.json"), "utf-8"));
+            assert.equal(metadata.source_cwd, wd);
+            assert.equal(metadata.cwd, runDir);
+            assert.deepEqual(metadata.argv, ["--madmax"]);
+            const registry = await readFile(join(runs, "registry.jsonl"), "utf-8");
+            assert.match(registry, /"launcher":"omx --madmax"/);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+            await rm(runs, { recursive: true, force: true });
+        }
+    });
+    it("stamps a stable detached launch context and exposes it to boxed launch", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-madmax-source-"));
+        const runs = await mkdtemp(join(tmpdir(), "omx-madmax-runs-"));
+        try {
+            const env = { OMX_RUNS_DIR: runs };
+            const runDir = createMadmaxIsolatedRoot(wd, ["--madmax", "--xhigh", "--tmux"], env);
+            const metadata = JSON.parse(await readFile(join(runDir, ".omxbox-run.json"), "utf-8"));
+            const expectedContext = buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--xhigh", "--tmux"], runDir);
+            assert.equal(metadata.detached_launch_context, expectedContext);
+            assert.equal(env.OMX_MADMAX_DETACHED_CONTEXT, expectedContext);
+            assert.equal(buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--xhigh", "--tmux"], runDir), buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--xhigh"], runDir), "explicit --tmux is a transport choice and must not create a second context");
+            assert.equal(buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--xhigh", "--tmux"], runDir), buildMadmaxDetachedLaunchContextKey(wd, ["--xhigh", "--madmax", "--direct"], runDir), "argument order and transport choices must not create duplicate detached contexts");
+            assert.notEqual(expectedContext, buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--low"], runDir), "different launch semantics may run concurrently");
+            assert.notEqual(buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--high", "--xhigh"], runDir), buildMadmaxDetachedLaunchContextKey(wd, ["--madmax", "--xhigh", "--high"], runDir), "last reasoning shorthand wins, so reversed reasoning order is a distinct context");
+            const otherWd = await mkdtemp(join(tmpdir(), "omx-madmax-other-source-"));
+            try {
+                assert.notEqual(expectedContext, buildMadmaxDetachedLaunchContextKey(otherWd, ["--madmax", "--xhigh"], runDir), "different work contexts may run concurrently");
+            }
+            finally {
+                await rm(otherWd, { recursive: true, force: true });
+            }
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+            await rm(runs, { recursive: true, force: true });
+        }
+    });
+    it("gives independent madmax run roots distinct detached launch context locks", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-madmax-source-"));
+        const runs = await mkdtemp(join(tmpdir(), "omx-madmax-runs-"));
+        try {
+            const firstEnv = { OMX_RUNS_DIR: runs };
+            const secondEnv = { OMX_RUNS_DIR: runs };
+            const firstRunDir = createMadmaxIsolatedRoot(wd, ["--madmax", "--high"], firstEnv);
+            const secondRunDir = createMadmaxIsolatedRoot(wd, ["--madmax", "--high"], secondEnv);
+            assert.notEqual(firstRunDir, secondRunDir);
+            assert.notEqual(firstEnv.OMX_MADMAX_DETACHED_CONTEXT, secondEnv.OMX_MADMAX_DETACHED_CONTEXT, "same cwd and argv from independent boxed runs must not contend on one active-detached lock");
+            assert.equal(firstEnv.OMX_MADMAX_DETACHED_CONTEXT, buildMadmaxDetachedLaunchContextKey(wd, ["--high", "--madmax", "--tmux"], firstRunDir), "transport and order normalization still deduplicates within the same isolated run");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+            await rm(runs, { recursive: true, force: true });
+        }
+    });
+    it("recovers a madmax detached context lock whose holder pid has already exited", async () => {
+        const runs = await mkdtemp(join(tmpdir(), "omx-madmax-lock-stale-"));
+        try {
+            const contextKey = "stale-context";
+            const lockPath = join(runs, "active-detached", `${contextKey}.lock`);
+            mkdirSync(lockPath, { recursive: true });
+            await writeFile(join(lockPath, "pid"), "2147483647");
+            let ran = false;
+            const result = withMadmaxDetachedContextLock(runs, contextKey, () => {
+                ran = true;
+                return "acquired";
+            }, { maxAttempts: 2, retryMs: 0 });
+            assert.equal(result, "acquired");
+            assert.equal(ran, true);
+            assert.equal(existsSync(lockPath), false);
+        }
+        finally {
+            await rm(runs, { recursive: true, force: true });
+        }
+    });
+    it("preserves a live madmax detached context lock and reports holder diagnostics on timeout", async () => {
+        const runs = await mkdtemp(join(tmpdir(), "omx-madmax-lock-live-"));
+        try {
+            const contextKey = "live-context";
+            const lockPath = join(runs, "active-detached", `${contextKey}.lock`);
+            mkdirSync(lockPath, { recursive: true });
+            await writeFile(join(lockPath, "owner.json"), `${JSON.stringify({
+                version: 1,
+                pid: process.pid,
+                context_key: contextKey,
+                acquired_at: new Date().toISOString(),
+            })}\n`);
+            await writeFile(join(lockPath, "pid"), String(process.pid));
+            assert.throws(() => withMadmaxDetachedContextLock(runs, contextKey, () => "should-not-run", { maxAttempts: 1, retryMs: 0 }), (err) => {
+                assert.ok(err instanceof Error);
+                assert.match(err.message, /timed out waiting for madmax detached launch context lock/);
+                assert.match(err.message, new RegExp(`holder pid ${process.pid} is still running`));
+                assert.match(err.message, /owner context live-context/);
+                assert.match(err.message, /Another madmax detached launch is active for this directory/);
+                assert.match(err.message, /close the existing madmax session or use --worktree for concurrent work/);
+                assert.match(err.message, /Multiple madmax sessions in one directory are unsafe/);
+                return true;
+            });
+            assert.equal(existsSync(lockPath), true);
+        }
+        finally {
+            await rm(runs, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveOmxRootForLaunch", () => {
+    it("preserves POSIX absolute OMX_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_ROOT: "/var/tmp/omx" }), "/var/tmp/omx");
+    });
+    it("preserves Windows drive-letter absolute OMX_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_ROOT: "C:\\Users\\me\\omx" }), "C:\\Users\\me\\omx");
+    });
+    it("preserves Windows drive-letter absolute OMX_STATE_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_STATE_ROOT: "D:\\omx-state" }), "D:\\omx-state");
+    });
+    it("preserves UNC absolute OMX_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_ROOT: "\\\\server\\share\\omx" }), "\\\\server\\share\\omx");
+    });
+    it("joins relative OMX_ROOT to cwd", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_ROOT: "relative/omx" }), join("/repo", "relative/omx"));
+    });
+    it("returns undefined for blank OMX_ROOT and OMX_STATE_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", { OMX_ROOT: "  ", OMX_STATE_ROOT: "" }), undefined);
+    });
+    it("prefers OMX_ROOT over OMX_STATE_ROOT", () => {
+        assert.equal(resolveOmxRootForLaunch("/repo", {
+            OMX_ROOT: "C:\\Users\\me\\root",
+            OMX_STATE_ROOT: "/state-root",
+        }), "C:\\Users\\me\\root");
+    });
+});
+describe("disposable worktree state root resolution", () => {
+    it("uses the source repo root for launch worktrees when no explicit root is set", () => {
+        assert.equal(resolveDisposableWorktreeOmxRootForLaunch({ enabled: true, repoRoot: "/repo" }, {}), "/repo");
+    });
+    it("preserves explicit OMX_ROOT and OMX_STATE_ROOT precedence", () => {
+        assert.equal(resolveDisposableWorktreeOmxRootForLaunch({ enabled: true, repoRoot: "/repo" }, { OMX_ROOT: "/explicit" }), undefined);
+        assert.equal(resolveDisposableWorktreeOmxRootForLaunch({ enabled: true, repoRoot: "/repo" }, { OMX_STATE_ROOT: "/state-root" }), undefined);
+    });
+    it("does not affect non-worktree launches", () => {
+        assert.equal(resolveDisposableWorktreeOmxRootForLaunch({ enabled: false }, {}), undefined);
+    });
+});
+describe("normalizeCodexLaunchArgs", () => {
+    it("maps --madmax to codex bypass flag", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--madmax"]), [
+            "--dangerously-bypass-approvals-and-sandbox",
+        ]);
+    });
+    it("does not forward --madmax and preserves other args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--model", "gpt-5", "--madmax", "--yolo"]), [
+            "--model",
+            "gpt-5",
+            "--yolo",
+            "--dangerously-bypass-approvals-and-sandbox",
+        ]);
+    });
+    it("avoids duplicate bypass flags when both are present", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs([
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--madmax",
+        ]), ["--dangerously-bypass-approvals-and-sandbox"]);
+    });
+    it("deduplicates repeated bypass-related flags", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs([
+            "--madmax",
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--madmax",
+            "--dangerously-bypass-approvals-and-sandbox",
+        ]), ["--dangerously-bypass-approvals-and-sandbox"]);
+    });
+    it("leaves unrelated args unchanged", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--model", "gpt-5", "--yolo"]), [
+            "--model",
+            "gpt-5",
+            "--yolo",
+        ]);
+    });
+    it("maps --high to reasoning override", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--high"]), [
+            "-c",
+            'model_reasoning_effort="high"',
+        ]);
+    });
+    it("maps --xhigh to reasoning override", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--xhigh"]), [
+            "-c",
+            'model_reasoning_effort="xhigh"',
+        ]);
+    });
+    it("uses the last reasoning shorthand when both are present", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--high", "--xhigh"]), [
+            "-c",
+            'model_reasoning_effort="xhigh"',
+        ]);
+    });
+    it("maps --xhigh --madmax to codex-native flags only", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--xhigh", "--madmax"]), [
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="xhigh"',
+        ]);
+    });
+    it("--spark is stripped from leader args (model goes to workers only)", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--spark", "--yolo"]), [
+            "--yolo",
+        ]);
+    });
+    it("--spark alone produces no leader args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--spark"]), []);
+    });
+    it("--madmax-spark adds bypass flag to leader args and is otherwise consumed", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--madmax-spark"]), [
+            "--dangerously-bypass-approvals-and-sandbox",
+        ]);
+    });
+    it("--madmax-spark deduplicates bypass when --madmax also present", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--madmax", "--madmax-spark"]), [
+            "--dangerously-bypass-approvals-and-sandbox",
+        ]);
+    });
+    it("--madmax-spark does not inject spark model into leader args", () => {
+        const args = normalizeCodexLaunchArgs(["--madmax-spark"]);
+        assert.ok(!args.includes("--model"), "leader args must not contain --model from --madmax-spark");
+        assert.ok(!args.some((a) => a.includes("spark")), "leader args must not reference spark model");
+    });
+    it("strips detached worktree flag from leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--worktree", "--yolo"]), [
+            "--yolo",
+        ]);
+    });
+    it("strips named worktree flag from leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--worktree=feature/demo", "--model", "gpt-5"]), ["--model", "gpt-5"]);
+    });
+    it("does not forward notify-temp flags/selectors to leader codex args", () => {
+        const parsed = resolveNotifyTempContract([
+            "--notify-temp",
+            "--discord",
+            "--custom",
+            "openclaw:ops",
+            "--custom=my-hook",
+            "--model",
+            "gpt-5",
+        ], {});
+        assert.deepEqual(normalizeCodexLaunchArgs(parsed.passthroughArgs), [
+            "--model",
+            "gpt-5",
+        ]);
+    });
+    it("strips --tmux from leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--tmux", "--yolo"]), [
+            "--yolo",
+        ]);
+    });
+    it("strips --direct from leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--direct", "--yolo"]), [
+            "--yolo",
+        ]);
+    });
+    it("preserves literal --tmux after -- in leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--", "--tmux", "--yolo"]), [
+            "--",
+            "--tmux",
+            "--yolo",
+        ]);
+    });
+    it("preserves literal --direct after -- in leader codex args", () => {
+        assert.deepEqual(normalizeCodexLaunchArgs(["--", "--direct", "--yolo"]), [
+            "--",
+            "--direct",
+            "--yolo",
+        ]);
+    });
+});
+describe("resolveLeaderLaunchPolicyOverride", () => {
+    it("detects explicit detached tmux launch requests", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--tmux", "--model", "gpt-5"]), "detached-tmux");
+    });
+    it("detects explicit direct launch requests", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--direct", "--model", "gpt-5"]), "direct");
+    });
+    it("uses the last CLI launch policy flag before --", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--direct", "--tmux"]), "detached-tmux");
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--tmux", "--direct"]), "direct");
+    });
+    it("returns undefined when no explicit policy override is present", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--model", "gpt-5"]), undefined);
+    });
+    it("stops scanning for --tmux after the end-of-options marker", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--", "--tmux", "--model", "gpt-5"]), undefined);
+    });
+    it("stops scanning for --direct after the end-of-options marker", () => {
+        assert.equal(resolveLeaderLaunchPolicyOverride(["--", "--direct", "--model", "gpt-5"]), undefined);
+    });
+});
+describe("resolveEnvLaunchPolicyOverride", () => {
+    it("accepts direct, tmux, detached-tmux, auto, and empty policy values", () => {
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "direct" }), "direct");
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "tmux" }), "detached-tmux");
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "detached-tmux" }), "detached-tmux");
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "auto" }), undefined);
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "" }), undefined);
+    });
+    it("warns once for invalid OMX_LAUNCH_POLICY and falls back to auto", () => {
+        const warn = mock.method(console, "warn", () => { });
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "banana" }), undefined);
+        assert.equal(resolveEnvLaunchPolicyOverride({ OMX_LAUNCH_POLICY: "banana" }), undefined);
+        assert.equal(warn.mock.callCount(), 1);
+    });
+});
+describe("resolveEffectiveLeaderLaunchPolicyOverride", () => {
+    it("uses env policy when no CLI policy flag is present", () => {
+        assert.equal(resolveEffectiveLeaderLaunchPolicyOverride(["--yolo"], {
+            OMX_LAUNCH_POLICY: "direct",
+        }), "direct");
+    });
+    it("lets CLI policy flags override OMX_LAUNCH_POLICY", () => {
+        assert.equal(resolveEffectiveLeaderLaunchPolicyOverride(["--tmux", "--yolo"], {
+            OMX_LAUNCH_POLICY: "direct",
+        }), "detached-tmux");
+        assert.equal(resolveEffectiveLeaderLaunchPolicyOverride(["--direct", "--yolo"], {
+            OMX_LAUNCH_POLICY: "tmux",
+        }), "direct");
+    });
+});
+describe("resolveNotifyTempContract", () => {
+    it("activates from --notify-temp with no providers", () => {
+        const parsed = resolveNotifyTempContract(["--notify-temp", "--model", "gpt-5"], {});
+        assert.equal(parsed.contract.active, true);
+        assert.equal(parsed.contract.source, "cli");
+        assert.deepEqual(parsed.contract.canonicalSelectors, []);
+        assert.deepEqual(parsed.passthroughArgs, ["--model", "gpt-5"]);
+    });
+    it("auto-activates when provider selectors are present", () => {
+        const parsed = resolveNotifyTempContract(["--discord", "--slack"], {});
+        assert.equal(parsed.contract.active, true);
+        assert.equal(parsed.contract.source, "providers");
+        assert.deepEqual(parsed.contract.canonicalSelectors, ["discord", "slack"]);
+        assert.equal(parsed.contract.warnings.some((line) => line.includes("imply temp mode")), true);
+    });
+    it("supports repeated --custom forms and canonicalizes selectors", () => {
+        const parsed = resolveNotifyTempContract(["--custom", "OpenClaw:Ops", "--custom=my-hook", "--custom=", "--custom"], {});
+        assert.deepEqual(parsed.contract.canonicalSelectors, [
+            "openclaw:ops",
+            "custom:my-hook",
+        ]);
+        assert.equal(parsed.contract.warnings.length >= 1, true);
+    });
+    it("activates from OMX_NOTIFY_TEMP=1 env parity", () => {
+        const parsed = resolveNotifyTempContract(["--model", "gpt-5"], {
+            OMX_NOTIFY_TEMP: "1",
+        });
+        assert.equal(parsed.contract.active, true);
+        assert.equal(parsed.contract.source, "env");
+        assert.deepEqual(parsed.passthroughArgs, ["--model", "gpt-5"]);
+    });
+});
+describe("cleanupLaunchOrphanedMcpProcesses", () => {
+    it("reaps only detached OMX MCP processes without a live Codex ancestor", async () => {
+        const processes = [
+            { pid: 700, ppid: 500, command: "codex" },
+            { pid: 701, ppid: 700, command: "node /repo/bin/omx.js" },
+            {
+                pid: 710,
+                ppid: 700,
+                command: "node /repo/oh-my-codex/dist/mcp/state-server.js",
+            },
+            {
+                pid: 800,
+                ppid: 1,
+                command: "node /tmp/oh-my-codex/dist/mcp/memory-server.js",
+            },
+            {
+                pid: 810,
+                ppid: 42,
+                command: "node /tmp/oh-my-codex/dist/mcp/trace-server.js",
+            },
+            {
+                pid: 820,
+                ppid: 50,
+                command: "codex --model gpt-5",
+            },
+            {
+                pid: 821,
+                ppid: 820,
+                command: "node /tmp/other-session/dist/mcp/state-server.js",
+            },
+            {
+                pid: 830,
+                ppid: 50,
+                command: "node /repo/bin/omx.js autoresearch --topic launch",
+            },
+            {
+                pid: 831,
+                ppid: 830,
+                command: "node /tmp/parallel-session/dist/mcp/memory-server.js",
+            },
+        ];
+        const signals = [];
+        const alive = new Set([800, 810]);
+        const result = await cleanupLaunchOrphanedMcpProcesses({
+            currentPid: 701,
+            listProcesses: () => processes,
+            isPidAlive: (pid) => alive.has(pid),
+            sendSignal: (pid, signal) => {
+                signals.push({ pid, signal });
+                alive.delete(pid);
+            },
+            sleep: async () => { },
+            now: () => 0,
+        });
+        assert.equal(result.terminatedCount, 2);
+        assert.equal(result.forceKilledCount, 0);
+        assert.deepEqual(result.failedPids, []);
+        assert.deepEqual(signals, [
+            { pid: 800, signal: "SIGTERM" },
+            { pid: 810, signal: "SIGTERM" },
+        ]);
+        assert.equal(signals.some(({ pid }) => pid === 821), false, "launch-safe cleanup must preserve OMX MCP processes still attached to another live Codex tree");
+        assert.equal(signals.some(({ pid }) => pid === 831), false, "launch-safe cleanup must preserve OMX MCP processes still attached to another live OMX launch tree");
+    });
+});
+describe("reapPostLaunchOrphanedMcpProcesses", () => {
+    it("logs postLaunch reaped MCP orphans and keeps cleanup non-fatal", async () => {
+        const info = [];
+        const warnings = [];
+        const errors = [];
+        await reapPostLaunchOrphanedMcpProcesses({
+            cleanup: async () => ({
+                dryRun: false,
+                candidates: [],
+                terminatedCount: 2,
+                forceKilledCount: 0,
+                failedPids: [810],
+            }),
+            writeInfo: (line) => info.push(line),
+            writeWarn: (line) => warnings.push(line),
+            writeError: (line) => errors.push(line),
+        });
+        assert.deepEqual(errors, []);
+        assert.match(info.join("\n"), /postLaunch: reaped 2 orphaned OMX MCP process/);
+        assert.match(warnings.join("\n"), /postLaunch: failed to reap 1 orphaned OMX MCP process/);
+    });
+    it("writes a non-fatal postLaunch cleanup error when the cleanup step throws", async () => {
+        const errors = [];
+        await reapPostLaunchOrphanedMcpProcesses({
+            cleanup: async () => {
+                throw new Error("boom");
+            },
+            writeError: (line) => errors.push(line),
+        });
+        assert.match(errors.join("\n"), /postLaunch MCP cleanup failed: Error: boom/);
+    });
+});
+describe("cleanupPostLaunchModeStateFiles", () => {
+    it("repairs empty or truncated mode state files and still cancels valid siblings", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-mode-cleanup-"));
+        const sessionId = "sess-postlaunch-cleanup";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        const partialState = '{\n  "active": true,\n  "mode": "ralph",\n';
+        const warnings = [];
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(sessionStateDir, "autopilot-state.json"), JSON.stringify({ active: true, mode: "autopilot" }, null, 2), "utf-8");
+        await writeFile(join(sessionStateDir, "deep-interview-state.json"), "", "utf-8");
+        await writeFile(join(sessionStateDir, "ralph-state.json"), partialState, "utf-8");
+        await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+            writeWarn: (line) => warnings.push(line),
+        });
+        const autopilot = JSON.parse(await readFile(join(sessionStateDir, "autopilot-state.json"), "utf-8"));
+        const deepInterview = JSON.parse(await readFile(join(sessionStateDir, "deep-interview-state.json"), "utf-8"));
+        const ralph = JSON.parse(await readFile(join(sessionStateDir, "ralph-state.json"), "utf-8"));
+        assert.equal(autopilot.active, false);
+        assert.equal(typeof autopilot.completed_at, "string");
+        assert.equal(deepInterview.active, false);
+        assert.equal(deepInterview.mode, "deep-interview");
+        assert.equal(deepInterview.current_phase, "cancelled");
+        assert.equal(typeof deepInterview.completed_at, "string");
+        assert.equal(typeof deepInterview.last_turn_at, "string");
+        assert.equal(ralph.active, false);
+        assert.equal(ralph.mode, "ralph");
+        assert.equal(ralph.current_phase, "cancelled");
+        assert.equal(typeof ralph.completed_at, "string");
+        assert.equal(typeof ralph.last_turn_at, "string");
+        const rootCanonicalPath = join(stateDir, "skill-active-state.json");
+        const sessionCanonicalPath = join(sessionStateDir, "skill-active-state.json");
+        if (existsSync(rootCanonicalPath)) {
+            const rootCanonical = JSON.parse(await readFile(rootCanonicalPath, "utf-8"));
+            assert.equal(rootCanonical.active, false);
+            assert.deepEqual(rootCanonical.active_skills, []);
+        }
+        if (existsSync(sessionCanonicalPath)) {
+            const sessionCanonical = JSON.parse(await readFile(sessionCanonicalPath, "utf-8"));
+            assert.equal(sessionCanonical.active, false);
+            assert.deepEqual(sessionCanonical.active_skills, []);
+        }
+        assert.deepEqual(warnings, []);
+    });
+    it("does not preserve complete Ralph cleanup state without completion-audit evidence", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-ralph-complete-audit-missing-"));
+        const sessionId = "sess-postlaunch-ralph-complete-audit-missing";
+        const sessionStateDir = join(wd, ".omx", "state", "sessions", sessionId);
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(sessionStateDir, "ralph-state.json"), JSON.stringify({
+            active: false,
+            mode: "ralph",
+            current_phase: "complete",
+            completed_at: "2026-05-09T07:00:00.000Z",
+        }, null, 2), "utf-8");
+        try {
+            await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+                now: () => new Date("2026-05-09T08:00:00.000Z"),
+            });
+            const ralph = JSON.parse(await readFile(join(sessionStateDir, "ralph-state.json"), "utf-8"));
+            assert.equal(ralph.active, false);
+            assert.equal(ralph.current_phase, "cancelled");
+            assert.equal(ralph.stop_reason, "missing_completion_audit:missing_completion_audit");
+            assert.equal(ralph.completion_audit_gate, "blocked");
+            assert.equal(ralph.completion_audit_missing_reason, "missing_completion_audit");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("preserves complete Ralph cleanup state when completion-audit evidence is present", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-ralph-complete-audit-present-"));
+        const sessionId = "sess-postlaunch-ralph-complete-audit-present";
+        const sessionStateDir = join(wd, ".omx", "state", "sessions", sessionId);
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(sessionStateDir, "ralph-state.json"), JSON.stringify({
+            active: false,
+            mode: "ralph",
+            current_phase: "complete",
+            completed_at: "2026-05-09T07:00:00.000Z",
+            completion_audit: {
+                passed: true,
+                prompt_to_artifact_checklist: ["all prompt requirements mapped"],
+                verification_evidence: ["npm test"],
+            },
+        }, null, 2), "utf-8");
+        try {
+            await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+                now: () => new Date("2026-05-09T08:00:00.000Z"),
+            });
+            const ralph = JSON.parse(await readFile(join(sessionStateDir, "ralph-state.json"), "utf-8"));
+            assert.equal(ralph.active, false);
+            assert.equal(ralph.current_phase, "complete");
+            assert.equal(ralph.stop_reason, undefined);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("marks active Ralph state cancelled with interrupted metadata during postLaunch cleanup", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-ralph-interrupted-"));
+        const sessionId = "sess-postlaunch-ralph-interrupted";
+        const sessionStateDir = join(wd, ".omx", "state", "sessions", sessionId);
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(sessionStateDir, "ralph-state.json"), JSON.stringify({
+            active: true,
+            mode: "ralph",
+            current_phase: "executing",
+            owner_omx_session_id: sessionId,
+        }, null, 2), "utf-8");
+        try {
+            await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+                now: () => new Date("2026-05-09T08:00:00.000Z"),
+            });
+            const ralph = JSON.parse(await readFile(join(sessionStateDir, "ralph-state.json"), "utf-8"));
+            assert.equal(ralph.active, false);
+            assert.equal(ralph.current_phase, "cancelled");
+            assert.equal(ralph.completed_at, "2026-05-09T08:00:00.000Z");
+            assert.equal(ralph.interrupted_at, "2026-05-09T08:00:00.000Z");
+            assert.equal(ralph.stop_reason, "session_exit");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("does not cancel root mode state during session-scoped postLaunch cleanup", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-root-preserve-"));
+        const sessionId = "sess-postlaunch-root-preserve";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(stateDir, "ralph-state.json"), JSON.stringify({ active: true, mode: "ralph", current_phase: "executing" }, null, 2), "utf-8");
+        await writeFile(join(sessionStateDir, "ralplan-state.json"), JSON.stringify({ active: true, mode: "ralplan", current_phase: "planning" }, null, 2), "utf-8");
+        try {
+            await cleanupPostLaunchModeStateFiles(wd, sessionId);
+            const rootRalph = JSON.parse(await readFile(join(stateDir, "ralph-state.json"), "utf-8"));
+            const sessionRalplan = JSON.parse(await readFile(join(sessionStateDir, "ralplan-state.json"), "utf-8"));
+            assert.equal(rootRalph.active, true);
+            assert.equal(sessionRalplan.active, false);
+            assert.equal(sessionRalplan.current_phase, "cancelled");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("retries a transient parse failure before cancelling the rewritten mode state", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-mode-retry-"));
+        const sessionId = "sess-postlaunch-retry";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        const statePath = join(sessionStateDir, "ralph-state.json");
+        const writes = [];
+        const validState = JSON.stringify({ active: true, mode: "ralph" }, null, 2);
+        let reads = 0;
+        await mkdir(sessionStateDir, { recursive: true });
+        const mockReaddir = (async (dir, _options) => (String(dir) === sessionStateDir ? ["ralph-state.json"] : []));
+        const mockReadFile = (async (path, _options) => {
+            assert.equal(String(path), statePath);
+            reads += 1;
+            return reads === 1
+                ? '{\n  "active": true,\n  "mode": "ralph"'
+                : validState;
+        });
+        const mockWriteFile = (async (path, content, _options) => {
+            writes.push({ path: String(path), content: String(content) });
+        });
+        const dependencies = {
+            readdir: mockReaddir,
+            readFile: mockReadFile,
+            writeFile: mockWriteFile,
+            sleep: async () => { },
+            now: () => new Date("2026-04-07T00:00:00.000Z"),
+        };
+        await cleanupPostLaunchModeStateFiles(wd, sessionId, dependencies);
+        assert.equal(reads, 2);
+        assert.equal(writes.length, 1);
+        assert.equal(writes[0]?.path, statePath);
+        const persisted = JSON.parse(writes[0]?.content ?? "{}");
+        assert.equal(persisted.active, false);
+        assert.equal(persisted.completed_at, "2026-04-07T00:00:00.000Z");
+    });
+    it("warns on structurally complete malformed JSON without aborting sibling cleanup", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-mode-malformed-"));
+        const sessionId = "sess-postlaunch-malformed";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        const warnings = [];
+        const malformedState = '{\n  "active": true,\n}\n';
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(sessionStateDir, "ralph-state.json"), malformedState, "utf-8");
+        await writeFile(join(sessionStateDir, "ultrawork-state.json"), JSON.stringify({ active: true, mode: "ultrawork" }, null, 2), "utf-8");
+        await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+            writeWarn: (line) => warnings.push(line),
+        });
+        const ultrawork = JSON.parse(await readFile(join(sessionStateDir, "ultrawork-state.json"), "utf-8"));
+        assert.equal(ultrawork.active, false);
+        assert.equal(typeof ultrawork.completed_at, "string");
+        const canonicalPath = join(stateDir, "skill-active-state.json");
+        if (existsSync(canonicalPath)) {
+            const canonical = JSON.parse(await readFile(canonicalPath, "utf-8"));
+            assert.equal(canonical.active, false);
+            assert.deepEqual(canonical.active_skills, []);
+        }
+        assert.equal(await readFile(join(sessionStateDir, "ralph-state.json"), "utf-8"), malformedState);
+        assert.equal(warnings.length, 1);
+        assert.match(warnings[0] ?? "", /skipped malformed mode state .*ralph-state\.json/);
+    });
+    it("reconciles root skill-active entries for the finished terminal session", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-root-skill-active-"));
+        const sessionId = "sess-terminal-autopilot";
+        const otherSessionId = "sess-other";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        try {
+            await mkdir(sessionStateDir, { recursive: true });
+            await writeFile(join(stateDir, "skill-active-state.json"), JSON.stringify({
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "ralph",
+                session_id: sessionId,
+                initialized_state_path: `.omx/state/sessions/${sessionId}/autopilot-state.json`,
+                active_skills: [
+                    { skill: "autopilot", phase: "ralph", active: true, session_id: sessionId },
+                    { skill: "team", phase: "running", active: true, session_id: otherSessionId },
+                ],
+            }, null, 2), "utf-8");
+            await cleanupPostLaunchModeStateFiles(wd, sessionId);
+            const rootCanonical = JSON.parse(await readFile(join(stateDir, "skill-active-state.json"), "utf-8"));
+            assert.equal(rootCanonical.active, true);
+            assert.deepEqual(rootCanonical.active_skills, [
+                { skill: "team", phase: "running", active: true, session_id: otherSessionId },
+            ]);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("preserves other-session active skills when session mode cleanup syncs before root scrub", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-mode-root-skill-active-"));
+        const sessionId = "sess-terminal-autopilot";
+        const otherSessionId = "sess-other-team";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        try {
+            await mkdir(sessionStateDir, { recursive: true });
+            await writeFile(join(stateDir, "skill-active-state.json"), JSON.stringify({
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "ralph",
+                session_id: sessionId,
+                initialized_state_path: `.omx/state/sessions/${sessionId}/autopilot-state.json`,
+                active_skills: [
+                    { skill: "autopilot", phase: "ralph", active: true, session_id: sessionId },
+                    { skill: "team", phase: "running", active: true, session_id: otherSessionId },
+                ],
+            }, null, 2), "utf-8");
+            await writeFile(join(sessionStateDir, "autopilot-state.json"), JSON.stringify({ active: true, mode: "autopilot", current_phase: "ralph" }, null, 2), "utf-8");
+            await cleanupPostLaunchModeStateFiles(wd, sessionId);
+            const autopilotState = JSON.parse(await readFile(join(sessionStateDir, "autopilot-state.json"), "utf-8"));
+            assert.equal(autopilotState.active, false);
+            assert.equal(autopilotState.current_phase, "cancelled");
+            const rootCanonical = JSON.parse(await readFile(join(stateDir, "skill-active-state.json"), "utf-8"));
+            assert.equal(rootCanonical.active, true);
+            assert.equal(rootCanonical.skill, "team");
+            assert.equal(rootCanonical.phase, "running");
+            assert.deepEqual(rootCanonical.active_skills, [
+                { skill: "team", phase: "running", active: true, session_id: otherSessionId },
+            ]);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("preserves review-pending Autopilot state across postLaunch compact cleanup", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-autopilot-review-pending-"));
+        const sessionId = "sess-autopilot-review-pending";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        try {
+            await mkdir(sessionStateDir, { recursive: true });
+            await writeFile(join(stateDir, "skill-active-state.json"), JSON.stringify({
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "code-review",
+                session_id: sessionId,
+                initialized_state_path: `.omx/state/sessions/${sessionId}/autopilot-state.json`,
+                active_skills: [
+                    { skill: "autopilot", phase: "code-review", active: true, session_id: sessionId },
+                ],
+            }, null, 2), "utf-8");
+            await writeFile(join(sessionStateDir, "skill-active-state.json"), JSON.stringify({
+                version: 1,
+                active: true,
+                skill: "autopilot",
+                phase: "code-review",
+                session_id: sessionId,
+                active_skills: [
+                    { skill: "autopilot", phase: "code-review", active: true, session_id: sessionId },
+                ],
+            }, null, 2), "utf-8");
+            await writeFile(join(sessionStateDir, "autopilot-state.json"), JSON.stringify({
+                active: true,
+                mode: "autopilot",
+                current_phase: "code-review",
+                iteration: 1,
+                review_cycle: 0,
+                state: {
+                    phase_cycle: ["ralplan", "ralph", "code-review"],
+                    handoff_artifacts: {
+                        ralplan: ".omx/plans/prd-issue-2366.md",
+                        ralph: { verification: ["npm test"], changed_files: ["src/cli/index.ts"] },
+                        code_review: null,
+                    },
+                    review_verdict: null,
+                    return_to_ralplan_reason: null,
+                },
+            }, null, 2), "utf-8");
+            await cleanupPostLaunchModeStateFiles(wd, sessionId, {
+                now: () => new Date("2026-05-16T11:00:00.000Z"),
+            });
+            const autopilotState = JSON.parse(await readFile(join(sessionStateDir, "autopilot-state.json"), "utf-8"));
+            assert.equal(autopilotState.active, true);
+            assert.equal(autopilotState.current_phase, "code-review");
+            assert.equal(autopilotState.completed_at, undefined);
+            assert.equal(autopilotState.state?.review_verdict, null);
+            const sessionSkill = JSON.parse(await readFile(join(sessionStateDir, "skill-active-state.json"), "utf-8"));
+            assert.equal(sessionSkill.active, true);
+            assert.equal(sessionSkill.skill, "autopilot");
+            assert.equal(sessionSkill.phase, "code-review");
+            const rootSkill = JSON.parse(await readFile(join(stateDir, "skill-active-state.json"), "utf-8"));
+            assert.equal(rootSkill.active, true);
+            assert.equal(rootSkill.skill, "autopilot");
+            assert.equal(rootSkill.phase, "code-review");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("clears canonical skill-active entries during cleanup and hides them from HUD/overlay readers", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-postlaunch-skill-active-cleanup-"));
+        const sessionId = "sess-skill-active-cleanup";
+        const stateDir = join(wd, ".omx", "state");
+        const sessionStateDir = join(stateDir, "sessions", sessionId);
+        await mkdir(sessionStateDir, { recursive: true });
+        await writeFile(join(stateDir, "session.json"), JSON.stringify({ session_id: sessionId }), "utf-8");
+        await writeFile(join(sessionStateDir, "skill-active-state.json"), JSON.stringify({
+            version: 1,
+            active: true,
+            skill: "autoresearch",
+            phase: "running",
+            session_id: sessionId,
+            active_skills: [
+                { skill: "autoresearch", phase: "running", active: true, session_id: sessionId },
+            ],
+        }, null, 2), "utf-8");
+        await cleanupPostLaunchModeStateFiles(wd, sessionId);
+        const canonical = JSON.parse(await readFile(join(sessionStateDir, "skill-active-state.json"), "utf-8"));
+        assert.equal(canonical.active, false);
+        assert.equal(canonical.phase, "complete");
+        assert.deepEqual(canonical.active_skills, []);
+        const hudState = await readAllState(wd);
+        assert.equal(hudState.autoresearch, null);
+        const overlay = await generateOverlay(wd, sessionId);
+        assert.equal(overlay.includes("- autoresearch:"), false);
+    });
+});
+describe("watcher script path resolution", () => {
+    it("resolves packaged watcher entrypoints from dist/scripts", () => {
+        assert.equal(resolveNotifyFallbackWatcherScript("/pkg"), "/pkg/dist/scripts/notify-fallback-watcher.js");
+        assert.equal(resolveHookDerivedWatcherScript("/pkg"), "/pkg/dist/scripts/hook-derived-watcher.js");
+        assert.equal(resolveNotifyHookScript("/pkg"), "/pkg/dist/scripts/notify-hook.js");
+    });
+});
+describe("buildNotifyFallbackWatcherEnv", () => {
+    it("enables watcher authority and propagates CODEX_HOME override when requested", () => {
+        const env = buildNotifyFallbackWatcherEnv({ HOME: "/tmp/home", OMX_HUD_AUTHORITY: "0", TMUX: "sock,1,0", TMUX_PANE: "%2" }, { codexHomeOverride: "/tmp/codex-home", omxRootOverride: "/tmp/omx-root", enableAuthority: true });
+        assert.equal(env.OMX_HUD_AUTHORITY, "1");
+        assert.equal(env.CODEX_HOME, "/tmp/codex-home");
+        assert.equal(env.OMX_ROOT, "/tmp/omx-root");
+        assert.equal(env.HOME, "/tmp/home");
+        assert.equal(env.TMUX, undefined);
+        assert.equal(env.TMUX_PANE, undefined);
+    });
+    it("disables watcher authority explicitly when not requested", () => {
+        const env = buildNotifyFallbackWatcherEnv({ HOME: "/tmp/home", OMX_HUD_AUTHORITY: "1", TMUX: "sock,1,0", TMUX_PANE: "%3" }, { enableAuthority: false });
+        assert.equal(env.OMX_HUD_AUTHORITY, "0");
+        assert.equal(env.HOME, "/tmp/home");
+        assert.equal(env.TMUX, undefined);
+        assert.equal(env.TMUX_PANE, undefined);
+    });
+});
+describe("shouldEnableNotifyFallbackWatcher", () => {
+    it("keeps notify fallback enabled by default on non-Windows hosts", () => {
+        assert.equal(shouldEnableNotifyFallbackWatcher({}, "linux"), true);
+    });
+    it("disables notify fallback explicitly on non-Windows hosts", () => {
+        assert.equal(shouldEnableNotifyFallbackWatcher({ OMX_NOTIFY_FALLBACK: "0" }, "linux"), false);
+    });
+    it("disables notify fallback by default on win32", () => {
+        assert.equal(shouldEnableNotifyFallbackWatcher({}, "win32"), false);
+    });
+    it("allows explicit opt-in for notify fallback on win32", () => {
+        assert.equal(shouldEnableNotifyFallbackWatcher({ OMX_NOTIFY_FALLBACK: "1" }, "win32"), true);
+    });
+});
+describe("reapStaleNotifyFallbackWatcher", () => {
+    it("stops an existing watcher even when a later startup gate would skip relaunch", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-stale-notify-fallback-"));
+        try {
+            const pidPath = join(cwd, "notify-fallback.pid");
+            await writeFile(pidPath, JSON.stringify({ pid: 4321, started_at: "2026-04-05T00:00:00.000Z" }), "utf-8");
+            const killed = [];
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                isWatcherProcess: () => true,
+                tryKillPid(pid, signal) {
+                    killed.push({ pid, signal });
+                    return true;
+                },
+            });
+            assert.deepEqual(killed, [{ pid: 4321, signal: "SIGTERM" }]);
+            assert.equal(shouldEnableNotifyFallbackWatcher({}, "win32"), false);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("ignores missing pid files", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-missing-notify-fallback-"));
+        try {
+            const pidPath = join(cwd, "notify-fallback.pid");
+            let killCalls = 0;
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                tryKillPid() {
+                    killCalls += 1;
+                    return true;
+                },
+            });
+            assert.equal(killCalls, 0);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("suppresses ESRCH cleanup errors but warns on unexpected failures", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-esrch-notify-fallback-"));
+        try {
+            const pidPath = join(cwd, "notify-fallback.pid");
+            await writeFile(pidPath, JSON.stringify({ pid: 99 }), "utf-8");
+            const warnings = [];
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                readFile: async () => {
+                    throw Object.assign(new Error("gone"), { code: "ESRCH" });
+                },
+                warn(message, meta) {
+                    warnings.push({ message, meta });
+                },
+            });
+            assert.deepEqual(warnings, []);
+            const warned = [];
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                readFile: async (path, encoding) => readFile(path, encoding),
+                isWatcherProcess: () => true,
+                tryKillPid() {
+                    throw new Error("permission denied");
+                },
+                warn(message, meta) {
+                    warned.push({ message, meta });
+                },
+            });
+            assert.equal(warned.length, 1);
+            assert.equal(warned[0]?.message, "[omx] warning: failed to stop stale notify fallback watcher");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+});
+describe("buildNotifyTempStartupMessages", () => {
+    it("always emits summary when temp mode is active", () => {
+        const result = buildNotifyTempStartupMessages({
+            active: true,
+            selectors: ["discord"],
+            canonicalSelectors: ["discord"],
+            warnings: [],
+            source: "cli",
+        }, true);
+        assert.deepEqual(result.infoLines, [
+            "notify temp: active | providers=discord | persistent-routing=bypassed",
+        ]);
+        assert.deepEqual(result.warningLines, []);
+    });
+    it("emits no-valid-provider warning when no provider is configured", () => {
+        const result = buildNotifyTempStartupMessages({
+            active: true,
+            selectors: [],
+            canonicalSelectors: [],
+            warnings: [
+                "notify temp: provider selectors imply temp mode (auto-activated)",
+            ],
+            source: "providers",
+        }, false);
+        assert.equal(result.warningLines.includes("notify temp: no valid providers resolved; notifications skipped"), true);
+    });
+});
+describe("resolveWorkerSparkModel", () => {
+    it("returns spark model string when --spark is present", () => {
+        assert.equal(resolveWorkerSparkModel(["--spark", "--yolo"]), expectedLowComplexityModel());
+    });
+    it("returns spark model string when --madmax-spark is present", () => {
+        assert.equal(resolveWorkerSparkModel(["--madmax-spark"]), expectedLowComplexityModel());
+    });
+    it("returns undefined when neither spark flag is present", () => {
+        assert.equal(resolveWorkerSparkModel(["--madmax", "--yolo", "--model", "gpt-5"]), undefined);
+    });
+    it("returns undefined for empty args", () => {
+        assert.equal(resolveWorkerSparkModel([]), undefined);
+    });
+    it("reads low-complexity team model from config when codexHomeOverride is provided", async () => {
+        const codexHome = await mkdtemp(join(tmpdir(), "omx-codex-home-"));
+        try {
+            await writeFile(join(codexHome, ".omx-config.json"), JSON.stringify({ models: { team_low_complexity: "gpt-4.1-mini" } }));
+            assert.equal(resolveWorkerSparkModel(["--spark"], codexHome), "gpt-4.1-mini");
+        }
+        finally {
+            await rm(codexHome, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveTeamWorkerLaunchArgsEnv (spark)", () => {
+    it("injects spark model as worker default when no explicit env model", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv(undefined, [], true, expectedLowComplexityModel()), `--model ${expectedLowComplexityModel()}`);
+    });
+    it("explicit env model overrides spark default", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--model gpt-5", [], true, expectedLowComplexityModel()), "--model gpt-5");
+    });
+    it("inherited leader model overrides spark default", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv(undefined, ["--model", "gpt-4.1"], true, expectedLowComplexityModel()), "--model gpt-4.1");
+    });
+});
+describe("commandOwnsLocalHelp", () => {
+    it("returns true for nested commands that render their own help output", () => {
+        for (const command of [
+            "adapt",
+            "agents-init",
+            "api",
+            "ask",
+            "question",
+            "autoresearch",
+            "deepinit",
+            "explore",
+            "hooks",
+            "hud",
+            "ralph",
+            "resume",
+            "session",
+            "sparkshell",
+            "team",
+            "tmux-hook",
+        ]) {
+            assert.equal(commandOwnsLocalHelp(command), true, `expected ${command} to own local help`);
+        }
+    });
+    it("returns false for top-level help-only commands", () => {
+        for (const command of ["help", "launch", "version", "update"]) {
+            assert.equal(commandOwnsLocalHelp(command), false, `expected ${command} to use top-level help`);
+        }
+    });
+});
+describe("resolveCliInvocation", () => {
+    it("resolves api to api command", () => {
+        assert.deepEqual(resolveCliInvocation(["api", "status"]), {
+            command: "api",
+            launchArgs: [],
+        });
+    });
+    it("resolves explore to explore command", () => {
+        assert.deepEqual(resolveCliInvocation(["explore", "--prompt", "find", "auth"]), {
+            command: "explore",
+            launchArgs: [],
+        });
+    });
+    it("resolves ask to ask command", () => {
+        assert.deepEqual(resolveCliInvocation(["ask", "claude", "hello"]), {
+            command: "ask",
+            launchArgs: [],
+        });
+    });
+    it("resolves question to question command", () => {
+        assert.deepEqual(resolveCliInvocation(["question", "--input", "{}"]), {
+            command: "question",
+            launchArgs: [],
+        });
+    });
+    it("resolves autoresearch to autoresearch command", () => {
+        assert.deepEqual(resolveCliInvocation(["autoresearch", "missions/demo"]), {
+            command: "autoresearch",
+            launchArgs: [],
+        });
+    });
+    it("resolves session to session command", () => {
+        assert.deepEqual(resolveCliInvocation(["session", "search", "startup evidence"]), {
+            command: "session",
+            launchArgs: [],
+        });
+    });
+    it("resolves resume to resume command and forwards trailing args", () => {
+        assert.deepEqual(resolveCliInvocation(["resume", "--last"]), {
+            command: "resume",
+            launchArgs: ["--last"],
+        });
+    });
+    it("resolves resume session id and prompt as forwarded args", () => {
+        assert.deepEqual(resolveCliInvocation(["resume", "session-123", "continue here"]), {
+            command: "resume",
+            launchArgs: ["session-123", "continue here"],
+        });
+    });
+    it("resolves exec to non-interactive launch passthrough and forwards trailing args", () => {
+        assert.deepEqual(resolveCliInvocation(["exec", "--model", "gpt-5", "say hi"]), {
+            command: "exec",
+            launchArgs: ["--model", "gpt-5", "say hi"],
+        });
+    });
+    it("resolves update to update command", () => {
+        assert.deepEqual(resolveCliInvocation(["update"]), {
+            command: "update",
+            launchArgs: [],
+        });
+    });
+    it("resolves update channel flags and rejects invalid combinations", () => {
+        assert.equal(resolveUpdateChannelArg([]), "stable");
+        assert.equal(resolveUpdateChannelArg(["--stable"]), "stable");
+        assert.equal(resolveUpdateChannelArg(["--dev"]), "dev");
+        assert.throws(() => resolveUpdateChannelArg(["--dev", "--stable"]), /mutually exclusive/);
+        assert.throws(() => resolveUpdateChannelArg(["--beta"]), /Unknown omx update option: --beta/);
+    });
+    it("resolves hooks to hooks command", () => {
+        assert.deepEqual(resolveCliInvocation(["hooks"]), {
+            command: "hooks",
+            launchArgs: [],
+        });
+    });
+    it("resolves agents-init to agents-init command", () => {
+        assert.deepEqual(resolveCliInvocation(["agents-init", "."]), {
+            command: "agents-init",
+            launchArgs: [],
+        });
+    });
+    it("resolves deepinit to deepinit alias command", () => {
+        assert.deepEqual(resolveCliInvocation(["deepinit", "src"]), {
+            command: "deepinit",
+            launchArgs: [],
+        });
+    });
+    it("resolves --help to the help command instead of launch", () => {
+        assert.deepEqual(resolveCliInvocation(["--help"]), {
+            command: "help",
+            launchArgs: [],
+        });
+    });
+    it("resolves --version to the version command instead of launch", () => {
+        assert.deepEqual(resolveCliInvocation(["--version"]), {
+            command: "version",
+            launchArgs: [],
+        });
+    });
+    it("resolves -v to the version command instead of launch", () => {
+        assert.deepEqual(resolveCliInvocation(["-v"]), {
+            command: "version",
+            launchArgs: [],
+        });
+    });
+    it("keeps unknown long flags as launch passthrough args", () => {
+        assert.deepEqual(resolveCliInvocation(["--model", "gpt-5"]), {
+            command: "launch",
+            launchArgs: ["--model", "gpt-5"],
+        });
+    });
+    it("advertises the explicit update command in top-level help", () => {
+        assert.match(HELP, /omx update\s+Install the stable channel now, then refresh setup/);
+        assert.match(HELP, /omx update --stable\s+Install\/rollback to npm stable \(oh-my-codex@latest\), then refresh setup/);
+        assert.match(HELP, /omx update --dev\s+Install the upstream dev branch, then refresh setup/);
+    });
+    it("advertises concise launch policy controls in top-level help", () => {
+        assert.match(HELP, /--direct\s+Launch the interactive leader directly/);
+        assert.match(HELP, /OMX_LAUNCH_POLICY=auto[\s\S]*Use the default policy/);
+        assert.match(HELP, /OMX_LAUNCH_POLICY=direct[\s\S]*Run without OMX tmux\/HUD management/);
+        assert.match(HELP, /OMX_LAUNCH_POLICY=tmux[\s\S]*Force OMX-managed detached tmux launch/);
+        assert.match(HELP, /OMX_LAUNCH_POLICY=detached-tmux[\s\S]*Force OMX-managed detached tmux launch/);
+        assert.match(HELP, /CLI policy flags \(--direct\/--tmux\) override OMX_LAUNCH_POLICY/);
+        assert.match(HELP, /Unset or empty OMX_LAUNCH_POLICY returns to auto\/default behavior/);
+        assert.match(HELP, /Config files are intentionally not used/);
+        assert.doesNotMatch(HELP, /OMX_LAUNCH_POLICY=direct\|tmux\|detached-tmux\|auto/);
+        assert.doesNotMatch(HELP, /OMX_LAUNCH_POLICY=direct omx --tmux --yolo/);
+    });
+});
+describe("resolveSetupInstallModeArg", () => {
+    it("maps explicit setup install mode flags", () => {
+        assert.equal(resolveSetupInstallModeArg(["--dry-run"]), undefined);
+        assert.equal(resolveSetupInstallModeArg(["--plugin"]), "plugin");
+        assert.equal(resolveSetupInstallModeArg(["--legacy"]), "legacy");
+        assert.equal(resolveSetupInstallModeArg(["--install-mode", "legacy"]), "legacy");
+        assert.equal(resolveSetupInstallModeArg(["--install-mode=plugin"]), "plugin");
+        assert.equal(resolveSetupInstallModeArg(["--scope", "project", "--plugin"]), "plugin");
+    });
+    it("rejects invalid setup install mode flags", () => {
+        assert.throws(() => resolveSetupInstallModeArg(["--install-mode"]), /Missing setup install mode value after --install-mode/);
+        assert.throws(() => resolveSetupInstallModeArg(["--install-mode", "workspace"]), /Invalid setup install mode: workspace/);
+        assert.throws(() => resolveSetupInstallModeArg(["--plugin", "--legacy"]), /Conflicting setup install mode flags/);
+        assert.throws(() => resolveSetupInstallModeArg(["--plugin", "--install-mode", "legacy"]), /Conflicting setup install mode flags/);
+        assert.throws(() => resolveSetupInstallModeArg(["--legacy", "--install-mode=plugin"]), /Conflicting setup install mode flags/);
+    });
+});
+describe("resolveSetupMcpModeArg", () => {
+    it("maps explicit setup MCP mode flags", () => {
+        assert.equal(resolveSetupMcpModeArg(["--dry-run"]), undefined);
+        assert.equal(resolveSetupMcpModeArg(["--no-mcp"]), "none");
+        assert.equal(resolveSetupMcpModeArg(["--with-mcp"]), "compat");
+        assert.equal(resolveSetupMcpModeArg(["--mcp", "none"]), "none");
+        assert.equal(resolveSetupMcpModeArg(["--mcp=compat"]), "compat");
+        assert.equal(resolveSetupMcpModeArg(["--scope", "project", "--mcp", "compat"]), "compat");
+    });
+    it("rejects invalid or conflicting setup MCP mode flags", () => {
+        assert.throws(() => resolveSetupMcpModeArg(["--mcp"]), /Missing setup MCP mode value after --mcp/);
+        assert.throws(() => resolveSetupMcpModeArg(["--mcp", "full"]), /Invalid setup MCP mode: full/);
+        assert.throws(() => resolveSetupMcpModeArg(["--no-mcp", "--with-mcp"]), /Conflicting setup MCP mode flags/);
+        assert.throws(() => resolveSetupMcpModeArg(["--no-mcp", "--mcp=compat"]), /Conflicting setup MCP mode flags/);
+    });
+});
+describe("resolveSetupTeamModeArg", () => {
+    it("maps explicit setup Team mode flags", () => {
+        assert.equal(resolveSetupTeamModeArg(["--dry-run"]), undefined);
+        assert.equal(resolveSetupTeamModeArg(["--disable-team"]), "disabled");
+        assert.equal(resolveSetupTeamModeArg(["--no-team"]), "disabled");
+        assert.equal(resolveSetupTeamModeArg(["--enable-team"]), "enabled");
+        assert.equal(resolveSetupTeamModeArg(["--team"]), "enabled");
+        assert.equal(resolveSetupTeamModeArg(["--team-mode", "disabled"]), "disabled");
+        assert.equal(resolveSetupTeamModeArg(["--team-mode=enabled"]), "enabled");
+        assert.equal(resolveSetupTeamModeArg(["--scope", "project", "--team-mode", "disabled"]), "disabled");
+    });
+    it("rejects invalid or conflicting setup Team mode flags", () => {
+        assert.throws(() => resolveSetupTeamModeArg(["--team-mode"]), /Missing setup Team mode value after --team-mode/);
+        assert.throws(() => resolveSetupTeamModeArg(["--team-mode", "minimal"]), /Invalid setup Team mode: minimal/);
+        assert.throws(() => resolveSetupTeamModeArg(["--disable-team", "--enable-team"]), /Conflicting setup Team mode flags/);
+        assert.throws(() => resolveSetupTeamModeArg(["--team-mode=enabled", "--no-team"]), /Conflicting setup Team mode flags/);
+    });
+});
+describe("resolveSetupScopeArg", () => {
+    it("returns undefined when scope is omitted", () => {
+        assert.equal(resolveSetupScopeArg(["--dry-run"]), undefined);
+    });
+    it("parses --scope <value> form", () => {
+        assert.equal(resolveSetupScopeArg(["--dry-run", "--scope", "project"]), "project");
+    });
+    it("parses --scope=<value> form", () => {
+        assert.equal(resolveSetupScopeArg(["--scope=project"]), "project");
+    });
+    it("throws on invalid scope value", () => {
+        assert.throws(() => resolveSetupScopeArg(["--scope", "workspace"]), /Invalid setup scope: workspace/);
+    });
+    it("throws when --scope value is missing", () => {
+        assert.throws(() => resolveSetupScopeArg(["--scope"]), /Missing setup scope value after --scope/);
+    });
+});
+describe("project launch scope helpers", () => {
+    it("reads persisted setup scope when valid", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(readPersistedSetupScope(wd), "project");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("reads persisted setup preferences when install mode is present", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "user", installMode: "plugin" }));
+            assert.deepEqual(readPersistedSetupPreferences(wd), {
+                scope: "user",
+                installMode: "plugin",
+            });
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("reads persisted setup Team mode when present", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project", teamMode: "disabled" }));
+            assert.deepEqual(readPersistedSetupPreferences(wd), {
+                scope: "project",
+                teamMode: "disabled",
+            });
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("ignores malformed persisted setup scope", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), "{not-json");
+            assert.equal(readPersistedSetupScope(wd), undefined);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses project CODEX_HOME when persisted scope is project", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveCodexHomeForLaunch(wd, {}), join(wd, ".codex"));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses project CODEX_HOME when persisted scope is project even if HOME is unusable", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            const badHome = join(wd, "home-as-file");
+            await writeFile(badHome, "not-a-directory");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveCodexHomeForLaunch(wd, { HOME: badHome }), join(wd, ".codex"));
+            assert.equal(resolveCodexConfigPathForLaunch(wd, { HOME: badHome }), join(wd, ".codex", "config.toml"));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses project config.toml for launch repair when persisted scope is project", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveCodexConfigPathForLaunch(wd, {}), join(wd, ".codex", "config.toml"));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("preserves explicit compat MCP during launch config repair", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(join(wd, ".codex"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project", mcpMode: "compat" }));
+            const configPath = join(wd, ".codex", "config.toml");
+            await mergeConfig(configPath, wd, {
+                includeFirstPartyMcp: true,
+                sharedMcpServers: [
+                    {
+                        name: "eslint",
+                        command: "npx",
+                        args: ["@eslint/mcp@latest"],
+                        enabled: true,
+                        startupTimeoutSec: 12,
+                    },
+                ],
+                sharedMcpRegistrySource: join(wd, ".omx", "mcp-registry.json"),
+            });
+            const clean = await readFile(configPath, "utf-8");
+            assert.match(clean, /^\[mcp_servers\.omx_state\]$/m);
+            assert.match(clean, /oh-my-codex \(OMX\) Shared MCP Registry Sync/);
+            assert.match(clean, /^\[mcp_servers\.eslint\]$/m);
+            await writeFile(configPath, `${clean}\n[tui]\nstatus_line = ["git-branch"]\n`);
+            const repaired = await repairConfigIfNeeded(configPath, wd, await resolveLaunchConfigRepairOptions(wd, configPath));
+            const repairedToml = await readFile(configPath, "utf-8");
+            assert.equal(repaired, true);
+            assert.match(repairedToml, /^\[mcp_servers\.omx_state\]$/m);
+            assert.match(repairedToml, /oh-my-codex \(OMX\) Shared MCP Registry Sync/);
+            assert.match(repairedToml, /^\[mcp_servers\.eslint\]$/m);
+            assert.equal((repairedToml.match(/^\[tui\]$/gm) ?? []).length, 1);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("preserves existing compat MCP during launch repair without cwd-local preferences", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            const configPath = join(wd, "global-codex", "config.toml");
+            await mkdir(dirname(configPath), { recursive: true });
+            await mergeConfig(configPath, wd, { includeFirstPartyMcp: true });
+            const clean = await readFile(configPath, "utf-8");
+            assert.equal(existsSync(join(wd, ".omx", "setup-scope.json")), false);
+            assert.match(clean, /^\[mcp_servers\.omx_state\]$/m);
+            await writeFile(configPath, `${clean}\n[tui]\nstatus_line = ["git-branch"]\n`);
+            const repaired = await repairConfigIfNeeded(configPath, wd, await resolveLaunchConfigRepairOptions(wd, configPath));
+            const repairedToml = await readFile(configPath, "utf-8");
+            assert.equal(repaired, true);
+            assert.match(repairedToml, /^\[mcp_servers\.omx_state\]$/m);
+            assert.equal((repairedToml.match(/^\[tui\]$/gm) ?? []).length, 1);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("marks only persisted project CODEX_HOME as project-local cleanup target", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveProjectLocalCodexHomeForLaunch(wd, {}), join(wd, ".codex"));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("does not mark explicit CODEX_HOME as project-local cleanup target", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveProjectLocalCodexHomeForLaunch(wd, {
+                CODEX_HOME: "/tmp/user-global-codex-home",
+            }), undefined);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("includes project Codex history artifacts in the runtime mirror for resume launches", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-resume-runtime-codex-home-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(join(projectCodexHome, "sessions", "2026", "06", "03"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(join(projectCodexHome, "config.toml"), 'model = "gpt-5.5"\n');
+            await writeFile(join(projectCodexHome, "state_5.sqlite"), "state db placeholder");
+            await writeFile(join(projectCodexHome, "state_5.sqlite-wal"), "state db wal placeholder");
+            await writeFile(join(projectCodexHome, "logs_2.sqlite-shm"), "logs db shm placeholder");
+            await writeFile(join(projectCodexHome, "sessions", "2026", "06", "03", "rollout-session-2712.jsonl"), '{"type":"session_meta","payload":{"id":"session-2712"}}\n');
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-resume", {}, {
+                includeHistoryArtifacts: true,
+            });
+            const runtimeCodexHome = runtimeCodexHomePath(wd, "session-resume");
+            assert.equal(prepared.codexHomeOverride, runtimeCodexHome);
+            assert.equal(prepared.sqliteHomeOverride, projectCodexHome);
+            assert.equal(existsSync(join(runtimeCodexHome, "state_5.sqlite")), true);
+            assert.equal(existsSync(join(runtimeCodexHome, "state_5.sqlite-wal")), true);
+            assert.equal(existsSync(join(runtimeCodexHome, "logs_2.sqlite-shm")), true);
+            assert.equal(existsSync(join(runtimeCodexHome, "sessions", "2026", "06", "03", "rollout-session-2712.jsonl")), true);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses a session-scoped CODEX_HOME mirror for project launch config writes", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-runtime-codex-home-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            const configPath = join(projectCodexHome, "config.toml");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(join(projectCodexHome, "agents"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            const originalConfig = [
+                'model = "gpt-5.5"',
+                "",
+                "[tui]",
+                'status_line = ["model-with-reasoning", "git-branch"]',
+                "",
+            ].join("\n");
+            await writeFile(configPath, originalConfig);
+            await writeFile(join(projectCodexHome, "agents", "planner.toml"), 'name = "planner"\n');
+            await writeFile(join(projectCodexHome, "hooks.json"), '{"hooks":{}}\n');
+            await writeFile(join(projectCodexHome, "state_5.sqlite"), "state db placeholder");
+            await writeFile(join(projectCodexHome, "state_5.sqlite-wal"), "state db wal placeholder");
+            await writeFile(join(projectCodexHome, "logs_2.sqlite-shm"), "logs db shm placeholder");
+            const beforeStat = await stat(configPath);
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-2033", {});
+            const runtimeCodexHome = runtimeCodexHomePath(wd, "session-2033");
+            assert.equal(prepared.codexHomeOverride, runtimeCodexHome);
+            assert.equal(prepared.sqliteHomeOverride, projectCodexHome);
+            assert.equal(prepared.projectLocalCodexHomeForCleanup, projectCodexHome);
+            assert.equal(prepared.runtimeCodexHomeForCleanup, runtimeCodexHome);
+            assert.equal(await readFile(join(runtimeCodexHome, "config.toml"), "utf-8"), originalConfig);
+            assert.equal(await readFile(join(runtimeCodexHome, "agents", "planner.toml"), "utf-8"), 'name = "planner"\n');
+            // GH #2470: hooks.json must NOT be mirrored into the runtime CODEX_HOME.
+            // Codex still loads the canonical project .codex/hooks.json as Project
+            // config; a runtime mirror would add a duplicate User config hook source.
+            assert.equal(existsSync(join(runtimeCodexHome, "hooks.json")), false);
+            assert.equal(existsSync(join(runtimeCodexHome, "state_5.sqlite")), false);
+            assert.equal(existsSync(join(runtimeCodexHome, "state_5.sqlite-wal")), false);
+            assert.equal(existsSync(join(runtimeCodexHome, "logs_2.sqlite-shm")), false);
+            await writeFile(join(runtimeCodexHome, "config.toml"), `${originalConfig}\n[tui.model_availability_nux]\n"gpt-5.5" = 1\n`);
+            assert.equal(await readFile(configPath, "utf-8"), originalConfig);
+            assert.doesNotMatch(await readFile(configPath, "utf-8"), /model_availability_nux/);
+            assert.equal((await stat(configPath)).mtimeMs, beforeStat.mtimeMs);
+            await prepareCodexHomeForLaunch(wd, "session-2033-repeat", {});
+            assert.equal(await readFile(configPath, "utf-8"), originalConfig);
+            assert.equal((await stat(configPath)).mtimeMs, beforeStat.mtimeMs);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("persists project-scope Codex auth written into the runtime CODEX_HOME mirror", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-runtime-auth-home-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(projectCodexHome, { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(join(projectCodexHome, "config.toml"), 'model = "gpt-5.5"\n');
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-auth", {});
+            const runtimeCodexHome = runtimeCodexHomePath(wd, "session-auth");
+            const opaqueAuthState = JSON.stringify({ token: "opaque-test-token" });
+            await writeFile(join(runtimeCodexHome, "auth.json"), opaqueAuthState);
+            await writeFile(join(runtimeCodexHome, "config.toml"), 'model = "gpt-5.5"\n[tui.model_availability_nux]\n"gpt-5.5" = 1\n');
+            await persistProjectLaunchRuntimeAuthState(prepared.runtimeCodexHomeForCleanup, prepared.projectLocalCodexHomeForCleanup);
+            assert.equal(await readFile(join(projectCodexHome, "auth.json"), "utf-8"), opaqueAuthState);
+            assert.equal(await readFile(join(projectCodexHome, "config.toml"), "utf-8"), 'model = "gpt-5.5"\n');
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("project-scope launch registers native hooks exactly once and persists trust state (GH #2470)", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-issue-2470-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(projectCodexHome, { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            const originalProjectConfig = [
+                'model = "gpt-5.5"',
+                "",
+                "[features]",
+                "hooks = true",
+                "",
+                "# OMX-owned Codex hook trust state",
+                "# Trusts only setup-managed codex-native-hook.js wrappers.",
+                `[hooks.state."${join(projectCodexHome, "hooks.json")}:pre_tool_use:0:0"]`,
+                'trusted_hash = "sha256:project-hooks-trusted"',
+                "# End OMX-owned Codex hook trust state",
+                "",
+            ].join("\n");
+            await writeFile(join(projectCodexHome, "config.toml"), originalProjectConfig);
+            await writeFile(join(projectCodexHome, "hooks.json"), '{"hooks":{}}\n');
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-2470", {});
+            const runtimeCodexHome = runtimeCodexHomePath(wd, "session-2470");
+            // 1. Hooks register exactly once: runtime CODEX_HOME holds no hooks.json
+            //    mirror, so Codex only sees the canonical project .codex/hooks.json.
+            assert.equal(prepared.codexHomeOverride, runtimeCodexHome);
+            assert.equal(existsSync(join(runtimeCodexHome, "hooks.json")), false);
+            assert.equal(existsSync(join(projectCodexHome, "hooks.json")), true);
+            // Simulate Codex writing workspace trust + a new hook trust ledger
+            // entry into the runtime config.toml during the session.
+            const runtimeConfigPath = join(runtimeCodexHome, "config.toml");
+            const runtimeConfigBefore = await readFile(runtimeConfigPath, "utf-8");
+            await writeFile(runtimeConfigPath, [
+                runtimeConfigBefore.replace(/\n+$/, ""),
+                "",
+                `[projects."${wd}"]`,
+                'trust_level = "trusted"',
+                "",
+                "[tui.model_availability_nux]",
+                '"gpt-5.5" = 1',
+                "",
+            ].join("\n"));
+            // 2. Workspace trust + ephemeral runtime state are persisted to the
+            //    project config.toml in a marker-fenced block; NUX counters and
+            //    other runtime-only writes are NOT leaked back to the project.
+            await persistProjectLaunchRuntimeProjectTrustState(prepared.runtimeCodexHomeForCleanup, prepared.projectLocalCodexHomeForCleanup);
+            const persistedProjectConfig = await readFile(join(projectCodexHome, "config.toml"), "utf-8");
+            assert.ok(persistedProjectConfig.includes("# OMX-synced Codex project trust state"), "expected synced-trust marker block in project config.toml");
+            assert.ok(persistedProjectConfig.includes(`[projects."${wd}"]`), "expected workspace trust entry to be persisted to project config.toml");
+            assert.ok(persistedProjectConfig.includes('trust_level = "trusted"'), "expected trust_level to be persisted to project config.toml");
+            assert.doesNotMatch(persistedProjectConfig, /model_availability_nux/, "NUX counters must not leak into durable project config.toml");
+            const projectHookTrustHeader = `[hooks.state."${join(projectCodexHome, "hooks.json")}:pre_tool_use:0:0"]`;
+            assert.ok(persistedProjectConfig.includes(projectHookTrustHeader), "setup-owned project hook trust state must remain intact");
+            assert.equal(countMatches(persistedProjectConfig, new RegExp(`^${escapeRegExp(projectHookTrustHeader)}$`, "gm")), 1, "runtime trust sync must not duplicate setup-owned hook trust state");
+            assert.doesNotThrow(() => TOML.parse(persistedProjectConfig));
+            // 3. On a subsequent launch, the runtime mirror carries the persisted
+            //    project trust state forward — so Codex finds the workspace as
+            //    already-trusted and never re-prompts.
+            await rm(runtimeCodexHome, { recursive: true, force: true });
+            await prepareCodexHomeForLaunch(wd, "session-2470-repeat", {});
+            const nextRuntimeCodexHome = runtimeCodexHomePath(wd, "session-2470-repeat");
+            const nextRuntimeConfig = await readFile(join(nextRuntimeCodexHome, "config.toml"), "utf-8");
+            assert.ok(nextRuntimeConfig.includes(`[projects."${wd}"]`), "next launch must inherit the persisted workspace trust entry");
+            assert.equal(countMatches(nextRuntimeConfig, new RegExp(`^${escapeRegExp(projectHookTrustHeader)}$`, "gm")), 1, "next runtime config must remain parseable without duplicate hook trust tables");
+            assert.doesNotThrow(() => TOML.parse(nextRuntimeConfig));
+            assert.equal(existsSync(join(nextRuntimeCodexHome, "hooks.json")), false);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("repairs duplicate project hook trust state before relaunching project-scope Codex home (GH #2401)", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-issue-2401-relaunch-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            const projectConfigPath = join(projectCodexHome, "config.toml");
+            const projectHooksPath = join(projectCodexHome, "hooks.json");
+            const projectHookTrustHeader = `[hooks.state."${projectHooksPath}:post_compact:0:0"]`;
+            const escapedProjectHookTrustHeader = escapeRegExp(projectHookTrustHeader);
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(projectCodexHome, { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(projectHooksPath, '{"hooks":{}}\n');
+            await writeFile(projectConfigPath, [
+                'model = "gpt-5.5"',
+                "",
+                "[features]",
+                "hooks = true",
+                "",
+                "# OMX-owned Codex hook trust state",
+                "# Trusts only setup-managed native hook wrappers.",
+                projectHookTrustHeader,
+                'trusted_hash = "sha256:setup-owned"',
+                "# End OMX-owned Codex hook trust state",
+                "",
+                "# OMX-synced Codex project trust state (from runtime CODEX_HOME)",
+                `[projects."${wd}"]`,
+                'trust_level = "trusted"',
+                "",
+                projectHookTrustHeader,
+                'trusted_hash = "sha256:setup-owned"',
+                "",
+                "# End OMX-synced Codex project trust state",
+                "",
+            ].join("\n"));
+            assert.throws(() => TOML.parse(readFileSync(projectConfigPath, "utf-8")));
+            await prepareCodexHomeForLaunch(wd, "session-relaunch", {});
+            const repairedProjectConfig = await readFile(projectConfigPath, "utf-8");
+            const runtimeConfig = await readFile(join(runtimeCodexHomePath(wd, "session-relaunch"), "config.toml"), "utf-8");
+            assert.doesNotThrow(() => TOML.parse(repairedProjectConfig));
+            assert.doesNotThrow(() => TOML.parse(runtimeConfig));
+            assert.equal(countMatches(repairedProjectConfig, new RegExp(`^${escapedProjectHookTrustHeader}$`, "gm")), 1);
+            assert.equal(countMatches(runtimeConfig, new RegExp(`^${escapedProjectHookTrustHeader}$`, "gm")), 1);
+            assert.ok(runtimeConfig.includes(`[projects."${wd}"]`));
+            assert.ok(repairedProjectConfig.includes(`[projects."${wd}"]`));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("keeps setup-owned hook trust state targeted at the project hooks path (GH #2470)", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-runtime-hook-trust-"));
+        try {
+            const projectCodexHome = join(wd, ".codex");
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(projectCodexHome, { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(join(projectCodexHome, "hooks.json"), '{"hooks":{}}\n');
+            const projectHookTrustHeader = `[hooks.state."${join(projectCodexHome, "hooks.json")}:pre_tool_use:0:0"]`;
+            await writeFile(join(projectCodexHome, "config.toml"), [
+                "[features]",
+                "hooks = true",
+                "",
+                "# OMX-owned Codex hook trust state",
+                "# Trusts only setup-managed codex-native-hook.js wrappers.",
+                projectHookTrustHeader,
+                'trusted_hash = "sha256:abc"',
+                "# End OMX-owned Codex hook trust state",
+                "",
+            ].join("\n"));
+            await prepareCodexHomeForLaunch(wd, "session-trust", {});
+            const runtimeCodexHome = runtimeCodexHomePath(wd, "session-trust");
+            const runtimeConfig = await readFile(join(runtimeCodexHome, "config.toml"), "utf-8");
+            // Runtime CODEX_HOME no longer holds a hooks.json mirror, so the trust
+            // block must continue pointing at the canonical project hooks.json path.
+            assert.equal(existsSync(join(runtimeCodexHome, "hooks.json")), false);
+            assert.ok(runtimeConfig.includes(projectHookTrustHeader), `expected runtime config.toml to keep ${projectHookTrustHeader}`);
+            assert.doesNotMatch(runtimeConfig, new RegExp(join(runtimeCodexHome, "hooks.json").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses boxed runtime root for project-scope CODEX_HOME mirrors", async () => {
+        const source = await mkdtemp(join(tmpdir(), "omx-launch-boxed-source-"));
+        const boxedRoot = await mkdtemp(join(tmpdir(), "omx-launch-boxed-root-"));
+        const prevOmxRoot = process.env.OMX_ROOT;
+        try {
+            process.env.OMX_ROOT = boxedRoot;
+            const projectCodexHome = join(source, ".codex");
+            await mkdir(join(source, ".omx"), { recursive: true });
+            await mkdir(projectCodexHome, { recursive: true });
+            await writeFile(join(source, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(join(projectCodexHome, "config.toml"), 'model = "gpt-5.5"\n');
+            const prepared = await prepareCodexHomeForLaunch(source, "session-boxed", {});
+            const runtimeCodexHome = runtimeCodexHomePath(source, "session-boxed");
+            assert.equal(runtimeCodexHome, join(boxedRoot, ".omx", "runtime", "codex-home", "session-boxed"));
+            assert.equal(prepared.codexHomeOverride, runtimeCodexHome);
+            assert.equal(prepared.runtimeCodexHomeForCleanup, runtimeCodexHome);
+            assert.equal(await readFile(join(runtimeCodexHome, "config.toml"), "utf-8"), 'model = "gpt-5.5"\n');
+        }
+        finally {
+            if (typeof prevOmxRoot === "string")
+                process.env.OMX_ROOT = prevOmxRoot;
+            else
+                delete process.env.OMX_ROOT;
+            await rm(source, { recursive: true, force: true });
+            await rm(boxedRoot, { recursive: true, force: true });
+        }
+    });
+    it("keeps explicit CODEX_HOME persistent instead of creating a runtime mirror", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-runtime-codex-home-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-explicit", {
+                CODEX_HOME: "/tmp/explicit-codex-home",
+            });
+            assert.equal(prepared.codexHomeOverride, "/tmp/explicit-codex-home");
+            assert.equal(prepared.sqliteHomeOverride, undefined);
+            assert.equal(prepared.projectLocalCodexHomeForCleanup, undefined);
+            assert.equal(prepared.runtimeCodexHomeForCleanup, undefined);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("respects explicit CODEX_SQLITE_HOME for project-scope launches", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-sqlite-home-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await mkdir(join(wd, ".codex"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            await writeFile(join(wd, ".codex", "config.toml"), 'model = "gpt-5.5"\n');
+            const prepared = await prepareCodexHomeForLaunch(wd, "session-explicit-sqlite", {
+                [CODEX_SQLITE_HOME_ENV]: "/tmp/explicit-sqlite-home",
+            });
+            assert.equal(prepared.codexHomeOverride, runtimeCodexHomePath(wd, "session-explicit-sqlite"));
+            assert.equal(prepared.sqliteHomeOverride, undefined);
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("keeps explicit CODEX_HOME override from env", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveCodexHomeForLaunch(wd, {
+                CODEX_HOME: "/tmp/explicit-codex-home",
+            }), "/tmp/explicit-codex-home");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("uses explicit CODEX_HOME config.toml for launch repair overrides", async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project" }));
+            assert.equal(resolveCodexConfigPathForLaunch(wd, {
+                CODEX_HOME: "/tmp/explicit-codex-home",
+            }), "/tmp/explicit-codex-home/config.toml");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it('migrates legacy "project-local" persisted scope to "project"', async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project-local" }));
+            assert.equal(readPersistedSetupScope(wd), "project");
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it('resolves CODEX_HOME for legacy "project-local" persisted scope', async () => {
+        const wd = await mkdtemp(join(tmpdir(), "omx-launch-scope-"));
+        try {
+            await mkdir(join(wd, ".omx"), { recursive: true });
+            await writeFile(join(wd, ".omx", "setup-scope.json"), JSON.stringify({ scope: "project-local" }));
+            assert.equal(resolveCodexHomeForLaunch(wd, {}), join(wd, ".codex"));
+        }
+        finally {
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+});
+describe("resolveCodexLaunchPolicy", () => {
+    it("uses detached tmux on macOS when outside tmux and tmux is available", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "darwin", true, false, true, true), "detached-tmux");
+    });
+    it("uses tmux-aware launch path when already inside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({ TMUX: "/tmp/tmux-1000/default,123,0" }, "darwin", true), "inside-tmux");
+    });
+    it("uses tmux-aware launch path when already inside tmux on native Windows", () => {
+        assert.equal(resolveCodexLaunchPolicy({ TMUX: "psmux-session" }, "win32", true, true), "inside-tmux");
+    });
+    it("uses detached tmux on non-macOS hosts when outside tmux and tmux is available", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", true, false, true, true), "detached-tmux");
+    });
+    it("launches directly on native Windows even when tmux is available", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "win32", true, true), "direct");
+    });
+    it("does not force direct launch for MSYS or Git Bash on win32", () => {
+        assert.equal(resolveCodexLaunchPolicy({ MSYSTEM: "MINGW64" }, "win32", true, false, true, true), "direct");
+    });
+    it("honors explicit detached tmux launch requests when tmux is available", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", true, false, true, true, "detached-tmux"), "detached-tmux");
+    });
+    it("honors explicit direct launch requests outside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", true, false, true, true, "direct"), "direct");
+    });
+    it("honors explicit direct launch requests inside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({ TMUX: "/tmp/tmux-1000/default,123,0" }, "linux", true, false, true, true, "direct"), "direct");
+    });
+    it("keeps explicit tmux policy tmux-aware inside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({ TMUX: "/tmp/tmux-1000/default,123,0" }, "linux", true, false, true, true, "detached-tmux"), "inside-tmux");
+    });
+    it("falls back directly for explicit tmux requests when tmux is unavailable", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", false, false, true, true, "detached-tmux"), "direct");
+    });
+    it("launches directly when stdin is not a tty outside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", true, false, false, true), "direct");
+    });
+    it("launches directly when stdout is not a tty outside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", true, false, true, false), "direct");
+    });
+    it("launches directly when tmux is unavailable outside tmux", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "linux", false), "direct");
+    });
+    it("launches directly on native Windows when tmux is unavailable", () => {
+        assert.equal(resolveCodexLaunchPolicy({}, "win32", false, true), "direct");
+    });
+});
+describe("resolveBackgroundHelperLaunchMode", () => {
+    it("uses the hidden Windows MSYS bootstrap for win32 Git Bash", () => {
+        assert.equal(resolveBackgroundHelperLaunchMode({ MSYSTEM: "MINGW64" }, "win32"), "windows-msys-bootstrap");
+    });
+    it("spawns helpers directly on native win32", () => {
+        assert.equal(resolveBackgroundHelperLaunchMode({}, "win32"), "direct-detached");
+    });
+    it("spawns helpers directly on non-Windows platforms", () => {
+        assert.equal(resolveBackgroundHelperLaunchMode({ MSYSTEM: "MINGW64" }, "linux"), "direct-detached");
+    });
+});
+describe("shouldDetachBackgroundHelper", () => {
+    it("keeps the long-running helper detached under win32 Git Bash", () => {
+        assert.equal(shouldDetachBackgroundHelper({ MSYSTEM: "MINGW64" }, "win32"), true);
+    });
+    it("keeps detached helpers on native win32", () => {
+        assert.equal(shouldDetachBackgroundHelper({}, "win32"), true);
+    });
+    it("keeps detached helpers on non-Windows platforms", () => {
+        assert.equal(shouldDetachBackgroundHelper({ MSYSTEM: "MINGW64" }, "linux"), true);
+    });
+});
+describe("classifyCodexExecFailure", () => {
+    it("classifies child process exit status as codex exit", () => {
+        const err = Object.assign(new Error("codex exited 9"), { status: 9 });
+        const classified = classifyCodexExecFailure(err);
+        assert.equal(classified.kind, "exit");
+        assert.equal(classified.exitCode, 9);
+    });
+    it("classifies signal termination as codex exit and maps to signal-based exit code", () => {
+        const err = Object.assign(new Error("terminated"), {
+            status: null,
+            signal: "SIGTERM",
+        });
+        const classified = classifyCodexExecFailure(err);
+        assert.equal(classified.kind, "exit");
+        assert.equal(classified.signal, "SIGTERM");
+        assert.equal(classified.exitCode, resolveSignalExitCode("SIGTERM"));
+    });
+    it("classifies ENOENT as launch error", () => {
+        const err = Object.assign(new Error("spawn codex ENOENT"), {
+            code: "ENOENT",
+        });
+        const classified = classifyCodexExecFailure(err);
+        assert.equal(classified.kind, "launch-error");
+        assert.equal(classified.code, "ENOENT");
+    });
+});
+describe("tmux HUD pane helpers", () => {
+    it("findHudWatchPaneIds detects stale HUD watch panes and excludes current pane", () => {
+        const panes = parseTmuxPaneSnapshot([
+            "%1\tzsh\tzsh",
+            "%2\tnode\tnode /tmp/bin/omx.js hud --watch",
+            "%3\tnode\tnode /tmp/bin/omx.js hud --watch",
+            "%4\tcodex\tcodex --model gpt-5",
+        ].join("\n"));
+        assert.deepEqual(findHudWatchPaneIds(panes, "%2"), ["%3"]);
+    });
+    it("buildHudPaneCleanupTargets de-dupes pane ids and includes created pane", () => {
+        assert.deepEqual(buildHudPaneCleanupTargets(["%3", "%3", "invalid"], "%4"), ["%3", "%4"]);
+    });
+    it("buildHudPaneCleanupTargets excludes leader pane from existing ids", () => {
+        // %5 is the leader pane — it must not be included even if findHudWatchPaneIds let it through.
+        assert.deepEqual(buildHudPaneCleanupTargets(["%3", "%5"], "%4", "%5"), [
+            "%3",
+            "%4",
+        ]);
+    });
+    it("buildHudPaneCleanupTargets excludes leader pane even when it matches the created HUD pane id", () => {
+        // Defensive edge case: if createHudWatchPane somehow returned the leader pane id, guard protects it.
+        assert.deepEqual(buildHudPaneCleanupTargets(["%3"], "%5", "%5"), ["%3"]);
+    });
+    it("buildHudPaneCleanupTargets is a no-op guard when leaderPaneId is absent", () => {
+        assert.deepEqual(buildHudPaneCleanupTargets(["%3"], "%4"), ["%3", "%4"]);
+    });
+    it("listCurrentWindowHudPaneIds scopes tmux pane listing to the emitting pane", () => {
+        const calls = [];
+        const panes = listCurrentWindowHudPaneIds("%leader", (args) => {
+            calls.push(args);
+            return [
+                "%leader\tcodex\tcodex",
+                "%hud\tnode\tnode /tmp/bin/omx.js hud --watch",
+            ].join("\n");
+        });
+        assert.deepEqual(panes, ["%hud"]);
+        assert.deepEqual(calls[0], [
+            "list-panes",
+            "-t",
+            "%leader",
+            "-F",
+            [
+                "#{pane_id}",
+                "#{pane_current_command}",
+                "#{pane_left}",
+                "#{pane_top}",
+                "#{pane_width}",
+                "#{pane_height}",
+                "#{pane_bottom}",
+                "#{window_width}",
+                "#{window_height}",
+                "#{pane_start_command}",
+                "#{pane_current_path}",
+            ].join("\x1f"),
+        ]);
+    });
+    it("createHudWatchPane splits from the emitting pane target when provided", () => {
+        const calls = [];
+        const paneId = createSharedHudWatchPane("/repo", "node /repo/dist/cli/omx.js hud --watch", { heightLines: 3, targetPaneId: "%leader" }, (args) => {
+            calls.push(args);
+            return "%hud\n";
+        });
+        assert.equal(paneId, "%hud");
+        assert.deepEqual(calls[0], [
+            "split-window",
+            "-v",
+            "-l",
+            "3",
+            "-d",
+            "-t",
+            "%leader",
+            "-c",
+            "/repo",
+            "-P",
+            "-F",
+            "#{pane_id}",
+            "node /repo/dist/cli/omx.js hud --watch",
+        ]);
+    });
+});
+describe("detached tmux new-session sequencing", () => {
+    it("buildDetachedSessionBootstrapSteps uses shared HUD height and split-capture ordering", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", "--model gpt-5", "/tmp/codex-home", '{"active":true}', false, "omx-session-test");
+        assert.deepEqual(steps.map((step) => step.name), ["new-session", "tag-session", "split-and-capture-hud-pane"]);
+        const splitStep = steps.find((step) => step.name === "split-and-capture-hud-pane");
+        assert.ok(splitStep);
+        assert.equal(splitStep.args[3], String(HUD_TMUX_HEIGHT_LINES));
+        assert.equal(splitStep.args[6], "omx-demo");
+        assert.equal(splitStep.args.includes("-P"), true);
+        assert.equal(splitStep.args.includes("#{pane_id}"), true);
+        assert.equal(steps[0]?.args.includes("-e"), true);
+        assert.equal(steps[0]?.args.includes("OMX_SESSION_ID=omx-session-test"), true);
+        assert.equal(steps[0]?.args.includes('OMX_NOTIFY_TEMP_CONTRACT={\"active\":true}'), true);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards temp contract env to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, '{"active":true,"canonicalSelectors":["discord"]}');
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.includes("-e") &&
+            newSession.args.some((arg) => arg.startsWith("OMX_NOTIFY_TEMP_CONTRACT=")), true);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards OMX_SESSION_ID to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'env' 'OMX_SESSION_ID=sess-detached-managed' 'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed");
+        const newSession = steps.find((step) => step.name === "new-session");
+        const tagSession = steps.find((step) => step.name === "tag-session");
+        assert.ok(newSession);
+        assert.ok(tagSession);
+        assert.equal(newSession.args.includes("-e") &&
+            newSession.args.some((arg) => arg === "OMX_SESSION_ID=sess-detached-managed"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_TMUX_HUD_OWNER=1"), true);
+        assert.deepEqual(tagSession.args, [
+            "set-option",
+            "-t",
+            "omx-demo",
+            "@omx_instance_id",
+            "sess-detached-managed",
+        ]);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards CODEX_HOME override to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, "/tmp/project/.codex", null, false, "sess-detached-managed");
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.includes("-e") &&
+            newSession.args.some((arg) => arg === "CODEX_HOME=/tmp/project/.codex"), true);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards CODEX_SQLITE_HOME override to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, "/tmp/project/.omx/runtime/codex-home/session-1", null, false, "sess-detached-managed", undefined, undefined, undefined, {}, "/tmp/project/.codex");
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.includes("-e") &&
+            newSession.args.some((arg) => arg === `${CODEX_SQLITE_HOME_ENV}=/tmp/project/.codex`), true);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards OMX_ROOT override to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, "/tmp/omx-root");
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.includes("-e") &&
+            newSession.args.some((arg) => arg === "OMX_ROOT=/tmp/omx-root"), true);
+    });
+    it("buildDetachedSessionBootstrapSteps forwards boxed env to detached tmux session", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/boxed-runtime", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, "/tmp/boxed-runtime", {
+            OMXBOX_ACTIVE: "1",
+            OMX_SOURCE_CWD: "/tmp/source-project",
+            OMX_STATE_ROOT: "/tmp/boxed-state-root",
+        });
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_ROOT=/tmp/boxed-runtime"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_STATE_ROOT=/tmp/boxed-state-root"), false);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_TMUX_HUD_OWNER=1"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMXBOX_ACTIVE=1"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_SOURCE_CWD=/tmp/source-project"), true);
+    });
+    it("buildDetachedSessionBootstrapSteps preserves OMX_STATE_ROOT identity when no root override is explicit", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, "/tmp/state-root", { OMX_STATE_ROOT: "/tmp/state-root" });
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_STATE_ROOT=/tmp/state-root"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_ROOT=/tmp/state-root"), false);
+    });
+    it("buildDetachedSessionBootstrapSteps preserves OMX_ROOT precedence over OMX_STATE_ROOT", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, "/tmp/root-from-omx-root", { OMX_STATE_ROOT: "/tmp/state-root-should-not-win" });
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_ROOT=/tmp/root-from-omx-root"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_STATE_ROOT=/tmp/state-root-should-not-win"), false);
+    });
+    it("buildDetachedSessionBootstrapSteps preserves OMX_TEAM_STATE_ROOT over explicit root env", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, "/tmp/root-from-omx-root", { OMX_ROOT: "/tmp/root-from-omx-root", OMX_TEAM_STATE_ROOT: "/tmp/team-state-root" });
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_TEAM_STATE_ROOT=/tmp/team-state-root"), true);
+        assert.equal(newSession.args.some((arg) => arg === "OMX_ROOT=/tmp/root-from-omx-root"), false);
+    });
+    it("serializes custom parent env for the interactive detached tmux leader without logging values in tmux args", () => {
+        const envFilePath = "/tmp/omx-runtime/tmux-env/sess.env";
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, undefined, { CUSTOM_LLM_API_KEY: "fake-provider-key", IS_GAJAE_SLOP_GENERATOR: "1" }, undefined, envFilePath);
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        const argsText = newSession.args.join("\n");
+        assert.match(argsText, new RegExp(envFilePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+        assert.doesNotMatch(argsText, /fake-provider-key/);
+        assert.doesNotMatch(argsText, /CUSTOM_LLM_API_KEY=/);
+        const envScript = serializeDetachedSessionParentEnv({
+            CUSTOM_LLM_API_KEY: "fake-provider-key",
+            IS_GAJAE_SLOP_GENERATOR: "1",
+            "not-a-shell-name": "ignored",
+        });
+        assert.match(envScript, /export CUSTOM_LLM_API_KEY='fake-provider-key'/);
+        assert.match(envScript, /export IS_GAJAE_SLOP_GENERATOR='1'/);
+        assert.doesNotMatch(envScript, /not-a-shell-name/);
+    });
+    it("creates a repo-local omx command shim for launched Codex sessions", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-"));
+        try {
+            const shimDir = ensureOmxRuntimeCommandShim(cwd, "/repo/dist/cli/omx.js", "/usr/local/bin/node");
+            const shimPath = omxRuntimeCommandShimPath(cwd);
+            assert.equal(shimDir, dirname(shimPath));
+            assert.equal(existsSync(shimPath), true);
+            assert.equal(await readFile(shimPath, "utf-8"), [
+                "#!/bin/sh",
+                `exec '/usr/local/bin/node' '/repo/dist/cli/omx.js' "$@"`,
+                "",
+            ].join("\n"));
+            assert.equal((await stat(shimPath)).mode & 0o700, 0o700);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("prepends the repo-local omx shim before global PATH entries", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-env-"));
+        try {
+            const env = prependOmxRuntimeCommandShimToEnv(cwd, {
+                PATH: "/opt/homebrew/bin:/usr/bin",
+                OMX_ENTRY_PATH: "/opt/homebrew/lib/node_modules/oh-my-codex/dist/cli/omx.js",
+            }, "/repo/dist/cli/omx.js", "/usr/local/bin/node");
+            const shimDir = dirname(omxRuntimeCommandShimPath(cwd));
+            assert.equal(env.PATH, `${shimDir}${delimiter}/opt/homebrew/bin:/usr/bin`);
+            assert.equal(env.OMX_ENTRY_PATH, "/repo/dist/cli/omx.js");
+            assert.equal(env.OMX_STARTUP_CWD, cwd);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("executes the repo-local omx shim before a stale global omx with misleading success output", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-exec-"));
+        try {
+            const fakeGlobalBin = join(cwd, "fake-global-bin");
+            const fakeLocalBin = join(cwd, "fake local's $() ; bin");
+            await mkdir(fakeGlobalBin);
+            await mkdir(fakeLocalBin);
+            const globalMarker = join(cwd, "GLOBAL_CALLED");
+            const localMarker = join(cwd, "LOCAL_CALLED");
+            const fakeGlobalOmx = join(fakeGlobalBin, "omx");
+            const fakeNode = join(fakeLocalBin, "node runner");
+            const localOmxEntry = join(fakeLocalBin, "omx entry's $() ;.js");
+            await writeFile(fakeGlobalOmx, `#!/bin/sh
+printf 'global-called\\n' > "${globalMarker}"
+printf '{"success":true,"source":"global"}\\n'
+exit 0
+`);
+            await chmod(fakeGlobalOmx, 0o755);
+            await writeFile(fakeNode, `#!/bin/sh
+printf '%s\\n' "$@" > "${localMarker}"
+printf '{"success":true,"source":"local"}\\n'
+exit 0
+`);
+            await chmod(fakeNode, 0o755);
+            const env = prependOmxRuntimeCommandShimToEnv(cwd, { PATH: `${fakeGlobalBin}${delimiter}/usr/bin:/bin` }, localOmxEntry, fakeNode);
+            const { execFileSync } = await import("node:child_process");
+            const output = execFileSync("omx", ["team", "status", "hud-check"], {
+                cwd,
+                env,
+                encoding: "utf-8",
+            });
+            assert.match(output, /"source":"local"/);
+            assert.equal(existsSync(globalMarker), false);
+            assert.deepEqual((await readFile(localMarker, "utf-8")).trim().split("\n"), [
+                localOmxEntry,
+                "team",
+                "status",
+                "hud-check",
+            ]);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("overwrites stale runtime shim contents and permissions", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-stale-"));
+        try {
+            const shimPath = omxRuntimeCommandShimPath(cwd);
+            await mkdir(dirname(shimPath), { recursive: true });
+            await writeFile(shimPath, "#!/bin/sh\necho stale-global\n");
+            await chmod(shimPath, 0o600);
+            ensureOmxRuntimeCommandShim(cwd, "/repo/dist/cli/omx.js", "/usr/local/bin/node");
+            assert.equal(await readFile(shimPath, "utf-8"), [
+                "#!/bin/sh",
+                `exec '/usr/local/bin/node' '/repo/dist/cli/omx.js' "$@"`,
+                "",
+            ].join("\n"));
+            assert.equal((await stat(shimPath)).mode & 0o777, 0o700);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("replaces a stale runtime shim symlink without following it", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-symlink-"));
+        try {
+            if (process.platform === "win32")
+                return;
+            const shimPath = omxRuntimeCommandShimPath(cwd);
+            const externalTarget = join(cwd, "outside-target");
+            await mkdir(dirname(shimPath), { recursive: true });
+            await writeFile(externalTarget, "do not overwrite\n");
+            await symlink(externalTarget, shimPath);
+            ensureOmxRuntimeCommandShim(cwd, "/repo/dist/cli/omx.js", "/usr/local/bin/node");
+            assert.equal(await readFile(externalTarget, "utf-8"), "do not overwrite\n");
+            assert.equal((await lstat(shimPath)).isSymbolicLink(), false);
+            assert.match(await readFile(shimPath, "utf-8"), /\/repo\/dist\/cli\/omx\.js/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("throws when the runtime shim bin path is not a directory", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-file-"));
+        try {
+            const shimPath = omxRuntimeCommandShimPath(cwd);
+            await mkdir(dirname(dirname(shimPath)), { recursive: true });
+            await writeFile(dirname(shimPath), "not a directory\n");
+            assert.throws(() => ensureOmxRuntimeCommandShim(cwd, "/repo/dist/cli/omx.js", "/usr/local/bin/node"), /not a directory/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("creates a Windows omx.cmd runtime shim with cmd batch content on win32", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-win-"));
+        try {
+            const shimDir = ensureOmxRuntimeCommandShim(cwd, "C:\\repo\\dist\\cli\\omx.js", "C:\\Program Files\\nodejs\\node.exe", "win32");
+            const shimPath = omxRuntimeCommandShimPath(cwd, "win32");
+            assert.equal(shimDir, dirname(shimPath));
+            assert.equal(shimPath.endsWith("omx.cmd"), true);
+            assert.equal(existsSync(shimPath), true);
+            assert.equal(await readFile(shimPath, "utf-8"), [
+                "@echo off",
+                `"C:\\Program Files\\nodejs\\node.exe" "C:\\repo\\dist\\cli\\omx.js" %*`,
+                "",
+            ].join("\r\n"));
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("preserves an inherited Windows Path key when prepending the shim dir", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-winpath-"));
+        try {
+            const env = prependOmxRuntimeCommandShimToEnv(cwd, { Path: "C:\\Windows\\System32;C:\\Windows" }, "C:\\repo\\dist\\cli\\omx.js", "C:\\Program Files\\nodejs\\node.exe", "win32");
+            const shimDir = dirname(omxRuntimeCommandShimPath(cwd, "win32"));
+            assert.equal(env.Path, `${shimDir};C:\\Windows\\System32;C:\\Windows`);
+            assert.equal(env.PATH, undefined);
+            assert.equal(env.OMX_ENTRY_PATH, "C:\\repo\\dist\\cli\\omx.js");
+            assert.equal(env.OMX_STARTUP_CWD, cwd);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("collapses duplicate Windows PATH/Path variants to a single Path key", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-windup-"));
+        try {
+            const env = prependOmxRuntimeCommandShimToEnv(cwd, { PATH: "", Path: "C:\\Windows\\System32" }, "C:\\repo\\dist\\cli\\omx.js", "C:\\Program Files\\nodejs\\node.exe", "win32");
+            const shimDir = dirname(omxRuntimeCommandShimPath(cwd, "win32"));
+            const pathKeys = Object.keys(env).filter((key) => key.toLowerCase() === "path");
+            assert.deepEqual(pathKeys, ["Path"]);
+            assert.equal(env.Path, `${shimDir};C:\\Windows\\System32`);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("seeds a Windows Path entry from the shim dir when none is inherited", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-runtime-command-shim-winempty-"));
+        try {
+            const env = prependOmxRuntimeCommandShimToEnv(cwd, {}, "C:\\repo\\dist\\cli\\omx.js", "C:\\Program Files\\nodejs\\node.exe", "win32");
+            const shimDir = dirname(omxRuntimeCommandShimPath(cwd, "win32"));
+            assert.equal(env.Path, shimDir);
+            assert.equal(env.PATH, undefined);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("keeps detached tmux bootstrap bounded when no interactive parent env file is requested", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, undefined, null, false, "sess-detached-managed", undefined, undefined, undefined, { CUSTOM_LLM_API_KEY: "fake-provider-key" });
+        const newSession = steps.find((step) => step.name === "new-session");
+        assert.ok(newSession);
+        const argsText = newSession.args.join("\n");
+        assert.doesNotMatch(argsText, /CUSTOM_LLM_API_KEY/);
+        assert.doesNotMatch(argsText, /fake-provider-key/);
+    });
+    it("runCodex cleans only same-session same-leader HUD panes before launch", async () => {
+        const source = await readFile(join(repoRoot, "src", "cli", "index.ts"), "utf8");
+        assert.match(source, /const staleHudPaneIds = currentPaneId\s*\? listHudWatchPaneIdsInCurrentWindow\(currentPaneId, \{ sessionId, leaderPaneId: currentPaneId \}\)\s*: \[\];/);
+        assert.match(source, /const \[keeperHudPaneId, \.\.\.duplicateHudPaneIds\] = staleHudPaneIds;/);
+        assert.match(source, /for \(const paneId of duplicateHudPaneIds\) \{\s*killTmuxPane\(paneId\);\s*\}/);
+        assert.match(source, /if \(keeperHudPaneId\) \{\s*hudPaneId = keeperHudPaneId;/);
+        assert.doesNotMatch(source, /const staleHudPaneIds = listHudWatchPaneIdsInCurrentWindow\(currentPaneId, \{ leaderPaneId: currentPaneId \}\);/);
+    });
+    it("runCodex skips launch-time HUD cleanup when TMUX_PANE is unavailable", async () => {
+        const source = await readFile(join(repoRoot, "src", "cli", "index.ts"), "utf8");
+        assert.match(source, /const staleHudPaneIds = currentPaneId\s*\? listHudWatchPaneIdsInCurrentWindow\(currentPaneId, \{ sessionId, leaderPaneId: currentPaneId \}\)\s*: \[\];/);
+    });
+    it("runCodex builds inside-tmux HUD command through explicit runtime-root resolver", async () => {
+        const source = await readFile(join(repoRoot, 'src', 'cli', 'index.ts'), 'utf-8');
+        assert.match(source, /const hudRuntimeRoot = resolveHudRuntimeRootForLaunch\(cwd, process\.env\);/);
+        assert.match(source, /const hudEnvArgs = Object\.entries\(buildHudRuntimeEnv\(\{\s*sessionId,\s*leaderPaneId: currentPaneId,\s*\.\.\.hudRuntimeRoot,\s*\}\)\.env\)\.map\(\(\[key, value\]\) => `\$\{key\}=\$\{value\}`\)/);
+        assert.match(source, /if \(env\.OMX_TEAM_STATE_ROOT\?\.trim\(\)\) return 'team-env';\s*if \(env\.OMX_ROOT\?\.trim\(\) \|\| omxRootOverride\) return 'omx-root-env';\s*if \(env\.OMX_STATE_ROOT\?\.trim\(\)\) return 'omx-state-root-env';/);
+        assert.match(source, /buildTmuxPaneCommand\("env",\s*\[\.\.\.hudEnvArgs,\s*"node",\s*omxBin,\s*"hud",\s*"--watch"\]\)/);
+    });
+    it("runCodex registers a HUD resize hook immediately for inside-tmux launches", async () => {
+        const source = await readFile(join(repoRoot, 'src', 'cli', 'index.ts'), 'utf-8');
+        assert.match(source, /registerInsideTmuxHudResizeHook\(\{\s*hudPaneId,\s*currentPaneId,\s*cwd,\s*sessionId,\s*omxRootOverride,\s*\}\)/);
+        assert.match(source, /if \(currentPaneId\) \{\s*unregisterHudResizeHook\(currentPaneId\);\s*\}/);
+    });
+    it("buildInsideTmuxHudHookEnv tags hook commands with session, owner, leader, and local root", () => {
+        const env = buildInsideTmuxHudHookEnv({ PATH: "/bin" }, "sess-a", "%leader", "/repo");
+        assert.equal(env.PATH, "/bin");
+        assert.equal(env.OMX_SESSION_ID, "sess-a");
+        assert.equal(env.OMX_TMUX_HUD_OWNER, "1");
+        assert.equal(env.OMX_TMUX_HUD_LEADER_PANE, "%leader");
+        assert.equal(env.OMX_ROOT, "/repo");
+    });
+    it("registerInsideTmuxHudResizeHook forwards cwd and env to hook registration", () => {
+        const calls = [];
+        const result = registerInsideTmuxHudResizeHook({
+            hudPaneId: "%hud",
+            currentPaneId: "%leader",
+            cwd: "/repo",
+            sessionId: "sess-a",
+            omxRootOverride: "/repo",
+            baseEnv: { PATH: "/bin" },
+            register: (hudPaneId, leaderPaneId, heightLines, options) => {
+                calls.push({ hudPaneId, leaderPaneId, heightLines, cwd: options?.cwd, env: options?.env });
+                return true;
+            },
+        });
+        assert.equal(result, true);
+        assert.deepEqual(calls, [{
+                hudPaneId: "%hud",
+                leaderPaneId: "%leader",
+                heightLines: HUD_TMUX_HEIGHT_LINES,
+                cwd: "/repo",
+                env: {
+                    PATH: "/bin",
+                    OMX_SESSION_ID: "sess-a",
+                    OMX_TMUX_HUD_OWNER: "1",
+                    OMX_TMUX_HUD_LEADER_PANE: "%leader",
+                    OMX_ROOT: "/repo",
+                },
+            }]);
+        assert.equal(registerInsideTmuxHudResizeHook({
+            hudPaneId: null,
+            currentPaneId: "%leader",
+            cwd: "/repo",
+            sessionId: "sess-a",
+            register: () => {
+                throw new Error("should not register without a HUD pane");
+            },
+        }), false);
+    });
+    it("buildDetachedHudHookEnv preserves tmux targeting and local launcher identity", () => {
+        const env = buildDetachedHudHookEnv({ PATH: "/bin" }, "sess-a", "%leader", "/tmp/tmux.sock,123,7", "/repo/dist/cli/omx.js", "/repo");
+        assert.equal(env.PATH, "/bin");
+        assert.equal(env.TMUX, "/tmp/tmux.sock,123,7");
+        assert.equal(env.TMUX_PANE, "%leader");
+        assert.equal(env.OMX_SESSION_ID, "sess-a");
+        assert.equal(env.OMX_TMUX_HUD_OWNER, "1");
+        assert.equal(env.OMX_ROOT, "/repo");
+        assert.equal(env.OMX_ENTRY_PATH, "/repo/dist/cli/omx.js");
+    });
+    it("registerDetachedHudLayoutReconcileHook reads TMUX from the detached leader pane before registering", () => {
+        const calls = [];
+        const readTargets = [];
+        const result = registerDetachedHudLayoutReconcileHook({
+            hudPaneId: "%hud",
+            detachedLeaderPaneId: "%leader",
+            cwd: "/repo",
+            sessionId: "sess-a",
+            omxBin: "/repo/dist/cli/omx.js",
+            omxRootOverride: "/repo",
+            baseEnv: { PATH: "/bin" },
+            readTmuxEnvValue: (targetPaneId) => {
+                readTargets.push(targetPaneId);
+                return "/tmp/tmux.sock,123,7";
+            },
+            register: (hudPaneId, leaderPaneId, heightLines, options) => {
+                calls.push({ hudPaneId, leaderPaneId, heightLines, cwd: options?.cwd, env: options?.env });
+                return true;
+            },
+        });
+        assert.equal(result, true);
+        assert.deepEqual(readTargets, ["%leader"]);
+        assert.deepEqual(calls, [{
+                hudPaneId: "%hud",
+                leaderPaneId: "%leader",
+                heightLines: HUD_TMUX_HEIGHT_LINES,
+                cwd: "/repo",
+                env: {
+                    PATH: "/bin",
+                    TMUX: "/tmp/tmux.sock,123,7",
+                    TMUX_PANE: "%leader",
+                    OMX_SESSION_ID: "sess-a",
+                    OMX_TMUX_HUD_OWNER: "1",
+                    OMX_ROOT: "/repo",
+                    OMX_ENTRY_PATH: "/repo/dist/cli/omx.js",
+                },
+            }]);
+        assert.equal(registerDetachedHudLayoutReconcileHook({
+            hudPaneId: "%hud",
+            detachedLeaderPaneId: "%leader",
+            cwd: "/repo",
+            sessionId: "sess-a",
+            omxBin: "/repo/dist/cli/omx.js",
+            readTmuxEnvValue: () => undefined,
+            register: () => {
+                throw new Error("should not register without TMUX");
+            },
+        }), false);
+    });
+    it("buildDetachedSessionBootstrapSteps starts native Windows detached sessions with powershell", () => {
+        const hudCmd = buildWindowsPromptCommand("node", [
+            "omx.js",
+            "hud",
+            "--watch",
+        ]);
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "C:/project", "'codex' '--dangerously-bypass-approvals-and-sandbox'", hudCmd, "--model gpt-5", "C:/codex-home", null, true);
+        assert.equal(steps[0]?.name, "new-session");
+        assert.equal(steps[0]?.args.at(-1), "powershell.exe");
+        assert.equal(steps[1]?.name, "split-and-capture-hud-pane");
+        assert.equal(steps[1]?.args.at(-1), hudCmd);
+    });
+    it("buildDetachedWindowsBootstrapScript targets the resolved tmux-compatible command", () => {
+        const script = buildDetachedWindowsBootstrapScript("omx-demo", "powershell.exe -NoLogo -NoExit -EncodedCommand abc", 2500, "C:\\Program Files\\psmux\\psmux.exe");
+        assert.match(script, /const tmuxCommand = "C:\\\\Program Files\\\\psmux\\\\psmux\.exe";/);
+        assert.match(script, /execFileSync\(tmuxCommand, \['send-keys'/);
+        assert.doesNotMatch(script, /execFileSync\('tmux'/);
+    });
+    it("buildDetachedSessionBootstrapSteps kills detached tmux session on normal shell exit", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+        const leaderCmd = steps[0]?.args.at(-1);
+        assert.equal(typeof leaderCmd, "string");
+        assert.match(leaderCmd, /^\/bin\/sh -c '/);
+        assert.doesNotMatch(leaderCmd, /^\/bin\/sh -lc '/);
+        assert.match(leaderCmd, /acquireTmuxExtendedKeysLease/);
+        assert.match(leaderCmd, /omx_detached_session_cleanup\(\)/);
+        assert.match(leaderCmd, /trap omx_detached_session_cleanup 0 INT TERM HUP;/);
+        assert.match(leaderCmd, /exec 3<&0;/);
+        assert.match(leaderCmd, /omx_codex_pid=\$!;/);
+        assert.match(leaderCmd, /<\&3 &/);
+        assert.match(leaderCmd, /wait "\$omx_codex_pid";/);
+        assert.match(leaderCmd, /kill -TERM "\$omx_codex_pid"/);
+        assert.match(leaderCmd, /releaseTmuxExtendedKeysLease/);
+        assert.match(leaderCmd, /if \[ "\$status" -eq 0 \]; then/);
+        assert.match(leaderCmd, /tmux kill-session -t/);
+        assert.match(leaderCmd, /"omx-demo"/);
+        assert.match(leaderCmd, /codex exited immediately with code 0/);
+        assert.match(leaderCmd, /codex exited with code/);
+        assert.match(leaderCmd, /detached tmux session is being kept open/);
+        assert.match(leaderCmd, /exit \$status/);
+    });
+    it("buildDetachedSessionBootstrapSteps finalizes postLaunch inside the detached leader when a session id is available", () => {
+        const steps = buildDetachedSessionBootstrapSteps("omx-demo", "/tmp/project", "'codex' '--model' 'gpt-5'", "'node' '/tmp/omx.js' 'hud' '--watch'", null, "/tmp/codex-home", null, false, "omx-session-123", "/tmp/project/.codex-project", "/tmp/project/.omx/runtime/codex-home/omx-session-123");
+        const leaderCmd = steps[0]?.args.at(-1);
+        assert.equal(typeof leaderCmd, "string");
+        assert.match(leaderCmd, /runDetachedSessionPostLaunch/);
+        assert.match(leaderCmd, /omx-session-123/);
+        assert.match(leaderCmd, /\/tmp\/codex-home/);
+        assert.match(leaderCmd, /\/tmp\/project\/\.codex-project/);
+        assert.match(leaderCmd, /\/tmp\/project\/\.omx\/runtime\/codex-home\/omx-session-123/);
+        const helperIndex = leaderCmd.indexOf("runDetachedSessionPostLaunch");
+        const signalGateIndex = leaderCmd.indexOf('if [ "$status" -eq 0 ]');
+        assert.ok(helperIndex >= 0);
+        assert.ok(signalGateIndex >= 0);
+        assert.ok(helperIndex < signalGateIndex, "detached postLaunch helper must run before the signal-derived tmux kill-session gate");
+    });
+    it("detached leader command keeps stdin open for the Codex child", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-stdin-"));
+        const fakeBin = join(cwd, "bin");
+        const stdinLogPath = join(cwd, "stdin.log");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+if IFS= read -r line; then
+  printf 'stdin:%s\n' "$line" > "${stdinLogPath}"
+else
+  printf 'stdin:EOF\n' > "${stdinLogPath}"
+fi
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\n'
+    else
+      printf '0\n'
+    fi
+    ;;
+  show-options)
+    printf 'off\n'
+    ;;
+  set-option|kill-session)
+    ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", [], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            const result = (await import("node:child_process")).spawnSync("/bin/sh", ["-c", leaderCmd], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                },
+                input: "hello from leader\n",
+                encoding: "utf-8",
+            });
+            assert.equal(result.status, 0, result.stderr || result.stdout);
+            const stdinLog = await readFile(stdinLogPath, "utf-8");
+            assert.match(stdinLog, /stdin:hello from leader/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("detached leader command preserves cwd and cleanup without shell-quote breakage", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-"));
+        const fakeBin = join(cwd, "bin");
+        const logPath = join(cwd, "leader.log");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+printf 'codex:%s\\n' "$*" >> "${logPath}"
+printf 'codex-pwd:%s\\n' "$(pwd)" >> "${logPath}"
+printf 'codex-bridge-env:%s\\n' "\${OMX_HERMES_MCP_BRIDGE-unset}" >> "${logPath}"
+exit 0
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(cwd, ".profile"), "cd ..\n");
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+printf 'tmux:%s\\n' "$*" >> "${logPath}"
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\\n'
+    else
+      printf '0\\n'
+    fi
+    ;;
+  show-options)
+    printf 'off\\n'
+    ;;
+  set-option|kill-session)
+    ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", ["--dangerously-bypass-approvals-and-sandbox"], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            (await import("node:child_process")).execFileSync("/bin/sh", ["-c", leaderCmd], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                    OMX_HERMES_MCP_BRIDGE: "1",
+                },
+                stdio: "ignore",
+            });
+            const log = await readFile(logPath, "utf-8");
+            assert.match(log, /codex:--dangerously-bypass-approvals-and-sandbox/);
+            assert.match(normalizeDarwinTmpPath(log), new RegExp(`codex-pwd:${escapeRegExp(normalizeDarwinTmpPath(cwd))}`));
+            assert.match(log, /codex-bridge-env:unset/);
+            assert.match(log, /tmux:display-message -p #\{socket_path\}/);
+            assert.match(log, /tmux:show-options -sv extended-keys/);
+            assert.match(log, /tmux:set-option -sq extended-keys always/);
+            assert.match(log, /tmux:set-option -sq extended-keys off/);
+            assert.match(log, /tmux:kill-session -t omx-demo/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("detached leader command preserves the detached tmux session on signal-derived exits", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-signal-"));
+        const fakeBin = join(cwd, "bin");
+        const logPath = join(cwd, "leader.log");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+printf 'codex:%s\\n' "$*" >> "${logPath}"
+exit 143
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+printf 'tmux:%s\\n' "$*" >> "${logPath}"
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\\n'
+    else
+      printf '0\\n'
+    fi
+    ;;
+  show-options)
+    printf 'off\\n'
+    ;;
+  set-option|kill-session)
+    ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", ["--dangerously-bypass-approvals-and-sandbox"], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            const result = (await import("node:child_process")).spawnSync("/bin/sh", ["-c", leaderCmd], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                },
+                encoding: "utf-8",
+            });
+            assert.equal(result.status, 143);
+            const log = await readFile(logPath, "utf-8");
+            assert.match(log, /codex:--dangerously-bypass-approvals-and-sandbox/);
+            assert.match(log, /tmux:display-message -p #\{socket_path\}/);
+            assert.match(log, /tmux:show-options -sv extended-keys/);
+            assert.match(log, /tmux:set-option -sq extended-keys always/);
+            assert.match(log, /tmux:set-option -sq extended-keys off/);
+            assert.doesNotMatch(log, /tmux:kill-session -t omx-demo/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("detached leader command keeps child startup errors visible instead of killing the session", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-error-"));
+        const fakeBin = join(cwd, "bin");
+        const logPath = join(cwd, "leader.log");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+printf 'codex-stderr: unsupported startup flag\\n' >&2
+exit 42
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+printf 'tmux:%s\\n' "$*" >> "${logPath}"
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\\n'
+    else
+      printf '0\\n'
+    fi
+    ;;
+  show-options)
+    printf 'off\\n'
+    ;;
+  set-option|kill-session)
+    ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", ["--bad-startup-flag"], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            const result = (await import("node:child_process")).spawnSync("/bin/sh", ["-c", leaderCmd], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                },
+                input: "\n",
+                encoding: "utf-8",
+            });
+            assert.equal(result.status, 42);
+            assert.match(result.stderr, /codex-stderr: unsupported startup flag/);
+            assert.match(result.stderr, /codex exited with code 42 during startup/);
+            assert.match(result.stderr, /detached tmux session is being kept open/);
+            const log = await readFile(logPath, "utf-8");
+            assert.doesNotMatch(log, /tmux:kill-session -t omx-demo/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("detached leader command keeps immediate zero-code exits visible instead of silently closing", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-zero-"));
+        const fakeBin = join(cwd, "bin");
+        const logPath = join(cwd, "leader.log");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+printf 'codex-started-then-quit\\n' >&2
+exit 0
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+printf 'tmux:%s\\n' "$*" >> "${logPath}"
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\\n'
+    else
+      printf '0\\n'
+    fi
+    ;;
+  show-options)
+    printf 'off\\n'
+    ;;
+  set-option|kill-session)
+    ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", [], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            const result = (await import("node:child_process")).spawnSync("/bin/sh", ["-c", leaderCmd], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                },
+                input: "\n",
+                encoding: "utf-8",
+            });
+            assert.equal(result.status, 0, result.stderr || result.stdout);
+            assert.match(result.stderr, /codex-started-then-quit/);
+            assert.match(result.stderr, /codex exited immediately with code 0 during startup/);
+            assert.match(result.stderr, /detached tmux session is being kept open/);
+            const log = await readFile(logPath, "utf-8");
+            assert.match(log, /tmux:kill-session -t omx-demo/);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("detached leader command terminates codex child on external SIGHUP", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-detached-leader-hup-"));
+        const fakeBin = join(cwd, "bin");
+        const pidFile = join(cwd, "codex.pid");
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "codex"), `#!/bin/sh
+echo $$ > "${pidFile}"
+trap '' HUP
+while true; do sleep 1; done
+`);
+            await chmod(join(fakeBin, "codex"), 0o755);
+            await writeFile(join(fakeBin, "tmux"), `#!/bin/sh
+case "$1" in
+  display-message)
+    if [ "$3" = '#{socket_path}' ] || [ "$4" = '#{socket_path}' ]; then
+      printf '/tmp/tmux-test.sock\\n'
+    else
+      printf '0\\n'
+    fi
+    ;;
+  show-options) printf 'off\\n' ;;
+  set-option|kill-session) ;;
+esac
+exit 0
+`);
+            await chmod(join(fakeBin, "tmux"), 0o755);
+            const steps = buildDetachedSessionBootstrapSteps("omx-demo", cwd, buildTmuxPaneCommand("codex", [], "/bin/sh"), "'node' '/tmp/omx.js' 'hud' '--watch'", null);
+            const leaderCmd = steps[0]?.args.at(-1);
+            assert.equal(typeof leaderCmd, "string");
+            const { spawn } = await import("node:child_process");
+            const child = spawn("/bin/sh", ["-c", `exec ${leaderCmd}`], {
+                cwd,
+                env: {
+                    ...process.env,
+                    PATH: `${fakeBin}:/usr/bin:/bin`,
+                    HOME: cwd,
+                },
+                stdio: "ignore",
+                detached: true,
+            });
+            try {
+                for (let i = 0; i < 50; i += 1) {
+                    if (existsSync(pidFile))
+                        break;
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+                assert.ok(existsSync(pidFile), "codex pid file not written");
+                const codexPid = Number.parseInt((await readFile(pidFile, "utf-8")).trim(), 10);
+                assert.ok(codexPid > 0, "codex pid must be positive");
+                assert.doesNotThrow(() => process.kill(codexPid, 0), "codex must be alive before signal");
+                const leaderExit = once(child, "exit");
+                process.kill(child.pid, "SIGHUP");
+                await Promise.race([
+                    leaderExit,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("leader did not exit after SIGHUP")), 3000)),
+                ]);
+                assert.throws(() => process.kill(codexPid, 0), (err) => typeof err === "object" &&
+                    err !== null &&
+                    "code" in err &&
+                    err.code === "ESRCH", "codex child must be terminated after leader SIGHUP");
+            }
+            finally {
+                try {
+                    process.kill(child.pid, "SIGKILL");
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("withTmuxExtendedKeys enables tmux extended keys during codex launch and restores them afterwards", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-lease-wrapper-"));
+        const calls = [];
+        const result = withTmuxExtendedKeys(cwd, () => {
+            calls.push(["run"]);
+            return "ok";
+        }, (_file, args) => {
+            calls.push([...args]);
+            if (args[0] === "show-options")
+                return "off\n";
+            return "";
+        });
+        await rm(cwd, { recursive: true, force: true });
+        assert.equal(result, "ok");
+        assert.deepEqual(calls, [
+            ["display-message", "-p", "#{socket_path}"],
+            ["show-options", "-sv", "extended-keys"],
+            ["set-option", "-sq", "extended-keys", "always"],
+            ["run"],
+            ["set-option", "-sq", "extended-keys", "off"],
+        ]);
+    });
+    it("acquireTmuxExtendedKeysLease can bind lease liveness to a long-lived owner pid", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-lease-owner-pid-"));
+        try {
+            const execStub = (_file, args) => {
+                if (args[0] === "display-message")
+                    return "/tmp/tmux-owner-pid.sock\n";
+                if (args[0] === "show-options")
+                    return "off\n";
+                return "";
+            };
+            const lease = acquireTmuxExtendedKeysLease(cwd, execStub, 12345);
+            assert.match(lease ?? "", /^\/tmp\/tmux-owner-pid\.sock\t12345-/);
+            if (lease)
+                releaseTmuxExtendedKeysLease(cwd, lease, execStub);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("overlapping tmux extended-keys leases restore only after the last holder exits", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-lease-overlap-"));
+        const calls = [];
+        const execStub = (_file, args) => {
+            calls.push([...args]);
+            if (args[0] === "display-message")
+                return "/tmp/tmux-test.sock\n";
+            if (args[0] === "show-options")
+                return "off\n";
+            return "";
+        };
+        const leaseA = acquireTmuxExtendedKeysLease(cwd, execStub);
+        const leaseB = acquireTmuxExtendedKeysLease(cwd, execStub);
+        assert.equal(typeof leaseA, "string");
+        assert.equal(typeof leaseB, "string");
+        releaseTmuxExtendedKeysLease(cwd, leaseA, execStub);
+        const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+        const leaseFilesAfterFirstRelease = await readFile(join(leaseDir, "tmp-tmux-test-sock.json"), "utf-8");
+        assert.match(leaseFilesAfterFirstRelease, /holders/);
+        releaseTmuxExtendedKeysLease(cwd, leaseB, execStub);
+        await assert.rejects(readFile(join(leaseDir, "tmp-tmux-test-sock.json"), "utf-8"), /ENOENT/);
+        await rm(cwd, { recursive: true, force: true });
+        assert.deepEqual(calls, [
+            ["display-message", "-p", "#{socket_path}"],
+            ["show-options", "-sv", "extended-keys"],
+            ["set-option", "-sq", "extended-keys", "always"],
+            ["display-message", "-p", "#{socket_path}"],
+            ["set-option", "-sq", "extended-keys", "off"],
+        ]);
+    });
+    it("withTmuxExtendedKeys degrades cleanly when tmux option probing fails", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-lease-fail-"));
+        const calls = [];
+        const result = withTmuxExtendedKeys(cwd, () => {
+            calls.push(["run"]);
+            return "ok";
+        }, (_file, args) => {
+            calls.push([...args]);
+            if (args[0] === "show-options")
+                throw new Error("tmux unavailable");
+            return "";
+        });
+        await rm(cwd, { recursive: true, force: true });
+        assert.equal(result, "ok");
+        assert.deepEqual(calls, [
+            ["display-message", "-p", "#{socket_path}"],
+            ["show-options", "-sv", "extended-keys"],
+            ["run"],
+        ]);
+    });
+    it("withTmuxExtendedKeys ignores tmux versions without the extended-keys option", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-lease-unsupported-"));
+        const calls = [];
+        const stderrWrite = mock.method(process.stderr, "write", () => true);
+        try {
+            const result = withTmuxExtendedKeys(cwd, () => {
+                calls.push(["run"]);
+                return "ok";
+            }, (_file, args) => {
+                calls.push([...args]);
+                if (args[0] === "display-message")
+                    return "/tmp/tmux-3-0.sock\n";
+                if (args[0] === "show-options") {
+                    throw Object.assign(new Error("Command failed: tmux show-options -sv extended-keys"), {
+                        status: 1,
+                        stderr: Buffer.from("invalid option: extended-keys\n"),
+                        stdout: Buffer.from(""),
+                    });
+                }
+                return "";
+            });
+            assert.equal(result, "ok");
+            assert.deepEqual(calls, [
+                ["display-message", "-p", "#{socket_path}"],
+                ["show-options", "-sv", "extended-keys"],
+                ["run"],
+            ]);
+            assert.equal(stderrWrite.mock.callCount(), 0);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("acquireTmuxExtendedKeysLease returns no lease when extended-keys is unsupported", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-acquire-unsupported-"));
+        const calls = [];
+        const stderrWrite = mock.method(process.stderr, "write", () => true);
+        try {
+            const lease = acquireTmuxExtendedKeysLease(cwd, (_file, args) => {
+                calls.push([...args]);
+                if (args[0] === "display-message")
+                    return "/tmp/tmux-3-0.sock\n";
+                if (args[0] === "show-options") {
+                    throw Object.assign(new Error("Command failed: tmux show-options -sv extended-keys"), {
+                        status: 1,
+                        stderr: Buffer.from("invalid option: extended-keys\n"),
+                        stdout: Buffer.from(""),
+                    });
+                }
+                return "";
+            });
+            assert.equal(lease, null);
+            assert.deepEqual(calls, [
+                ["display-message", "-p", "#{socket_path}"],
+                ["show-options", "-sv", "extended-keys"],
+            ]);
+            assert.equal(stderrWrite.mock.callCount(), 0);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("reapStaleNotifyFallbackWatcher skips kill when process identity does not match a watcher", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-reap-pid-identity-"));
+        const pidPath = join(cwd, "watcher.pid");
+        await writeFile(pidPath, JSON.stringify({ pid: 99999, started_at: new Date().toISOString() }));
+        const killed = [];
+        await reapStaleNotifyFallbackWatcher(pidPath, {
+            isWatcherProcess: () => false,
+            tryKillPid: (pid) => { killed.push(pid); return true; },
+        });
+        assert.equal(killed.length, 0, "should not kill a process that is not a watcher");
+        await rm(cwd, { recursive: true, force: true });
+    });
+    it("reapStaleNotifyFallbackWatcher sends SIGTERM only after confirming watcher identity", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-reap-pid-confirmed-"));
+        const pidPath = join(cwd, "watcher.pid");
+        await writeFile(pidPath, JSON.stringify({ pid: 12345, started_at: "2026-04-05T00:00:00.000Z" }));
+        const killed = [];
+        await reapStaleNotifyFallbackWatcher(pidPath, {
+            isWatcherProcess: () => true,
+            tryKillPid: (pid) => { killed.push(pid); return true; },
+        });
+        assert.deepEqual(killed, [12345], "should SIGTERM the verified watcher process");
+        await rm(cwd, { recursive: true, force: true });
+    });
+    it("reapStaleNotifyFallbackWatcher skips recently started watcher records to avoid respawn loops", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-reap-pid-recent-"));
+        const pidPath = join(cwd, "watcher.pid");
+        await writeFile(pidPath, JSON.stringify({ pid: 24680, started_at: "2026-05-15T00:00:00.000Z" }));
+        const killed = [];
+        const result = await reapStaleNotifyFallbackWatcher(pidPath, {
+            isWatcherProcess: () => true,
+            nowMs: () => Date.parse("2026-05-15T00:00:03.000Z"),
+            reapGraceMs: 5000,
+            tryKillPid: (pid) => { killed.push(pid); return true; },
+        });
+        assert.equal(result, "recent_active");
+        assert.equal(killed.length, 0, "should not kill a watcher still inside the startup grace window");
+        await rm(cwd, { recursive: true, force: true });
+    });
+    it("reuses legacy plain-text PID parsing without widening stale reap semantics across PID reuse", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-reap-legacy-pid-"));
+        try {
+            const pidPath = join(cwd, "watcher.pid");
+            await writeFile(pidPath, "12345\n", "utf-8");
+            const observed = [];
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                isWatcherProcess(pid) {
+                    observed.push(pid);
+                    return false;
+                },
+                tryKillPid: (pid) => {
+                    observed.push(pid);
+                    return true;
+                },
+            });
+            assert.deepEqual(observed, [12345], "legacy plain-text PID files should still identity-check reused PIDs before any kill");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("reaps watcher-record PIDs only after the record path confirms watcher identity across PID reuse", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-reap-record-pid-"));
+        try {
+            const pidPath = join(cwd, "watcher.pid");
+            await writeFile(pidPath, JSON.stringify({ pid: 54321, started_at: "2026-04-05T00:00:00.000Z" }), "utf-8");
+            const observed = [];
+            await reapStaleNotifyFallbackWatcher(pidPath, {
+                isWatcherProcess(pid) {
+                    observed.push({ step: "identity", pid });
+                    return true;
+                },
+                tryKillPid(pid) {
+                    observed.push({ step: "kill", pid });
+                    return true;
+                },
+            });
+            assert.deepEqual(observed, [
+                { step: "identity", pid: 54321 },
+                { step: "kill", pid: 54321 },
+            ]);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("acquireTmuxExtendedKeysLease recovers from a stale lock left by a crashed process", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-stale-lock-"));
+        const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+        const lockDir = join(leaseDir, "tmp-stale-sock.lock");
+        mkdirSync(lockDir, { recursive: true });
+        const staleTime = new Date(Date.now() - 60_000);
+        utimesSync(lockDir, staleTime, staleTime);
+        const calls = [];
+        const execStub = (_file, args) => {
+            calls.push([...args]);
+            if (args[0] === "display-message")
+                return "/tmp/stale-sock";
+            return "";
+        };
+        const lease = acquireTmuxExtendedKeysLease(cwd, execStub);
+        assert.equal(typeof lease, "string", "lease should succeed after stale lock recovery");
+        assert.ok(!existsSync(lockDir), "stale lock directory should be removed");
+        if (lease)
+            releaseTmuxExtendedKeysLease(cwd, lease, execStub);
+        await rm(cwd, { recursive: true, force: true });
+    });
+    it("acquireTmuxExtendedKeysLease reaps dead holders and restores before taking a new lease", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-dead-holder-acquire-"));
+        try {
+            const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+            const leasePath = join(leaseDir, "tmp-stale-holder-sock.json");
+            await mkdir(leaseDir, { recursive: true });
+            await writeFile(leasePath, JSON.stringify({
+                originalMode: "off",
+                holders: ["2147483647-stale-holder"],
+            }), "utf-8");
+            const calls = [];
+            const execStub = (_file, args) => {
+                calls.push([...args]);
+                if (args[0] === "display-message")
+                    return "/tmp/stale-holder.sock\n";
+                if (args[0] === "show-options")
+                    return "off\n";
+                return "";
+            };
+            const lease = acquireTmuxExtendedKeysLease(cwd, execStub);
+            assert.equal(typeof lease, "string");
+            const persisted = JSON.parse(await readFile(leasePath, "utf-8"));
+            assert.equal(persisted.holders.length, 1);
+            const holder = persisted.holders[0];
+            const holderId = typeof holder === "string" ? holder : holder?.id ?? "";
+            assert.match(holderId, new RegExp(`^${process.pid}-`));
+            assert.equal(typeof holder === "object" ? holder.pid : process.pid, process.pid);
+            assert.doesNotMatch(JSON.stringify(persisted), /2147483647-stale-holder/);
+            if (lease)
+                releaseTmuxExtendedKeysLease(cwd, lease, execStub);
+            assert.deepEqual(calls, [
+                ["display-message", "-p", "#{socket_path}"],
+                ["set-option", "-sq", "extended-keys", "off"],
+                ["show-options", "-sv", "extended-keys"],
+                ["set-option", "-sq", "extended-keys", "always"],
+                ["set-option", "-sq", "extended-keys", "off"],
+            ]);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("releaseTmuxExtendedKeysLease preserves live legacy string holders", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-live-legacy-holder-"));
+        try {
+            const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+            const leasePath = join(leaseDir, "tmp-live-legacy-sock.json");
+            const legacyHolder = `${process.pid}-legacy-holder`;
+            await mkdir(leaseDir, { recursive: true });
+            await writeFile(leasePath, JSON.stringify({
+                originalMode: "off",
+                holders: [legacyHolder],
+            }), "utf-8");
+            const calls = [];
+            const execStub = (_file, args) => {
+                calls.push([...args]);
+                return "";
+            };
+            releaseTmuxExtendedKeysLease(cwd, "/tmp/live-legacy.sock\tmissing-holder", execStub);
+            const persisted = JSON.parse(await readFile(leasePath, "utf-8"));
+            assert.deepEqual(persisted.holders, [legacyHolder]);
+            assert.deepEqual(calls, [], "live legacy string holders should not be restored away");
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("acquireTmuxExtendedKeysLease reaps Linux PID-reuse identity mismatches", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-pid-reuse-holder-"));
+        try {
+            const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+            const leasePath = join(leaseDir, "tmp-pid-reuse-sock.json");
+            await mkdir(leaseDir, { recursive: true });
+            await writeFile(leasePath, JSON.stringify({
+                originalMode: "off",
+                holders: [{
+                        id: `${process.pid}-reused-holder`,
+                        pid: process.pid,
+                        platform: "linux",
+                        linuxStartTicks: -1,
+                    }],
+            }), "utf-8");
+            const calls = [];
+            const execStub = (_file, args) => {
+                calls.push([...args]);
+                if (args[0] === "display-message")
+                    return "/tmp/pid-reuse.sock\n";
+                if (args[0] === "show-options")
+                    return "off\n";
+                return "";
+            };
+            const lease = acquireTmuxExtendedKeysLease(cwd, execStub);
+            assert.equal(typeof lease, "string");
+            const persisted = JSON.parse(await readFile(leasePath, "utf-8"));
+            const holderIds = persisted.holders.map((holder) => typeof holder === "string" ? holder : holder.id ?? "");
+            if (process.platform === "linux") {
+                assert.equal(persisted.holders.length, 1);
+                assert.match(holderIds[0] ?? "", new RegExp(`^${process.pid}-`));
+                assert.doesNotMatch(JSON.stringify(persisted), /reused-holder/);
+                assert.deepEqual(calls, [
+                    ["display-message", "-p", "#{socket_path}"],
+                    ["set-option", "-sq", "extended-keys", "off"],
+                    ["show-options", "-sv", "extended-keys"],
+                    ["set-option", "-sq", "extended-keys", "always"],
+                ]);
+            }
+            else {
+                assert.ok(holderIds.includes(`${process.pid}-reused-holder`));
+            }
+            if (lease)
+                releaseTmuxExtendedKeysLease(cwd, lease, execStub);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("releaseTmuxExtendedKeysLease restores when all remaining holders are dead", async () => {
+        const cwd = await mkdtemp(join(tmpdir(), "omx-tmux-dead-holder-release-"));
+        try {
+            const leaseDir = join(cwd, ".omx", "state", "tmux-extended-keys");
+            const leasePath = join(leaseDir, "tmp-dead-release-sock.json");
+            await mkdir(leaseDir, { recursive: true });
+            await writeFile(leasePath, JSON.stringify({
+                originalMode: "off",
+                holders: ["2147483647-stale-holder"],
+            }), "utf-8");
+            const calls = [];
+            const execStub = (_file, args) => {
+                calls.push([...args]);
+                return "";
+            };
+            releaseTmuxExtendedKeysLease(cwd, "/tmp/dead-release.sock\tmissing-holder", execStub);
+            assert.ok(!existsSync(leasePath), "stale-only lease file should be removed");
+            assert.deepEqual(calls, [["set-option", "-sq", "extended-keys", "off"]]);
+        }
+        finally {
+            await rm(cwd, { recursive: true, force: true });
+        }
+    });
+    it("buildDetachedSessionFinalizeSteps keeps schedule after split-capture and before attach", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true, false, true, "%leader");
+        const names = steps.map((step) => step.name);
+        const attachedIndex = names.indexOf("register-client-attached-reconcile");
+        const scheduleIndex = names.indexOf("schedule-delayed-resize");
+        const attachIndex = names.indexOf("attach-session");
+        assert.equal(attachedIndex >= 0, true);
+        assert.equal(scheduleIndex > attachedIndex, true);
+        assert.equal(scheduleIndex >= 0, true);
+        assert.equal(attachIndex > scheduleIndex, true);
+        assert.equal(names.includes("register-resize-hook"), true);
+        assert.equal(names.includes("reconcile-hud-resize"), true);
+        assert.equal(DETACHED_TMUX_HISTORY_LIMIT, 500);
+        const historyHook = steps.find((step) => step.name === "register-detached-history-prune-hook");
+        assert.ok(historyHook);
+        assert.deepEqual(historyHook.args.slice(0, 3), ["set-hook", "-t", "omx-demo"]);
+        assert.match(historyHook.args[3] || "", /^client-detached\[[0-9]+\]$/);
+        assert.equal(historyHook.args[4], `if-shell -F '#{==:#{session_attached},0}' 'run-shell -b "tmux clear-history -t %leader >/dev/null 2>&1 || true"'`);
+    });
+    it("detached history prune hook tolerates a dead leader pane", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true, false, true, "%leader");
+        const historyHook = steps.find((step) => step.name === "register-detached-history-prune-hook");
+        assert.ok(historyHook);
+        const hookCommand = historyHook.args[4] || "";
+        assert.match(hookCommand, /run-shell -b/);
+        assert.match(hookCommand, />\/dev\/null 2>&1 \|\| true/);
+    });
+    it("buildDetachedSessionFinalizeSteps skips attach for Hermes MCP bridge launches", () => {
+        assert.equal(shouldAttachDetachedTmuxSession({ OMX_HERMES_MCP_BRIDGE: "1" }), false);
+        assert.equal(shouldAttachDetachedTmuxSession({}), true);
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true, false, shouldAttachDetachedTmuxSession({ OMX_HERMES_MCP_BRIDGE: "1" }));
+        assert.equal(steps.some((step) => step.name === "attach-session"), false);
+        assert.equal(steps.some((step) => step.name === "register-resize-hook"), true);
+        assert.equal(steps.some((step) => step.name === "set-mouse"), true);
+    });
+    it("buildDetachedSessionFinalizeSteps uses quiet best-effort tmux resize commands", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", false);
+        const registerHook = steps.find((step) => step.name === "register-resize-hook");
+        const schedule = steps.find((step) => step.name === "schedule-delayed-resize");
+        const reconcile = steps.find((step) => step.name === "reconcile-hud-resize");
+        assert.match(registerHook?.args[4] ?? "", />\/dev\/null 2>&1 \|\| true/);
+        assert.match(registerHook?.args[4] ?? "", new RegExp(`-y ${HUD_TMUX_HEIGHT_LINES}\\b`));
+        assert.match(schedule?.args[2] ?? "", />\/dev\/null 2>&1 \|\| true/);
+        assert.match(schedule?.args[2] ?? "", new RegExp(`-y ${HUD_TMUX_HEIGHT_LINES}\\b`));
+        assert.match((reconcile?.args ?? []).join(" "), />\/dev\/null 2>&1 \|\| true/);
+        assert.match((reconcile?.args ?? []).join(" "), new RegExp(`-y ${HUD_TMUX_HEIGHT_LINES}\\b`));
+    });
+    it("buildDetachedSessionFinalizeSteps skips detached resize hooks on native Windows", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true, true);
+        assert.deepEqual(steps.map((step) => step.name), ["set-mouse", "sanitize-copy-mode-style", "attach-session"]);
+    });
+    it("buildDetachedSessionFinalizeSteps sanitizes copy-mode styling before attach when mouse mode is enabled", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true);
+        assert.equal(steps.findIndex((step) => step.name === "sanitize-copy-mode-style")
+            > steps.findIndex((step) => step.name === "set-mouse"), true);
+        assert.equal(steps.findIndex((step) => step.name === "attach-session")
+            > steps.findIndex((step) => step.name === "sanitize-copy-mode-style"), true);
+    });
+    it("buildDetachedSessionFinalizeSteps never appends server-global terminal-overrides", () => {
+        const steps = buildDetachedSessionFinalizeSteps("omx-demo", "%12", "3", true);
+        assert.equal(steps.some((step) => step.name === "set-wsl-xt"), false);
+        assert.equal(steps.some((step) => step.args.includes("terminal-overrides")), false);
+    });
+    it("buildDetachedSessionRollbackSteps unregisters hooks before killing session", () => {
+        const steps = buildDetachedSessionRollbackSteps("omx-demo", "omx-demo:0", "omx_resize_launch_demo_0_12", "omx_attached_launch_demo_0_12");
+        assert.deepEqual(steps.map((step) => step.name), [
+            "unregister-client-attached-reconcile",
+            "unregister-resize-hook",
+            "kill-session",
+        ]);
+        assert.equal(steps[0]?.args[0], "set-hook");
+        assert.equal(steps[0]?.args[1], "-u");
+        assert.equal(steps[0]?.args[2], "-t");
+        assert.equal(steps[0]?.args[3], "omx-demo:0");
+        assert.match(steps[0]?.args[4] ?? "", /^client-attached\[\d+\]$/);
+        assert.match(steps[1]?.args[4] ?? "", /^client-resized\[\d+\]$/);
+        assert.doesNotMatch(steps[1]?.args.join(" ") ?? "", /window-resized/);
+        assert.deepEqual(steps[2]?.args, ["kill-session", "-t", "omx-demo"]);
+    });
+    it("buildDetachedSessionRollbackSteps only kills session when no hook metadata exists", () => {
+        const steps = buildDetachedSessionRollbackSteps("omx-demo", null, null, null);
+        assert.deepEqual(steps.map((step) => step.name), ["kill-session"]);
+    });
+});
+describe("buildTmuxShellCommand", () => {
+    it("preserves quoted config values for tmux shell-command execution", () => {
+        assert.equal(buildTmuxShellCommand("codex", [
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="xhigh"',
+        ]), `'codex' '--dangerously-bypass-approvals-and-sandbox' '-c' 'model_reasoning_effort="xhigh"'`);
+    });
+});
+describe("buildTmuxPaneCommand", () => {
+    it("wraps command with zsh without sourcing rc files by default", () => {
+        const result = buildTmuxPaneCommand("codex", ["--model", "gpt-5"], "/usr/bin/zsh", {});
+        assert.ok(result.startsWith("'/usr/bin/zsh' -c "), "should start with zsh non-login shell to preserve tmux cwd");
+        assert.ok(!result.includes(" -lc "), "should not use a login shell");
+        assert.ok(!result.includes("source ~/.zshrc"), "should not source .zshrc by default");
+        assert.ok(result.includes("exec "), "should exec the command");
+    });
+    it("keeps Homebrew zsh instead of downgrading to /bin/sh", () => {
+        const result = buildTmuxPaneCommand("codex", ["--model", "gpt-5"], "/opt/homebrew/bin/zsh", {});
+        assert.ok(result.startsWith("'/opt/homebrew/bin/zsh' -c "), "should preserve Homebrew zsh when SHELL points to it");
+        assert.ok(!result.startsWith("'/bin/sh' -c "), "should not fall back to /bin/sh for supported Homebrew zsh");
+        assert.ok(!result.includes("source ~/.zshrc"), "should not source .zshrc by default");
+    });
+    it("keeps MacPorts zsh instead of downgrading to /bin/sh", () => {
+        const result = buildTmuxPaneCommand("codex", ["--model", "gpt-5"], "/opt/local/bin/zsh", {});
+        assert.ok(result.startsWith("'/opt/local/bin/zsh' -c "), "should preserve MacPorts zsh when SHELL points to it");
+        assert.ok(!result.startsWith("'/bin/sh' -c "), "should not fall back to /bin/sh for supported MacPorts zsh");
+        assert.ok(!result.includes("source ~/.zshrc"), "should not source .zshrc by default");
+    });
+    it("prevents issue #2282 bash rc fan-out by default", () => {
+        const result = buildTmuxPaneCommand("codex", [], "/bin/bash", {});
+        assert.ok(result.startsWith("'/bin/bash' -c "), "should start with bash non-login shell to preserve tmux cwd");
+        assert.ok(!result.includes(" -lc "), "should not use a login shell");
+        assert.ok(!result.includes("source ~/.bashrc"), "should not source .bashrc by default");
+        assert.ok(result.includes("exec "), "should exec the command");
+    });
+    it("sources zsh and bash rc files only when explicitly opted in", () => {
+        assert.equal(shouldSourceTmuxPaneShellRc({}), false);
+        assert.equal(shouldSourceTmuxPaneShellRc({ OMX_TMUX_SOURCE_SHELL_RC: "1" }), true);
+        assert.ok(buildTmuxPaneCommand("codex", [], "/usr/bin/zsh", { OMX_TMUX_SOURCE_SHELL_RC: "1" }).includes("source ~/.zshrc"), "opt-in zsh launches may source .zshrc");
+        assert.ok(buildTmuxPaneCommand("codex", [], "/bin/bash", { OMX_TMUX_SOURCE_SHELL_RC: "1" }).includes("source ~/.bashrc"), "opt-in bash launches may source .bashrc");
+    });
+    it("skips rc sourcing for unknown shells without using a login shell", () => {
+        const result = buildTmuxPaneCommand("codex", [], "/bin/fish");
+        assert.ok(result.startsWith("'/bin/fish' -c "), "should start with fish non-login shell");
+        assert.ok(!result.includes(" -lc "), "should not use a login shell");
+        assert.ok(!result.includes("source"), "should not source any rc file");
+        assert.ok(result.includes("exec "), "should exec the command");
+    });
+    it("falls back to /bin/sh without using a login shell when shell path is empty", () => {
+        const result = buildTmuxPaneCommand("codex", [], "");
+        assert.ok(result.startsWith("'/bin/sh' -c "), "should fall back to /bin/sh");
+        assert.ok(!result.includes(" -lc "), "should not use a login shell");
+    });
+});
+describe("buildWindowsPromptCommand", () => {
+    it("encodes detached Windows commands for safe PowerShell prompt injection", () => {
+        const result = buildWindowsPromptCommand("codex", [
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="high"',
+            "it's",
+        ]);
+        const prefix = "powershell.exe -NoLogo -NoExit -EncodedCommand ";
+        assert.ok(result.startsWith(prefix));
+        const payload = result.slice(prefix.length);
+        const decoded = Buffer.from(payload, "base64").toString("utf16le");
+        assert.equal(decoded, "$ErrorActionPreference = 'Stop'; & { & 'codex' '--dangerously-bypass-approvals-and-sandbox' '-c' 'model_reasoning_effort=\"high\"' 'it''s' }");
+    });
+});
+describe("buildTmuxSessionName", () => {
+    it("uses detached fallback quietly outside git repos", () => {
+        const name = buildTmuxSessionName("/tmp/My Repo", "omx-1770992424158-abc123");
+        assert.equal(name, "omx-my-repo-detached-1770992424158-abc123");
+    });
+    it("sanitizes invalid characters", () => {
+        const name = buildTmuxSessionName("/tmp/@#$", "omx-+++");
+        assert.match(name, /^omx-(unknown|[a-z0-9-]+)-[a-z0-9-]+-(unknown|[a-z0-9-]+)$/);
+        assert.equal(name.includes("_"), false);
+        assert.equal(name.includes(" "), false);
+    });
+    it("includes repo name when cwd is inside .omx-worktrees", () => {
+        const name = buildTmuxSessionName("/home/user/my-repo.omx-worktrees/launch-feature-x", "omx-123-abc");
+        assert.match(name, /^omx-my-repo-launch-feature-x-/);
+    });
+    it("includes repo name for detached worktree paths", () => {
+        const name = buildTmuxSessionName("/projects/cool-project.omx-worktrees/launch-detached", "omx-456-def");
+        assert.match(name, /^omx-cool-project-launch-detached-/);
+    });
+    it("includes repo name when cwd is inside .omx/worktrees", () => {
+        const name = buildTmuxSessionName("/home/user/my-repo/.omx/worktrees/autoresearch-demo", "omx-789-ghi");
+        assert.match(name, /^omx-my-repo-autoresearch-demo-/);
+    });
+});
+describe("buildDetachedTmuxSessionName", () => {
+    it("reuses the OMX session id for the detached tmux session name", () => {
+        const sessionName = buildDetachedTmuxSessionName("/tmp/My Repo", "omx-1770992424158-abc123");
+        assert.equal(sessionName, "omx-my-repo-detached-1770992424158-abc123");
+    });
+});
+describe("native Windows psmux-compatible tmux resolution", () => {
+    it("resolveNativeSessionName uses the shared tmux-aware resolver for current session lookup", async () => {
+        const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+        const originalPath = process.env.PATH;
+        const originalPathext = process.env.PATHEXT;
+        const wd = await mkdtemp(join(tmpdir(), "omx-psmux-native-session-"));
+        const fakeBin = join(wd, "bin");
+        Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "psmux.exe"), `#!/bin/sh
+if [ "$1" = "display-message" ] && [ "$2" = "-p" ] && [ "$3" = "-t" ] && [ "$4" = "%7" ] && [ "$5" = "#S" ]; then
+  printf 'psmux-session\\n'
+  exit 0
+fi
+printf 'unexpected:%s\\n' "$*" >&2
+exit 1
+`);
+            await chmod(join(fakeBin, "psmux.exe"), 0o755);
+            process.env.PATH = fakeBin;
+            process.env.PATHEXT = ".EXE";
+            const sessionName = resolveNativeSessionName("/tmp/repo", "omx-abc123", {
+                ...process.env,
+                TMUX: "1",
+                TMUX_PANE: "%7",
+            });
+            assert.equal(sessionName, "psmux-session");
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathext;
+            if (originalPlatform)
+                Object.defineProperty(process, "platform", originalPlatform);
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+    it("detectDetachedSessionWindowIndex uses the shared tmux-aware resolver on native Windows", async () => {
+        const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform");
+        const originalPath = process.env.PATH;
+        const originalPathext = process.env.PATHEXT;
+        const wd = await mkdtemp(join(tmpdir(), "omx-psmux-window-index-"));
+        const fakeBin = join(wd, "bin");
+        Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+        try {
+            await mkdir(fakeBin, { recursive: true });
+            await writeFile(join(fakeBin, "psmux.exe"), `#!/bin/sh
+if [ "$1" = "display-message" ] && [ "$2" = "-p" ] && [ "$3" = "-t" ] && [ "$4" = "omx-demo" ] && [ "$5" = "#{window_index}" ]; then
+  printf '3\\n'
+  exit 0
+fi
+printf 'unexpected:%s\\n' "$*" >&2
+exit 1
+`);
+            await chmod(join(fakeBin, "psmux.exe"), 0o755);
+            process.env.PATH = fakeBin;
+            process.env.PATHEXT = ".EXE";
+            assert.equal(detectDetachedSessionWindowIndex("omx-demo"), "3");
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathext;
+            if (originalPlatform)
+                Object.defineProperty(process, "platform", originalPlatform);
+            await rm(wd, { recursive: true, force: true });
+        }
+    });
+});
+describe("worktree dependency bootstrap helpers", () => {
+    it("returns an explicit warning when reusable worktree dependencies are unavailable", () => {
+        const result = ensureReusableNodeModules("/tmp/non-worktree", {
+            gitRunner: () => ({ status: 1, stdout: "", stderr: "not a worktree" }),
+        });
+        assert.equal(result.strategy, "missing");
+        assert.match(String(result.warning || ""), /No reusable parent-repo node_modules was found/);
+    });
+});
+describe("team worker launch arg inheritance helpers", () => {
+    it("collectInheritableTeamWorkerArgs extracts bypass, reasoning, and model overrides", () => {
+        assert.deepEqual(collectInheritableTeamWorkerArgs([
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="xhigh"',
+            "--model",
+            "gpt-5",
+        ]), [
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="xhigh"',
+            "--model",
+            "gpt-5",
+        ]);
+    });
+    it("collectInheritableTeamWorkerArgs supports --model=<value> syntax", () => {
+        assert.deepEqual(collectInheritableTeamWorkerArgs(["--model=gpt-5.3-codex"]), ["--model", "gpt-5.3-codex"]);
+    });
+    it("collectInheritableTeamWorkerArgs preserves only safe model_provider config overrides", () => {
+        assert.deepEqual(collectInheritableTeamWorkerArgs([
+            "-c",
+            'sandbox_mode="danger-full-access"',
+            "-c",
+            'model_provider="cheapRouter"',
+            "--model",
+            "gpt-5.5",
+        ]), ["-c", 'model_provider="cheapRouter"', "--model", "gpt-5.5"]);
+    });
+    it("resolveTeamWorkerLaunchArgsEnv merges and normalizes with de-dupe + last reasoning/model wins", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv('--dangerously-bypass-approvals-and-sandbox -c model_reasoning_effort="high" --model old-a --no-alt-screen --model=old-b', [
+            "-c",
+            'model_reasoning_effort="xhigh"',
+            "--dangerously-bypass-approvals-and-sandbox",
+            "--model",
+            "gpt-5",
+        ], true), '--no-alt-screen --dangerously-bypass-approvals-and-sandbox -c model_reasoning_effort="xhigh" --model old-b');
+    });
+    it("resolveTeamWorkerLaunchArgsEnv can opt out of leader inheritance", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--no-alt-screen", [
+            "--dangerously-bypass-approvals-and-sandbox",
+            "-c",
+            'model_reasoning_effort="xhigh"',
+        ], false), "--no-alt-screen");
+    });
+    it("resolveTeamWorkerLaunchArgsEnv uses inherited model when env model is absent", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--no-alt-screen", ["--model=gpt-5.3-codex"], true), "--no-alt-screen --model gpt-5.3-codex");
+    });
+    it("resolveTeamWorkerLaunchArgsEnv uses frontier default model when env and inherited models are absent", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--no-alt-screen", ["--dangerously-bypass-approvals-and-sandbox"], true, DEFAULT_FRONTIER_MODEL), `--no-alt-screen --dangerously-bypass-approvals-and-sandbox --model ${DEFAULT_FRONTIER_MODEL}`);
+    });
+    it("resolveTeamWorkerLaunchArgsEnv keeps exactly one final model with precedence env > inherited > default", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--model env-model --model=env-model-final", ["--model", "inherited-model"], true, "fallback-model"), "--model env-model-final");
+    });
+    it("resolveTeamWorkerLaunchArgsEnv prefers inherited model over default when env model is absent", () => {
+        assert.equal(resolveTeamWorkerLaunchArgsEnv("--no-alt-screen", ["--model", "inherited-model"], true, "fallback-model"), "--no-alt-screen --model inherited-model");
+    });
+});
+describe("readTopLevelTomlString", () => {
+    it("reads a top-level string value", () => {
+        const value = readTopLevelTomlString('model_reasoning_effort = "high"\n[mcp_servers.test]\nmodel_reasoning_effort = "low"\n', "model_reasoning_effort");
+        assert.equal(value, "high");
+    });
+    it("ignores table-local values", () => {
+        const value = readTopLevelTomlString('[mcp_servers.test]\nmodel_reasoning_effort = "xhigh"\n', "model_reasoning_effort");
+        assert.equal(value, null);
+    });
+});
+describe("injectModelInstructionsBypassArgs", () => {
+    it("appends model_instructions_file override by default", () => {
+        const args = injectModelInstructionsBypassArgs("/tmp/my-project", ["--model", "gpt-5"], {});
+        assert.deepEqual(args, [
+            "--model",
+            "gpt-5",
+            "-c",
+            'model_instructions_file="/tmp/my-project/AGENTS.md"',
+        ]);
+    });
+    it("does not append when bypass is disabled via env", () => {
+        const args = injectModelInstructionsBypassArgs("/tmp/my-project", ["--model", "gpt-5"], { OMX_BYPASS_DEFAULT_SYSTEM_PROMPT: "0" });
+        assert.deepEqual(args, ["--model", "gpt-5"]);
+    });
+    it("does not append when model_instructions_file is already set", () => {
+        const args = injectModelInstructionsBypassArgs("/tmp/my-project", ["-c", 'model_instructions_file="/tmp/custom.md"'], {});
+        assert.deepEqual(args, ["-c", 'model_instructions_file="/tmp/custom.md"']);
+    });
+    it("respects OMX_MODEL_INSTRUCTIONS_FILE env override", () => {
+        const args = injectModelInstructionsBypassArgs("/tmp/my-project", [], {
+            OMX_MODEL_INSTRUCTIONS_FILE: "/tmp/alt instructions.md",
+        });
+        assert.deepEqual(args, [
+            "-c",
+            'model_instructions_file="/tmp/alt instructions.md"',
+        ]);
+    });
+    it("uses session-scoped default model_instructions_file when provided", () => {
+        const args = injectModelInstructionsBypassArgs("/tmp/my-project", ["--model", "gpt-5"], {}, "/tmp/my-project/.omx/state/sessions/session-1/AGENTS.md");
+        assert.deepEqual(args, [
+            "--model",
+            "gpt-5",
+            "-c",
+            'model_instructions_file="/tmp/my-project/.omx/state/sessions/session-1/AGENTS.md"',
+        ]);
+    });
+});
+describe("upsertTopLevelTomlString", () => {
+    it("replaces an existing top-level key", () => {
+        const updated = upsertTopLevelTomlString('model_reasoning_effort = "low"\n[tui]\nstatus_line = []\n', "model_reasoning_effort", "high");
+        assert.match(updated, /^model_reasoning_effort = "high"$/m);
+        assert.doesNotMatch(updated, /^model_reasoning_effort = "low"$/m);
+    });
+    it("inserts before the first table when key is missing", () => {
+        const updated = upsertTopLevelTomlString("[tui]\nstatus_line = []\n", "model_reasoning_effort", "xhigh");
+        assert.equal(updated, 'model_reasoning_effort = "xhigh"\n[tui]\nstatus_line = []\n');
+    });
+});
+describe("isExistingTmuxWindowTooCrampedForLaunchHud (#2754)", () => {
+    it("skips the launch-time HUD split for cramped existing tmux windows", () => {
+        // The reported repro: a 160x41 existing tmux window where forcing the HUD
+        // split dropped the Codex TUI to 38 rows and became unreadable.
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(41), true);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(38), true);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(HUD_TMUX_MIN_LAUNCH_WINDOW_HEIGHT_LINES - 1), true);
+    });
+    it("keeps default HUD behavior for normal-height existing tmux windows", () => {
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(HUD_TMUX_MIN_LAUNCH_WINDOW_HEIGHT_LINES), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(50), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(120), false);
+    });
+    it("creates the HUD when the window height is unknown or invalid", () => {
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(null), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(undefined), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(0), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(Number.NaN), false);
+    });
+    it("honors an explicit minimum-height override", () => {
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(41, 40), false);
+        assert.equal(isExistingTmuxWindowTooCrampedForLaunchHud(39, 40), true);
+    });
+});
+//# sourceMappingURL=index.test.js.map