oh-my-codex 0.20.3 → 0.21.0

package/dist/cli/setup.js

@@ -10,17 +10,17 @@ import { createInterface } from "readline/promises";
 import { homedir } from "os";
 import TOML from "@iarna/toml";
 import { createHash } from "crypto";
-import { clearNativeHookClaimJournal as clearNativeHookClaimJournalWithDurability, createNativeHookClaimJournalDurability, persistNativeHookClaimJournal as persistNativeHookClaimJournalWithDurability, recoverNativeHookClaimJournal, syncNativeHookClaimParent as syncNativeHookClaimParentWithDurability, restoreNativeHookClaimNoClobber as restoreNativeHookClaimNoClobberWithDurability, } from "./native-hook-claim-journal.js";
+import { clearNativeHookClaimJournal as clearNativeHookClaimJournalWithDurability, createNativeHookClaimJournalDurability, persistNativeHookClaimJournal as persistNativeHookClaimJournalWithDurability, recoverNativeHookClaimJournal, syncNativeHookClaimParent as syncNativeHookClaimParentWithDurability, restoreNativeHookClaimNoClobber as restoreNativeHookClaimNoClobberWithDurability, wrapNativeHookClaimJournalDurability, } from "./native-hook-claim-journal.js";
 import { codexHome, codexConfigPath, codexPromptsDir, codexAgentsDir, userSkillsDir, omxStateDir, detectLegacySkillRootOverlap, omxPlansDir, omxLogsDir, } from "../utils/paths.js";
 import { emitDegradedDurabilityWarning, recordRegularFileSyncOutcome, syncRegularFile, } from "../utils/file-durability.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 { buildMergedConfig, formatTomlStringArray, 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 { buildManagedCodexNativeHookWindowsShimContent, buildManagedCodexNativeHookWindowsShimPath, planManagedCodexHooksMerge, planManagedCodexHooksRemoval, classifyManagedCodexNativeHookWindowsShimOwnership, ManagedCodexHooksPlanError, validateCodexHooksConfigStrict, } 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";
 import { getCatalogAgentStatusByName, getInstallableNativeAgentNames, isNativeAgentInstallableStatus, isSetupPromptAssetName, } from "../agents/policy.js";
 import { getPackageRoot } from "../utils/package.js";
-import { readSessionState, isSessionStale } from "../hooks/session.js";
+import { readSessionState, classifySessionStateLiveness } from "../hooks/session.js";
 import { getCatalogHeadlineCounts } from "./catalog-contract.js";
 import { tryReadCatalogManifest } from "../catalog/reader.js";
 import { DEFAULT_FRONTIER_MODEL } from "../config/models.js";
@@ -28,7 +28,7 @@ import { teamModeEnabled, } from "../config/team-mode.js";
 import { addGeneratedAgentsMarker, hasOmxAgentsContract, hasOmxManagedAgentsSections, isOmxGeneratedAgentsMd, preserveUserOmxPolicyBlocks, upsertManagedAgentsBlock, } from "../utils/agents-md.js";
 import { DEFAULT_HUD_CONFIG } from "../hud/types.js";
 import { SETUP_INSTALL_MODES, SETUP_MCP_MODES, SETUP_SCOPES, getSetupScopeFilePath, readPersistedSetupPreferences, resolvePersistedSetupMergeAgents, writePersistedSetupPreferences, } from "./setup-preferences.js";
-import { OMX_LOCAL_MARKETPLACE_NAME, OMX_PLUGIN_NAME, materializePackagedOmxPluginCache, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, upsertLocalOmxPluginEnablement, upsertLocalOmxPluginMcpServerEnablement, hasLocalOmxPluginMcpServerRegistrations, pluginHookCacheMatchesPackaged, } from "./plugin-marketplace.js";
+import { OMX_LOCAL_MARKETPLACE_NAME, OMX_PLUGIN_NAME, discoverOmxPluginCacheDirs, materializePackagedOmxPluginCache, resolvePackagedOmxMarketplace, upsertLocalOmxMarketplaceRegistration, upsertLocalOmxPluginEnablement, upsertLocalOmxPluginMcpServerEnablement, hasLocalOmxPluginMcpServerRegistrations, } from "./plugin-marketplace.js";
 import { resolveCodexHookFeatureSupportForCli } from "./codex-feature-probe.js";
 async function resolveStatusLinePresetForSetup(projectRoot, options) {
     if (options.force) {
@@ -67,7 +67,6 @@ 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"]);
 const TEAM_MODE_NATIVE_AGENT_NAMES = new Set(["team-executor"]);
@@ -211,6 +210,7 @@ let nativeHookTransactionTemporaryPathOverride;
 let setupLatePhaseFailureInjector;
 let nativeHookTransactionRegularFileSyncOverride;
 let nativeHookClaimJournalDurabilityOverride;
+let nativeHookTransactionArtifactLstatOverride;
 /** @internal Test seam for deterministic atomic-write and rollback coverage. */
 export function setNativeHookTransactionFailureInjectorForTest(injector) {
     const previous = nativeHookTransactionFailureInjector;
@@ -251,6 +251,14 @@ export function setNativeHookTransactionRegularFileSyncForTest(sync) {
         nativeHookTransactionRegularFileSyncOverride = previous;
     };
 }
+/** @internal Test seam for deterministic artifact read-back coverage. */
+export function setNativeHookTransactionArtifactLstatForTest(artifactLstat) {
+    const previous = nativeHookTransactionArtifactLstatOverride;
+    nativeHookTransactionArtifactLstatOverride = artifactLstat;
+    return () => {
+        nativeHookTransactionArtifactLstatOverride = previous;
+    };
+}
 /** @internal Test seam for deterministic claim-journal durability coverage. */
 export function setNativeHookClaimJournalDurabilityForTest(durability) {
     const previous = nativeHookClaimJournalDurabilityOverride;
@@ -262,21 +270,21 @@ export function setNativeHookClaimJournalDurabilityForTest(durability) {
 function nativeHookPlatform() {
     return nativeHookTransactionPlatformOverride ?? process.platform;
 }
-function nativeHookClaimJournalDurability() {
-    return nativeHookClaimJournalDurabilityOverride
-        ?? createNativeHookClaimJournalDurability(nativeHookPlatform());
+function nativeHookClaimJournalDurability(tracker) {
+    return wrapNativeHookClaimJournalDurability(nativeHookClaimJournalDurabilityOverride
+        ?? createNativeHookClaimJournalDurability(nativeHookPlatform()), tracker);
 }
-async function clearNativeHookClaimJournal(root) {
-    return clearNativeHookClaimJournalWithDurability(root, nativeHookClaimJournalDurability());
+async function clearNativeHookClaimJournal(root, tracker) {
+    return clearNativeHookClaimJournalWithDurability(root, nativeHookClaimJournalDurability(tracker));
 }
-async function persistNativeHookClaimJournal(root, entry) {
-    return persistNativeHookClaimJournalWithDurability(root, entry, nativeHookClaimJournalDurability());
+async function persistNativeHookClaimJournal(root, entry, tracker) {
+    return persistNativeHookClaimJournalWithDurability(root, entry, nativeHookClaimJournalDurability(tracker));
 }
-async function restoreNativeHookClaimNoClobber(claimPath, destinationPath) {
-    return restoreNativeHookClaimNoClobberWithDurability(claimPath, destinationPath, nativeHookClaimJournalDurability());
+async function restoreNativeHookClaimNoClobber(claimPath, destinationPath, tracker) {
+    return restoreNativeHookClaimNoClobberWithDurability(claimPath, destinationPath, nativeHookClaimJournalDurability(tracker));
 }
-async function syncNativeHookClaimParent(path) {
-    return syncNativeHookClaimParentWithDurability(path, nativeHookClaimJournalDurability());
+async function syncNativeHookClaimParent(path, tracker) {
+    return syncNativeHookClaimParentWithDurability(path, nativeHookClaimJournalDurability(tracker));
 }
 async function syncNativeHookRegularFile(handle) {
     const platform = nativeHookPlatform();
@@ -293,6 +301,20 @@ function nativeHookTransactionTopologyEqual(left, right) {
         ? left.kind === right.kind
         : left.mode === right.mode;
 }
+function nativeHookTransactionTopologyMatchesDuringReadback(left, right) {
+    if (nativeHookPlatform() === "win32" &&
+        left.kind === "regular_file" &&
+        right.kind === "regular_file" &&
+        left.mode === 0o600 &&
+        right.mode === 0o666) {
+        // Windows can synthesize a requested new-file mode of 0o600 as 0o666
+        // when the same file is reopened for read-back. Accept only that one-way
+        // transition inside a single identity-checked snapshot; later snapshots
+        // remain mode-strict so real permission drift still fails closed.
+        return true;
+    }
+    return nativeHookTransactionTopologyEqual(left, right);
+}
 function isMissingPathError(error) {
     return (typeof error === "object" &&
         error !== null &&
@@ -405,7 +427,7 @@ function decodeNativeHookTransactionUtf8(bytes, label) {
 async function captureNativeHookTransactionArtifact(path, label) {
     let before;
     try {
-        before = await lstat(path);
+        before = await (nativeHookTransactionArtifactLstatOverride?.(path) ?? lstat(path));
     }
     catch (error) {
         if (isMissingPathError(error)) {
@@ -417,7 +439,7 @@ async function captureNativeHookTransactionArtifact(path, label) {
         throw new Error(`Refusing native hook transaction for ${label}: expected a single-link regular file or absence.`);
     }
     const bytes = await readFile(path);
-    const after = await lstat(path);
+    const after = await (nativeHookTransactionArtifactLstatOverride?.(path) ?? lstat(path));
     const beforeTopology = {
         kind: "regular_file",
         mode: before.mode & 0o7777,
@@ -428,7 +450,7 @@ async function captureNativeHookTransactionArtifact(path, label) {
     };
     if (!after.isFile() ||
         after.nlink !== 1 ||
-        !nativeHookTransactionTopologyEqual(beforeTopology, afterTopology) ||
+        !nativeHookTransactionTopologyMatchesDuringReadback(beforeTopology, afterTopology) ||
         before.dev !== after.dev ||
         before.ino !== after.ino ||
         before.nlink !== after.nlink) {
@@ -436,7 +458,7 @@ async function captureNativeHookTransactionArtifact(path, label) {
     }
     return {
         bytes,
-        topology: beforeTopology,
+        topology: afterTopology,
         device: before.dev,
         inode: before.ino,
         links: before.nlink,
@@ -451,7 +473,7 @@ function nativeHookTransactionSnapshotsEqual(left, right) {
 }
 function nativeHookTransactionSnapshotMatchesExpected(snapshot, expected) {
     return (hookTransactionBytesEqual(snapshot.bytes, expected.bytes) &&
-        nativeHookTransactionTopologyEqual(snapshot.topology, expected.topology));
+        nativeHookTransactionTopologyMatchesDuringReadback(expected.topology, snapshot.topology));
 }
 function nativeHookTransactionOutputTopology(before, after) {
     if (after === null)
@@ -622,7 +644,7 @@ function nativeHookTransactionClaimPath(path) {
     return join(dirname(path), `.${basename(path)}.omx-claim-${process.pid}-${nativeHookTransactionSequence}.tmp`);
 }
 async function restoreNativeHookClaim(claimPath, destinationPath, tracker) {
-    recordRegularFileSyncOutcome(tracker, await restoreNativeHookClaimNoClobber(claimPath, destinationPath));
+    recordRegularFileSyncOutcome(tracker, await restoreNativeHookClaimNoClobber(claimPath, destinationPath, tracker));
 }
 async function atomicWriteNativeHookTransactionArtifact(artifact, content, stage, expectedCurrent, ancestorPrecondition, tracker, onWriteApplied, onWriteStabilized, assertApplied) {
     const temporaryPath = nativeHookTransactionTemporaryPath(artifact.path, "write");
@@ -688,14 +710,14 @@ async function atomicWriteNativeHookTransactionArtifact(artifact, content, stage
                     claimPath,
                     before: expectedCurrent.bytes,
                     after: content,
-                }));
+                }, tracker));
                 await refreshNativeHookTransactionAncestorPrecondition(ancestorPrecondition, join(ancestorPrecondition.controlledRoot, ".omx", "native-hook-claim-journal.json"));
                 journaledClaim = true;
             }
             await rename(artifact.path, claimPath);
             claimCreated = true;
             if (journaledClaim)
-                await syncNativeHookClaimParent(claimPath);
+                await syncNativeHookClaimParent(claimPath, tracker);
             await assertNativeHookTransactionArtifactSnapshot(claimPath, `${artifact.label} replacement claim`, expectedCurrent, stage === "write" ? "precondition" : "rollback");
         }
         await copyFile(temporaryPath, artifact.path, constants.COPYFILE_EXCL);
@@ -709,15 +731,15 @@ async function atomicWriteNativeHookTransactionArtifact(artifact, content, stage
         finally {
             await installedHandle.close();
         }
-        await syncNativeHookClaimParent(artifact.path);
+        await syncNativeHookClaimParent(artifact.path, tracker);
         const installedSnapshot = await assertNativeHookTransactionArtifactState(artifact.path, artifact.label, { bytes: content, topology: artifact.afterTopology }, stage === "write" ? "precondition" : "rollback");
         if (claimCreated && claimPath) {
             await rm(claimPath);
-            await syncNativeHookClaimParent(claimPath);
+            await syncNativeHookClaimParent(claimPath, tracker);
             claimCreated = false;
         }
         if (journaledClaim) {
-            await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot);
+            await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot, tracker);
             journaledClaim = false;
         }
         await rm(temporaryPath);
@@ -733,10 +755,10 @@ async function atomicWriteNativeHookTransactionArtifact(artifact, content, stage
         if (claimCreated && claimPath) {
             try {
                 await restoreNativeHookClaim(claimPath, artifact.path, tracker);
-                await syncNativeHookClaimParent(artifact.path);
+                await syncNativeHookClaimParent(artifact.path, tracker);
                 claimCreated = false;
                 if (journaledClaim) {
-                    await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot);
+                    await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot, tracker);
                     journaledClaim = false;
                 }
             }
@@ -872,11 +894,11 @@ async function applyNativeHookTransactionArtifact(artifact, ancestorPrecondition
                 claimPath,
                 before: artifact.before.bytes,
                 after: null,
-            }));
+            }, tracker));
         }
         await rename(artifact.path, claimPath);
         if (journaledClaim)
-            await syncNativeHookClaimParent(claimPath);
+            await syncNativeHookClaimParent(claimPath, tracker);
         const entry = {
             artifact,
             appliedSnapshot: { bytes: null, topology: { kind: "absent" } },
@@ -893,9 +915,9 @@ async function applyNativeHookTransactionArtifact(artifact, ancestorPrecondition
                 const claimed = await captureNativeHookTransactionArtifact(claimPath, `${artifact.label} removal claim`);
                 await restoreNativeHookClaim(claimPath, artifact.path, tracker);
                 if (journaledClaim)
-                    await syncNativeHookClaimParent(artifact.path);
+                    await syncNativeHookClaimParent(artifact.path, tracker);
                 if (journaledClaim) {
-                    await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot);
+                    await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot, tracker);
                 }
                 await assertNativeHookTransactionArtifactSnapshot(artifact.path, artifact.label, claimed, "precondition");
                 const entryIndex = applied.indexOf(entry);
@@ -909,9 +931,9 @@ async function applyNativeHookTransactionArtifact(artifact, ancestorPrecondition
         }
         await rm(claimPath);
         if (journaledClaim)
-            await syncNativeHookClaimParent(claimPath);
+            await syncNativeHookClaimParent(claimPath, tracker);
         if (journaledClaim) {
-            await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot);
+            await clearNativeHookClaimJournal(ancestorPrecondition.controlledRoot, tracker);
         }
         originalRemoved = true;
         injectNativeHookTransactionFailure("after_remove", artifact);
@@ -1314,9 +1336,134 @@ export async function validateSkillFile(skillMdPath) {
     const content = await readFile(skillMdPath, "utf-8");
     parseSkillFrontmatter(content, skillMdPath);
 }
+const INSTALLED_SKILL_BADGE_PREFIX = "[OMX] ";
+function installedSkillReceiptPath(scope, projectRoot) {
+    const authorityRoot = scope === "project" ? projectRoot : homedir();
+    return join(authorityRoot, ".omx", "state", "setup", "installed-skills.json");
+}
+async function readInstalledSkillReceipt(receiptPath) {
+    try {
+        const parsed = JSON.parse(await readFile(receiptPath, "utf-8"));
+        if (parsed?.version === 1 && parsed.skills && typeof parsed.skills === "object") {
+            // Re-key through a prototype-less record so a `__proto__` entry in a persisted receipt is a
+            // real own property on both sides of the comparison.
+            const skills = Object.create(null);
+            for (const [name, entry] of Object.entries(parsed.skills)) {
+                const files = Object.create(null);
+                for (const [file, digest] of Object.entries(entry?.files ?? {}))
+                    files[file] = String(digest);
+                skills[name] = { files };
+            }
+            return { version: 1, skills };
+        }
+    }
+    catch {
+        // A missing or unreadable receipt means "no proof of ownership", which retains conservatively.
+    }
+    return { version: 1, skills: Object.create(null) };
+}
+/**
+ * Digest the CURRENT contents of a skill directory, used to compare against a receipt.
+ *
+ * Non-regular entries (symlinks, sockets) are recorded as a sentinel rather than skipped, so a
+ * directory containing one can never compare equal to a receipt of regular files and is therefore
+ * retained instead of deleted.
+ */
+async function digestSkillDirectory(skillDir) {
+    // Prototype-less: a file literally named `__proto__` assigned into a normal object literal is not an
+    // own enumerable property, so it would vanish from Object.keys() and let a user entry be deleted
+    // while the comparison still reported equality.
+    const files = Object.create(null);
+    const walk = async (dir, prefix) => {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full, relPath);
+                continue;
+            }
+            if (!entry.isFile()) {
+                files[relPath] = "non-regular-entry";
+                continue;
+            }
+            files[relPath] = createHash("sha256").update(await readFile(full)).digest("hex");
+        }
+    };
+    await walk(skillDir, "");
+    return files;
+}
+/** True only when every current file matches the digest OMX recorded at install time. */
+async function isUnmodifiedRecordedInstall(receiptPath, skillName, skillDir) {
+    const receipt = await readInstalledSkillReceipt(receiptPath);
+    const recorded = receipt.skills[skillName]?.files;
+    if (!recorded || Object.keys(recorded).length === 0)
+        return false;
+    let current;
+    try {
+        current = await digestSkillDirectory(skillDir);
+    }
+    catch {
+        return false;
+    }
+    const recordedNames = Object.keys(recorded).sort();
+    const currentNames = Object.keys(current).sort();
+    if (recordedNames.length !== currentNames.length)
+        return false;
+    return recordedNames.every((name, index) => currentNames[index] === name && current[name] === recorded[name]);
+}
+/**
+ * Record digests for EXACTLY the files OMX wrote, keyed by skill.
+ *
+ * Digesting the destination tree instead would poison the receipt: a note a user drops into an active
+ * skill directory would be recorded as OMX-owned and then deleted when that skill is later retired.
+ * The receipt therefore describes the installer's own output, and any extra entry present at
+ * retirement time makes the comparison fail, which retains the directory.
+ */
+async function writeInstalledSkillReceipt(receiptPath, skillsDir, writtenFilesBySkill, options) {
+    if (options.dryRun)
+        return;
+    const receipt = await readInstalledSkillReceipt(receiptPath);
+    for (const [name, relativePaths] of writtenFilesBySkill) {
+        const files = Object.create(null);
+        let complete = true;
+        for (const relPath of relativePaths) {
+            const full = join(skillsDir, name, relPath);
+            try {
+                files[relPath] = createHash("sha256").update(await readFile(full)).digest("hex");
+            }
+            catch {
+                complete = false;
+                break;
+            }
+        }
+        if (complete && Object.keys(files).length > 0)
+            receipt.skills[name] = { files };
+        else
+            delete receipt.skills[name];
+    }
+    try {
+        await mkdir(dirname(receiptPath), { recursive: true });
+        await writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+    }
+    catch {
+        // A receipt we cannot persist simply means the next refresh retains conservatively.
+    }
+}
+async function isOmxManagedInstalledSkillDir(skillDir) {
+    const skillMdPath = join(skillDir, "SKILL.md");
+    if (!existsSync(skillMdPath))
+        return false;
+    try {
+        const metadata = parseSkillFrontmatter(await readFile(skillMdPath, "utf-8"), skillMdPath);
+        return metadata.description.startsWith(INSTALLED_SKILL_BADGE_PREFIX);
+    }
+    catch {
+        return false;
+    }
+}
 function rewriteInstalledSkillDescriptionBadge(content, filePath = "SKILL.md") {
     const metadata = parseSkillFrontmatter(content, filePath);
-    const badgePrefix = "[OMX] ";
+    const badgePrefix = INSTALLED_SKILL_BADGE_PREFIX;
     const displayDescription = metadata.description.startsWith(badgePrefix)
         ? metadata.description
         : `${badgePrefix}${metadata.description}`;
@@ -1701,155 +1848,8 @@ async function resolveSetupScope(projectRoot, requestedScope, persistedReviewDec
     }
     return { scope: DEFAULT_SETUP_SCOPE, source: "default" };
 }
-async function readPluginManifestName(manifestPath) {
-    try {
-        const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
-        return typeof parsed === "object" &&
-            parsed !== null &&
-            "name" in parsed &&
-            typeof parsed.name === "string"
-            ? parsed.name
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-async function readPluginManifestSummary(manifestPath) {
-    try {
-        const parsed = JSON.parse(await readFile(manifestPath, "utf-8"));
-        if (typeof parsed !== "object" || parsed === null)
-            return null;
-        const manifest = parsed;
-        return {
-            name: typeof manifest.name === "string" ? manifest.name : null,
-            version: typeof manifest.version === "string" ? manifest.version : null,
-            skills: typeof manifest.skills === "string" ? manifest.skills : null,
-            hooks: typeof manifest.hooks === "string" ? manifest.hooks : null,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-async function listChildDirectoryNames(dir) {
-    try {
-        const entries = await readdir(dir, { withFileTypes: true });
-        return entries
-            .filter((entry) => entry.isDirectory())
-            .map((entry) => entry.name)
-            .sort();
-    }
-    catch {
-        return null;
-    }
-}
-async function discoverOmxPluginCacheDirs(cacheRoot = join(codexHome(), "plugins", "cache")) {
-    if (!existsSync(cacheRoot))
-        return [];
-    const queue = [
-        { path: cacheRoot, depth: 0 },
-    ];
-    const maxDepth = 5;
-    const matches = [];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current)
-            break;
-        const manifestPath = join(current.path, ".codex-plugin", "plugin.json");
-        if (existsSync(manifestPath)) {
-            const name = await readPluginManifestName(manifestPath);
-            if (name === "oh-my-codex") {
-                matches.push(current.path);
-                continue;
-            }
-        }
-        if (current.depth >= maxDepth)
-            continue;
-        let entries;
-        try {
-            entries = await readdir(current.path, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            if (entry.name === ".git" || entry.name === "node_modules")
-                continue;
-            queue.push({
-                path: join(current.path, entry.name),
-                depth: current.depth + 1,
-            });
-        }
-    }
-    return matches.sort();
-}
-async function discoverOmxPluginCacheDir(cacheRoot = join(codexHome(), "plugins", "cache")) {
-    return (await discoverOmxPluginCacheDirs(cacheRoot))[0] ?? null;
-}
-async function refreshOmxPluginDiscoveryCache(pkgRoot, options, codexHomeDir = codexHome()) {
-    const packagedMarketplace = await resolvePackagedOmxMarketplace(pkgRoot);
-    if (!packagedMarketplace) {
-        return { status: "unavailable", staleDirs: [] };
-    }
-    const [pkg, expectedSkillNames, cachedDirs] = await Promise.all([
-        readFile(join(pkgRoot, "package.json"), "utf-8").then((raw) => JSON.parse(raw)),
-        listChildDirectoryNames(join(packagedMarketplace.pluginRoot, "skills")),
-        discoverOmxPluginCacheDirs(join(codexHomeDir, "plugins", "cache")),
-    ]);
-    const expectedVersion = typeof pkg.version === "string" ? pkg.version : null;
-    const staleDirs = [];
-    for (const cacheDir of cachedDirs) {
-        const manifest = await readPluginManifestSummary(join(cacheDir, ".codex-plugin", "plugin.json"));
-        if (manifest?.name !== "oh-my-codex")
-            continue;
-        const cachedSkillNames = await listChildDirectoryNames(join(cacheDir, "skills"));
-        const versionChanged = expectedVersion !== null && manifest.version !== expectedVersion;
-        const skillsPointerChanged = manifest.skills !== "./skills/";
-        const hooksPointerChanged = manifest.hooks !== "./hooks/hooks.json";
-        const hookFilesMissing = !existsSync(join(cacheDir, "hooks", "hooks.json"))
-            || !existsSync(join(cacheDir, "hooks", "codex-native-hook.mjs"))
-            || !existsSync(join(cacheDir, "hooks", "omx-command.json"));
-        const hookFilesChanged = !hookFilesMissing
-            && !(await pluginHookCacheMatchesPackaged(cacheDir, packagedMarketplace));
-        const skillListChanged = expectedSkillNames !== null &&
-            cachedSkillNames !== null &&
-            JSON.stringify(cachedSkillNames) !== JSON.stringify(expectedSkillNames);
-        if (!versionChanged &&
-            !skillsPointerChanged &&
-            !hooksPointerChanged &&
-            !hookFilesMissing &&
-            !hookFilesChanged &&
-            !skillListChanged)
-            continue;
-        staleDirs.push(cacheDir);
-        if (!options.dryRun) {
-            await rm(cacheDir, { recursive: true, force: true });
-        }
-        if (options.verbose) {
-            const reasons = [
-                versionChanged
-                    ? `version ${manifest.version ?? "unknown"} -> ${expectedVersion}`
-                    : null,
-                skillsPointerChanged
-                    ? `skills pointer ${manifest.skills ?? "missing"} -> ./skills/`
-                    : null,
-                hooksPointerChanged
-                    ? `hooks pointer ${manifest.hooks ?? "missing"} -> ./hooks/hooks.json`
-                    : null,
-                hookFilesMissing ? "plugin hook files missing" : null,
-                hookFilesChanged ? "plugin hook files changed" : null,
-                skillListChanged ? "skill directory list changed" : null,
-            ].filter(Boolean);
-            console.log(`  ${options.dryRun ? "would invalidate" : "invalidated"} Codex plugin discovery cache ${cacheDir} (${reasons.join(", ")})`);
-        }
-    }
-    return {
-        status: staleDirs.length > 0 ? "refreshed" : "unchanged",
-        staleDirs,
-    };
+async function discoverOmxPluginCacheDir(codexHomeDir = codexHome()) {
+    return (await discoverOmxPluginCacheDirs(codexHomeDir))[0] ?? null;
 }
 function resolveSetupMcpMode(scope, requestedMcpMode, persistedReviewDecision, persistedPreferences) {
     if (requestedMcpMode) {
@@ -2211,6 +2211,122 @@ function buildPluginModeLegacyConfig(original, options) {
     config = config.trim();
     return config.length > 0 ? `${config}\n` : "";
 }
+function stripLocalOmxPluginEnablementForDisable(config) {
+    const lines = config.split(/\r?\n/);
+    const header = '[plugins."oh-my-codex@oh-my-codex-local"]';
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start >= 0) {
+        let end = lines.length;
+        for (let index = start + 1; index < lines.length; index += 1) {
+            if (/^\s*\[/.test(lines[index])) {
+                end = index;
+                break;
+            }
+        }
+        for (let index = end - 1; index > start; index -= 1) {
+            if (/^\s*enabled\s*=\s*true\s*(?:#.*)?$/.test(lines[index])) {
+                lines[index] = lines[index].replace("true", "false");
+                break;
+            }
+        }
+    }
+    const pluginsStart = lines.findIndex((line) => /^\s*\[plugins\]\s*$/.test(line));
+    if (pluginsStart >= 0) {
+        for (let index = pluginsStart + 1; index < lines.length && !/^\s*\[/.test(lines[index]); index += 1) {
+            if (/^\s*"oh-my-codex@oh-my-codex-local"\s*=\s*true\s*(?:#.*)?$/.test(lines[index])) {
+                lines[index] = lines[index].replace("true", "false");
+                break;
+            }
+        }
+    }
+    return lines.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function stripHookFeatureFlagsForDisable(config, preserveNativeHooks) {
+    const lines = config.split(/\r?\n/);
+    const featuresStart = lines.findIndex((line) => /^\s*\[features\]\s*$/.test(line));
+    if (featuresStart < 0)
+        return config;
+    let sectionEnd = lines.length;
+    for (let index = featuresStart + 1; index < lines.length; index += 1) {
+        if (/^\s*\[\[?[^\]]+\]?\]\s*$/.test(lines[index])) {
+            sectionEnd = index;
+            break;
+        }
+    }
+    const removable = new Set(preserveNativeHooks
+        ? ["plugin_hooks"]
+        : ["hooks", "codex_hooks", "plugin_hooks"]);
+    for (let index = sectionEnd - 1; index > featuresStart; index -= 1) {
+        const match = /^\s*([A-Za-z0-9_-]+)\s*=\s*true\s*(?:#.*)?$/.exec(lines[index]);
+        if (match && removable.has(match[1]))
+            lines[index] = lines[index].replace("true", "false");
+    }
+    const nextFeaturesStart = lines.findIndex((line) => /^\s*\[features\]\s*$/.test(line));
+    if (nextFeaturesStart >= 0) {
+        let nextSectionEnd = lines.length;
+        for (let index = nextFeaturesStart + 1; index < lines.length; index += 1) {
+            if (/^\s*\[\[?[^\]]+\]?\]\s*$/.test(lines[index])) {
+                nextSectionEnd = index;
+                break;
+            }
+        }
+        if (lines.slice(nextFeaturesStart + 1, nextSectionEnd).every((line) => line.trim() === "")) {
+            lines.splice(nextFeaturesStart, nextSectionEnd - nextFeaturesStart);
+        }
+    }
+    return lines.join("\n");
+}
+function parseDisableHooksNotifyMetadata(snapshot, metadataPath, currentNotify) {
+    if (!snapshot.bytes) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to remove managed notification dispatcher: metadata ${metadataPath} is missing.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decodeNativeHookTransactionUtf8(snapshot.bytes, `notification metadata ${metadataPath}`));
+    }
+    catch (error) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to remove managed notification dispatcher: metadata ${metadataPath} is invalid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to remove managed notification dispatcher: metadata ${metadataPath} must be an object.`);
+    }
+    const metadata = parsed;
+    const dispatcherNotify = metadata.dispatcherNotify;
+    if (metadata.managedBy !== "oh-my-codex" || metadata.version !== 1 ||
+        !Array.isArray(dispatcherNotify) ||
+        dispatcherNotify.length !== currentNotify.length ||
+        dispatcherNotify.some((part, index) => part !== currentNotify[index])) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to remove managed notification dispatcher: metadata ${metadataPath} does not prove OMX ownership.`);
+    }
+    const previousNotify = metadata.previousNotify;
+    if (previousNotify !== null && (!Array.isArray(previousNotify) || !previousNotify.every((part) => typeof part === "string"))) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to remove managed notification dispatcher: metadata ${metadataPath} has invalid previousNotify.`);
+    }
+    return sanitizePreviousNotifyCommand(previousNotify, getPackageRoot());
+}
+async function planDisableHooksConfig(existingConfig, pkgRoot, managedHooksPlan, codexHomeDir, notifyMetadataSnapshot) {
+    const priorManagedHookTrustState = managedHooksPlan?.priorTrustState ?? {};
+    let finalConfig = stripManagedCodexHookTrustState(existingConfig, {
+        priorManagedHookTrustState,
+        managedTrustState: {},
+    });
+    finalConfig = stripHookFeatureFlagsForDisable(finalConfig, managedHooksPlan?.hasForeignHooks === true);
+    finalConfig = stripLocalOmxPluginEnablementForDisable(finalConfig);
+    const notify = getRootTomlArray(finalConfig, "notify");
+    if (!notify || !isOmxManagedNotifyCommand(notify, pkgRoot)) {
+        return { finalConfig, metadataAfter: null };
+    }
+    const metadataPath = getNotifyMetadataPath(codexHomeDir);
+    if (isOmxDispatcherNotifyCommand(notify, pkgRoot)) {
+        const previousNotify = parseDisableHooksNotifyMetadata(notifyMetadataSnapshot ?? { bytes: null, topology: { kind: "absent" } }, metadataPath, notify);
+        finalConfig = removeRootTomlKey(finalConfig, "notify");
+        if (previousNotify) {
+            finalConfig = insertRootTomlKey(finalConfig, `notify = ${formatTomlStringArray(previousNotify)}`);
+        }
+        return { finalConfig, metadataPath, metadataAfter: null };
+    }
+    return { finalConfig: removeRootTomlKey(finalConfig, "notify"), metadataAfter: null };
+}
 async function planNativeHookSetupTransaction(options) {
     const existingConfigSnapshot = options.configSnapshot;
     const existingHooksSnapshot = await captureNativeHookTransactionArtifact(options.hooksPath, `native hooks ${options.hooksPath}`);
@@ -2231,7 +2347,29 @@ async function planNativeHookSetupTransaction(options) {
     let notifyMetadataPrecondition = null;
     let modelUpgrade;
     let repairedLegacyTeamRunTable = false;
-    if (options.isPluginInstallMode) {
+    if (options.disableHooks) {
+        let managedHooksPlan = null;
+        if (existingHooksContent !== null) {
+            const removal = planManagedCodexHooksRemoval(existingHooksContent, options.hooksPath, {
+                platform: options.platform,
+                codexHomeDir: options.codexHomeDir,
+            });
+            if (!removal.ok)
+                throw removal.error;
+            managedHooksPlan = removal;
+            finalHooksContent = removal.finalContent;
+            hooksRemovedCount = removal.removedCount;
+            diagnostics = removal.diagnostics;
+        }
+        const notifyPlan = await planDisableHooksConfig(existingConfig, options.pkgRoot, managedHooksPlan, options.codexHomeDir, options.notifyMetadataSnapshot);
+        finalConfig = notifyPlan.finalConfig;
+        if (notifyPlan.metadataPath) {
+            const metadataBefore = options.notifyMetadataSnapshot ?? { bytes: null, topology: { kind: "absent" } };
+            notifyMetadataPrecondition = nativeHookTransactionPrecondition("metadata", notifyPlan.metadataPath, `notification metadata ${notifyPlan.metadataPath}`, metadataBefore);
+            notifyMetadataArtifact = nativeHookTransactionArtifact("metadata", notifyPlan.metadataPath, `notification metadata ${notifyPlan.metadataPath}`, metadataBefore, notifyPlan.metadataAfter);
+        }
+    }
+    if (!options.disableHooks && options.isPluginInstallMode) {
         const pluginPlan = buildPluginModeHooksConfigPlan(existingConfig, existingHooksContent, options.pkgRoot, options.hooksPath, options.codexHomeDir, {
             codexHookFeatureFlag: options.codexHookFeatureFlag,
             pluginScopedHooks: options.pluginScopedHooks,
@@ -2257,7 +2395,7 @@ async function planNativeHookSetupTransaction(options) {
         finalConfig = developerInstructionsPlan.finalConfig;
         pluginDeveloperInstructionsResult = developerInstructionsPlan.result;
     }
-    else {
+    else if (!options.disableHooks) {
         const managedHooksPlan = planManagedCodexHooksMerge(existingHooksContent, options.pkgRoot, options.hooksPath, {
             platform: options.platform,
             codexHomeDir: options.codexHomeDir,
@@ -2308,7 +2446,7 @@ async function planNativeHookSetupTransaction(options) {
             }
         }
     }
-    if (options.isPluginInstallMode && options.sharedMcpRegistry.servers.length > 0) {
+    if (!options.disableHooks && options.isPluginInstallMode && options.sharedMcpRegistry.servers.length > 0) {
         finalConfig = mergeSharedMcpRegistryBlock(finalConfig, options.sharedMcpRegistry.servers, options.sharedMcpRegistry.sourcePath);
     }
     try {
@@ -2327,8 +2465,9 @@ async function planNativeHookSetupTransaction(options) {
         const shimAfter = Buffer.from(buildManagedCodexNativeHookWindowsShimContent(options.pkgRoot), "utf-8");
         assertWindowsNativeHookShimOwnership(shimPath, shimSnapshot.bytes, shimAfter);
         const shimReference = decideWindowsNativeHookShimReference(finalHooksContent, shimPath);
-        shimArtifact = nativeHookTransactionArtifact("shim", shimPath, `native hook Windows shim ${shimPath}`, shimSnapshot, options.isPluginInstallMode && options.pluginScopedHooks &&
-            shimReference === "not_referenced"
+        const shouldDeleteShim = shimReference === "not_referenced" &&
+            (options.disableHooks || (options.isPluginInstallMode && options.pluginScopedHooks));
+        shimArtifact = nativeHookTransactionArtifact("shim", shimPath, `native hook Windows shim ${shimPath}`, shimSnapshot, shouldDeleteShim
             ? null
             : shimAfter);
         shimPrecondition = nativeHookTransactionPrecondition("shim", shimPath, `native hook Windows shim ${shimPath}`, shimSnapshot);
@@ -2371,7 +2510,7 @@ async function planNativeHookSetupTransaction(options) {
     };
 }
 export async function setup(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 { disableHooks = false, 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 });
@@ -2434,7 +2573,7 @@ export async function setup(options = {}) {
     const scopeDirs = resolveScopeDirectories(resolvedScope.scope, projectRoot);
     if (!dryRun) {
         const recoveryTracker = { degraded: false };
-        const recovery = await recoverNativeHookClaimJournal(scopeDirs.codexHomeDir, nativeHookClaimJournalDurability());
+        const recovery = await recoverNativeHookClaimJournal(scopeDirs.codexHomeDir, nativeHookClaimJournalDurability(recoveryTracker));
         recordRegularFileSyncOutcome(recoveryTracker, recovery.outcome);
         if (recovery.recovered) {
             emitDegradedDurabilityWarning("native-hook claim-journal recovery", recoveryTracker);
@@ -2458,6 +2597,9 @@ export async function setup(options = {}) {
     const notifyMetadataSnapshot = configRequiresNotificationMetadataSnapshot(existingConfigForMcpMigration, pkgRoot, resolvedScope.scope)
         ? await captureNativeHookTransactionArtifact(getNotifyMetadataPath(scopeDirs.codexHomeDir), `notification metadata ${getNotifyMetadataPath(scopeDirs.codexHomeDir)}`)
         : undefined;
+    if (disableHooks && !notifyMetadataSnapshot && isOmxDispatcherNotifyCommand(getRootTomlArray(existingConfigForMcpMigration, "notify"), pkgRoot)) {
+        throw new ManagedCodexHooksPlanError("invalid_document", `Refusing to disable OMX hooks: managed notification metadata is unavailable for ${getNotifyMetadataPath(scopeDirs.codexHomeDir)}.`);
+    }
     const firstPartyMcpRegistrationKinds = [
         hasFirstPartyOmxMcpRegistrations(existingConfigForMcpMigration)
             ? "config.toml [mcp_servers.omx_*]"
@@ -2480,6 +2622,7 @@ export async function setup(options = {}) {
     }
     const scopeSourceMessage = resolvedScope.source === "persisted" ? " (from .omx/setup-scope.json)" : "";
     const backupContext = getBackupContext(resolvedScope.scope, projectRoot);
+    const skillReceiptPath = installedSkillReceiptPath(resolvedScope.scope, projectRoot);
     const isPluginInstallMode = resolvedInstallMode?.installMode === "plugin";
     const pluginAgentsMdDst = resolvedScope.scope === "project"
         ? join(projectRoot, "AGENTS.md")
@@ -2553,6 +2696,7 @@ export async function setup(options = {}) {
         forceStatusLinePreset: force,
         configSnapshot: existingConfigForMcpMigrationSnapshot,
         notifyMetadataSnapshot,
+        disableHooks,
     });
     const summary = createEmptyRunSummary();
     for (const precondition of nativeHookSetupTransaction.preconditions) {
@@ -2560,6 +2704,14 @@ export async function setup(options = {}) {
         await assertNativeHookTransactionPrecondition(precondition);
     }
     await assertNativeHookTransactionAncestorPrecondition(nativeHookTransactionAncestorPrecondition);
+    if (disableHooks) {
+        const disableSummary = createEmptyRunSummary();
+        const durabilityTracker = { degraded: false };
+        await commitNativeHookTransaction(nativeHookSetupTransaction.artifacts, nativeHookSetupTransaction.preconditions, nativeHookTransactionAncestorPrecondition, backupContext, durabilityTracker, disableSummary.config, { dryRun, verbose });
+        emitDegradedDurabilityWarning("native-hook setup", durabilityTracker);
+        console.log(`${dryRun ? "Would disable" : "Disabled"} OMX hook registrations; non-OMX hooks and .omx artifacts were preserved.`);
+        return;
+    }
     console.log("oh-my-codex setup");
     console.log("=================\n");
     console.log(`Using setup scope: ${resolvedScope.scope}${scopeSourceMessage}\n`);
@@ -2673,7 +2825,7 @@ export async function setup(options = {}) {
         const skillsDst = scopeDirs.skillsDir;
         if (isPluginInstallMode) {
             summary.skills = createEmptyCategorySummary();
-            const cleanup = await cleanupLegacyManagedSkills(skillsSrc, skillsDst, backupContext, { dryRun, verbose });
+            const cleanup = await cleanupLegacyManagedSkills(skillsSrc, skillsDst, backupContext, { dryRun, verbose, skillReceiptPath });
             summary.skills.backedUp += cleanup.backedUp;
             summary.skills.removed += cleanup.removedSkillNames.length;
             summary.skills.skipped += cleanup.skippedSkillNames.length;
@@ -2692,6 +2844,7 @@ export async function setup(options = {}) {
                 force,
                 dryRun,
                 verbose,
+                skillReceiptPath,
                 teamMode: resolvedTeamMode,
             });
         }
@@ -2718,7 +2871,7 @@ export async function setup(options = {}) {
         });
         console.log(`  Native agent role refresh complete (${scopeDirs.nativeAgentsDir}); plugin mode still installs role TOML so agent_type routing works.\n`);
     }
-    else {
+    else if (!options.disableHooks) {
         summary.nativeAgents = await refreshNativeAgentConfigs(pkgRoot, scopeDirs.nativeAgentsDir, backupContext, {
             force,
             dryRun,
@@ -2793,18 +2946,6 @@ export async function setup(options = {}) {
         else {
             console.log(`  Local Codex plugin marketplace ${OMX_LOCAL_MARKETPLACE_NAME} already registered (${pkgRoot}).`);
         }
-        const pluginCacheRefresh = await refreshOmxPluginDiscoveryCache(pkgRoot, {
-            dryRun,
-            verbose,
-        }, scopeDirs.codexHomeDir);
-        if (pluginCacheRefresh.status === "refreshed") {
-            if (pluginCacheRefresh.staleDirs.length > 0) {
-                console.log(`  ${dryRun ? "Would invalidate" : "Invalidated"} ${pluginCacheRefresh.staleDirs.length} stale Codex plugin discovery cache entr${pluginCacheRefresh.staleDirs.length === 1 ? "y" : "ies"} so plugin skills refresh from the packaged manifest.`);
-            }
-        }
-        else if (pluginCacheRefresh.status === "unchanged") {
-            console.log("  Codex plugin discovery cache already matches packaged plugin metadata.");
-        }
         const pluginCacheMaterialize = await materializePackagedOmxPluginCache(scopeDirs.codexHomeDir, preflightMarketplace, { dryRun, teamMode: resolvedTeamMode });
         if (pluginCacheMaterialize.status === "materialized") {
             console.log(`  ${dryRun ? "Would install" : "Installed"} local Codex plugin cache for ${OMX_LOCAL_MARKETPLACE_NAME}/${OMX_PLUGIN_NAME} at ${pluginCacheMaterialize.cacheDir}.`);
@@ -2865,7 +3006,11 @@ export async function setup(options = {}) {
     const activeSession = resolvedScope.scope === "project"
         ? await readSessionState(projectRoot)
         : null;
-    const sessionIsActive = activeSession && !isSessionStale(activeSession);
+    // Only a definitely dead session releases the overlay. macOS records no process-birth evidence, so
+    // a live session classifies as identity-indeterminate; treating that as stale would let setup
+    // overwrite the AGENTS.md overlay of a running session.
+    const sessionIsActive = activeSession !== null &&
+        classifySessionStateLiveness(activeSession) !== "stale-dead";
     if (isPluginInstallMode) {
         const agentsMdSrc = join(pkgRoot, "templates", "AGENTS.md");
         const pluginAgentsMdExists = pluginAgentsMdPathExists;
@@ -3639,7 +3784,14 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
         : null;
     const isSetupInstallableSkill = (skillName, status) => isCatalogInstallableStatus(status) || installableSkillNames.has(skillName);
     const entries = await readdir(srcDir, { withFileTypes: true });
-    const staleCandidateSkillNames = new Set(manifest?.skills.map((skill) => skill.name) ?? []);
+    const catalogKnownSkillNames = new Set(manifest?.skills.map((skill) => skill.name) ?? []);
+    const staleCandidateSkillNames = new Set(catalogKnownSkillNames);
+    if (existsSync(dstDir)) {
+        for (const installed of await readdir(dstDir, { withFileTypes: true })) {
+            if (installed.isDirectory())
+                staleCandidateSkillNames.add(installed.name);
+        }
+    }
     for (const entry of entries) {
         if (!entry.isDirectory())
             continue;
@@ -3674,6 +3826,7 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
     for (const skill of installableSkills) {
         await validateSkillFile(join(skill.sourceDir, "SKILL.md"));
     }
+    const writtenFilesBySkill = new Map();
     for (const skill of installableSkills) {
         const skillName = skill.name;
         const skillSrc = skill.sourceDir;
@@ -3682,18 +3835,27 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
             await mkdir(skillDst, { recursive: true });
         }
         const skillFiles = await readdir(skillSrc);
+        const writtenForSkill = [];
         for (const sf of skillFiles) {
             const sfPath = join(skillSrc, sf);
             const sfStat = await stat(sfPath);
             if (!sfStat.isFile())
                 continue;
             const dstPath = join(skillDst, sf);
+            writtenForSkill.push(sf);
             if (sf === "SKILL.md") {
                 await syncManagedContent(rewriteInstalledSkillDescriptionBadge(await readFile(sfPath, "utf-8"), sfPath), dstPath, summary, backupContext, options, `skill ${skillName}/${sf}`);
                 continue;
             }
             await syncManagedFileFromDisk(sfPath, dstPath, summary, backupContext, options, `skill ${skillName}/${sf}`);
         }
+        writtenFilesBySkill.set(skillName, writtenForSkill);
+    }
+    // Record what we just wrote so a later refresh can prove an unmodified install before retiring it.
+    // Without an authority path, refuse to create a receipt rather than placing deletion authority
+    // in the user-writable skills directory.
+    if (options.skillReceiptPath) {
+        await writeInstalledSkillReceipt(options.skillReceiptPath, dstDir, writtenFilesBySkill, options);
     }
     if (manifest && existsSync(dstDir)) {
         for (const staleSkill of staleCandidateSkillNames) {
@@ -3701,14 +3863,32 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
             const disabledTeamSkill = !teamModeEnabled(options.teamMode) && TEAM_MODE_SKILL_NAMES.has(staleSkill);
             if (isSetupInstallableSkill(staleSkill, status) && !disabledTeamSkill)
                 continue;
-            const hardDeprecated = HARD_DEPRECATED_SKILL_NAMES.has(staleSkill);
-            if (!options.force && !hardDeprecated && !disabledTeamSkill)
-                continue;
             const staleSkillDir = join(dstDir, staleSkill);
             if (!existsSync(staleSkillDir))
                 continue;
-            if (!options.dryRun) {
-                await rm(staleSkillDir, { recursive: true, force: true });
+            // A directory the catalog no longer ships is ours to retire on any refresh - which is what
+            // makes `omx update` drop deprecated skills without an extra flag - but only when we can
+            // prove it is an UNMODIFIED install we wrote. The badge alone is not proof: a user who
+            // edits the body keeps it, and archiving their edit is not preserving it.
+            const unmodifiedInstall = Boolean(options.skillReceiptPath)
+                && await isUnmodifiedRecordedInstall(options.skillReceiptPath, staleSkill, staleSkillDir);
+            const omxManaged = await isOmxManagedInstalledSkillDir(staleSkillDir) && unmodifiedInstall;
+            const forcedCatalogSkill = options.force && catalogKnownSkillNames.has(staleSkill);
+            // Disabling Team mode is a configuration change, not a destructive opt-in, so it must not
+            // delete a directory we cannot prove we wrote. --force remains the explicit destructive path.
+            const removableDisabledTeamSkill = disabledTeamSkill && unmodifiedInstall;
+            if (!omxManaged && !forcedCatalogSkill && !removableDisabledTeamSkill) {
+                summary.skipped += 1;
+                if (options.verbose) {
+                    const why = await isOmxManagedInstalledSkillDir(staleSkillDir)
+                        ? "modified since install, or installed before receipts existed"
+                        : "not an OMX-managed skill install";
+                    console.log(`  kept ${staleSkill}/ (${why})`);
+                }
+                continue;
+            }
+            if (await removeDirectoryCopyAware(staleSkillDir, backupContext, options)) {
+                summary.backedUp += 1;
             }
             summary.removed += 1;
             if (options.verbose) {
@@ -3716,9 +3896,9 @@ export async function installSkills(srcDir, dstDir, backupContext, options) {
                     ? "would remove stale skill"
                     : "removed stale skill";
                 const label = status ?? "unlisted";
-                const reason = disabledTeamSkill
+                const reason = removableDisabledTeamSkill
                     ? ", Team mode disabled"
-                    : hardDeprecated ? ", hard-deprecated" : "";
+                    : omxManaged ? ", retired from the catalog" : "";
                 console.log(`  ${prefix} ${staleSkill}/ (status: ${label}${reason})`);
             }
         }
@@ -3776,12 +3956,42 @@ async function cleanupLegacyManagedSkills(srcDir, dstDir, backupContext, options
             result.warnings.push(warning);
             continue;
         }
+        // A matching SKILL.md does not prove the whole directory is ours: a user file sitting beside it
+        // would be deleted with the directory. Require the same unmodified-install proof the ordinary
+        // retirement sweep uses.
+        if (!options.skillReceiptPath || !(await isUnmodifiedRecordedInstall(options.skillReceiptPath, skillName, installedSkillDir))) {
+            const warning = `Skipping legacy skill cleanup for ${skillName}: directory contents are not a receipted unmodified OMX install.`;
+            result.skippedSkillNames.push(skillName);
+            result.warnings.push(warning);
+            continue;
+        }
         const removed = await removeDirectoryCopyAware(installedSkillDir, backupContext, options);
         if (removed) {
             result.backedUp += 1;
             result.removedSkillNames.push(skillName);
         }
     }
+    // Plugin mode never reinstalls into the legacy directory, so a skill the catalog has retired
+    // would otherwise survive there forever. Retire OMX-badged orphans on every refresh.
+    for (const entry of await readdir(dstDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (installableSkillNames.has(entry.name))
+            continue;
+        const installedSkillDir = join(dstDir, entry.name);
+        if (!(await isOmxManagedInstalledSkillDir(installedSkillDir)))
+            continue;
+        // The badge alone is not proof of ownership for deletion; a user-edited body keeps it.
+        if (!options.skillReceiptPath || !(await isUnmodifiedRecordedInstall(options.skillReceiptPath, entry.name, installedSkillDir))) {
+            result.skippedSkillNames.push(entry.name);
+            result.warnings.push(`Skipping retired skill ${entry.name}: modified since install, or installed before receipts existed.`);
+            continue;
+        }
+        if (await removeDirectoryCopyAware(installedSkillDir, backupContext, options)) {
+            result.backedUp += 1;
+            result.removedSkillNames.push(entry.name);
+        }
+    }
     return result;
 }
 function getNotifyMetadataPath(codexHomeDir) {