oh-my-codex 0.19.1 → 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";
@@ -42,10 +42,12 @@ 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";
@@ -70,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");
 }
@@ -118,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
@@ -223,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",
@@ -264,6 +271,7 @@ const NESTED_HELP_COMMANDS = new Set([
     "agents-init",
     "deepinit",
     "exec",
+    "capabilities",
     "mission",
     "imagegen",
     "hooks",
@@ -567,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);
 }
@@ -629,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") {
@@ -637,7 +650,7 @@ async function persistProjectLaunchRuntimeHistoryArtifacts(runtimeCodexHome, pro
             continue;
         }
         if (sourceStat.isFile()) {
-            await copyFile(source, destination);
+            await copyFilePreservingTimestamps(source, destination);
         }
     }
 }
@@ -666,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) {
@@ -684,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;
         }
@@ -696,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;
             }
@@ -707,7 +720,7 @@ async function mergeProjectLaunchRuntimeHistoryEntries(runtimeCodexHome, sourceC
             mergedHistorySourceRealpaths.add(sourceRealpath);
             continue;
         }
-        await copyFile(source, destination);
+        await copyFilePreservingTimestamps(source, destination);
         mergedHistorySourceRealpaths.add(sourceRealpath);
     }
 }
@@ -821,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 };
@@ -833,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) {
@@ -856,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: {
@@ -870,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: {
@@ -883,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: {
@@ -895,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) {
@@ -1469,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" ||
@@ -1835,6 +1870,7 @@ export async function main(args) {
         "exec",
         "mission",
         "imagegen",
+        "capabilities",
         "setup",
         "update",
         "list",
@@ -1967,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);
@@ -2217,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 });
@@ -2260,6 +2302,7 @@ export async function launchWithAuthHotswap(args) {
     }
     clearInheritedMadmaxRootForDisposableWorktreeLaunch(parsedWorktree.remainingArgs);
     applyDisposableWorktreeOmxRootForLaunch(ensuredLaunchWorktree);
+    applyWorktreeToolContextForLaunch(cwd, ensuredLaunchWorktree);
     try {
         await maybeCheckAndPromptUpdate(cwd);
     }
@@ -2367,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);
@@ -2467,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);
@@ -2553,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;
@@ -3616,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)) {
@@ -3651,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";
@@ -3850,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