oh-my-codex 0.19.0 → 0.20.0

package/dist/cli/index.js

@@ -5,9 +5,9 @@
 import { execFileSync, spawn } from "child_process";
 import { basename, dirname, join, posix, resolve, win32 } from "path";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "fs";
-import { copyFile, cp, lstat, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "fs/promises";
+import { copyFile, cp, lstat, mkdir, readFile, readdir, rm, stat, symlink, utimes, writeFile } from "fs/promises";
 import { constants as osConstants, homedir } from "os";
-import { createHash } from "crypto";
+import { createHash, randomUUID } from "crypto";
 import { setup, SETUP_MCP_MODES, SETUP_SCOPES, SETUP_TEAM_MODES, } from "./setup.js";
 import { uninstall } from "./uninstall.js";
 import { version } from "./version.js";
@@ -37,14 +37,17 @@ import { mcpServeCommand } from "./mcp-serve.js";
 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 { 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 { 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 { materializePackagedOmxPluginCache, packagedOmxPluginVersion, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, upsertLocalOmxPluginEnablement, } from "./plugin-marketplace.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";
 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";
@@ -69,9 +72,11 @@ 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 { parseWorktreeMode, planWorktreeTarget, ensureWorktree, } from "../team/worktree.js";
 import { ensureReusableNodeModules } from "../utils/repo-deps.js";
+import { resolveWorktreeToolContext, worktreeToolContextEnv } from "../utils/worktree-tool-context.js";
 import { OMX_NOTIFY_TEMP_CONTRACT_ENV, parseNotifyTempContractFromArgs, serializeNotifyTempContract, } from "../notifications/temp-contract.js";
 import { execInjectCommand } from "../exec/followup.js";
 import { imagegenCommand } from "../imagegen/continuation.js";
+import { capabilitiesCommand } from "./capabilities.js";
 export function resolveNotifyFallbackWatcherScript(pkgRoot = getPackageRoot()) {
     return resolveDistScript(pkgRoot, "notify-fallback-watcher.js");
 }
@@ -92,6 +97,8 @@ Usage:
   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 mission <file>
+                Run a prompt/checklist file sequentially through omx exec with durable summary
   omx imagegen continuation <session-id> --artifact <name>
                 Queue a Stop-hook continuation for built-in image generation turns
   omx setup     Install skills, prompts, CLI-first config, and scope-specific AGENTS.md
@@ -115,6 +122,8 @@ Usage:
   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)
   omx url       Passive URL reader (read <url> --json)
+  omx capabilities
+                Lock/check deterministic configured tool, skill, agent, and observation surfaces
   omx agents-init [path]
                 Bootstrap lightweight AGENTS.md files for a repo/subtree
   omx agents    Manage Codex native agent TOML files
@@ -220,9 +229,10 @@ 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"];
+const REASONING_MODES = CANONICAL_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.';
 const ALLOWED_SHELLS = new Set([
     "/bin/sh",
     "/bin/bash",
@@ -261,6 +271,8 @@ const NESTED_HELP_COMMANDS = new Set([
     "agents-init",
     "deepinit",
     "exec",
+    "capabilities",
+    "mission",
     "imagegen",
     "hooks",
     "list",
@@ -563,6 +575,11 @@ async function linkOrCopyCodexHomeEntry(source, destination) {
         await copyFile(source, destination);
     }
 }
+async function copyFilePreservingTimestamps(source, destination) {
+    await copyFile(source, destination);
+    const sourceStat = await stat(source);
+    await utimes(destination, sourceStat.atime, sourceStat.mtime);
+}
 function isCodexSqliteArtifact(entryName) {
     return /^(?:state|logs)_\d+\.sqlite(?:-(?:shm|wal))?$/.test(entryName);
 }
@@ -625,7 +642,7 @@ async function persistProjectLaunchRuntimeHistoryArtifacts(runtimeCodexHome, pro
             continue;
         const destination = join(projectCodexHome, entryName);
         if (sourceStat.isDirectory()) {
-            await cp(source, destination, { recursive: true, force: true, verbatimSymlinks: true });
+            await cp(source, destination, { recursive: true, force: true, preserveTimestamps: true, verbatimSymlinks: true });
             continue;
         }
         if (entryName === "history.jsonl" || entryName === "session_index.jsonl") {
@@ -633,7 +650,7 @@ async function persistProjectLaunchRuntimeHistoryArtifacts(runtimeCodexHome, pro
             continue;
         }
         if (sourceStat.isFile()) {
-            await copyFile(source, destination);
+            await copyFilePreservingTimestamps(source, destination);
         }
     }
 }
@@ -662,10 +679,10 @@ async function materializeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, s
         await rm(destination, { recursive: true, force: true });
         const sourceStat = await lstat(source);
         if (sourceStat.isDirectory()) {
-            await cp(source, destination, { recursive: true, force: true, dereference: true });
+            await cp(source, destination, { recursive: true, force: true, dereference: true, preserveTimestamps: true });
             continue;
         }
-        await copyFile(source, destination);
+        await copyFilePreservingTimestamps(source, destination);
     }
 }
 async function mergeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, sourceCodexHome, mergedHistorySourceRealpaths) {
@@ -680,7 +697,7 @@ async function mergeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, sourceC
         const sourceStat = await stat(source);
         if (sourceStat.isDirectory()) {
             await mkdir(destination, { recursive: true });
-            await cp(source, destination, { recursive: true, force: true, dereference: true });
+            await cp(source, destination, { recursive: true, force: true, dereference: true, preserveTimestamps: true });
             mergedHistorySourceRealpaths.add(sourceRealpath);
             continue;
         }
@@ -692,7 +709,7 @@ async function mergeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, sourceC
             const destinationStat = await stat(destination);
             if (!destinationStat.isFile()) {
                 await rm(destination, { recursive: true, force: true });
-                await copyFile(source, destination);
+                await copyFilePreservingTimestamps(source, destination);
                 mergedHistorySourceRealpaths.add(sourceRealpath);
                 continue;
             }
@@ -703,7 +720,7 @@ async function mergeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, sourceC
             mergedHistorySourceRealpaths.add(sourceRealpath);
             continue;
         }
-        await copyFile(source, destination);
+        await copyFilePreservingTimestamps(source, destination);
         mergedHistorySourceRealpaths.add(sourceRealpath);
     }
 }
@@ -817,10 +834,24 @@ export function parseResumeCodexHomeSelection(args) {
         projectOnly,
     };
 }
-export async function preflightResumeOmxPluginState(codexHomeDir, pkgRoot = getPackageRoot()) {
+async function shouldPreflightResumeOmxPluginState(selectedCodexHomeDir, existingConfig, options) {
+    if (hasLocalOmxPluginEnablement(existingConfig))
+        return true;
+    if (options.projectRoot &&
+        readPersistedSetupPreferences(options.projectRoot)?.installMode === "plugin") {
+        return true;
+    }
+    return (await discoverOmxPluginCacheDirs(selectedCodexHomeDir)).length > 0;
+}
+export async function preflightResumeOmxPluginState(codexHomeDir, pkgRoot = getPackageRoot(), options = {}) {
     const selectedCodexHomeDir = codexHomeDir && codexHomeDir.trim() !== ""
         ? codexHomeDir
         : join(homedir(), ".codex");
+    const configPath = join(selectedCodexHomeDir, "config.toml");
+    const existingConfig = existsSync(configPath) ? await readFile(configPath, "utf-8") : "";
+    if (!(await shouldPreflightResumeOmxPluginState(selectedCodexHomeDir, existingConfig, options))) {
+        return { status: "skipped", prunedStaleDirs: [], configUpdated: false };
+    }
     const packagedMarketplace = await resolvePackagedOmxMarketplace(pkgRoot);
     if (!packagedMarketplace) {
         return { status: "unavailable", prunedStaleDirs: [], configUpdated: false };
@@ -829,8 +860,6 @@ export async function preflightResumeOmxPluginState(codexHomeDir, pkgRoot = getP
     const version = materialized.version ?? (await packagedOmxPluginVersion(packagedMarketplace)) ?? undefined;
     const currentCacheDir = materialized.cacheDir ?? (version ? join(selectedCodexHomeDir, "plugins", "cache", "oh-my-codex-local", "oh-my-codex", version) : undefined);
     const prunedStaleDirs = [];
-    const configPath = join(selectedCodexHomeDir, "config.toml");
-    const existingConfig = existsSync(configPath) ? await readFile(configPath, "utf-8") : "";
     const nextConfig = upsertLocalOmxMarketplaceRegistration(upsertLocalOmxPluginEnablement(existingConfig), pkgRoot);
     const configUpdated = nextConfig !== existingConfig;
     if (configUpdated) {
@@ -852,7 +881,7 @@ async function prepareResumeCodexHomeForLaunch(cwd, sessionId, args, env = proce
     const selection = parseResumeCodexHomeSelection(args);
     if (selection.explicitCodexHome) {
         const codexHomeOverride = resolve(selection.explicitCodexHome);
-        await preflightResumeOmxPluginState(codexHomeOverride);
+        await preflightResumeOmxPluginState(codexHomeOverride, getPackageRoot(), { projectRoot: cwd });
         return {
             args: selection.args,
             prepared: {
@@ -866,7 +895,7 @@ async function prepareResumeCodexHomeForLaunch(cwd, sessionId, args, env = proce
             const emptyRuntimeCodexHome = runtimeCodexHomePath(cwd, sessionId);
             await rm(emptyRuntimeCodexHome, { recursive: true, force: true });
             await mkdir(join(emptyRuntimeCodexHome, "sessions"), { recursive: true });
-            await preflightResumeOmxPluginState(emptyRuntimeCodexHome);
+            await preflightResumeOmxPluginState(emptyRuntimeCodexHome, getPackageRoot(), { projectRoot: cwd });
             return {
                 args: selection.args,
                 prepared: {
@@ -879,7 +908,7 @@ async function prepareResumeCodexHomeForLaunch(cwd, sessionId, args, env = proce
             includeHistoryArtifacts: true,
             extraHistoryCodexHomes: projectHomes.slice(1).map((home) => home.path),
         });
-        await preflightResumeOmxPluginState(runtimeCodexHome);
+        await preflightResumeOmxPluginState(runtimeCodexHome, getPackageRoot(), { projectRoot: cwd });
         return {
             args: selection.args,
             prepared: {
@@ -891,7 +920,7 @@ async function prepareResumeCodexHomeForLaunch(cwd, sessionId, args, env = proce
         includeHistoryArtifacts: true,
         extraHistoryCodexHomes: projectHomes.map((home) => home.path),
     });
-    await preflightResumeOmxPluginState(prepared.codexHomeOverride);
+    await preflightResumeOmxPluginState(prepared.codexHomeOverride, getPackageRoot(), { projectRoot: cwd });
     return { args: selection.args, prepared };
 }
 export async function persistProjectLaunchRuntimeProjectTrustState(runtimeCodexHome, projectCodexHome) {
@@ -1465,6 +1494,16 @@ function applyDisposableWorktreeOmxRootForLaunch(ensuredWorktree, env = process.
         return;
     env.OMX_ROOT = omxRootOverride;
 }
+function applyWorktreeToolContextForLaunch(cwd, ensuredWorktree, env = process.env) {
+    const context = resolveWorktreeToolContext({
+        cwd,
+        scope: "launch",
+        repoRoot: ensuredWorktree?.enabled ? ensuredWorktree.repoRoot : undefined,
+        worktreeRoot: ensuredWorktree?.enabled ? ensuredWorktree.worktreePath : cwd,
+        env,
+    });
+    Object.assign(env, worktreeToolContextEnv(context));
+}
 function launchArgRequestsDisposableWorktree(arg) {
     return arg === "--worktree" ||
         arg === "-w" ||
@@ -1829,7 +1868,9 @@ export async function main(args) {
     const knownCommands = new Set([
         "launch",
         "exec",
+        "mission",
         "imagegen",
+        "capabilities",
         "setup",
         "update",
         "list",
@@ -1962,6 +2003,9 @@ export async function main(args) {
             case "api":
                 await apiCommand(args.slice(1));
                 break;
+            case "capabilities":
+                await capabilitiesCommand(args.slice(1));
+                break;
             case "exec":
                 if (launchArgs[0] === "inject") {
                     await execInjectCommand(launchArgs);
@@ -1970,6 +2014,18 @@ export async function main(args) {
                     await execWithOverlay(launchArgs);
                 }
                 break;
+            case "mission":
+                await missionCommand(args.slice(1), {
+                    runTask: async (prompt, codexArgs) => {
+                        const priorExitCode = process.exitCode;
+                        process.exitCode = undefined;
+                        await execWithOverlay([...codexArgs, prompt]);
+                        const exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
+                        process.exitCode = priorExitCode;
+                        return exitCode;
+                    },
+                });
+                break;
             case "imagegen":
                 await imagegenCommand(args.slice(1));
                 break;
@@ -2092,6 +2148,11 @@ async function readStaleCurrentAutopilotStatus(cwd) {
         return null;
     return { phase: phase ?? "active" };
 }
+function formatDurableUltragoalStatusForCli(status) {
+    return status === "failed"
+        ? "ultragoal: FAILED (phase: failed)"
+        : `ultragoal: ACTIVE (phase: ${status})`;
+}
 async function showStatus() {
     const { readFile } = await import("fs/promises");
     const cwd = process.cwd();
@@ -2128,7 +2189,7 @@ async function showStatus() {
         const ultragoalState = await readUltragoalState(cwd).catch(() => null);
         if (states.length === 0) {
             if (ultragoalState?.active) {
-                console.log(`ultragoal: ACTIVE (phase: ${ultragoalState.status})`);
+                console.log(formatDurableUltragoalStatusForCli(ultragoalState.status ?? "active"));
                 return;
             }
             const staleAutopilot = await readStaleCurrentAutopilotStatus(cwd);
@@ -2139,6 +2200,7 @@ async function showStatus() {
             console.log("No active modes.");
             return;
         }
+        let hasAuthoritativeActiveUltragoalMode = false;
         for (const path of states) {
             const content = await readFile(path, "utf-8");
             let state;
@@ -2151,12 +2213,15 @@ async function showStatus() {
             }
             const file = basename(path);
             const mode = file.replace("-state.json", "");
-            if (mode === "ultragoal" && ultragoalState?.active)
+            if (mode === "ultragoal" && state.active === true) {
+                hasAuthoritativeActiveUltragoalMode = true;
+            }
+            if (mode === "ultragoal" && ultragoalState?.active && state.active !== true)
                 continue;
             console.log(`${mode}: ${state.active === true ? "ACTIVE" : "inactive"} (phase: ${String(state.current_phase || "n/a")})`);
         }
-        if (ultragoalState?.active) {
-            console.log(`ultragoal: ACTIVE (phase: ${ultragoalState.status})`);
+        if (ultragoalState?.active && !hasAuthoritativeActiveUltragoalMode) {
+            console.log(formatDurableUltragoalStatusForCli(ultragoalState.status ?? "active"));
         }
         if (!hasAuthoritativeActiveMode && !ultragoalState?.active) {
             const staleAutopilot = await readStaleCurrentAutopilotStatus(cwd);
@@ -2191,7 +2256,10 @@ async function reasoningCommand(args) {
         return;
     }
     if (!REASONING_MODE_SET.has(mode)) {
-        throw new Error(`Invalid reasoning mode "${mode}". Expected one of: ${REASONING_MODES.join(", ")}.\n${REASONING_USAGE}`);
+        const guidance = isAmbiguousUnsupportedReasoningEffort(mode)
+            ? `${AMBIGUOUS_REASONING_MESSAGE}\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");
     await mkdir(dirname(configPath), { recursive: true });
@@ -2234,6 +2302,7 @@ export async function launchWithAuthHotswap(args) {
     }
     clearInheritedMadmaxRootForDisposableWorktreeLaunch(parsedWorktree.remainingArgs);
     applyDisposableWorktreeOmxRootForLaunch(ensuredLaunchWorktree);
+    applyWorktreeToolContextForLaunch(cwd, ensuredLaunchWorktree);
     try {
         await maybeCheckAndPromptUpdate(cwd);
     }
@@ -2341,6 +2410,7 @@ export async function launchWithHud(args) {
     });
     clearInheritedMadmaxRootForDisposableWorktreeLaunch(parsedWorktree.remainingArgs);
     applyDisposableWorktreeOmxRootForLaunch(ensuredLaunchWorktree);
+    applyWorktreeToolContextForLaunch(cwd, ensuredLaunchWorktree);
     const sessionId = `omx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
         await maybeCheckAndPromptUpdate(cwd);
@@ -2441,6 +2511,7 @@ export async function execWithOverlay(args) {
     }
     clearInheritedMadmaxRootForDisposableWorktreeLaunch(parsedWorktree.remainingArgs);
     applyDisposableWorktreeOmxRootForLaunch(ensuredLaunchWorktree);
+    applyWorktreeToolContextForLaunch(cwd, ensuredLaunchWorktree);
     const sessionId = `omx-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
         await maybeCheckAndPromptUpdate(cwd);
@@ -2527,6 +2598,9 @@ export function normalizeCodexLaunchArgs(args) {
             reasoningMode = "xhigh";
             continue;
         }
+        if (arg === "--max" || arg === "--ultra") {
+            throw new Error(AMBIGUOUS_REASONING_MESSAGE);
+        }
         if (arg === SPARK_FLAG) {
             // Spark model is injected into worker env only (not the leader). Consume flag.
             continue;
@@ -3590,6 +3664,14 @@ export async function cleanupPostLaunchModeStateFiles(cwd, sessionId, dependenci
                 && Array.isArray(result.state.active_skills)
                 && result.state.active_skills.length > 0;
             if (result.state.active !== true && !skillStateStillVisible) {
+                const completedAt = now().toISOString();
+                const normalized = mode === SKILL_ACTIVE_STATE_MODE
+                    ? { state: result.state, changed: false }
+                    : normalizeTerminalWorkflowState(result.state, { mode, nowIso: completedAt });
+                if (normalized.changed) {
+                    result.state = normalized.state;
+                    await writeFile(path, JSON.stringify(result.state, null, 2));
+                }
                 if (mode === "ralph") {
                     const completedAt = now().toISOString();
                     if (markRalphCompletionAuditBlockedForPostLaunch(result.state, cwd, completedAt)) {
@@ -3625,6 +3707,7 @@ export async function cleanupPostLaunchModeStateFiles(cwd, sessionId, dependenci
                 result.state.active = false;
                 result.state.current_phase = "cancelled";
                 result.state.completed_at = completedAt;
+                result.state = normalizeTerminalWorkflowState(result.state, { mode, nowIso: completedAt }).state;
                 if (mode === "ralph") {
                     result.state.interrupted_at = completedAt;
                     result.state.stop_reason = cleanPostLaunchString(result.state.stop_reason) || "session_exit";
@@ -3824,6 +3907,7 @@ function runCodex(cwd, args, sessionId, workerDefaultModel, codexHomeOverride, s
     }, omxBin);
     const codexEnvWithSession = {
         ...codexBaseEnv,
+        OMX_CODEX_LAUNCH_ID: randomUUID(),
         ...buildHudRuntimeEnv({ sessionId }).env,
     };
     const codexEnv = workerLaunchArgs