oh-my-codex 0.14.4 → 0.15.1

package/dist/cli/index.js

@@ -12,6 +12,7 @@ import { version } from "./version.js";
 import { tmuxHookCommand } from "./tmux-hook.js";
 import { hooksCommand } from "./hooks.js";
 import { hudCommand } from "../hud/index.js";
+import { sidecarCommand } from "../sidecar/index.js";
 import { teamCommand } from "./team.js";
 import { ralphCommand } from "./ralph.js";
 import { askCommand } from "./ask.js";
@@ -25,11 +26,13 @@ import { agentsCommand } from "./agents.js";
 import { sessionCommand } from "./session-search.js";
 import { autoresearchCommand } from "./autoresearch.js";
 import { mcpParityCommand } from "./mcp-parity.js";
+import { mcpServeCommand } from "./mcp-serve.js";
 import { adaptCommand } from "./adapt.js";
+import { listCommand } from "./list.js";
 import { MADMAX_FLAG, CODEX_BYPASS_FLAG, HIGH_REASONING_FLAG, XHIGH_REASONING_FLAG, SPARK_FLAG, MADMAX_SPARK_FLAG, CONFIG_FLAG, LONG_CONFIG_FLAG, } from "./constants.js";
 import { getBaseStateDir, getStateDir, listModeStateFilesWithScopePreference, } from "../mcp/state-paths.js";
-import { resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, } from "./codex-home.js";
-export { readPersistedSetupPreferences, readPersistedSetupScope, resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, } from "./codex-home.js";
+import { resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, resolveProjectLocalCodexHomeForLaunch, } from "./codex-home.js";
+export { readPersistedSetupPreferences, readPersistedSetupScope, resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, resolveProjectLocalCodexHomeForLaunch, } from "./codex-home.js";
 import { SKILL_ACTIVE_STATE_MODE, syncCanonicalSkillStateForMode } from "../state/skill-active.js";
 import { isTrackedWorkflowMode } from "../state/workflow-transition.js";
 import { maybeCheckAndPromptUpdate, runImmediateUpdate } from "./update.js";
@@ -39,7 +42,7 @@ import { readSessionState, writeSessionStart, writeSessionEnd, resetSessionMetri
 import { buildClientAttachedReconcileHookName, buildReconcileHudResizeArgs, buildRegisterClientAttachedReconcileArgs, buildRegisterResizeHookArgs, buildResizeHookName, buildResizeHookTarget, buildScheduleDelayedHudResizeArgs, buildUnregisterClientAttachedReconcileArgs, buildUnregisterResizeHookArgs, enableMouseScrolling, isMsysOrGitBash, isNativeWindows, isTmuxAvailable, mitigateCopyModeUnderlineArtifacts, } from "../team/tmux-session.js";
 import { getPackageRoot } from "../utils/package.js";
 import { codexConfigPath, rememberOmxLaunchContext, resolveOmxEntryPath } from "../utils/paths.js";
-import { repairConfigIfNeeded } from "../config/generator.js";
+import { cleanCodexModelAvailabilityNuxIfNeeded, repairConfigIfNeeded } from "../config/generator.js";
 import { HUD_TMUX_HEIGHT_LINES } from "../hud/constants.js";
 import { createHudWatchPane as createSharedHudWatchPane, killTmuxPane as killSharedTmuxPane, listCurrentWindowHudPaneIds, parsePaneIdFromTmuxOutput, } from "../hud/tmux.js";
 export { parseTmuxPaneSnapshot, isHudWatchPane, findHudWatchPaneIds } from "../hud/tmux.js";
@@ -51,6 +54,7 @@ import { collectInheritableTeamWorkerArgs as collectInheritableTeamWorkerArgsSha
 import { parseWorktreeMode, planWorktreeTarget, ensureWorktree, } from "../team/worktree.js";
 import { ensureReusableNodeModules } from "../utils/repo-deps.js";
 import { OMX_NOTIFY_TEMP_CONTRACT_ENV, parseNotifyTempContractFromArgs, serializeNotifyTempContract, } from "../notifications/temp-contract.js";
+import { execInjectCommand } from "../exec/followup.js";
 export function resolveNotifyFallbackWatcherScript(pkgRoot = getPackageRoot()) {
     return resolveDistScript(pkgRoot, "notify-fallback-watcher.js");
 }
@@ -67,12 +71,16 @@ export const HELP = `
 oh-my-codex (omx) - Multi-agent orchestration for Codex CLI
 
 Usage:
-  omx           Launch Codex CLI (HUD auto-attaches only when already inside tmux)
+  omx           Launch Codex CLI (detached tmux by default on supported interactive terminals)
   omx exec      Run codex exec non-interactively with OMX AGENTS/overlay injection
+  omx exec inject <session-id> --prompt <text>
+                Queue audited follow-up instructions for a running non-interactive exec job
   omx setup     Install skills, prompts, MCP servers, and scope-specific AGENTS.md
+                (user scope prompts for legacy vs plugin skill delivery when needed)
   omx update    Check npm now, update the global install immediately, then refresh setup
   omx uninstall Remove OMX configuration and clean up installed artifacts
   omx doctor    Check installation health
+  omx list      List packaged OMX skills and native agent prompts (--json)
   omx cleanup   Kill orphaned OMX MCP server processes and remove stale OMX /tmp directories
   omx doctor --team  Check team/swarm runtime health diagnostics
   omx ask       Ask local provider CLI (claude|gemini) and write artifact output
@@ -93,6 +101,7 @@ Usage:
   omx tmux-hook Manage tmux prompt injection workaround (init|status|validate|test)
   omx hooks     Manage hook plugins (init|status|validate|test)
   omx hud       Show HUD statusline (--watch, --json, --preset=NAME)
+  omx sidecar   Show read-only team/multi-agent visualization (--watch, --json, --tmux)
   omx state     Read/write/list OMX mode state via CLI parity surface
   omx notepad   CLI parity for OMX notepad MCP tools
   omx project-memory
@@ -101,6 +110,7 @@ Usage:
   omx code-intel
                 CLI parity for OMX code-intel MCP tools
   omx wiki      CLI parity for OMX wiki MCP tools
+  omx mcp-serve Launch an OMX stdio MCP server target (plugin/runtime use)
   omx sparkshell <command> [args...]
   omx sparkshell --tmux-pane <pane-id> [--tail-lines <100-1000>]
                 Run native sparkshell sidecar for direct command execution or explicit tmux-pane summarization
@@ -123,6 +133,7 @@ Options:
   --madmax-spark  spark model for workers + bypass approvals for leader and workers
                 (shorthand for: --spark --madmax)
   --notify-temp  Enable temporary notification routing for this run/session only
+  --direct       Launch the interactive leader directly without OMX tmux/HUD management
   --tmux         Launch the interactive leader session in detached tmux
   --discord      Select Discord provider for temporary notification mode
   --slack        Select Slack provider for temporary notification mode
@@ -132,15 +143,32 @@ Options:
   -w, --worktree[=<name>]
                 Launch Codex in a git worktree (detached when no name is given)
   --force       Force reinstall (overwrite existing files)
+  --merge-agents
+                Merge OMX-managed AGENTS.md sections into an existing AGENTS.md
+                instead of overwriting user-authored content
   --dry-run     Show what would be done without doing it
+  --plugin      Use Codex plugin delivery for omx setup and remove legacy OMX-managed user/project components
+  --legacy      Use legacy setup delivery for omx setup, overriding persisted plugin mode
+  --install-mode <legacy|plugin>
+                Explicit setup install mode (canonical form; --legacy/--plugin are aliases)
   --keep-config Skip config.toml cleanup during uninstall
   --purge       Remove .omx/ cache directory during uninstall
   --verbose     Show detailed output
   --scope       Setup scope for "omx setup" only:
                 user | project
-  --skill-target
-                User-scope skills target for "omx setup" only:
-                codex-home
+
+Launch policy:
+  OMX_LAUNCH_POLICY=direct|tmux|detached-tmux|auto
+                Choose the default leader launch policy when no CLI policy flag is present
+  unset OMX_LAUNCH_POLICY
+                Return to the auto/default policy (detached tmux on supported interactive terminals)
+  omx --direct --yolo
+                Run this launch without OMX tmux/HUD management
+  OMX_LAUNCH_POLICY=direct omx --yolo
+                Use direct launch from the environment
+  OMX_LAUNCH_POLICY=direct omx --tmux --yolo
+                CLI policy flags override the environment for one launch
+  Config files are intentionally not used for launch policy in this release.
 `;
 const REASONING_KEY = "model_reasoning_effort";
 const MODEL_INSTRUCTIONS_FILE_KEY = "model_instructions_file";
@@ -167,6 +195,7 @@ const ALLOWED_SHELLS = new Set([
     "/usr/local/bin/bash",
     "/usr/local/bin/zsh",
     "/usr/local/bin/fish",
+    "/opt/local/bin/zsh",
     "/opt/homebrew/bin/zsh",
 ]);
 const WINDOWS_DETACHED_BOOTSTRAP_DELAY_MS = 2500;
@@ -188,9 +217,12 @@ const NESTED_HELP_COMMANDS = new Set([
     "deepinit",
     "exec",
     "hooks",
+    "list",
     "hud",
+    "sidecar",
     "state",
     "wiki",
+    "mcp-serve",
     "ralph",
     "resume",
     "session",
@@ -198,6 +230,46 @@ const NESTED_HELP_COMMANDS = new Set([
     "team",
     "tmux-hook",
 ]);
+export function resolveSetupInstallModeArg(args) {
+    let value;
+    const setValue = (next, source) => {
+        if (value && value !== next) {
+            throw new Error(`Conflicting setup install mode flags: ${source} selects ${next}, but another flag already selected ${value}`);
+        }
+        value = next;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--plugin") {
+            setValue("plugin", arg);
+            continue;
+        }
+        if (arg === "--legacy") {
+            setValue("legacy", arg);
+            continue;
+        }
+        if (arg === "--install-mode") {
+            const next = args[index + 1];
+            if (!next || next.startsWith("-")) {
+                throw new Error(`Missing setup install mode value after --install-mode. Expected one of: legacy, plugin`);
+            }
+            if (next !== "legacy" && next !== "plugin") {
+                throw new Error(`Invalid setup install mode: ${next}. Expected one of: legacy, plugin`);
+            }
+            setValue(next, arg);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--install-mode=")) {
+            const next = arg.slice("--install-mode=".length);
+            if (next !== "legacy" && next !== "plugin") {
+                throw new Error(`Invalid setup install mode: ${next}. Expected one of: legacy, plugin`);
+            }
+            setValue(next, "--install-mode");
+        }
+    }
+    return value;
+}
 export function resolveSetupScopeArg(args) {
     let value;
     for (let index = 0; index < args.length; index += 1) {
@@ -250,6 +322,8 @@ export function resolveNotifyTempContract(args, env = process.env) {
 export function commandOwnsLocalHelp(command) {
     return NESTED_HELP_COMMANDS.has(command);
 }
+const OMX_LAUNCH_POLICY_ENV = "OMX_LAUNCH_POLICY";
+let warnedInvalidEnvLaunchPolicy = false;
 function splitLeaderLaunchPolicyArgs(args) {
     const remainingArgs = [];
     let explicitPolicy;
@@ -264,6 +338,10 @@ function splitLeaderLaunchPolicyArgs(args) {
             remainingArgs.push(arg);
             continue;
         }
+        if (arg === "--direct") {
+            explicitPolicy = "direct";
+            continue;
+        }
         if (arg === "--tmux") {
             explicitPolicy = "detached-tmux";
             continue;
@@ -275,13 +353,34 @@ function splitLeaderLaunchPolicyArgs(args) {
 export function resolveLeaderLaunchPolicyOverride(args) {
     return splitLeaderLaunchPolicyArgs(args).explicitPolicy;
 }
+export function resolveEnvLaunchPolicyOverride(env = process.env) {
+    const rawValue = env[OMX_LAUNCH_POLICY_ENV]?.trim();
+    if (!rawValue)
+        return undefined;
+    const value = rawValue.toLowerCase();
+    if (value === "auto")
+        return undefined;
+    if (value === "direct")
+        return "direct";
+    if (value === "tmux" || value === "detached-tmux")
+        return "detached-tmux";
+    if (!warnedInvalidEnvLaunchPolicy) {
+        warnedInvalidEnvLaunchPolicy = true;
+        console.warn(`[omx] warning: invalid ${OMX_LAUNCH_POLICY_ENV}="${rawValue}". ` +
+            "Expected direct, tmux, detached-tmux, or auto. Falling back to auto/default launch policy.");
+    }
+    return undefined;
+}
+export function resolveEffectiveLeaderLaunchPolicyOverride(args, env = process.env) {
+    return (resolveLeaderLaunchPolicyOverride(args) ?? resolveEnvLaunchPolicyOverride(env));
+}
 export function resolveCodexLaunchPolicy(env = process.env, _platform = process.platform, tmuxAvailable = isTmuxAvailable(), nativeWindows = isNativeWindows(), stdinIsTTY = Boolean(process.stdin.isTTY), stdoutIsTTY = Boolean(process.stdout.isTTY), explicitPolicy) {
+    if (explicitPolicy === "direct")
+        return "direct";
     if (env.TMUX)
         return "inside-tmux";
     if (explicitPolicy === "detached-tmux")
         return tmuxAvailable ? "detached-tmux" : "direct";
-    if (explicitPolicy === "direct")
-        return "direct";
     if (_platform === "win32")
         return "direct";
     if (nativeWindows)
@@ -305,6 +404,60 @@ function hasErrnoCode(error, code) {
         "code" in error &&
         error.code === code);
 }
+function isMissingTmuxLaunchNoise(error) {
+    return error instanceof Error && /spawnSync tmux ENOENT/i.test(error.message);
+}
+function logCliOperationFailure(error) {
+    if (isMissingTmuxLaunchNoise(error))
+        return;
+    process.stderr.write(`[cli/index] operation failed: ${error}
+`);
+}
+function tmuxFailureMessage(error) {
+    if (!error || typeof error !== "object")
+        return String(error);
+    const err = error;
+    const stderr = typeof err.stderr === "string" ? err.stderr : err.stderr?.toString();
+    const stdout = typeof err.stdout === "string" ? err.stdout : err.stdout?.toString();
+    const detail = (stderr || stdout || err.message || String(error)).trim();
+    return detail.replace(/\s+/g, " ");
+}
+function isBenignMissingTmuxServerMessage(message) {
+    return (/no server running/i.test(message) ||
+        /error connecting to .*\(No such file or directory\)/i.test(message));
+}
+export function checkDetachedTmuxLaunchHealth() {
+    try {
+        execTmuxFileSync(["list-sessions"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+        return { usable: true };
+    }
+    catch (err) {
+        const reason = tmuxFailureMessage(err);
+        if (isBenignMissingTmuxServerMessage(reason)) {
+            return { usable: true };
+        }
+        return { usable: false, reason };
+    }
+}
+function warnDetachedTmuxFallback(reason) {
+    const suffix = reason ? ` (${reason})` : "";
+    console.warn(`[omx] warning: tmux is installed but its server/socket is unusable${suffix}. Falling back to direct Codex launch.`);
+}
+function resolveTmuxAwareLaunchPolicy(explicitLaunchPolicy, nativeWindows) {
+    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, nativeWindows, undefined, undefined, explicitLaunchPolicy);
+    if (launchPolicy !== "detached-tmux") {
+        return { launchPolicy, effectiveExplicitLaunchPolicy: explicitLaunchPolicy };
+    }
+    const tmuxHealth = checkDetachedTmuxLaunchHealth();
+    if (tmuxHealth.usable) {
+        return { launchPolicy, effectiveExplicitLaunchPolicy: explicitLaunchPolicy };
+    }
+    warnDetachedTmuxFallback(tmuxHealth.reason);
+    return { launchPolicy: "direct", effectiveExplicitLaunchPolicy: "direct" };
+}
 export function resolveSignalExitCode(signal) {
     if (!signal)
         return 1;
@@ -393,6 +546,7 @@ export async function main(args) {
         "exec",
         "setup",
         "update",
+        "list",
         "agents",
         "agents-init",
         "deepinit",
@@ -412,7 +566,9 @@ export async function main(args) {
         "tmux-hook",
         "hooks",
         "hud",
+        "sidecar",
         "state",
+        "mcp-serve",
         "status",
         "cancel",
         "help",
@@ -424,6 +580,7 @@ export async function main(args) {
     const flags = new Set(args.filter((a) => a.startsWith("--")));
     const options = {
         force: flags.has("--force"),
+        mergeAgents: flags.has("--merge-agents"),
         dryRun: flags.has("--dry-run"),
         verbose: flags.has("--verbose"),
         team: flags.has("--team"),
@@ -443,14 +600,19 @@ export async function main(args) {
             case "setup":
                 await setup({
                     force: options.force,
+                    mergeAgents: options.mergeAgents,
                     dryRun: options.dryRun,
                     verbose: options.verbose,
                     scope: resolveSetupScopeArg(args.slice(1)),
+                    installMode: resolveSetupInstallModeArg(args.slice(1)),
                 });
                 break;
             case "update":
                 await runImmediateUpdate(process.cwd());
                 break;
+            case "list":
+                await listCommand(args.slice(1));
+                break;
             case "agents":
                 await agentsCommand(args.slice(1));
                 break;
@@ -493,7 +655,12 @@ export async function main(args) {
                 await exploreCommand(args.slice(1));
                 break;
             case "exec":
-                await execWithOverlay(launchArgs);
+                if (launchArgs[0] === "inject") {
+                    await execInjectCommand(launchArgs);
+                }
+                else {
+                    await execWithOverlay(launchArgs);
+                }
                 break;
             case "sparkshell":
                 await sparkshellCommand(args.slice(1));
@@ -513,6 +680,9 @@ export async function main(args) {
             case "hud":
                 await hudCommand(args.slice(1));
                 break;
+            case "sidecar":
+                await sidecarCommand(args.slice(1));
+                break;
             case "state":
                 await stateCommand(args.slice(1));
                 break;
@@ -531,6 +701,9 @@ export async function main(args) {
             case "wiki":
                 await mcpParityCommand("wiki", args.slice(1));
                 break;
+            case "mcp-serve":
+                await mcpServeCommand(args.slice(1));
+                break;
             case "tmux-hook":
                 await tmuxHookCommand(args.slice(1));
                 break;
@@ -585,7 +758,7 @@ async function showStatus() {
                 state = JSON.parse(content);
             }
             catch (err) {
-                process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                logCliOperationFailure(err);
                 continue;
             }
             const file = basename(path);
@@ -594,7 +767,7 @@ async function showStatus() {
         }
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         console.log("No active modes.");
     }
 }
@@ -657,9 +830,10 @@ export async function launchWithHud(args) {
     const launchCwd = process.cwd();
     const parsedWorktree = parseWorktreeMode(args);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
-    const explicitLaunchPolicy = resolveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs);
+    const explicitLaunchPolicy = resolveEffectiveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs, process.env);
     const codexHomeOverride = resolveCodexHomeForLaunch(launchCwd, process.env);
-    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, isNativeWindows(), undefined, undefined, explicitLaunchPolicy);
+    const projectLocalCodexHomeForCleanup = resolveProjectLocalCodexHomeForLaunch(launchCwd, process.env);
+    const { launchPolicy, effectiveExplicitLaunchPolicy } = resolveTmuxAwareLaunchPolicy(explicitLaunchPolicy, isNativeWindows());
     const enableNotifyFallbackAuthority = launchPolicy === "direct";
     const workerSparkModel = resolveWorkerSparkModel(notifyTempResult.passthroughArgs, codexHomeOverride);
     const normalizedArgs = normalizeCodexLaunchArgs(notifyTempResult.passthroughArgs);
@@ -693,14 +867,14 @@ export async function launchWithHud(args) {
         await maybeCheckAndPromptUpdate(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal: update checks must never block launch
     }
     try {
         await maybePromptGithubStar();
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal: star prompt must never block launch
     }
     // ── Phase 0.5: config repair ────────────────────────────────────────────
@@ -729,11 +903,11 @@ export async function launchWithHud(args) {
         const notifyTempContractRaw = notifyTempResult.contract.active
             ? serializeNotifyTempContract(notifyTempResult.contract)
             : null;
-        runCodex(cwd, normalizedArgs, sessionId, workerSparkModel, codexHomeOverride, notifyTempContractRaw, explicitLaunchPolicy);
+        runCodex(cwd, normalizedArgs, sessionId, workerSparkModel, codexHomeOverride, notifyTempContractRaw, effectiveExplicitLaunchPolicy);
     }
     finally {
         // ── Phase 3: postLaunch ─────────────────────────────────────────────
-        await postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority);
+        await postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority, projectLocalCodexHomeForCleanup);
     }
 }
 export async function execWithOverlay(args) {
@@ -741,6 +915,7 @@ export async function execWithOverlay(args) {
     const parsedWorktree = parseWorktreeMode(args);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
     const codexHomeOverride = resolveCodexHomeForLaunch(launchCwd, process.env);
+    const projectLocalCodexHomeForCleanup = resolveProjectLocalCodexHomeForLaunch(launchCwd, process.env);
     const normalizedArgs = normalizeCodexLaunchArgs(notifyTempResult.passthroughArgs);
     let cwd = launchCwd;
     let worktreeDirty = false;
@@ -772,13 +947,13 @@ export async function execWithOverlay(args) {
         await maybeCheckAndPromptUpdate(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
     }
     try {
         await maybePromptGithubStar();
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
     }
     try {
         const repaired = await repairConfigIfNeeded(resolveCodexConfigPathForLaunch(launchCwd, process.env), getPackageRoot());
@@ -812,7 +987,7 @@ export async function execWithOverlay(args) {
         runCodexBlocking(cwd, codexArgs, codexEnv);
     }
     finally {
-        await postLaunch(cwd, sessionId, codexHomeOverride, true);
+        await postLaunch(cwd, sessionId, codexHomeOverride, true, projectLocalCodexHomeForCleanup);
     }
 }
 export function normalizeCodexLaunchArgs(args) {
@@ -1111,7 +1286,7 @@ export function detectDetachedSessionWindowIndex(sessionName) {
         return parseWindowIndexFromTmuxOutput(output);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         return null;
     }
 }
@@ -1143,6 +1318,24 @@ function resolveTmuxSocketPath(execFileSyncImpl = (file, tmuxArgs) => execFileSy
 function tmuxExtendedKeysLeasePath(cwd, socketPath) {
     return join(tmuxExtendedKeysLeaseRoot(cwd), `${sanitizeTmuxLeaseKey(socketPath)}.json`);
 }
+function isTmuxExtendedKeysLeaseHolderRecord(holder) {
+    if (!holder || typeof holder !== "object")
+        return false;
+    const record = holder;
+    if (typeof record.id !== "string" || !record.id.trim())
+        return false;
+    if (!Number.isSafeInteger(record.pid) || Number(record.pid) <= 0)
+        return false;
+    if (record.platform !== undefined && typeof record.platform !== "string")
+        return false;
+    if (record.linuxStartTicks !== undefined &&
+        !Number.isSafeInteger(record.linuxStartTicks))
+        return false;
+    return true;
+}
+function isTmuxExtendedKeysLeaseHolder(holder) {
+    return typeof holder === "string" || isTmuxExtendedKeysLeaseHolderRecord(holder);
+}
 function readTmuxExtendedKeysLeaseState(leasePath) {
     if (!existsSync(leasePath))
         return null;
@@ -1150,7 +1343,7 @@ function readTmuxExtendedKeysLeaseState(leasePath) {
         const parsed = JSON.parse(readFileSync(leasePath, "utf-8"));
         if (typeof parsed.originalMode !== "string" ||
             !Array.isArray(parsed.holders) ||
-            !parsed.holders.every((holder) => typeof holder === "string")) {
+            !parsed.holders.every(isTmuxExtendedKeysLeaseHolder)) {
             return null;
         }
         return {
@@ -1166,6 +1359,81 @@ function writeTmuxExtendedKeysLeaseState(leasePath, state) {
     mkdirSync(dirname(leasePath), { recursive: true });
     writeFileSync(leasePath, JSON.stringify(state, null, 2));
 }
+function parseTmuxExtendedKeysLeaseHolderPid(holder) {
+    const match = /^([1-9]\d*)-/.exec(holder);
+    if (!match)
+        return null;
+    const pid = Number.parseInt(match[1], 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function getTmuxExtendedKeysLeaseHolderId(holder) {
+    return typeof holder === "string" ? holder : holder.id;
+}
+function getTmuxExtendedKeysLeaseHolderPid(holder) {
+    if (typeof holder === "string")
+        return parseTmuxExtendedKeysLeaseHolderPid(holder);
+    return Number.isSafeInteger(holder.pid) && holder.pid > 0 ? holder.pid : null;
+}
+function parseLinuxProcStartTicks(statContent) {
+    const commandEnd = statContent.lastIndexOf(")");
+    if (commandEnd === -1)
+        return null;
+    const remainder = statContent.slice(commandEnd + 1).trim();
+    const fields = remainder.split(/\s+/);
+    if (fields.length <= 19)
+        return null;
+    const startTicks = Number(fields[19]);
+    return Number.isSafeInteger(startTicks) ? startTicks : null;
+}
+function readLinuxProcessStartTicks(pid) {
+    try {
+        return parseLinuxProcStartTicks(readFileSync(`/proc/${pid}/stat`, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function createTmuxExtendedKeysLeaseHolder(id, pid) {
+    const linuxStartTicks = process.platform === "linux"
+        ? readLinuxProcessStartTicks(pid) ?? undefined
+        : undefined;
+    return {
+        id,
+        pid,
+        platform: process.platform,
+        ...(linuxStartTicks !== undefined ? { linuxStartTicks } : {}),
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? String(err.code)
+            : "";
+        return code === "EPERM";
+    }
+}
+function isTmuxExtendedKeysLeaseHolderAlive(holder) {
+    const pid = getTmuxExtendedKeysLeaseHolderPid(holder);
+    if (pid === null || !isProcessAlive(pid))
+        return false;
+    if (typeof holder === "string")
+        return true;
+    if (holder.platform !== "linux" || process.platform !== "linux")
+        return true;
+    if (holder.linuxStartTicks === undefined)
+        return true;
+    return readLinuxProcessStartTicks(pid) === holder.linuxStartTicks;
+}
+function reapDeadTmuxExtendedKeysLeaseHolders(state) {
+    return {
+        originalMode: state.originalMode,
+        holders: state.holders.filter(isTmuxExtendedKeysLeaseHolderAlive),
+    };
+}
 function withTmuxExtendedKeysLeaseLock(cwd, socketPath, run) {
     const leaseRoot = tmuxExtendedKeysLeaseRoot(cwd);
     mkdirSync(leaseRoot, { recursive: true });
@@ -1245,30 +1513,36 @@ function execTmuxSync(args, execFileSyncImpl = (file, tmuxArgs) => execFileSync(
 export function acquireTmuxExtendedKeysLease(cwd, execFileSyncImpl = (file, tmuxArgs) => execFileSync(file, tmuxArgs, {
     encoding: "utf-8",
     ...(process.platform === "win32" ? { windowsHide: true } : {}),
-})) {
+}), ownerPid = process.pid) {
     try {
         const socketPath = resolveTmuxSocketPath(execFileSyncImpl);
         const leasePath = tmuxExtendedKeysLeasePath(cwd, socketPath);
-        const leaseId = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        const holderPid = Number.isSafeInteger(ownerPid) && ownerPid > 0 ? ownerPid : process.pid;
+        const leaseId = `${holderPid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
         withTmuxExtendedKeysLeaseLock(cwd, socketPath, () => {
-            const state = readTmuxExtendedKeysLeaseState(leasePath);
+            const stateRaw = readTmuxExtendedKeysLeaseState(leasePath);
+            const state = stateRaw ? reapDeadTmuxExtendedKeysLeaseHolders(stateRaw) : null;
+            if (stateRaw && state?.holders.length === 0) {
+                execTmuxSync(["set-option", "-sq", "extended-keys", state.originalMode], execFileSyncImpl);
+                rmSync(leasePath, { force: true });
+            }
             if (!state || state.holders.length === 0) {
                 const previousMode = execTmuxSync(["show-options", "-sv", "extended-keys"], execFileSyncImpl) ||
                     TMUX_EXTENDED_KEYS_FALLBACK_MODE;
                 execTmuxSync(["set-option", "-sq", "extended-keys", TMUX_EXTENDED_KEYS_MODE], execFileSyncImpl);
                 writeTmuxExtendedKeysLeaseState(leasePath, {
                     originalMode: previousMode,
-                    holders: [leaseId],
+                    holders: [createTmuxExtendedKeysLeaseHolder(leaseId, holderPid)],
                 });
                 return;
             }
-            state.holders.push(leaseId);
+            state.holders.push(createTmuxExtendedKeysLeaseHolder(leaseId, holderPid));
             writeTmuxExtendedKeysLeaseState(leasePath, state);
         });
         return `${socketPath}\t${leaseId}`;
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         return null;
     }
 }
@@ -1285,12 +1559,16 @@ export function releaseTmuxExtendedKeysLease(cwd, leaseHandle, execFileSyncImpl
     try {
         const leasePath = tmuxExtendedKeysLeasePath(cwd, socketPath);
         withTmuxExtendedKeysLeaseLock(cwd, socketPath, () => {
-            const state = readTmuxExtendedKeysLeaseState(leasePath);
+            const stateRaw = readTmuxExtendedKeysLeaseState(leasePath);
+            const state = stateRaw ? reapDeadTmuxExtendedKeysLeaseHolders(stateRaw) : null;
             if (!state || state.holders.length === 0) {
+                if (stateRaw) {
+                    execTmuxSync(["set-option", "-sq", "extended-keys", stateRaw.originalMode], execFileSyncImpl);
+                }
                 rmSync(leasePath, { force: true });
                 return;
             }
-            const holders = state.holders.filter((holder) => holder !== leaseId);
+            const holders = state.holders.filter((holder) => getTmuxExtendedKeysLeaseHolderId(holder) !== leaseId);
             if (holders.length > 0) {
                 writeTmuxExtendedKeysLeaseState(leasePath, {
                     originalMode: state.originalMode,
@@ -1303,19 +1581,19 @@ export function releaseTmuxExtendedKeysLease(cwd, leaseHandle, execFileSyncImpl
         });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
     }
 }
 function buildTmuxExtendedKeysHelperCommand(cwd, operation) {
     const cwdLiteral = JSON.stringify(cwd);
     const moduleUrlLiteral = JSON.stringify(import.meta.url);
     const script = operation === "acquire"
-        ? `const mod = await import(${moduleUrlLiteral}); const lease = mod.acquireTmuxExtendedKeysLease(${cwdLiteral}); if (lease) process.stdout.write(lease);`
+        ? `const mod = await import(${moduleUrlLiteral}); const ownerPid = Number.parseInt(process.argv[1] ?? "", 10); const lease = mod.acquireTmuxExtendedKeysLease(${cwdLiteral}, undefined, Number.isSafeInteger(ownerPid) && ownerPid > 0 ? ownerPid : undefined); if (lease) process.stdout.write(lease);`
         : `const mod = await import(${moduleUrlLiteral}); mod.releaseTmuxExtendedKeysLease(${cwdLiteral}, process.argv[1] ?? "");`;
     return `${quoteShellArg(process.execPath)} --input-type=module -e ${quoteShellArg(script)}`;
 }
 function buildTmuxExtendedKeysAcquireShellSnippet(cwd) {
-    return `OMX_TMUX_EXTENDED_KEYS_LEASE=$(${buildTmuxExtendedKeysHelperCommand(cwd, "acquire")} 2>/dev/null || true);`;
+    return `OMX_TMUX_EXTENDED_KEYS_LEASE=$(${buildTmuxExtendedKeysHelperCommand(cwd, "acquire")} "$$" 2>/dev/null || true);`;
 }
 function buildTmuxExtendedKeysReleaseShellSnippet(cwd) {
     return `if [ -n "\${OMX_TMUX_EXTENDED_KEYS_LEASE:-}" ]; then ${buildTmuxExtendedKeysHelperCommand(cwd, "release")} "\${OMX_TMUX_EXTENDED_KEYS_LEASE}" >/dev/null 2>&1 || true; fi;`;
@@ -1692,7 +1970,7 @@ async function preLaunch(cwd, sessionId, notifyTempContract, codexHomeOverride,
         }
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 2. Generate runtime overlay + write session-scoped model instructions file
@@ -1716,7 +1994,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         await startNotifyFallbackWatcher(cwd, { codexHomeOverride, enableAuthority: enableNotifyFallbackAuthority, sessionId });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 5. Start derived watcher (best effort, opt-in)
@@ -1724,7 +2002,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         await startHookDerivedWatcher(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 6. Emit temp notification startup summary + warnings, then send session-start lifecycle notification (best effort)
@@ -1753,7 +2031,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal: notification failures must never block launch
     }
     // 7. Dispatch native hook event (best effort)
@@ -1768,7 +2046,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
 }
@@ -1798,7 +2076,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
     const codexEnvWithNotify = notifyTempContractRaw
         ? { ...codexEnv, [OMX_NOTIFY_TEMP_CONTRACT_ENV]: notifyTempContractRaw }
         : codexEnv;
-    const launchPolicy = resolveCodexLaunchPolicy(process.env, process.platform, undefined, nativeWindows, undefined, undefined, explicitLaunchPolicy);
+    const { launchPolicy } = resolveTmuxAwareLaunchPolicy(explicitLaunchPolicy, nativeWindows);
     if (isCodexVersionRequest(launchArgs)) {
         runCodexBlocking(cwd, launchArgs, codexEnvWithNotify);
         return;
@@ -1815,7 +2093,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
             hudPaneId = createHudWatchPane(cwd, hudCmd);
         }
         catch (err) {
-            process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+            logCliOperationFailure(err);
             // HUD split failed, continue without it
         }
         // Enable mouse scrolling at session start so scroll works before team
@@ -1834,7 +2112,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
                     enableMouseScrolling(tmuxSession);
             }
             catch (err) {
-                process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                logCliOperationFailure(err);
                 // Non-fatal: mouse scrolling is a convenience feature
             }
         }
@@ -1871,6 +2149,10 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
             ? buildWindowsPromptCommand("codex", launchArgs)
             : null;
         const sessionName = buildDetachedTmuxSessionName(cwd, sessionId);
+        void writeSessionStart(cwd, sessionId, { tmuxSessionName: sessionName }).catch((err) => {
+            logCliOperationFailure(err);
+            // Non-fatal: managed tmux recovery can still use compatibility fallback.
+        });
         let createdDetachedSession = false;
         let registeredHookTarget = null;
         let registeredHookName = null;
@@ -1910,7 +2192,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
                                 mitigateCopyModeUnderlineArtifacts(sessionName);
                             }
                             catch (err) {
-                                process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                                logCliOperationFailure(err);
                             }
                             continue;
                         }
@@ -1919,7 +2201,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
                             execTmuxFileSync(finalizeStep.args, { stdio });
                         }
                         catch (err) {
-                            process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                            logCliOperationFailure(err);
                             if (finalizeStep.name === "attach-session")
                                 throw new Error("failed to attach detached tmux session");
                             continue;
@@ -1939,7 +2221,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
             }
         }
         catch (err) {
-            process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+            logCliOperationFailure(err);
             if (createdDetachedSession) {
                 const rollbackSteps = buildDetachedSessionRollbackSteps(sessionName, registeredHookTarget, registeredHookName, registeredClientAttachedHookName);
                 for (const rollbackStep of rollbackSteps) {
@@ -1947,7 +2229,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, n
                         execTmuxFileSync(rollbackStep.args, { stdio: "ignore" });
                     }
                     catch (err) {
-                        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                        logCliOperationFailure(err);
                         // best-effort rollback only
                     }
                 }
@@ -1962,7 +2244,7 @@ function listHudWatchPaneIdsInCurrentWindow(currentPaneId) {
         return listCurrentWindowHudPaneIds(currentPaneId);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         return [];
     }
 }
@@ -1976,7 +2258,7 @@ function killTmuxPane(paneId) {
         killSharedTmuxPane(paneId);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Pane may already be gone; ignore.
     }
 }
@@ -2055,7 +2337,7 @@ function scheduleDetachedWindowsCodexLaunch(sessionName, commandText) {
  * postLaunch: Clean up after Codex exits.
  * Each step is independently fault-tolerant (try/catch per step).
  */
-async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority = false) {
+async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority = false, projectLocalCodexHomeForCleanup) {
     // Capture session start time before cleanup (writeSessionEnd deletes session.json)
     let sessionStartedAt;
     try {
@@ -2063,7 +2345,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         sessionStartedAt = sessionState?.started_at;
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 0. Reap MCP orphans left behind by the session that just exited.
@@ -2073,7 +2355,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         await flushNotifyFallbackOnce(cwd, { codexHomeOverride, enableAuthority: enableNotifyFallbackAuthority, sessionId });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 0. Stop notify fallback watcher first.
@@ -2081,7 +2363,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         await stopNotifyFallbackWatcher(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 0. Flush derived watcher once on shutdown (opt-in, best effort).
@@ -2089,7 +2371,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         await flushHookDerivedWatcherOnce(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 0.1 Stop derived watcher first (opt-in, best effort).
@@ -2097,9 +2379,18 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         await stopHookDerivedWatcher(cwd);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
+    // 0.5. Remove Codex transient TUI NUX counters from project-local config only.
+    try {
+        if (projectLocalCodexHomeForCleanup) {
+            await cleanCodexModelAvailabilityNuxIfNeeded(join(projectLocalCodexHomeForCleanup, "config.toml"));
+        }
+    }
+    catch (err) {
+        console.error(`[omx] postLaunch: project config transient NUX cleanup failed: ${err instanceof Error ? err.message : err}`);
+    }
     // 1. Remove session-scoped model instructions file
     try {
         await removeSessionModelInstructionsFile(cwd, sessionId);
@@ -2120,7 +2411,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         onSessionEnd({ cwd, session_id: sessionId });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal: wiki capture must never block session cleanup
     }
     // 3. Cancel any still-active modes
@@ -2145,7 +2436,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal: notification failures must never block session cleanup
     }
     // 4.5. Persist team leader attention when an active leader session exits.
@@ -2154,7 +2445,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         await markOwnedTeamsLeaderSessionStopped(cwd, sessionId);
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
     // 5. Dispatch native hook event (best effort)
@@ -2182,7 +2473,7 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         });
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         // Non-fatal
     }
 }
@@ -2578,7 +2869,7 @@ async function cancelModes() {
                 parsedState = JSON.parse(content);
             }
             catch (err) {
-                process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+                logCliOperationFailure(err);
                 continue;
             }
             states.set(ref.mode, {
@@ -2635,7 +2926,7 @@ async function cancelModes() {
         }
     }
     catch (err) {
-        process.stderr.write(`[cli/index] operation failed: ${err}\n`);
+        logCliOperationFailure(err);
         console.log("No active modes to cancel.");
     }
 }