oh-my-codex 0.20.0 → 0.20.2

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";
@@ -40,7 +41,7 @@ import { authCommand } from "./auth.js";
 import { missionCommand } from "./mission.js";
 import { 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, 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";
@@ -54,7 +55,8 @@ 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";
@@ -131,6 +133,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 +188,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
@@ -286,6 +292,7 @@ const NESTED_HELP_COMMANDS = new Set([
     "wiki",
     "mcp-serve",
     "ralph",
+    "ralplan",
     "ultragoal",
     "performance-goal",
     "resume",
@@ -296,6 +303,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) => {
@@ -1890,6 +1934,7 @@ export async function main(args) {
         "sparkshell",
         "team",
         "ralph",
+        "ralplan",
         "ultragoal",
         "performance-goal",
         "session",
@@ -1912,7 +1957,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"),
+        mergeAgents: undefined,
         dryRun: flags.has("--dry-run"),
         verbose: flags.has("--verbose"),
         team: flags.has("--team"),
@@ -1939,6 +1984,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)),
@@ -2044,6 +2090,9 @@ export async function main(args) {
             case "ralph":
                 await ralphCommand(args.slice(1));
                 break;
+            case "ralplan":
+                await ralplanCommand(args.slice(1));
+                break;
             case "ultragoal":
                 await ultragoalCommand(args.slice(1));
                 break;
@@ -2457,7 +2506,14 @@ 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}`);
+            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 ────────────────────────────────────────────────────────
@@ -2543,6 +2599,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 {
@@ -2706,6 +2769,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();
@@ -2776,7 +2852,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 +3268,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 +3850,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 +3872,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 +3887,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 +3898,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 +3906,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 +3935,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,
@@ -4894,7 +4982,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 +5125,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 +5153,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) => {