oh-my-codex 0.15.0 → 0.15.2

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";
@@ -30,8 +31,8 @@ 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";
@@ -41,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";
@@ -53,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");
 }
@@ -69,8 +71,10 @@ 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
@@ -97,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
@@ -128,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
@@ -137,13 +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
+
+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";
@@ -151,6 +176,7 @@ const TEAM_WORKER_LAUNCH_ARGS_ENV = "OMX_TEAM_WORKER_LAUNCH_ARGS";
 const TEAM_INHERIT_LEADER_FLAGS_ENV = "OMX_TEAM_INHERIT_LEADER_FLAGS";
 const OMX_BYPASS_DEFAULT_SYSTEM_PROMPT_ENV = "OMX_BYPASS_DEFAULT_SYSTEM_PROMPT";
 const OMX_MODEL_INSTRUCTIONS_FILE_ENV = "OMX_MODEL_INSTRUCTIONS_FILE";
+const OMX_INSTANCE_OPTION = "@omx_instance_id";
 const OMX_RALPH_APPEND_INSTRUCTIONS_FILE_ENV = "OMX_RALPH_APPEND_INSTRUCTIONS_FILE";
 const OMX_AUTORESEARCH_APPEND_INSTRUCTIONS_FILE_ENV = "OMX_AUTORESEARCH_APPEND_INSTRUCTIONS_FILE";
 const REASONING_MODES = ["low", "medium", "high", "xhigh"];
@@ -170,6 +196,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;
@@ -193,6 +220,7 @@ const NESTED_HELP_COMMANDS = new Set([
     "hooks",
     "list",
     "hud",
+    "sidecar",
     "state",
     "wiki",
     "mcp-serve",
@@ -204,9 +232,44 @@ const NESTED_HELP_COMMANDS = new Set([
     "tmux-hook",
 ]);
 export function resolveSetupInstallModeArg(args) {
-    if (args.includes("--plugin"))
-        return "plugin";
-    return undefined;
+    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;
@@ -260,6 +323,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;
@@ -274,6 +339,10 @@ function splitLeaderLaunchPolicyArgs(args) {
             remainingArgs.push(arg);
             continue;
         }
+        if (arg === "--direct") {
+            explicitPolicy = "direct";
+            continue;
+        }
         if (arg === "--tmux") {
             explicitPolicy = "detached-tmux";
             continue;
@@ -285,13 +354,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)
@@ -334,7 +424,8 @@ function tmuxFailureMessage(error) {
     return detail.replace(/\s+/g, " ");
 }
 function isBenignMissingTmuxServerMessage(message) {
-    return /no server running/i.test(message);
+    return (/no server running/i.test(message) ||
+        /error connecting to .*\(No such file or directory\)/i.test(message));
 }
 export function checkDetachedTmuxLaunchHealth() {
     try {
@@ -476,6 +567,7 @@ export async function main(args) {
         "tmux-hook",
         "hooks",
         "hud",
+        "sidecar",
         "state",
         "mcp-serve",
         "status",
@@ -489,6 +581,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"),
@@ -508,6 +601,7 @@ 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)),
@@ -562,7 +656,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));
@@ -582,6 +681,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;
@@ -729,8 +831,9 @@ export async function launchWithHud(args) {
     const launchCwd = process.cwd();
     const parsedWorktree = parseWorktreeMode(args);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
-    const explicitLaunchPolicy = resolveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs);
+    const explicitLaunchPolicy = resolveEffectiveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs, process.env);
     const codexHomeOverride = resolveCodexHomeForLaunch(launchCwd, process.env);
+    const projectLocalCodexHomeForCleanup = resolveProjectLocalCodexHomeForLaunch(launchCwd, process.env);
     const { launchPolicy, effectiveExplicitLaunchPolicy } = resolveTmuxAwareLaunchPolicy(explicitLaunchPolicy, isNativeWindows());
     const enableNotifyFallbackAuthority = launchPolicy === "direct";
     const workerSparkModel = resolveWorkerSparkModel(notifyTempResult.passthroughArgs, codexHomeOverride);
@@ -805,7 +908,7 @@ export async function launchWithHud(args) {
     }
     finally {
         // ── Phase 3: postLaunch ─────────────────────────────────────────────
-        await postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority);
+        await postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbackAuthority, projectLocalCodexHomeForCleanup);
     }
 }
 export async function execWithOverlay(args) {
@@ -813,6 +916,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;
@@ -884,7 +988,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) {
@@ -1020,6 +1124,36 @@ export function resolveNativeSessionName(cwd, sessionId, env = process.env) {
     }
     return buildTmuxSessionName(cwd, sessionId);
 }
+function tagTmuxSessionWithInstance(sessionName, sessionId) {
+    const target = sessionName.trim();
+    const instanceId = sessionId.trim();
+    if (!target || !instanceId)
+        return;
+    execFileSync("tmux", ["set-option", "-t", target, OMX_INSTANCE_OPTION, instanceId], {
+        stdio: ["ignore", "ignore", "ignore"],
+        timeout: 2000,
+    });
+}
+function tagCurrentTmuxSessionWithInstance(sessionId) {
+    if (!process.env.TMUX)
+        return;
+    try {
+        const tmuxPaneTarget = process.env.TMUX_PANE;
+        const displayArgs = tmuxPaneTarget
+            ? ["display-message", "-p", "-t", tmuxPaneTarget, "#S"]
+            : ["display-message", "-p", "#S"];
+        const sessionName = execFileSync("tmux", displayArgs, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        if (sessionName)
+            tagTmuxSessionWithInstance(sessionName, sessionId);
+    }
+    catch {
+        // Best effort only: launch should not fail just because tmux tagging failed.
+    }
+}
 function buildNativeHookBaseContext(cwd, sessionId, normalizedEvent, extra = {}) {
     const repoPath = tryReadGitValue(cwd, ["rev-parse", "--show-toplevel"]) || cwd;
     const branch = tryReadGitValue(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
@@ -1215,6 +1349,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;
@@ -1222,7 +1374,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 {
@@ -1238,6 +1390,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 });
@@ -1317,24 +1544,30 @@ 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}`;
@@ -1357,12 +1590,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,
@@ -1382,12 +1619,12 @@ 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;`;
@@ -1446,6 +1683,14 @@ export function buildDetachedSessionBootstrapSteps(sessionName, cwd, codexCmd, h
     ];
     return [
         { name: "new-session", args: newSessionArgs },
+        ...(sessionId
+            ? [
+                {
+                    name: "tag-session",
+                    args: ["set-option", "-t", sessionName, OMX_INSTANCE_OPTION, sessionId],
+                },
+            ]
+            : []),
         { name: "split-and-capture-hud-pane", args: splitCaptureArgs },
     ];
 }
@@ -1783,6 +2028,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
     // 3. Write session state
     await resetSessionMetrics(cwd, sessionId);
     await writeSessionStart(cwd, sessionId);
+    tagCurrentTmuxSessionWithInstance(sessionId);
     // 4. Start notify fallback watcher (best effort)
     try {
         await startNotifyFallbackWatcher(cwd, { codexHomeOverride, enableAuthority: enableNotifyFallbackAuthority, sessionId });
@@ -1943,6 +2189,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;
@@ -2127,7 +2377,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 {
@@ -2172,6 +2422,15 @@ async function postLaunch(cwd, sessionId, codexHomeOverride, enableNotifyFallbac
         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);