oh-my-codex 0.18.11 → 0.18.13

package/dist/cli/setup.js

@@ -8,9 +8,11 @@ import { existsSync } from "fs";
 import { spawnSync } from "child_process";
 import { createInterface } from "readline/promises";
 import { homedir } from "os";
+import TOML from "@iarna/toml";
+import { createHash } from "crypto";
 import { codexHome, codexConfigPath, codexPromptsDir, codexAgentsDir, userSkillsDir, omxStateDir, detectLegacySkillRootOverlap, omxPlansDir, omxLogsDir, } from "../utils/paths.js";
-import { buildMergedConfig, getRootModelName, getRootTomlArray, hasLegacyOmxTeamRunTable, isOmxManagedNotifyCommand, sanitizePreviousNotifyCommand, stripExistingOmxBlocks, stripExistingSharedMcpRegistryBlock, mergeSharedMcpRegistryBlock, stripOmxEnvSettings, stripOmxFeatureFlags, stripOmxSeededBehavioralDefaults, upsertPluginModeRuntimeFeatureFlags, upsertManagedCodexHookTrustState, stripManagedCodexHookTrustState, OMX_PLUGIN_DEVELOPER_INSTRUCTIONS, hasFirstPartyOmxMcpRegistrations, extractFirstPartyOmxMcpSections, stripFirstPartyOmxMcpSections, } from "../config/generator.js";
-import { buildManagedCodexHookTrustState, buildManagedCodexNativeHookWindowsShimContent, buildManagedCodexNativeHookWindowsShimPath, mergeManagedCodexHooksConfig, removeManagedCodexHooks, } from "../config/codex-hooks.js";
+import { buildMergedConfig, getRootModelName, getRootTomlArray, hasLegacyOmxTeamRunTable, isOmxManagedNotifyCommand, sanitizePreviousNotifyCommand, stripExistingOmxBlocks, stripExistingSharedMcpRegistryBlock, mergeSharedMcpRegistryBlock, stripOmxEnvSettings, stripOmxFeatureFlags, stripOmxSeededBehavioralDefaults, upsertPluginModeRuntimeFeatureFlags, upsertManagedCodexHookTrustState, stripManagedCodexHookTrustState, OMX_DEVELOPER_INSTRUCTIONS, OMX_PLUGIN_DEVELOPER_INSTRUCTIONS, hasFirstPartyOmxMcpRegistrations, extractFirstPartyOmxMcpSections, stripFirstPartyOmxMcpSections, } from "../config/generator.js";
+import { buildManagedCodexHookTrustState, buildManagedCodexNativeHookWindowsShimContent, buildManagedCodexNativeHookWindowsShimPath, mergeManagedCodexHooksConfig, extractCodexHooksJsonTrustState, removeManagedCodexHooks, } from "../config/codex-hooks.js";
 import { getLegacyUnifiedMcpRegistryCandidate, getUnifiedMcpRegistryCandidates, loadUnifiedMcpRegistry, planClaudeCodeMcpSettingsSync, } from "../config/mcp-registry.js";
 import { generateAgentToml } from "../agents/native-config.js";
 import { AGENT_DEFINITIONS } from "../agents/definitions.js";
@@ -62,6 +64,7 @@ const PROJECT_GITIGNORE_ENTRIES = [
 const LEGACY_PROJECT_GITIGNORE_ENTRIES = [".codex/"];
 const SETUP_ONLY_INSTALLABLE_SKILLS = new Set(["wiki"]);
 const DEFAULT_SETUP_MCP_MODE = "none";
+const SKIP_NATIVE_AGENT_REFRESH_ENV = "OMX_SKIP_NATIVE_AGENT_REFRESH";
 const HARD_DEPRECATED_SKILL_NAMES = new Set(["web-clone"]);
 const TEAM_MODE_SKILL_NAMES = new Set(["team", "worker"]);
 const TEAM_MODE_PROMPT_NAMES = new Set(["team-executor"]);
@@ -192,6 +195,68 @@ function getBackupContext(scope, projectRoot) {
         baseRoot: homedir(),
     };
 }
+function escapeTomlBasicString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function renderHooksJsonTrustStateToml(content) {
+    const trustState = extractCodexHooksJsonTrustState(content);
+    return Object.entries(trustState)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([key, state]) => [
+        `[hooks.state."${escapeTomlBasicString(key)}"]`,
+        `trusted_hash = "${escapeTomlBasicString(state.trusted_hash)}"`,
+        ...(typeof state.enabled === "boolean" ? [`enabled = ${state.enabled}`] : []),
+        "",
+    ])
+        .join("\n")
+        .trimEnd();
+}
+function existingHooksStateKeys(config) {
+    try {
+        const parsed = TOML.parse(config);
+        return new Set(Object.keys(parsed.hooks?.state ?? {}));
+    }
+    catch {
+        return new Set();
+    }
+}
+function appendHooksJsonTrustStateToConfig(config, hooksContent) {
+    const existingKeys = existingHooksStateKeys(config);
+    const trustState = extractCodexHooksJsonTrustState(hooksContent);
+    const migratableContent = JSON.stringify({
+        state: Object.fromEntries(Object.entries(trustState).filter(([key]) => !existingKeys.has(key))),
+    });
+    const trustToml = renderHooksJsonTrustStateToml(migratableContent);
+    if (!trustToml)
+        return config;
+    const base = config.trimEnd();
+    return [
+        base,
+        base ? "" : null,
+        "# Migrated from legacy hooks.json state; kept in Codex config.toml because Codex 0.140 rejects top-level hooks.json state.",
+        trustToml,
+        "",
+    ].filter((line) => line !== null).join("\n");
+}
+async function migrateLegacyHooksJsonTrustStateToConfig(configPath, hooksContent, backupContext, summary, options) {
+    const existingConfig = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const nextConfig = appendHooksJsonTrustStateToConfig(existingConfig, hooksContent);
+    if (nextConfig === existingConfig)
+        return;
+    if (await ensureBackup(configPath, existsSync(configPath), backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, nextConfig);
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would migrate" : "migrated"} legacy hooks.json trust state to ${configPath}`);
+    }
+}
 async function ensureBackup(destinationPath, contentChanged, backupContext, options) {
     if (!contentChanged || !existsSync(destinationPath))
         return false;
@@ -517,41 +582,55 @@ async function promptForAgentsOverwrite(destinationPath) {
 }
 async function promptForPluginAgentsMdDefault(destinationPath) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        return false;
+        return !existsSync(destinationPath);
     }
     const rl = createInterface({
         input: process.stdin,
         output: process.stdout,
     });
     try {
-        const answer = (await rl.question(`Plugin mode: install OMX AGENTS.md defaults at "${destinationPath}"? [y/N]: `))
+        const answer = (await rl.question(`Plugin mode: install/update OMX AGENTS.md defaults at "${destinationPath}"? [Y/n]: `))
             .trim()
             .toLowerCase();
-        return answer === "y" || answer === "yes";
+        return answer === "" || answer === "y" || answer === "yes";
     }
     finally {
         rl.close();
     }
 }
-async function promptForPluginDeveloperInstructionsDefault(configPath) {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        return false;
+const LEGACY_PLUGIN_DEVELOPER_INSTRUCTIONS = "You have oh-my-codex installed through Codex plugin mode. AGENTS.md is the orchestration brain and main control surface. Follow AGENTS.md for skill/keyword routing and $name workflow invocation. When spawning native subagents, set `agent_type` to an installed role and never omit it for OMX work. Registered Codex plugin marketplace surfaces supply OMX workflows and plugin-scoped companion resources when the plugin is installed; native agent roles are installed as setup-owned Codex agent TOML files in plugin mode so agent_type routing works. User-installed skills may still live under ~/.codex/skills. Use outcome-first, concise progress updates: state the target result, constraints, validation evidence, and stop condition before adding process detail.";
+function normalizeDeveloperInstructionsText(value) {
+    return value.replace(/\r\n/g, "\n").trim();
+}
+function classifyPluginDeveloperInstructions(value) {
+    if (typeof value !== "string")
+        return "custom";
+    const normalized = normalizeDeveloperInstructionsText(value);
+    if (normalized ===
+        normalizeDeveloperInstructionsText(OMX_PLUGIN_DEVELOPER_INSTRUCTIONS)) {
+        return "current";
     }
-    const rl = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
+    if (normalized ===
+        normalizeDeveloperInstructionsText(LEGACY_PLUGIN_DEVELOPER_INSTRUCTIONS)) {
+        return "current";
+    }
+    if (normalized === normalizeDeveloperInstructionsText(OMX_DEVELOPER_INSTRUCTIONS)) {
+        return "historical";
+    }
+    return "custom";
+}
+function readRootDeveloperInstructions(config) {
+    if (!rootHasTomlKey(config, "developer_instructions"))
+        return undefined;
     try {
-        const answer = (await rl.question(`Plugin mode: add OMX developer_instructions defaults to "${configPath}"? [y/N]: `))
-            .trim()
-            .toLowerCase();
-        return answer === "y" || answer === "yes";
+        const parsed = TOML.parse(config);
+        return parsed.developer_instructions;
     }
-    finally {
-        rl.close();
+    catch {
+        return Symbol.for("omx.invalid-developer-instructions");
     }
 }
-async function promptForPluginDeveloperInstructionsOverwrite(configPath) {
+async function askYesNoDefaultYes(question) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         return false;
     }
@@ -560,15 +639,99 @@ async function promptForPluginDeveloperInstructionsOverwrite(configPath) {
         output: process.stdout,
     });
     try {
-        const answer = (await rl.question(`Plugin mode: overwrite existing developer_instructions in "${configPath}" with OMX defaults? [y/N]: `))
-            .trim()
-            .toLowerCase();
-        return answer === "y" || answer === "yes";
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
     }
     finally {
         rl.close();
     }
 }
+function legacyPluginDeveloperInstructionsDecision(choice, state = "missing") {
+    if (choice === "refresh" || (choice === true && state === "historical")) {
+        return {
+            action: "update",
+            state: "historical",
+            reason: choice === "refresh"
+                ? "legacy explicit refresh policy"
+                : "legacy boolean approval refreshed historical developer_instructions",
+        };
+    }
+    if (choice === true || choice === "preserve-or-add") {
+        return {
+            action: "add",
+            state: "missing",
+            reason: "legacy explicit add-if-missing policy",
+        };
+    }
+    return {
+        action: "preserve",
+        state,
+        reason: "legacy explicit skip policy",
+    };
+}
+async function resolvePluginDeveloperInstructionsDecision(configPath, options) {
+    const existing = existsSync(configPath)
+        ? await readFile(configPath, "utf-8")
+        : "";
+    const value = readRootDeveloperInstructions(existing);
+    if (value === undefined) {
+        if (options.pluginDeveloperInstructionsPrompt) {
+            return legacyPluginDeveloperInstructionsDecision(await options.pluginDeveloperInstructionsPrompt(configPath), "missing");
+        }
+        const install = await askYesNoDefaultYes(`Plugin mode: add OMX developer_instructions bootstrap to "${configPath}"? [Y/n]: `);
+        return install
+            ? {
+                action: "add",
+                state: "missing",
+                reason: "missing developer_instructions",
+            }
+            : {
+                action: "preserve",
+                state: "missing",
+                reason: "missing developer_instructions skipped",
+            };
+    }
+    const state = classifyPluginDeveloperInstructions(value);
+    if (state === "current") {
+        return {
+            action: "preserve",
+            state,
+            reason: "current OMX developer_instructions already installed",
+        };
+    }
+    if (state === "historical") {
+        const updateDecision = options.pluginDeveloperInstructionsPrompt
+            ? legacyPluginDeveloperInstructionsDecision(await options.pluginDeveloperInstructionsPrompt(configPath), state)
+            : await askYesNoDefaultYes(`Plugin mode: update OMX developer_instructions bootstrap at "${configPath}"? [Y/n]: `)
+                ? {
+                    action: "update",
+                    state,
+                    reason: "recognized historical OMX developer_instructions",
+                }
+                : {
+                    action: "preserve",
+                    state,
+                    reason: "historical OMX developer_instructions preserved",
+                };
+        const update = updateDecision.action === "update";
+        return update
+            ? {
+                action: "update",
+                state,
+                reason: "recognized historical OMX developer_instructions",
+            }
+            : {
+                action: "preserve",
+                state,
+                reason: "historical OMX developer_instructions preserved",
+            };
+    }
+    return {
+        action: "preserve",
+        state: "custom",
+        reason: "custom or unknown developer_instructions preserved",
+    };
+}
 async function resolveSetupScope(projectRoot, requestedScope, persistedReviewDecision = "keep", persistedPreferences, setupScopePrompt) {
     if (requestedScope) {
         return { scope: requestedScope, source: "cli" };
@@ -898,7 +1061,15 @@ async function cleanupPluginModeLegacyPrompts(srcDir, dstDir, backupContext, opt
     await removeEmptyDirectoryIfPresent(dstDir, options);
     return summary;
 }
-function stripPluginModeLegacyRootDefaults(config) {
+function removeRootTomlKey(config, key) {
+    const range = findRootTomlKeyRange(config, key);
+    if (!range)
+        return config;
+    const before = config.slice(0, range.start);
+    const after = config.slice(range.end).replace(/^\r?\n?/, "\n");
+    return `${before}${after}`;
+}
+function stripPluginModeLegacyRootDefaults(config, developerInstructionsDecision) {
     const lines = config.split(/\r?\n/);
     const firstTableIndex = lines.findIndex((line) => /^\s*\[/.test(line));
     const boundary = firstTableIndex >= 0 ? firstTableIndex : lines.length;
@@ -918,14 +1089,15 @@ function stripPluginModeLegacyRootDefaults(config) {
             /^\s*model_reasoning_effort\s*=\s*"medium"\s*$/.test(line)) {
             continue;
         }
-        if (index < boundary &&
-            /^\s*developer_instructions\s*=/.test(line) &&
-            line.includes("You have oh-my-codex installed.")) {
-            continue;
-        }
         result.push(line);
     }
-    return result.join("\n").replace(/\n{3,}/g, "\n\n");
+    let nextConfig = result.join("\n").replace(/\n{3,}/g, "\n\n");
+    if (developerInstructionsDecision.action === "update" &&
+        developerInstructionsDecision.state === "historical" &&
+        classifyPluginDeveloperInstructions(readRootDeveloperInstructions(nextConfig)) === "historical") {
+        nextConfig = removeRootTomlKey(nextConfig, "developer_instructions");
+    }
+    return nextConfig;
 }
 function rootHasTomlKey(config, key) {
     const lines = config.split(/\r?\n/);
@@ -936,18 +1108,62 @@ function rootHasTomlKey(config, key) {
     return lines.slice(0, boundary).some((line) => pattern.test(line));
 }
 function replaceRootTomlKey(config, key, line) {
-    const lines = config.trimEnd().split(/\r?\n/);
-    const firstTableIndex = lines.findIndex((entry) => /^\s*\[/.test(entry));
-    const boundary = firstTableIndex < 0 ? lines.length : firstTableIndex;
+    const range = findRootTomlKeyRange(config, key);
+    if (!range)
+        return insertRootTomlKey(config, line);
+    const before = config.slice(0, range.start);
+    const after = config.slice(range.end).replace(/^\r?\n?/, "\n");
+    return `${before}${line}${after}`.replace(/\n?$/, "\n");
+}
+function findRootTomlKeyRange(config, key) {
     const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pattern = new RegExp(`^\\s*${escapedKey}\\s*=`);
-    for (let i = 0; i < boundary; i++) {
-        if (pattern.test(lines[i])) {
-            lines[i] = line;
-            return lines.join("\n") + "\n";
+    const keyPattern = new RegExp(`^\\s*${escapedKey}\\s*=`);
+    const nextRootKeyPattern = /^\s*[A-Za-z0-9_-]+\s*=/;
+    const tablePattern = /^\s*\[/;
+    const linePattern = /.*(?:\r?\n|$)/g;
+    let match;
+    let found = null;
+    let inMultiline = false;
+    let multilineDelimiter = null;
+    while ((match = linePattern.exec(config)) && match[0] !== "") {
+        const line = match[0];
+        const lineStart = match.index;
+        const lineEnd = lineStart + line.length;
+        const trimmedLine = line.replace(/\r?\n$/, "");
+        if (!found) {
+            if (tablePattern.test(trimmedLine))
+                return null;
+            if (keyPattern.test(trimmedLine)) {
+                found = { start: lineStart, end: lineEnd };
+                const valuePart = trimmedLine.slice(trimmedLine.indexOf("=") + 1);
+                const delimiter = valuePart.includes('"""')
+                    ? '"""'
+                    : valuePart.includes("'''")
+                        ? "'''"
+                        : null;
+                if (delimiter && valuePart.split(delimiter).length - 1 === 1) {
+                    inMultiline = true;
+                    multilineDelimiter = delimiter;
+                }
+                else {
+                    return found;
+                }
+            }
+            continue;
+        }
+        found.end = lineEnd;
+        if (inMultiline && multilineDelimiter) {
+            if (trimmedLine.includes(multilineDelimiter)) {
+                return found;
+            }
+            continue;
+        }
+        if (tablePattern.test(trimmedLine) || nextRootKeyPattern.test(trimmedLine)) {
+            found.end = lineStart;
+            return found;
         }
     }
-    return insertRootTomlKey(config, line);
+    return found;
 }
 function insertRootTomlKey(config, line) {
     const lines = config.trimEnd().split(/\r?\n/);
@@ -1041,6 +1257,7 @@ async function applyPluginModeHooksConfig(configPath, hooksPath, pkgRoot, codexH
     const existingHooksContent = existsSync(hooksPath)
         ? await readFile(hooksPath, "utf-8")
         : null;
+    await migrateLegacyHooksJsonTrustStateToConfig(configPath, existingHooksContent, backupContext, summary, options);
     if (options.pluginScopedHooks) {
         await cleanupPluginModeManagedHooksJson(existingHooksContent, hooksPath, backupContext, summary, options);
     }
@@ -1060,19 +1277,21 @@ async function applyPluginDeveloperInstructionsDefault(configPath, backupContext
     const existing = existsSync(configPath)
         ? await readFile(configPath, "utf-8")
         : "";
+    if (options.decision.action === "preserve") {
+        summary.skipped += 1;
+        if (options.verbose) {
+            console.log(`  preserved plugin developer_instructions default: ${options.decision.reason}`);
+        }
+        return options.decision.state === "missing" ? "skipped" : "exists";
+    }
     const line = `developer_instructions = ${JSON.stringify(OMX_PLUGIN_DEVELOPER_INSTRUCTIONS)}`;
     const hasExistingDeveloperInstructions = rootHasTomlKey(existing, "developer_instructions");
-    if (hasExistingDeveloperInstructions) {
-        const overwrite = options.pluginDeveloperInstructionsOverwritePrompt
-            ? await options.pluginDeveloperInstructionsOverwritePrompt(configPath)
-            : await promptForPluginDeveloperInstructionsOverwrite(configPath);
-        if (!overwrite) {
-            summary.skipped += 1;
-            if (options.verbose) {
-                console.log("  skipped plugin developer_instructions default: root developer_instructions already exists");
-            }
-            return "exists";
+    if (hasExistingDeveloperInstructions && options.decision.action === "add") {
+        summary.skipped += 1;
+        if (options.verbose) {
+            console.log("  skipped plugin developer_instructions default: root developer_instructions already exists");
         }
+        return "exists";
     }
     const nextConfig = hasExistingDeveloperInstructions
         ? replaceRootTomlKey(existing, "developer_instructions", line)
@@ -1102,7 +1321,7 @@ async function cleanupPluginModeLegacyConfig(configPath, backupContext, options)
     config = stripFirstPartyOmxMcpSections(config);
     config = stripExistingOmxBlocks(config).cleaned;
     config = stripExistingSharedMcpRegistryBlock(config).cleaned;
-    config = stripPluginModeLegacyRootDefaults(config);
+    config = stripPluginModeLegacyRootDefaults(config, options.developerInstructionsDecision);
     config = stripOmxSeededBehavioralDefaults(config);
     config = stripOmxFeatureFlags(config);
     config = stripManagedCodexHookTrustState(config);
@@ -1130,32 +1349,8 @@ async function cleanupPluginModeLegacyConfig(configPath, backupContext, options)
     }
     return true;
 }
-async function cleanupPluginModeLegacyAgentsMd(agentsMdPath, backupContext, options) {
-    if (!existsSync(agentsMdPath))
-        return false;
-    const fileInfo = await lstat(agentsMdPath);
-    if (fileInfo.isSymbolicLink()) {
-        if (options.verbose) {
-            console.log(`  preserved symlinked AGENTS.md at ${agentsMdPath}; plugin mode only removes direct legacy OMX-generated files`);
-        }
-        return false;
-    }
-    const content = await readFile(agentsMdPath, "utf-8");
-    if (!isOmxGeneratedAgentsMd(content))
-        return false;
-    if (await ensureBackup(agentsMdPath, true, backupContext, options)) {
-        // backup created for pre-existing AGENTS.md
-    }
-    if (!options.dryRun) {
-        await rm(agentsMdPath, { force: true });
-    }
-    if (options.verbose) {
-        console.log(`  ${options.dryRun ? "would remove" : "removed"} legacy OMX-generated AGENTS.md`);
-    }
-    return true;
-}
 export async function setup(options = {}) {
-    const { force = false, dryRun = false, installMode: requestedInstallMode, mcpMode: requestedMcpMode, teamMode: requestedTeamMode, scope: requestedScope, verbose = false, setupScopePrompt, persistedSetupReviewPrompt, installModePrompt, modelUpgradePrompt, pluginAgentsMdPrompt, pluginDeveloperInstructionsPrompt, pluginDeveloperInstructionsOverwritePrompt, firstPartyMcpRemovalPrompt, } = options;
+    const { force = false, dryRun = false, installMode: requestedInstallMode, mcpMode: requestedMcpMode, teamMode: requestedTeamMode, scope: requestedScope, verbose = false, skipNativeAgentRefresh: requestedSkipNativeAgentRefresh = false, setupScopePrompt, persistedSetupReviewPrompt, installModePrompt, modelUpgradePrompt, pluginAgentsMdPrompt, pluginDeveloperInstructionsPrompt, firstPartyMcpRemovalPrompt, } = options;
     const pkgRoot = getPackageRoot();
     const projectRoot = process.cwd();
     const persistedPreferences = await readPersistedSetupPreferences(projectRoot, { warnOnLegacyScope: true });
@@ -1194,6 +1389,8 @@ export async function setup(options = {}) {
             : undefined)
         ?? "enabled";
     const isTeamModeEnabled = teamModeEnabled(resolvedTeamMode);
+    const skipNativeAgentRefresh = requestedSkipNativeAgentRefresh ||
+        process.env[SKIP_NATIVE_AGENT_REFRESH_ENV] === "1";
     const scopeDirs = resolveScopeDirectories(resolvedScope.scope, projectRoot);
     const existingConfigForMcpMigration = existsSync(scopeDirs.codexConfigFile)
         ? await readFile(scopeDirs.codexConfigFile, "utf-8")
@@ -1224,15 +1421,32 @@ export async function setup(options = {}) {
     const pluginAgentsMdDst = resolvedScope.scope === "project"
         ? join(projectRoot, "AGENTS.md")
         : join(scopeDirs.codexHomeDir, "AGENTS.md");
-    const usePluginDeveloperInstructionsDefault = isPluginInstallMode
-        ? pluginDeveloperInstructionsPrompt
-            ? await pluginDeveloperInstructionsPrompt(scopeDirs.codexConfigFile)
-            : await promptForPluginDeveloperInstructionsDefault(scopeDirs.codexConfigFile)
-        : false;
+    const pluginDeveloperInstructionsDecision = isPluginInstallMode
+        ? await resolvePluginDeveloperInstructionsDecision(scopeDirs.codexConfigFile, { pluginDeveloperInstructionsPrompt })
+        : {
+            action: "preserve",
+            state: "custom",
+            reason: "non-plugin setup mode",
+        };
+    let pluginAgentsMdPathExists = false;
+    let pluginAgentsMdIsSymlink = false;
+    try {
+        const pluginAgentsMdStat = await lstat(pluginAgentsMdDst);
+        pluginAgentsMdPathExists = true;
+        pluginAgentsMdIsSymlink = pluginAgentsMdStat.isSymbolicLink();
+    }
+    catch {
+        pluginAgentsMdPathExists = false;
+        pluginAgentsMdIsSymlink = false;
+    }
     const usePluginAgentsMdDefault = isPluginInstallMode
-        ? pluginAgentsMdPrompt
-            ? await pluginAgentsMdPrompt(pluginAgentsMdDst)
-            : await promptForPluginAgentsMdDefault(pluginAgentsMdDst)
+        ? options.mergeAgents || pluginAgentsMdIsSymlink
+            ? false
+            : force
+                ? true
+                : pluginAgentsMdPrompt
+                    ? await pluginAgentsMdPrompt(pluginAgentsMdDst)
+                    : await promptForPluginAgentsMdDefault(pluginAgentsMdDst)
         : false;
     console.log("oh-my-codex setup");
     console.log("=================\n");
@@ -1382,7 +1596,11 @@ export async function setup(options = {}) {
     }
     // Step 4: Install native agent configs
     console.log("[4/8] Installing native agent configs...");
-    if (isPluginInstallMode) {
+    if (skipNativeAgentRefresh) {
+        summary.nativeAgents = createEmptyCategorySummary();
+        console.log("  Native agent refresh skipped for background update-check setup refresh.\n");
+    }
+    else if (isPluginInstallMode) {
         summary.nativeAgents = await refreshNativeAgentConfigs(pkgRoot, scopeDirs.nativeAgentsDir, backupContext, {
             force,
             dryRun,
@@ -1443,6 +1661,7 @@ export async function setup(options = {}) {
             verbose,
             preserveFirstPartyMcp: shouldOfferFirstPartyMcpRemoval &&
                 !removeFirstPartyMcpRegistrations,
+            developerInstructionsDecision: pluginDeveloperInstructionsDecision,
         });
         if (configCleaned)
             summary.config.removed += 1;
@@ -1495,11 +1714,11 @@ export async function setup(options = {}) {
         console.log(pluginScopedHooksSupported
             ? "  Plugin-scoped Codex hooks and runtime feature flags refresh complete (plugin_hooks, goals).\n"
             : `  Native Codex hooks fallback and runtime feature flags refresh complete (${scopeDirs.codexHooksFile}; hooks, goals).\n`);
-        if (usePluginDeveloperInstructionsDefault) {
+        if (pluginDeveloperInstructionsDecision.action !== "preserve") {
             const developerInstructionsResult = await applyPluginDeveloperInstructionsDefault(scopeDirs.codexConfigFile, backupContext, summary.config, {
                 dryRun,
                 verbose,
-                pluginDeveloperInstructionsOverwritePrompt,
+                decision: pluginDeveloperInstructionsDecision,
             });
             if (developerInstructionsResult === "updated") {
                 resolvedConfig = existsSync(scopeDirs.codexConfigFile)
@@ -1512,7 +1731,7 @@ export async function setup(options = {}) {
             }
         }
         else {
-            console.log("  Plugin-mode developer_instructions default not selected.\n");
+            console.log(`  Plugin-mode developer_instructions default preserved (${pluginDeveloperInstructionsDecision.reason}).\n`);
         }
     }
     else {
@@ -1537,6 +1756,7 @@ export async function setup(options = {}) {
         const existingHooksContent = existsSync(scopeDirs.codexHooksFile)
             ? await readFile(scopeDirs.codexHooksFile, "utf-8")
             : null;
+        await migrateLegacyHooksJsonTrustStateToConfig(scopeDirs.codexConfigFile, existingHooksContent, backupContext, summary.config, { dryRun, verbose });
         const hooksConfig = mergeManagedCodexHooksConfig(existingHooksContent, pkgRoot, scopeDirs.codexHooksFile, { platform: process.platform, codexHomeDir: scopeDirs.codexHomeDir });
         await syncManagedContent(hooksConfig, scopeDirs.codexHooksFile, summary.config, backupContext, { dryRun, verbose }, `native hooks ${scopeDirs.codexHooksFile}`);
         await syncManagedWindowsNativeHookShim(scopeDirs.codexHomeDir, pkgRoot, summary.config, backupContext, { dryRun, verbose });
@@ -1560,51 +1780,99 @@ export async function setup(options = {}) {
     console.log();
     // Step 6: Generate AGENTS.md
     console.log("[6/8] Generating AGENTS.md...");
+    const activeSession = resolvedScope.scope === "project"
+        ? await readSessionState(projectRoot)
+        : null;
+    const sessionIsActive = activeSession && !isSessionStale(activeSession);
     if (isPluginInstallMode) {
-        const agentsMdRemoved = await cleanupPluginModeLegacyAgentsMd(pluginAgentsMdDst, backupContext, { dryRun, verbose });
-        if (agentsMdRemoved) {
-            summary.agentsMd.removed += 1;
-            console.log(`  ${dryRun ? "Would remove" : "Removed"} legacy OMX-generated AGENTS.md for plugin mode.\n`);
-        }
-        if (usePluginAgentsMdDefault) {
-            const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
-            if (existsSync(agentsMdSrc)) {
-                const content = await readFile(agentsMdSrc, "utf-8");
-                const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
-                    codexHomeOverride: scopeDirs.codexHomeDir,
-                });
-                const modelTableDefinitions = getAgentsModelTableDefinitionsForTeamMode(resolvedTeamMode);
-                const rewritten = upsertAgentsModelTable(addGeneratedAgentsMarker(applyTeamModeToAgentsTemplate(applyPluginModeWordingToAgentsTemplate(content, resolvedScope.scope), resolvedTeamMode)), modelTableContext, modelTableDefinitions);
-                const result = await syncManagedAgentsContent(rewritten, pluginAgentsMdDst, summary.agentsMd, backupContext, {
-                    agentsOverwritePrompt: options.agentsOverwritePrompt,
-                    dryRun,
-                    force,
-                    verbose,
-                });
-                if (result === "updated") {
-                    console.log(resolvedScope.scope === "project"
-                        ? "  Generated plugin-mode AGENTS.md defaults in project root."
-                        : `  Generated plugin-mode AGENTS.md defaults in ${scopeDirs.codexHomeDir}.`);
+        const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
+        const pluginAgentsMdExists = pluginAgentsMdPathExists;
+        if (existsSync(agentsMdSrc)) {
+            const content = await readFile(agentsMdSrc, "utf-8");
+            const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
+                codexHomeOverride: scopeDirs.codexHomeDir,
+            });
+            const modelTableDefinitions = getAgentsModelTableDefinitionsForTeamMode(resolvedTeamMode);
+            const rewritten = upsertAgentsModelTable(addGeneratedAgentsMarker(applyTeamModeToAgentsTemplate(applyPluginModeWordingToAgentsTemplate(content, resolvedScope.scope), resolvedTeamMode)), modelTableContext, modelTableDefinitions);
+            if (options.mergeAgents && pluginAgentsMdExists) {
+                if (pluginAgentsMdIsSymlink) {
+                    summary.agentsMd.skipped += 1;
+                    console.log(`  Skipped plugin-mode AGENTS.md merge for symlinked ${pluginAgentsMdDst}; existing AGENTS.md left untouched.`);
                 }
-                else if (result === "unchanged") {
-                    console.log(resolvedScope.scope === "project"
-                        ? "  Plugin-mode AGENTS.md defaults already up to date in project root."
-                        : `  Plugin-mode AGENTS.md defaults already up to date in ${scopeDirs.codexHomeDir}.`);
+                else {
+                    const existing = await readFile(pluginAgentsMdDst, "utf-8");
+                    const mergedAgentsContent = upsertManagedAgentsBlock(existing, rewritten);
+                    const canApplyManagedAgentsMerge = mergedAgentsContent !== existing;
+                    if (resolvedScope.scope === "project" &&
+                        sessionIsActive &&
+                        canApplyManagedAgentsMerge) {
+                        summary.agentsMd.skipped += 1;
+                        console.log("  WARNING: Active omx session detected (pid " +
+                            activeSession?.pid +
+                            ").");
+                        console.log("  Skipping AGENTS.md overwrite to avoid corrupting runtime overlay.");
+                        console.log("  Stop the active session first, then re-run setup.");
+                    }
+                    else if (!canApplyManagedAgentsMerge) {
+                        summary.agentsMd.unchanged += 1;
+                        console.log(resolvedScope.scope === "project"
+                            ? "  Plugin-mode AGENTS.md already up to date in project root."
+                            : `  Plugin-mode AGENTS.md already up to date in ${scopeDirs.codexHomeDir}.`);
+                    }
+                    else {
+                        await syncManagedContent(mergedAgentsContent, pluginAgentsMdDst, summary.agentsMd, backupContext, { dryRun, verbose }, `plugin AGENTS merge ${pluginAgentsMdDst}`);
+                        console.log(resolvedScope.scope === "project"
+                            ? "  Merged plugin-mode OMX-managed AGENTS.md sections into project root."
+                            : `  Merged plugin-mode OMX-managed AGENTS.md sections into ${scopeDirs.codexHomeDir}.`);
+                    }
+                }
+            }
+            else if (usePluginAgentsMdDefault) {
+                const defaultWouldChange = pluginAgentsMdExists
+                    ? (await readFile(pluginAgentsMdDst, "utf-8")) !== rewritten
+                    : true;
+                if (resolvedScope.scope === "project" &&
+                    sessionIsActive &&
+                    defaultWouldChange) {
+                    summary.agentsMd.skipped += 1;
+                    console.log("  WARNING: Active omx session detected (pid " +
+                        activeSession?.pid +
+                        ").");
+                    console.log("  Skipping AGENTS.md overwrite to avoid corrupting runtime overlay.");
+                    console.log("  Stop the active session first, then re-run setup.");
                 }
                 else {
-                    console.log(`  Skipped plugin-mode AGENTS.md defaults for ${pluginAgentsMdDst}.`);
+                    const result = await syncManagedAgentsContent(rewritten, pluginAgentsMdDst, summary.agentsMd, backupContext, {
+                        agentsOverwritePrompt: options.agentsOverwritePrompt,
+                        dryRun,
+                        force,
+                        verbose,
+                    });
+                    if (result === "updated") {
+                        console.log(resolvedScope.scope === "project"
+                            ? "  Generated plugin-mode AGENTS.md defaults in project root."
+                            : `  Generated plugin-mode AGENTS.md defaults in ${scopeDirs.codexHomeDir}.`);
+                    }
+                    else if (result === "unchanged") {
+                        console.log(resolvedScope.scope === "project"
+                            ? "  Plugin-mode AGENTS.md defaults already up to date in project root."
+                            : `  Plugin-mode AGENTS.md defaults already up to date in ${scopeDirs.codexHomeDir}.`);
+                    }
+                    else {
+                        console.log(`  Skipped plugin-mode AGENTS.md defaults for ${pluginAgentsMdDst}.`);
+                    }
                 }
             }
             else {
                 summary.agentsMd.skipped += 1;
-                console.log("  AGENTS.md template not found, skipping.");
+                console.log(pluginAgentsMdExists
+                    ? "  Plugin-mode AGENTS.md defaults not selected; existing AGENTS.md left untouched.\n"
+                    : "  Plugin-mode AGENTS.md defaults not selected; no AGENTS.md was generated.\n");
             }
         }
         else {
             summary.agentsMd.skipped += 1;
-            console.log(agentsMdRemoved
-                ? "  Plugin-mode AGENTS.md defaults not selected.\n"
-                : "  AGENTS.md generation skipped; no legacy OMX-generated AGENTS.md found and defaults not selected.\n");
+            console.log("  AGENTS.md template not found, skipping.");
         }
     }
     else {
@@ -1614,10 +1882,6 @@ export async function setup(options = {}) {
             : join(scopeDirs.codexHomeDir, "AGENTS.md");
         const agentsMdExists = existsSync(agentsMdDst);
         // Guard: refuse to overwrite project-root AGENTS.md during active session
-        const activeSession = resolvedScope.scope === "project"
-            ? await readSessionState(projectRoot)
-            : null;
-        const sessionIsActive = activeSession && !isSessionStale(activeSession);
         if (existsSync(agentsMdSrc)) {
             const content = await readFile(agentsMdSrc, "utf-8");
             const modelTableContext = resolveAgentsModelTableContext(resolvedConfig, {
@@ -1772,7 +2036,7 @@ export async function setup(options = {}) {
     if (isPluginInstallMode) {
         console.log(`  2. Registered Codex marketplace ${OMX_LOCAL_MARKETPLACE_NAME} supplies OMX skills and workflow surfaces`);
         console.log("  3. Browse plugin-provided skills with /skills");
-        console.log("  4. Optional AGENTS.md and developer_instructions defaults are only installed when selected during plugin-mode setup");
+        console.log("  4. Plugin-mode AGENTS.md defaults provide persistent orchestration guidance; developer_instructions is an optional bootstrap");
         console.log("  5. Native agent role TOML files written to .codex/agents/ for agent_type routing");
     }
     else {
@@ -1875,6 +2139,93 @@ async function syncManagedContent(content, dstPath, summary, backupContext, opti
         console.log(`  ${options.dryRun ? "would update" : "updated"} ${verboseLabel}`);
     }
 }
+function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+function nativeAgentInstallManifestPath(agentsDir) {
+    return join(agentsDir, "..", ".omx", "native-agents.json");
+}
+async function readNativeAgentInstallManifest(agentsDir) {
+    const manifestPath = nativeAgentInstallManifestPath(agentsDir);
+    if (!existsSync(manifestPath))
+        return { version: 1, files: {} };
+    try {
+        const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
+        if (parsed.version !== 1 ||
+            !parsed.files ||
+            typeof parsed.files !== "object") {
+            return { version: 1, files: {} };
+        }
+        const files = {};
+        for (const [fileName, entry] of Object.entries(parsed.files)) {
+            if (!fileName.endsWith(".toml"))
+                continue;
+            if (!entry || typeof entry !== "object")
+                continue;
+            const sha256 = entry.sha256;
+            if (typeof sha256 === "string" && /^[0-9a-f]{64}$/i.test(sha256)) {
+                files[fileName] = { sha256: sha256.toLowerCase() };
+            }
+        }
+        return { version: 1, files };
+    }
+    catch {
+        return { version: 1, files: {} };
+    }
+}
+async function writeNativeAgentInstallManifest(agentsDir, manifest) {
+    const manifestPath = nativeAgentInstallManifestPath(agentsDir);
+    await mkdir(dirname(manifestPath), { recursive: true });
+    const sortedFiles = Object.fromEntries(Object.entries(manifest.files).sort(([left], [right]) => left.localeCompare(right)));
+    await writeFile(manifestPath, JSON.stringify({ version: 1, files: sortedFiles }, null, 2) + "\n");
+}
+async function syncNativeAgentToml(content, dstPath, summary, backupContext, options, verboseLabel, manifest) {
+    const fileName = basename(dstPath);
+    const nextHash = hashContent(content);
+    const destinationExists = existsSync(dstPath);
+    if (!destinationExists) {
+        if (!options.dryRun) {
+            await mkdir(dirname(dstPath), { recursive: true });
+            await writeFile(dstPath, content);
+            manifest.files[fileName] = { sha256: nextHash };
+        }
+        summary.updated += 1;
+        if (options.verbose) {
+            console.log(`  ${options.dryRun ? "would update" : "updated"} ${verboseLabel}`);
+        }
+        return;
+    }
+    const existing = await readFile(dstPath, "utf-8");
+    const existingHash = hashContent(existing);
+    if (existing === content) {
+        if (!options.dryRun) {
+            manifest.files[fileName] = { sha256: nextHash };
+        }
+        summary.unchanged += 1;
+        return;
+    }
+    const priorHash = manifest.files[fileName]?.sha256;
+    const safeToOverwrite = options.force || priorHash === existingHash;
+    if (!safeToOverwrite) {
+        summary.skipped += 1;
+        if (options.verbose) {
+            console.log(`  skipped ${verboseLabel} (local modifications preserved; use --force to overwrite)`);
+        }
+        return;
+    }
+    if (await ensureBackup(dstPath, true, backupContext, options)) {
+        summary.backedUp += 1;
+    }
+    if (!options.dryRun) {
+        await mkdir(dirname(dstPath), { recursive: true });
+        await writeFile(dstPath, content);
+        manifest.files[fileName] = { sha256: nextHash };
+    }
+    summary.updated += 1;
+    if (options.verbose) {
+        console.log(`  ${options.dryRun ? "would update" : "updated"} ${verboseLabel}`);
+    }
+}
 async function syncManagedWindowsNativeHookShim(codexHomeDir, pkgRoot, summary, backupContext, options) {
     if (process.platform !== "win32")
         return;
@@ -2059,6 +2410,7 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
     if (!options.dryRun) {
         await mkdir(agentsDir, { recursive: true });
     }
+    const nativeAgentManifest = await readNativeAgentInstallManifest(agentsDir);
     const manifest = tryReadCatalogManifest();
     const agentStatusByName = manifest
         ? getCatalogAgentStatusByName(manifest)
@@ -2093,7 +2445,7 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
             codexHomeOverride: join(agentsDir, ".."),
         });
         const dst = join(agentsDir, `${name}.toml`);
-        await syncManagedContent(toml, dst, summary, backupContext, options, `native agent ${name}.toml`);
+        await syncNativeAgentToml(toml, dst, summary, backupContext, options, `native agent ${name}.toml`, nativeAgentManifest);
     }
     summary.removed += await cleanupObsoleteNativeAgents(agentsDir, backupContext, options);
     if (manifest) {
@@ -2124,6 +2476,7 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
             }
             if (!options.dryRun) {
                 await rm(staleAgentPath, { force: true });
+                delete nativeAgentManifest.files[file];
             }
             summary.removed += 1;
             if (options.verbose) {
@@ -2136,6 +2489,9 @@ async function refreshNativeAgentConfigs(pkgRoot, agentsDir, backupContext, opti
             }
         }
     }
+    if (!options.dryRun) {
+        await writeNativeAgentInstallManifest(agentsDir, nativeAgentManifest);
+    }
     return summary;
 }
 async function cleanupObsoleteNativeAgents(agentsDir, backupContext, options) {