oh-my-codex 0.20.1 → 0.20.3

package/dist/cli/index.js

@@ -17,6 +17,7 @@ import { hudCommand } from "../hud/index.js";
 import { sidecarCommand } from "../sidecar/index.js";
 import { teamCommand } from "./team.js";
 import { ralphCommand } from "./ralph.js";
+import { ralplanCommand } from "./ralplan.js";
 import { ultragoalCommand } from "./ultragoal.js";
 import { performanceGoalCommand } from "./performance-goal.js";
 import { askCommand } from "./ask.js";
@@ -38,23 +39,24 @@ import { adaptCommand } from "./adapt.js";
 import { listCommand } from "./list.js";
 import { authCommand } from "./auth.js";
 import { missionCommand } from "./mission.js";
-import { runAuthHotswap } from "../auth/hotswap.js";
+import { resolveCodexGlobalOptionValue, runAuthHotswap, } from "../auth/hotswap.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 { getBaseStateDir, getBaseStateDirWithSource, getStateDir, listModeStateFilesWithScopePreference, resolveWritableStateScope, } from "../mcp/state-paths.js";
 import { evaluateRalphCompletionAuditEvidence, isRalphCompletePhase } from "../ralph/completion-audit.js";
 import { normalizeTerminalWorkflowState } from "../state/terminal-normalization.js";
 import { readPersistedSetupPreferences, resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, resolveProjectLocalCodexHomeForLaunch, } from "./codex-home.js";
 import { discoverProjectRuntimeCodexHomes } from "./project-runtime-codex-homes.js";
 import { discoverOmxPluginCacheDirs, hasLocalOmxPluginEnablement, materializePackagedOmxPluginCache, packagedOmxPluginVersion, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, upsertLocalOmxPluginEnablement, } from "./plugin-marketplace.js";
 import { escapeTomlString, readTopLevelTomlString, upsertTopLevelTomlString } from "../utils/toml.js";
-import { CANONICAL_REASONING_EFFORTS, isAmbiguousUnsupportedReasoningEffort, } from "../config/models.js";
+import { ROOT_REASONING_EFFORTS, isUnsupportedRootReasoningEffort, normalizeUnsupportedRootReasoningEffort, } from "../config/models.js";
 export { readPersistedSetupPreferences, readPersistedSetupScope, resolveCodexConfigPathForLaunch, resolveCodexHomeForLaunch, resolveProjectLocalCodexHomeForLaunch, } from "./codex-home.js";
 import { SKILL_ACTIVE_STATE_MODE, extractSessionIdFromInitializedStatePath, getSkillActiveStatePathsForStateDir, listActiveSkills, readSkillActiveState, syncCanonicalSkillStateForMode, } from "../state/skill-active.js";
 import { isTrackedWorkflowMode } from "../state/workflow-transition.js";
 import { maybeCheckAndPromptUpdate, runImmediateUpdate } from "./update.js";
 import { maybePromptGithubStar } from "./star-prompt.js";
 import { generateOverlay, removeSessionModelInstructionsFile, resolveSessionOrchestrationMode, sessionModelInstructionsPath, writeSessionModelInstructionsFile, } from "../hooks/agents-overlay.js";
-import { readSessionState, writeSessionStart, writeSessionEnd, resetSessionMetrics, } from "../hooks/session.js";
+import { isSessionPointerLaunchAbort, normalizeSessionId, readSessionState, writeSessionStart, writeSessionEnd, resetSessionMetrics, } from "../hooks/session.js";
+import { probeActualTmuxInstanceEvidence, tmuxEvidenceBindsCandidate } from "../scripts/notify-hook/managed-tmux.js";
 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, omxRoot, rememberOmxLaunchContext, resolveOmxCliEntryPath } from "../utils/paths.js";
@@ -69,7 +71,7 @@ rememberOmxLaunchContext({ argv1: process.argv[1], cwd: process.cwd(), env: proc
 import { classifySpawnError, resolveTmuxBinaryForPlatform, spawnPlatformCommandSync, } from "../utils/platform-command.js";
 import { buildHookEvent } from "../hooks/extensibility/events.js";
 import { dispatchHookEvent } from "../hooks/extensibility/dispatcher.js";
-import { collectInheritableTeamWorkerArgs as collectInheritableTeamWorkerArgsShared, parseTeamWorkerLaunchArgs, resolveTeamWorkerLaunchArgs, resolveTeamLowComplexityDefaultModel, TEAM_WORKER_INHERITED_MODEL_ENV, } from "../team/model-contract.js";
+import { collectInheritableTeamWorkerArgs as collectInheritableTeamWorkerArgsShared, parseTeamWorkerLaunchArgs, resolveTeamWorkerLaunchArgs, resolveTeamLowComplexityDefaultModel, serializeTeamWorkerLaunchArgs, TEAM_WORKER_INHERITED_MODEL_ENV, } from "../team/model-contract.js";
 import { parseWorktreeMode, planWorktreeTarget, ensureWorktree, } from "../team/worktree.js";
 import { ensureReusableNodeModules } from "../utils/repo-deps.js";
 import { resolveWorktreeToolContext, worktreeToolContextEnv } from "../utils/worktree-tool-context.js";
@@ -121,6 +123,7 @@ Usage:
   omx explore   DEPRECATED compatibility command; use normal repo inspection or omx sparkshell
   omx api       Run native omx-api localhost gateway commands (serve|status|stop|generate)
   omx session   Search and summarize local session history (--codex-home <path> escape hatch)
+                Includes session lock inspect/recover diagnostics
   omx url       Passive URL reader (read <url> --json)
   omx capabilities
                 Lock/check deterministic configured tool, skill, agent, and observation surfaces
@@ -131,6 +134,7 @@ Usage:
                 Alias for agents-init (lightweight AGENTS bootstrap only)
   omx team      Spawn parallel worker panes in tmux and bootstrap inbox/task state
   omx ralph     Launch Codex with ralph persistence mode active
+  omx ralplan   Record validated role intents for adapted native subagent spawns
   omx ultragoal Create, resume, and checkpoint durable multi-goal plans over Codex goal mode
   omx performance-goal
                 Create, hand off, and gate evaluator-backed performance goals
@@ -185,8 +189,11 @@ Options:
                 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
+                Merge OMX-managed AGENTS.md sections and persist that explicit policy for this project root
+  --no-merge-agents
+                Persist an explicit non-merge policy; current non-merge behavior remains contextual
+  --clear-merge-agents-policy
+                Clear the persisted AGENTS merge policy for this project root
   --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
@@ -229,10 +236,15 @@ 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 = CANONICAL_REASONING_EFFORTS;
+const REASONING_MODES = ROOT_REASONING_EFFORTS;
 const REASONING_MODE_SET = new Set(REASONING_MODES);
 const REASONING_USAGE = "Usage: omx reasoning <low|medium|high|xhigh>";
-const AMBIGUOUS_REASONING_MESSAGE = 'Codex/OMX canonical highest reasoning effort is "xhigh"; "max" and "ultra" are not accepted aliases.';
+function unsupportedLaunchShorthandError(flag) {
+    const guidance = flag === "--max"
+        ? 'No --max shorthand exists; use agentReasoning for per-agent "max" or pass -c model_reasoning_effort=... directly to Codex.'
+        : '"ultra" is not an OMX root or per-agent reasoning value and is not an alias for "max".';
+    return new Error(`Unsupported OMX launch shorthand "${flag}".\n${guidance}\nRun "omx help" for usage.`);
+}
 const ALLOWED_SHELLS = new Set([
     "/bin/sh",
     "/bin/bash",
@@ -258,6 +270,9 @@ const TMUX_EXTENDED_KEYS_LEASE_DIR = "tmux-extended-keys";
 const TMUX_EXTENDED_KEYS_LOCK_RETRY_MS = 20;
 const TMUX_EXTENDED_KEYS_LOCK_MAX_ATTEMPTS = 100;
 const TMUX_EXTENDED_KEYS_LOCK_STALE_MS = 30_000;
+const RESUME_HELP = `Usage: omx resume [--project] [--codex-home <path>] [codex resume options]
+
+Read-only help does not prepare or launch a Codex session.`;
 const NESTED_HELP_COMMANDS = new Set([
     "ask",
     "question",
@@ -286,6 +301,7 @@ const NESTED_HELP_COMMANDS = new Set([
     "wiki",
     "mcp-serve",
     "ralph",
+    "ralplan",
     "ultragoal",
     "performance-goal",
     "resume",
@@ -296,6 +312,43 @@ const NESTED_HELP_COMMANDS = new Set([
     "team",
     "tmux-hook",
 ]);
+export function resolveSetupAgentsMergePolicyArg(args) {
+    let policy;
+    const setPolicy = (next, source) => {
+        if (policy && (policy.kind !== next.kind || (policy.kind === "set" && next.kind === "set" && policy.value !== next.value))) {
+            throw new Error(`Conflicting setup AGENTS merge policy flags: ${source} conflicts with another merge policy selector.`);
+        }
+        policy = next;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--merge-agents" || arg === "--no-merge-agents" || arg === "--clear-merge-agents-policy") {
+            const next = args[index + 1];
+            if (next && !next.startsWith("--")) {
+                throw new Error(`Setup AGENTS merge policy flags do not accept values: ${arg} ${next}`);
+            }
+            if (arg === "--merge-agents") {
+                setPolicy({ kind: "set", value: true }, arg);
+            }
+            else if (arg === "--no-merge-agents") {
+                setPolicy({ kind: "set", value: false }, arg);
+            }
+            else {
+                setPolicy({ kind: "clear" }, arg);
+            }
+        }
+        else if (arg.startsWith("--merge-agents=") ||
+            arg.startsWith("--no-merge-agents=") ||
+            arg.startsWith("--clear-merge-agents-policy=")) {
+            throw new Error(`Setup AGENTS merge policy flags do not accept values: ${arg}`);
+        }
+    }
+    return policy;
+}
+export function resolveSetupMergeAgentsArg(args) {
+    const policy = resolveSetupAgentsMergePolicyArg(args);
+    return policy?.kind === "set" ? policy.value : undefined;
+}
 export function resolveSetupInstallModeArg(args) {
     let value;
     const setValue = (next, source) => {
@@ -438,6 +491,15 @@ export function resolveSetupTeamModeArg(args) {
     }
     return value;
 }
+function splitOmxArgsAtEndOfOptions(args) {
+    const endOfOptionsIndex = args.indexOf("--");
+    if (endOfOptionsIndex === -1)
+        return { omxArgs: args, suffix: [] };
+    return {
+        omxArgs: args.slice(0, endOfOptionsIndex),
+        suffix: args.slice(endOfOptionsIndex),
+    };
+}
 export function resolveCliInvocation(args) {
     const firstArg = args[0];
     if (firstArg === "--help" || firstArg === "-h") {
@@ -801,13 +863,14 @@ export async function prepareCodexHomeForLaunch(cwd, sessionId, env = process.en
     };
 }
 export function parseResumeCodexHomeSelection(args) {
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
     const nextArgs = [];
     let explicitCodexHome;
     let projectOnly = false;
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
+    for (let index = 0; index < omxArgs.length; index += 1) {
+        const arg = omxArgs[index];
         if (arg === "--codex-home") {
-            const value = args[index + 1];
+            const value = omxArgs[index + 1];
             if (!value || value.startsWith("-")) {
                 throw new Error("Missing value after --codex-home.");
             }
@@ -829,7 +892,7 @@ export function parseResumeCodexHomeSelection(args) {
         nextArgs.push(arg);
     }
     return {
-        args: nextArgs,
+        args: [...nextArgs, ...suffix],
         explicitCodexHome,
         projectOnly,
     };
@@ -874,8 +937,32 @@ export async function preflightResumeOmxPluginState(codexHomeDir, pkgRoot = getP
         configUpdated,
     };
 }
-function isResumeCodexLaunch(args) {
-    return args.includes("resume");
+export { CODEX_GLOBAL_OPTIONS_WITH_SPLIT_VALUE } from "../auth/hotswap.js";
+export function isResumeCodexLaunch(args) {
+    const { omxArgs } = splitOmxArgsAtEndOfOptions(args);
+    for (let index = 0; index < omxArgs.length; index += 1) {
+        const arg = omxArgs[index];
+        const optionValue = resolveCodexGlobalOptionValue(arg);
+        if (optionValue?.valueArity === "single") {
+            if (!optionValue.attached)
+                index += 1;
+            continue;
+        }
+        if (optionValue?.valueArity === "variadic") {
+            if (optionValue.attached)
+                continue;
+            let nextIndex = index + 1;
+            while (nextIndex < omxArgs.length && !omxArgs[nextIndex].startsWith("-")) {
+                nextIndex += 1;
+            }
+            index = nextIndex - 1;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            continue;
+        return arg === "resume";
+    }
+    return false;
 }
 async function prepareResumeCodexHomeForLaunch(cwd, sessionId, args, env = process.env) {
     const selection = parseResumeCodexHomeSelection(args);
@@ -1088,6 +1175,18 @@ function hasErrnoCode(error, code) {
 function isMissingTmuxLaunchNoise(error) {
     return error instanceof Error && /spawnSync tmux ENOENT/i.test(error.message);
 }
+function reportOrdinaryLaunchRootConflict(error, cwd, ordinaryLaunch) {
+    if (!ordinaryLaunch || !isSessionPointerLaunchAbort(error)
+        || error.code !== "session_pointer_owner_conflict"
+        || getBaseStateDirWithSource(cwd).rootSource !== "cwd-default")
+        return;
+    console.error("[omx] concurrent conversations in this checkout require distinct user-specified OMX_ROOT values.\n" +
+        "[omx] Choose a distinct directory and set OMX_ROOT before launching the additional conversation.\n" +
+        "[omx] POSIX: OMX_ROOT=\"$HOME/.omx/instances/second-conversation\" omx\n" +
+        "[omx] PowerShell: $env:OMX_ROOT = \"$HOME/.omx/instances/second-conversation\"; omx\n" +
+        "[omx] cmd.exe: set \"OMX_ROOT=%USERPROFILE%\\.omx\\instances\\second-conversation\" && omx\n" +
+        "[omx] The selected OMX_ROOT is used literally; OMX does not reroute or allocate one automatically.");
+}
 function logCliOperationFailure(error) {
     if (isMissingTmuxLaunchNoise(error))
         return;
@@ -1513,10 +1612,31 @@ function launchArgRequestsDisposableWorktree(arg) {
         (arg.startsWith("-w") && arg.length > 2);
 }
 function launchArgsRequestMadmaxIsolation(launchArgs) {
-    return launchArgs.some((arg) => arg === MADMAX_FLAG || arg === MADMAX_SPARK_FLAG);
+    for (const arg of launchArgs) {
+        if (arg === "--")
+            break;
+        if (arg === MADMAX_FLAG || arg === MADMAX_SPARK_FLAG)
+            return true;
+    }
+    return false;
+}
+function launchArgsRequestAuthHotswap(launchArgs) {
+    for (const arg of launchArgs) {
+        if (arg === "--")
+            break;
+        if (arg === "--hotswap")
+            return true;
+    }
+    return false;
 }
 function launchArgsRequestDisposableWorktree(launchArgs) {
-    return launchArgs.some((arg) => launchArgRequestsDisposableWorktree(arg));
+    for (const arg of launchArgs) {
+        if (arg === "--")
+            break;
+        if (launchArgRequestsDisposableWorktree(arg))
+            return true;
+    }
+    return false;
 }
 function clearInheritedMadmaxRootForDisposableWorktreeLaunch(launchArgs, env = process.env) {
     if (!launchArgsRequestDisposableWorktree(launchArgs))
@@ -1890,6 +2010,7 @@ export async function main(args) {
         "sparkshell",
         "team",
         "ralph",
+        "ralplan",
         "ultragoal",
         "performance-goal",
         "session",
@@ -1909,10 +2030,11 @@ export async function main(args) {
     ]);
     const firstArg = args[0];
     const { command, launchArgs } = resolveCliInvocation(args);
-    const flags = new Set(args.filter((a) => a.startsWith("--")));
+    const { omxArgs } = splitOmxArgsAtEndOfOptions(args);
+    const flags = new Set(omxArgs.filter((arg) => arg.startsWith("--")));
     const options = {
         force: flags.has("--force"),
-        mergeAgents: flags.has("--merge-agents"),
+        mergeAgents: undefined,
         dryRun: flags.has("--dry-run"),
         verbose: flags.has("--verbose"),
         team: flags.has("--team"),
@@ -1921,11 +2043,19 @@ export async function main(args) {
         console.log(HELP);
         return;
     }
-    activateMadmaxIsolationIfNeeded(command, launchArgs, process.cwd(), process.env);
     try {
+        if (command === "session") {
+            await sessionCommand(args.slice(1));
+            return;
+        }
+        if (command === "resume" && launchArgs.some((arg) => arg === "--help" || arg === "-h")) {
+            console.log(RESUME_HELP);
+            return;
+        }
+        activateMadmaxIsolationIfNeeded(command, launchArgs, process.cwd(), process.env);
         switch (command) {
             case "launch":
-                if (launchArgs.includes("--hotswap")) {
+                if (launchArgsRequestAuthHotswap(launchArgs)) {
                     await launchWithAuthHotswap(launchArgs);
                 }
                 else {
@@ -1939,6 +2069,7 @@ export async function main(args) {
                 await setup({
                     force: options.force,
                     mergeAgents: options.mergeAgents,
+                    mergeAgentsPolicy: resolveSetupAgentsMergePolicyArg(args.slice(1)),
                     dryRun: options.dryRun,
                     verbose: options.verbose,
                     scope: resolveSetupScopeArg(args.slice(1)),
@@ -2035,15 +2166,15 @@ export async function main(args) {
             case "team":
                 await teamCommand(args.slice(1), options);
                 break;
-            case "session":
-                await sessionCommand(args.slice(1));
-                break;
             case "url":
                 await urlCommand(args.slice(1));
                 break;
             case "ralph":
                 await ralphCommand(args.slice(1));
                 break;
+            case "ralplan":
+                await ralplanCommand(args.slice(1));
+                break;
             case "ultragoal":
                 await ultragoalCommand(args.slice(1));
                 break;
@@ -2256,9 +2387,14 @@ async function reasoningCommand(args) {
         return;
     }
     if (!REASONING_MODE_SET.has(mode)) {
-        const guidance = isAmbiguousUnsupportedReasoningEffort(mode)
-            ? `${AMBIGUOUS_REASONING_MESSAGE}\n`
-            : "";
+        const unsupportedMode = isUnsupportedRootReasoningEffort(mode)
+            ? normalizeUnsupportedRootReasoningEffort(mode)
+            : undefined;
+        const guidance = unsupportedMode === "max"
+            ? `Reasoning mode "${mode}" is not supported by "omx reasoning".\nPer-agent "max" is configured with agentReasoning; direct -c model_reasoning_effort=... is passed to Codex and remains capability-dependent.\n`
+            : unsupportedMode === "ultra"
+                ? `Reasoning mode "${mode}" is not supported by OMX root or per-agent reasoning and is not an alias for "max".\nDirect -c model_reasoning_effort=... remains opaque Codex passthrough.\n`
+                : "";
         throw new Error(`${guidance}Invalid reasoning mode "${mode}". Expected one of: ${REASONING_MODES.join(", ")}.\n${REASONING_USAGE}`);
     }
     const { mkdir, readFile, writeFile } = await import("fs/promises");
@@ -2272,7 +2408,9 @@ async function reasoningCommand(args) {
 }
 export async function launchWithAuthHotswap(args) {
     const launchCwd = process.cwd();
-    const parsedWorktree = parseWorktreeMode(args);
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
+    const parsedWorktree = parseWorktreeMode(omxArgs);
+    const hotswapArgs = [...parsedWorktree.remainingArgs, ...suffix];
     let cwd = launchCwd;
     let worktreeDirty = false;
     let ensuredLaunchWorktree;
@@ -2326,7 +2464,7 @@ export async function launchWithAuthHotswap(args) {
     }
     const status = await runAuthHotswap({
         cwd,
-        argv: parsedWorktree.remainingArgs,
+        argv: hotswapArgs,
         lifecycle: {
             prepareCodexHomeForLaunch,
             preLaunch: (launchPath, sessionId, notifyTempContract, codexHomeOverride, enableAuthority) => preLaunch(launchPath, sessionId, notifyTempContract, codexHomeOverride, enableAuthority, worktreeDirty),
@@ -2366,14 +2504,16 @@ export async function launchWithHud(args) {
         }
     }
     const launchCwd = process.cwd();
-    const parsedWorktree = parseWorktreeMode(args);
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
+    const parsedWorktree = parseWorktreeMode(omxArgs);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
-    const explicitLaunchPolicy = resolveEffectiveLeaderLaunchPolicyOverride(notifyTempResult.passthroughArgs, process.env);
+    const passthroughArgs = [...notifyTempResult.passthroughArgs, ...suffix];
+    const explicitLaunchPolicy = resolveEffectiveLeaderLaunchPolicyOverride(passthroughArgs, process.env);
     const persistentCodexHomeForLaunch = resolveCodexHomeForLaunch(launchCwd, process.env);
     const { launchPolicy, effectiveExplicitLaunchPolicy } = resolveTmuxAwareLaunchPolicy(explicitLaunchPolicy, isNativeWindows());
     const enableNotifyFallbackAuthority = launchPolicy === "direct";
-    const workerSparkModel = resolveWorkerSparkModel(notifyTempResult.passthroughArgs, persistentCodexHomeForLaunch);
-    let normalizedArgs = normalizeCodexLaunchArgs(notifyTempResult.passthroughArgs);
+    const workerSparkModel = resolveWorkerSparkModel(passthroughArgs, persistentCodexHomeForLaunch);
+    let normalizedArgs = normalizeCodexLaunchArgs(passthroughArgs);
     let cwd = launchCwd;
     let worktreeDirty = false;
     let ensuredLaunchWorktree;
@@ -2402,7 +2542,7 @@ export async function launchWithHud(args) {
         }
     }
     const madmaxWorktreeRuntimeContext = captureMadmaxWorktreeRuntimeContext({
-        originalLaunchArgs: args,
+        originalLaunchArgs: omxArgs,
         worktreeEnabled: Boolean(parsedWorktree.mode.enabled && ensuredLaunchWorktree?.enabled),
         sourceCwd: launchCwd,
         worktreeCwd: ensuredLaunchWorktree?.enabled ? ensuredLaunchWorktree.worktreePath : undefined,
@@ -2457,7 +2597,15 @@ export async function launchWithHud(args) {
         await preLaunch(cwd, sessionId, notifyTempResult.contract, codexHomeOverride, enableNotifyFallbackAuthority, worktreeDirty);
     }
     catch (err) {
-        // preLaunch errors must NOT prevent Codex from starting
+        if (isSessionPointerLaunchAbort(err)) {
+            console.error(`[omx] session pointer launch aborted: ${err.code}`);
+            reportOrdinaryLaunchRootConflict(err, cwd, cwd === launchCwd && !parsedWorktree.mode.enabled && !isResumeCodexLaunch(normalizedArgs));
+            await cleanupRuntimeCodexHome(preparedCodexHome.runtimeCodexHomeForCleanup, projectLocalCodexHomeForCleanup).catch((cleanupErr) => {
+                console.error(`[omx] preLaunch abort cleanup warning: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+            });
+            throw err;
+        }
+        // preLaunch errors after pointer commit must not prevent Codex from starting.
         console.error(`[omx] preLaunch warning: ${err instanceof Error ? err.message : err}`);
     }
     // ── Phase 2: run ────────────────────────────────────────────────────────
@@ -2479,9 +2627,11 @@ export async function launchWithHud(args) {
 }
 export async function execWithOverlay(args) {
     const launchCwd = process.cwd();
-    const parsedWorktree = parseWorktreeMode(args);
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
+    const parsedWorktree = parseWorktreeMode(omxArgs);
     const notifyTempResult = resolveNotifyTempContract(parsedWorktree.remainingArgs, process.env);
-    const normalizedArgs = normalizeCodexLaunchArgs(notifyTempResult.passthroughArgs);
+    const passthroughArgs = [...notifyTempResult.passthroughArgs, ...suffix];
+    const normalizedArgs = normalizeCodexLaunchArgs(passthroughArgs);
     let cwd = launchCwd;
     let worktreeDirty = false;
     let ensuredLaunchWorktree;
@@ -2543,6 +2693,13 @@ export async function execWithOverlay(args) {
         await preLaunch(cwd, sessionId, notifyTempResult.contract, codexHomeOverride, true, worktreeDirty);
     }
     catch (err) {
+        if (isSessionPointerLaunchAbort(err)) {
+            console.error(`[omx] session pointer launch aborted: ${err.code}`);
+            await cleanupRuntimeCodexHome(preparedCodexHome.runtimeCodexHomeForCleanup, projectLocalCodexHomeForCleanup).catch((cleanupErr) => {
+                console.error(`[omx] preLaunch abort cleanup warning: ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+            });
+            throw err;
+        }
         console.error(`[omx] preLaunch warning: ${err instanceof Error ? err.message : err}`);
     }
     try {
@@ -2571,7 +2728,8 @@ export async function execWithOverlay(args) {
     }
 }
 export function normalizeCodexLaunchArgs(args) {
-    const parsed = parseWorktreeMode(args);
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
+    const parsed = parseWorktreeMode(omxArgs);
     const launchPolicyParsed = splitLeaderLaunchPolicyArgs(parsed.remainingArgs);
     const normalized = [];
     let wantsBypass = false;
@@ -2599,7 +2757,7 @@ export function normalizeCodexLaunchArgs(args) {
             continue;
         }
         if (arg === "--max" || arg === "--ultra") {
-            throw new Error(AMBIGUOUS_REASONING_MESSAGE);
+            throw unsupportedLaunchShorthandError(arg);
         }
         if (arg === SPARK_FLAG) {
             // Spark model is injected into worker env only (not the leader). Consume flag.
@@ -2618,7 +2776,7 @@ export function normalizeCodexLaunchArgs(args) {
     if (reasoningMode) {
         normalized.push(CONFIG_FLAG, `${REASONING_KEY}="${reasoningMode}"`);
     }
-    return normalized;
+    return [...normalized, ...suffix];
 }
 /**
  * Returns the spark model string if --spark or --madmax-spark appears in the
@@ -2627,6 +2785,8 @@ export function normalizeCodexLaunchArgs(args) {
  */
 export function resolveWorkerSparkModel(args, codexHomeOverride) {
     for (const arg of args) {
+        if (arg === "--")
+            break;
         if (arg === SPARK_FLAG || arg === MADMAX_SPARK_FLAG) {
             return resolveTeamLowComplexityDefaultModel(codexHomeOverride);
         }
@@ -2706,6 +2866,19 @@ export function resolveNativeSessionName(cwd, sessionId, env = process.env) {
     }
     return buildTmuxSessionName(cwd, sessionId);
 }
+async function resolvePreLaunchSessionPointerOptions() {
+    const ownerCandidate = normalizeSessionId(process.env.OMX_SESSION_ID);
+    if (!ownerCandidate)
+        return {};
+    const evidence = await probeActualTmuxInstanceEvidence(process.env.TMUX_PANE);
+    if (!tmuxEvidenceBindsCandidate(evidence, ownerCandidate))
+        return {};
+    return {
+        ownerAliasVerified: true,
+        ...(evidence.sessionName ? { tmuxSessionName: evidence.sessionName } : {}),
+        ...(evidence.paneTarget ? { tmuxPaneId: evidence.paneTarget } : {}),
+    };
+}
 function tagTmuxSessionWithInstance(sessionName, sessionId) {
     const target = sessionName.trim();
     const instanceId = sessionId.trim();
@@ -2754,12 +2927,14 @@ function buildNativeHookBaseContext(cwd, sessionId, normalizedEvent, extra = {})
 export function injectModelInstructionsBypassArgs(cwd, args, env = process.env, defaultFilePath) {
     if (!shouldBypassDefaultSystemPrompt(env))
         return [...args];
-    if (hasModelInstructionsOverride(args))
+    const { omxArgs, suffix } = splitOmxArgsAtEndOfOptions(args);
+    if (hasModelInstructionsOverride(omxArgs))
         return [...args];
     return [
-        ...args,
+        ...omxArgs,
         CONFIG_FLAG,
         buildModelInstructionsOverride(cwd, env, defaultFilePath),
+        ...suffix,
     ];
 }
 export function collectInheritableTeamWorkerArgs(codexArgs) {
@@ -2776,7 +2951,7 @@ export function resolveTeamWorkerLaunchArgsEnv(existingRaw, codexArgs, inheritLe
     });
     if (normalized.length === 0)
         return null;
-    return normalized.join(" ");
+    return serializeTeamWorkerLaunchArgs(normalized);
 }
 export { readTopLevelTomlString, upsertTopLevelTomlString } from "../utils/toml.js";
 function sanitizeTmuxToken(value) {
@@ -3192,11 +3367,22 @@ 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;`;
 }
 const SHELL_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DETACHED_SESSION_PANE_ENV_KEYS = new Set([
+    "TERM",
+    "TERM_PROGRAM",
+    "TERM_PROGRAM_VERSION",
+    "TMUX",
+    "TMUX_PANE",
+    "COLUMNS",
+    "LINES",
+]);
 export function serializeDetachedSessionParentEnv(env) {
     const lines = [];
     for (const key of Object.keys(env).sort()) {
         if (!SHELL_ENV_NAME_PATTERN.test(key))
             continue;
+        if (DETACHED_SESSION_PANE_ENV_KEYS.has(key))
+            continue;
         const value = env[key];
         if (typeof value !== "string")
             continue;
@@ -3763,8 +3949,8 @@ export async function reapPostLaunchOrphanedMcpProcesses(dependencies = {}) {
 /**
  * preLaunch: Prepare environment before Codex starts.
  * 1. Best-effort launch-safe orphan cleanup for detached OMX MCP processes
- * 2. Generate runtime overlay + write session-scoped model instructions file
- * 3. Write session.json
+ * 2. Establish the canonical session pointer
+ * 3. Generate session-scoped launch artifacts and start best-effort helpers
  *
  * Automatic broad stale-session cleanup remains disabled here. Only detached
  * OMX MCP processes without a live Codex ancestor are reaped so new launches
@@ -3785,7 +3971,9 @@ export async function preLaunch(cwd, sessionId, notifyTempContract, codexHomeOve
         logCliOperationFailure(err);
         // Non-fatal
     }
-    // 2. Generate runtime overlay + write session-scoped model instructions file
+    // 2. Establish the canonical pointer before any session-scoped launch artifact.
+    await writeSessionStart(cwd, sessionId, await resolvePreLaunchSessionPointerOptions());
+    // 3. Generate runtime overlay + write session-scoped model instructions file
     const orchestrationMode = await resolveSessionOrchestrationMode(cwd, sessionId);
     const overlay = await generateOverlay(cwd, sessionId, { orchestrationMode });
     const launchAppendix = await readLaunchAppendInstructions();
@@ -3798,11 +3986,10 @@ export async function preLaunch(cwd, sessionId, notifyTempContract, codexHomeOve
 ${launchAppendix}${dirtyWorktreeGuidance}`
         : `${overlay}${dirtyWorktreeGuidance}`;
     await writeSessionModelInstructionsFile(cwd, sessionId, sessionInstructions);
-    // 3. Write session state
+    // 4. Reset session metrics and tag the established session.
     await resetSessionMetrics(cwd, sessionId);
-    await writeSessionStart(cwd, sessionId);
     tagCurrentTmuxSessionWithInstance(sessionId);
-    // 4. Start notify fallback watcher (best effort)
+    // 5. Start notify fallback watcher (best effort)
     try {
         await startNotifyFallbackWatcher(cwd, { codexHomeOverride, enableAuthority: enableNotifyFallbackAuthority, sessionId });
     }
@@ -3810,7 +3997,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         logCliOperationFailure(err);
         // Non-fatal
     }
-    // 5. Start derived watcher (best effort, opt-in)
+    // 6. Start derived watcher (best effort, opt-in)
     try {
         await startHookDerivedWatcher(cwd);
     }
@@ -3818,7 +4005,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         logCliOperationFailure(err);
         // Non-fatal
     }
-    // 6. Emit temp notification startup summary + warnings, then send session-start lifecycle notification (best effort)
+    // 7. Emit temp notification startup summary + warnings, then send session-start lifecycle notification (best effort)
     try {
         if (notifyTempContract?.active) {
             process.env[OMX_NOTIFY_TEMP_CONTRACT_ENV] =
@@ -3847,7 +4034,7 @@ ${launchAppendix}${dirtyWorktreeGuidance}`
         logCliOperationFailure(err);
         // Non-fatal: notification failures must never block launch
     }
-    // 7. Dispatch native hook event (best effort)
+    // 8. Dispatch native hook event (best effort)
     try {
         await emitNativeHookEvent(cwd, "session-start", {
             session_id: sessionId,
@@ -4295,8 +4482,9 @@ export function buildTmuxShellCommand(command, args) {
 function encodePowerShellCommand(commandText) {
     return Buffer.from(commandText, "utf16le").toString("base64");
 }
-function isCodexVersionRequest(args) {
-    return args.some((arg) => CODEX_VERSION_FLAGS.has(arg));
+export function isCodexVersionRequest(args) {
+    const { omxArgs } = splitOmxArgsAtEndOfOptions(args);
+    return omxArgs.some((arg) => CODEX_VERSION_FLAGS.has(arg));
 }
 export function buildWindowsPromptCommand(command, args) {
     const invocation = [
@@ -4894,7 +5082,7 @@ async function flushNotifyFallbackOnce(cwd, options = {}) {
     spawnSync(process.execPath, [watcherScript, "--once", "--cwd", cwd, "--notify-script", notifyScript], {
         cwd,
         stdio: "ignore",
-        timeout: 3000,
+        timeout: 45_000,
         windowsHide: true,
         env: buildNotifyFallbackWatcherEnv(process.env, {
             codexHomeOverride: options.codexHomeOverride,
@@ -5037,6 +5225,7 @@ async function cancelModes(args = []) {
     const nowIso = new Date().toISOString();
     const force = args.includes("--force");
     try {
+        const writableScope = await resolveWritableStateScope(cwd);
         const loadStates = async (refs) => {
             const loaded = new Map();
             for (const ref of refs) {
@@ -5064,8 +5253,7 @@ async function cancelModes(args = []) {
             if (hasActiveWorkflowMode(runDirStates))
                 states = runDirStates;
         }
-        const currentSession = await readSessionState(cwd).catch(() => null);
-        const currentSessionId = typeof currentSession?.session_id === "string" ? currentSession.session_id.trim() : "";
+        const currentSessionId = writableScope.sessionId ?? "";
         const changed = new Set();
         const reported = new Set();
         const cancelMode = (mode, phase = "cancelled", reportIfWasActive = true) => {