superpowers-manager 0.5.1 → 0.6.0

package/dist/harnesses/codex/adapter.js

@@ -2,23 +2,31 @@ import { Buffer } from "node:buffer";
 import { execFile } from "node:child_process";
 import { constants } from "node:fs";
 import { access, copyFile, mkdir, readFile, realpath, stat, writeFile, } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import { delimiter, isAbsolute, join } from "node:path";
-import { AdapterMessageLog, failureResult, successResult, } from "../../adapter-result.js";
-import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./json.js";
+import { AdapterMessageLog, failureResult, hasTerminalControl, successResult, } from "../../adapter-result.js";
+import { activePluginVersionFromJson, codexInstalledPluginsFromJson, installedListingHas, marketplaceRootFromJson, } from "./json.js";
 import { CODEX_LEGACY_PLUGIN_ID, CODEX_MANAGER_PLUGIN_ID, inspectCodexConflicts, } from "./conflicts.js";
 import { oneLine } from "../../cli-arguments.js";
-import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./state.js";
+import { installedRootForVersion, pathsEqual } from "./state.js";
+import { codexHome } from "./paths.js";
+import { readCodexStoredState } from "./stored-state.js";
 import { validateGeneratedPlugin } from "./generated-plugin.js";
 import { classifyHooks, materializeHooks, readManifest, } from "./hooks.js";
 import { applyManifestOverlay } from "./manifest-overlay.js";
 import { readCodexBuildSource } from "../../provenance.js";
 import { isAcceptedSplitValue } from "../../validate-generated-plugin-cli.js";
-import { withWorkspace, workspaceRemovalFailure } from "../../workspace.js";
+import { codexControlInspection, codexOwnershipInspection, } from "./lifecycle.js";
+import { codexInstallReceipt } from "./presentation.js";
 const PLUGIN_ID = CODEX_MANAGER_PLUGIN_ID;
 const MARKETPLACE_NAME = "superpowers-manager";
 const LEGACY_PLUGIN_ID = CODEX_LEGACY_PLUGIN_ID;
 const LEGACY_MARKETPLACE_NAME = "superpowers-wrapper";
+export function codexInstallRefreshMode(env) {
+    const refreshMode = env.SUPERPOWERS_INSTALL_REFRESH_MODE || "add-only";
+    return refreshMode === "add-only" || refreshMode === "remove-add"
+        ? refreshMode
+        : null;
+}
 class AdapterFailure extends Error {
     code;
     hints;
@@ -31,28 +39,6 @@ class AdapterFailure extends Error {
 function fail(code, message, hints = []) {
     throw new AdapterFailure(code, message, hints);
 }
-function parseFlags(argv, allowed) {
-    const values = {};
-    for (let index = 0; index < argv.length; index += 2) {
-        const flag = argv[index];
-        if (!allowed.includes(flag)) {
-            fail("invalid-arguments", `unknown flag: ${flag}`);
-        }
-        if (index + 1 >= argv.length) {
-            fail("invalid-arguments", `missing value for ${flag}`);
-        }
-        if (Object.hasOwn(values, flag)) {
-            fail("invalid-arguments", `duplicate flag: ${flag}`);
-        }
-        values[flag] = argv[index + 1];
-    }
-    for (const flag of allowed) {
-        if (!Object.hasOwn(values, flag)) {
-            fail("invalid-arguments", `missing required flag: ${flag}`);
-        }
-    }
-    return values;
-}
 function runCommand(file, args, env) {
     // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/common.sh:71::NODE_OPTIONS`
     // is the system's only scrubbing site and it dies with scripts/ in 4c.
@@ -95,6 +81,14 @@ export { runCommand as runCommandForTest };
 function commandFailed(result) {
     return result.status !== 0;
 }
+async function storedStateAfterListingFailure(env, code, message) {
+    try {
+        return await readCodexStoredState(env, process.cwd());
+    }
+    catch {
+        fail(code, message);
+    }
+}
 // Exported only so its unit test can reach it. No integration test can cover
 // it: on Linux glibc, `execvp`'s ENOEXEC falls back to `/bin/sh`, so the spawn
 // still succeeds, and every other candidate errno is already peeled off by an
@@ -130,11 +124,6 @@ async function runCodexCommand(codexBin, args, env) {
         return mapCodexLaunchFailure(cause, codexBin);
     }
 }
-function reportOrphanedWorkspace(log) {
-    return (path) => {
-        log.appendText("stderr", workspaceRemovalFailure(path));
-    };
-}
 async function mutationCommand(log, codexBin, args, env) {
     const result = await runCodexCommand(codexBin, args, env);
     log.appendBytes("stderr", result.stdout);
@@ -172,16 +161,6 @@ async function requireCodex(codexBin, env) {
         fail("command-not-found", `required Codex command not found: ${codexBin}`);
     }
 }
-const BUILD_FLAGS = [
-    "--upstream-root",
-    "--candidate-root",
-    "--requested-ref",
-    "--resolved-ref",
-    "--commit",
-    "--manager-version",
-    "--upstream-manifest-version",
-    "--fallback-manifest",
-];
 async function directoryExists(path) {
     try {
         return (await stat(path)).isDirectory();
@@ -215,165 +194,153 @@ async function runBuild(input, env, log) {
     if (!(await fileExists(fallbackManifest))) {
         fail("invalid-arguments", `fallback manifest not found: ${fallbackManifest}`);
     }
-    let entered = false;
+    const candidateManifest = join(candidateRoot, ".codex-plugin/plugin.json");
+    const upstreamManifest = join(upstreamRoot, ".codex-plugin/plugin.json");
+    const manifestSource = (await fileExists(upstreamManifest))
+        ? "upstream"
+        : "fallback";
     try {
-        return await withWorkspace(tmpdir(), "superpowers-manager.adapter-build.", async () => {
-            entered = true;
-            const candidateManifest = join(candidateRoot, ".codex-plugin/plugin.json");
-            const upstreamManifest = join(upstreamRoot, ".codex-plugin/plugin.json");
-            const manifestSource = (await fileExists(upstreamManifest))
-                ? "upstream"
-                : "fallback";
-            try {
-                await mkdir(join(candidateRoot, ".codex-plugin"), {
-                    recursive: true,
-                });
-                await copyFile(manifestSource === "upstream" ? upstreamManifest : fallbackManifest, candidateManifest);
-            }
-            catch {
-                fail("build-failed", manifestSource === "upstream"
-                    ? "cannot copy upstream manifest into candidate"
-                    : "cannot copy fallback manifest into candidate");
-            }
-            let plan;
-            let sourceRoot;
-            let realCandidateRoot;
-            try {
-                sourceRoot = await realpath(upstreamRoot);
-                realCandidateRoot = await realpath(candidateRoot);
-                const manifest = await readManifest(candidateManifest);
-                plan = await classifyHooks(manifest, manifestSource, sourceRoot);
-            }
-            catch (cause) {
-                log.appendText("stderr", `hook classification failed: ${oneLine(cause)}`);
-                fail("build-failed", "failed to prepare upstream Codex hooks");
-            }
-            try {
-                await materializeHooks(plan, sourceRoot, realCandidateRoot);
-            }
-            catch (cause) {
-                log.appendText("stderr", `hook materialization failed: ${oneLine(cause)}`);
-                fail("build-failed", "failed to prepare upstream Codex hooks");
-            }
-            let source;
-            try {
-                // Decoded fatally, not leniently: the file can change between this read and `readManifest`'s read above.
-                const rawManifestBytes = await readFile(candidateManifest);
-                source = new TextDecoder("utf-8", {
-                    fatal: true,
-                    ignoreBOM: true,
-                }).decode(rawManifestBytes);
-            }
-            catch {
-                // Deliberately drops the cause. The Python interpolated the raw OSError here:
-                // `git show 0b6d50e1e9c688397285c6fa274dc8c9437d8ba3:scripts/adapters/codex/apply-manifest-overlay.py:42::read`,
-                // putting "[Errno 2] No such file or directory" on the operator's stream.
-                // The prefix is preserved; the errno leak is not.
-                log.appendText("stderr", `cannot read manifest JSON in ${candidateManifest}`);
-                fail("build-failed", "failed to apply manager manifest overlay");
-            }
-            let overlaid;
-            try {
-                overlaid = applyManifestOverlay(source, input.managerVersion, candidateManifest);
-            }
-            catch (cause) {
-                // applyManifestOverlay's own messages already name the manifest
-                // path — three are the frozen CPython wording, and the fourth (the
-                // numeric-overflow diagnostic, which has no CPython oracle wording
-                // to match) now carries the path via its own rewrap in
-                // src/harnesses/codex/manifest-overlay.ts. Emit as-is, with no added prefix — a
-                // prefix here would double up the path these messages already
-                // name.
-                log.appendText("stderr", oneLine(cause));
-                fail("build-failed", "failed to apply manager manifest overlay");
-            }
-            try {
-                await writeFile(candidateManifest, overlaid, "utf8");
-            }
-            catch {
-                log.appendText("stderr", `cannot write manifest JSON in ${candidateManifest}`);
-                fail("build-failed", "failed to apply manager manifest overlay");
-            }
-            try {
-                await copyFile(fallbackManifest, join(candidateRoot, ".codex-plugin/plugin.template.json"));
-            }
-            catch {
-                fail("build-failed", "cannot copy fallback manifest template into candidate");
-            }
-            let upstreamSource;
-            try {
-                upstreamSource = await readCodexBuildSource(join(candidateRoot, ".superpowers-upstream.json"));
-            }
-            catch {
-                fail("invalid-provenance", "candidate provenance is missing or invalid");
-            }
-            // The seven values the validator CLI would receive in split form:
-            // --plugin-root, --requested-ref, --resolved-ref, --commit,
-            // --manifest-version, --manifest-source, --upstream-manifest-version.
-            // The eighth, --source, is passed attached, where argparse accepts any
-            // dash-leading value, so it is deliberately absent here. Each value is
-            // paired with the ADAPTER-facing flag name to report: --manager-version
-            // (the CLI calls it --manifest-version) and --plugin-root /
-            // --manifest-source (derived, not user-supplied) deliberately differ
-            // from the validator CLI's own names, since the operator can only act
-            // on the adapter's surface.
-            const splitValues = [
-                { value: candidateRoot, name: "--plugin-root" },
-                { value: input.requestedRef, name: "--requested-ref" },
-                { value: input.resolvedRef, name: "--resolved-ref" },
-                { value: input.commit, name: "--commit" },
-                { value: input.managerVersion, name: "--manager-version" },
-                { value: manifestSource, name: "--manifest-source" },
-                {
-                    value: input.upstreamManifestVersion,
-                    name: "--upstream-manifest-version",
-                },
-            ];
-            const firstRejected = splitValues.find(({ value }) => !isAcceptedSplitValue(value));
-            if (firstRejected !== undefined) {
-                // Declared exception to message-record parity: argparse wrote usage
-                // records here; this guard precedes the call and writes a
-                // differently-worded record naming the rejected flag instead. The
-                // failure code and message are unchanged.
-                const text = "Generated plugin validation failed:\n" +
-                    `- validator argument \`${firstRejected.name}\` has a dash-leading value the argument parser rejects\n`;
-                log.appendBytes("stderr", Buffer.from(text, "utf8"));
-                fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
-            }
-            let errors;
-            try {
-                errors = await validateGeneratedPlugin({
-                    pluginRoot: candidateRoot,
-                    source: upstreamSource,
-                    requestedRef: input.requestedRef,
-                    resolvedRef: input.resolvedRef,
-                    commit: input.commit,
-                    manifestVersion: input.managerVersion,
-                    manifestSource,
-                    upstreamManifestVersion: input.upstreamManifestVersion,
-                });
-            }
-            catch {
-                fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
-            }
-            if (errors.length > 0) {
-                // appendBytes, not appendText: one record per line, matching what
-                // mutationCommand writes from the subprocess streams.
-                const text = "Generated plugin validation failed:\n" +
-                    errors.map((error) => `- ${error}\n`).join("");
-                log.appendBytes("stderr", Buffer.from(text, "utf8"));
-                fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
-            }
-            log.appendBytes("stdout", Buffer.from(`generated plugin validation passed: ${candidateRoot}\n`, "utf8"));
-            return {};
-        }, { onCleanupFailure: reportOrphanedWorkspace(log) });
+        await mkdir(join(candidateRoot, ".codex-plugin"), {
+            recursive: true,
+        });
+        await copyFile(manifestSource === "upstream" ? upstreamManifest : fallbackManifest, candidateManifest);
+    }
+    catch {
+        fail("build-failed", manifestSource === "upstream"
+            ? "cannot copy upstream manifest into candidate"
+            : "cannot copy fallback manifest into candidate");
+    }
+    let plan;
+    let sourceRoot;
+    let realCandidateRoot;
+    try {
+        sourceRoot = await realpath(upstreamRoot);
+        realCandidateRoot = await realpath(candidateRoot);
+        const manifest = await readManifest(candidateManifest);
+        plan = await classifyHooks(manifest, manifestSource, sourceRoot);
     }
     catch (cause) {
-        if (!entered) {
-            fail("build-failed", `cannot create adapter build workspace under ${tmpdir()}`);
-        }
-        throw cause;
+        log.appendText("stderr", `hook classification failed: ${oneLine(cause)}`);
+        fail("build-failed", "failed to prepare upstream Codex hooks");
+    }
+    try {
+        await materializeHooks(plan, sourceRoot, realCandidateRoot);
+    }
+    catch (cause) {
+        log.appendText("stderr", `hook materialization failed: ${oneLine(cause)}`);
+        fail("build-failed", "failed to prepare upstream Codex hooks");
+    }
+    let source;
+    try {
+        // Decoded fatally, not leniently: the file can change between this read and `readManifest`'s read above.
+        const rawManifestBytes = await readFile(candidateManifest);
+        source = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(rawManifestBytes);
+    }
+    catch {
+        // Deliberately drops the cause. The Python interpolated the raw OSError here:
+        // `git show 0b6d50e1e9c688397285c6fa274dc8c9437d8ba3:scripts/adapters/codex/apply-manifest-overlay.py:42::read`,
+        // putting "[Errno 2] No such file or directory" on the operator's stream.
+        // The prefix is preserved; the errno leak is not.
+        log.appendText("stderr", `cannot read manifest JSON in ${candidateManifest}`);
+        fail("build-failed", "failed to apply manager manifest overlay");
+    }
+    let overlaid;
+    try {
+        overlaid = applyManifestOverlay(source, input.managerVersion, candidateManifest);
+    }
+    catch (cause) {
+        // applyManifestOverlay's own messages already name the manifest
+        // path — three are the frozen CPython wording, and the fourth (the
+        // numeric-overflow diagnostic, which has no CPython oracle wording
+        // to match) now carries the path via its own rewrap in
+        // src/harnesses/codex/manifest-overlay.ts. Emit as-is, with no added prefix — a
+        // prefix here would double up the path these messages already
+        // name.
+        log.appendText("stderr", oneLine(cause));
+        fail("build-failed", "failed to apply manager manifest overlay");
+    }
+    try {
+        await writeFile(candidateManifest, overlaid, "utf8");
     }
+    catch {
+        log.appendText("stderr", `cannot write manifest JSON in ${candidateManifest}`);
+        fail("build-failed", "failed to apply manager manifest overlay");
+    }
+    try {
+        await copyFile(fallbackManifest, join(candidateRoot, ".codex-plugin/plugin.template.json"));
+    }
+    catch {
+        fail("build-failed", "cannot copy fallback manifest template into candidate");
+    }
+    let upstreamSource;
+    try {
+        upstreamSource = await readCodexBuildSource(join(candidateRoot, ".superpowers-upstream.json"));
+    }
+    catch {
+        fail("invalid-provenance", "candidate provenance is missing or invalid");
+    }
+    // The seven values the validator CLI would receive in split form:
+    // --plugin-root, --requested-ref, --resolved-ref, --commit,
+    // --manifest-version, --manifest-source, --upstream-manifest-version.
+    // The eighth, --source, is passed attached, where argparse accepts any
+    // dash-leading value, so it is deliberately absent here. Each value is
+    // paired with the ADAPTER-facing flag name to report: --manager-version
+    // (the CLI calls it --manifest-version) and --plugin-root /
+    // --manifest-source (derived, not user-supplied) deliberately differ
+    // from the validator CLI's own names, since the operator can only act
+    // on the adapter's surface.
+    const splitValues = [
+        { value: candidateRoot, name: "--plugin-root" },
+        { value: input.requestedRef, name: "--requested-ref" },
+        { value: input.resolvedRef, name: "--resolved-ref" },
+        { value: input.commit, name: "--commit" },
+        { value: input.managerVersion, name: "--manager-version" },
+        { value: manifestSource, name: "--manifest-source" },
+        {
+            value: input.upstreamManifestVersion,
+            name: "--upstream-manifest-version",
+        },
+    ];
+    const firstRejected = splitValues.find(({ value }) => !isAcceptedSplitValue(value));
+    if (firstRejected !== undefined) {
+        // Declared exception to message-record parity: argparse wrote usage
+        // records here; this guard precedes the call and writes a
+        // differently-worded record naming the rejected flag instead. The
+        // failure code and message are unchanged.
+        const text = "Generated plugin validation failed:\n" +
+            `- validator argument \`${firstRejected.name}\` has a dash-leading value the argument parser rejects\n`;
+        log.appendBytes("stderr", Buffer.from(text, "utf8"));
+        fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
+    }
+    let errors;
+    try {
+        errors = await validateGeneratedPlugin({
+            pluginRoot: candidateRoot,
+            source: upstreamSource,
+            requestedRef: input.requestedRef,
+            resolvedRef: input.resolvedRef,
+            commit: input.commit,
+            manifestVersion: input.managerVersion,
+            manifestSource,
+            upstreamManifestVersion: input.upstreamManifestVersion,
+        });
+    }
+    catch {
+        fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
+    }
+    if (errors.length > 0) {
+        // appendBytes, not appendText: one record per line, matching what
+        // mutationCommand writes from the subprocess streams.
+        const text = "Generated plugin validation failed:\n" +
+            errors.map((error) => `- ${error}\n`).join("");
+        log.appendBytes("stderr", Buffer.from(text, "utf8"));
+        fail("generated-plugin-validation-failed", "built-in generated plugin validation failed");
+    }
+    log.appendBytes("stdout", Buffer.from(`generated plugin validation passed: ${candidateRoot}\n`, "utf8"));
+    return {};
 }
 async function runInstall(packageRoot, env, log) {
     if (!isAbsolute(packageRoot)) {
@@ -383,224 +350,133 @@ async function runInstall(packageRoot, env, log) {
         fail("invalid-arguments", `package root not found: ${packageRoot}`);
     }
     const codexBin = env.SUPERPOWERS_CODEX || "codex";
-    const refreshMode = env.SUPERPOWERS_INSTALL_REFRESH_MODE || "add-only";
+    const refreshMode = codexInstallRefreshMode(env);
     await requireCodex(codexBin, env);
-    if (refreshMode !== "add-only" && refreshMode !== "remove-add") {
-        fail("invalid-arguments", `unsupported SUPERPOWERS_INSTALL_REFRESH_MODE: ${refreshMode}`);
+    if (refreshMode === null) {
+        fail("invalid-arguments", `unsupported SUPERPOWERS_INSTALL_REFRESH_MODE: ${env.SUPERPOWERS_INSTALL_REFRESH_MODE}`);
     }
-    let entered = false;
-    try {
-        return await withWorkspace(tmpdir(), "superpowers-manager.adapter-install.", async () => {
-            entered = true;
-            const marketplaceList = await listingCommand(log, codexBin, ["plugin", "marketplace", "list", "--json"], env);
-            if (commandFailed(marketplaceList)) {
-                fail("install-failed", `cannot list Codex marketplaces via '${codexBin} plugin marketplace list --json'`);
-            }
-            let registeredRoot;
-            try {
-                registeredRoot = marketplaceRootFromJson(marketplaceList.stdout, MARKETPLACE_NAME);
-            }
-            catch {
-                fail("install-failed", `cannot parse output of '${codexBin} plugin marketplace list --json'`);
-            }
-            if (registeredRoot.length === 0) {
-                const added = await mutationCommand(log, codexBin, ["plugin", "marketplace", "add", packageRoot], env);
-                if (commandFailed(added)) {
-                    fail("install-failed", `codex marketplace add failed for ${packageRoot}`);
-                }
-            }
-            else if (!(await pathsEqual(packageRoot, registeredRoot))) {
-                log.appendText("stdout", `marketplace ${MARKETPLACE_NAME} registered at ${registeredRoot}; re-registering at ${packageRoot}`);
-                const removed = await mutationCommand(log, codexBin, ["plugin", "marketplace", "remove", MARKETPLACE_NAME], env);
-                if (commandFailed(removed)) {
-                    fail("install-failed", `codex marketplace remove failed for ${MARKETPLACE_NAME} (registered at ${registeredRoot})`);
-                }
-                const added = await mutationCommand(log, codexBin, ["plugin", "marketplace", "add", packageRoot], env);
-                if (commandFailed(added)) {
-                    fail("install-failed", `marketplace ${MARKETPLACE_NAME} was removed but re-adding failed.`, [
-                        `recover with: ${codexBin} plugin marketplace add ${packageRoot}`,
-                        `previous root (last known good): ${registeredRoot}`,
-                    ]);
-                }
-            }
-            if (refreshMode === "remove-add") {
-                await mutationCommand(log, codexBin, ["plugin", "remove", PLUGIN_ID], env);
-            }
-            const pluginAdded = await mutationCommand(log, codexBin, ["plugin", "add", PLUGIN_ID], env);
-            if (commandFailed(pluginAdded)) {
-                fail("install-failed", `codex plugin add failed for ${PLUGIN_ID}`);
-            }
-            return {
-                verification_hints: {
-                    ...(refreshMode === "add-only"
-                        ? {
-                            mismatch: "retry with SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add",
-                        }
-                        : {}),
-                    missing: "verify with 'codex plugin list --json'.",
-                },
-            };
-        }, { onCleanupFailure: reportOrphanedWorkspace(log) });
+    const marketplaceList = await listingCommand(log, codexBin, ["plugin", "marketplace", "list", "--json"], env);
+    let registeredRoot;
+    if (commandFailed(marketplaceList)) {
+        registeredRoot = (await storedStateAfterListingFailure(env, "install-failed", `cannot list Codex marketplaces via '${codexBin} plugin marketplace list --json'`)).managerMarketplaceRoot;
     }
-    catch (cause) {
-        if (!entered) {
-            fail("install-failed", `cannot create adapter install workspace under ${tmpdir()}`);
+    else {
+        try {
+            registeredRoot = marketplaceRootFromJson(marketplaceList.stdout, MARKETPLACE_NAME);
+        }
+        catch {
+            fail("install-failed", `cannot parse output of '${codexBin} plugin marketplace list --json'`);
         }
-        throw cause;
     }
+    if (registeredRoot.length === 0) {
+        const added = await mutationCommand(log, codexBin, ["plugin", "marketplace", "add", packageRoot], env);
+        if (commandFailed(added)) {
+            fail("install-failed", `codex marketplace add failed for ${packageRoot}`);
+        }
+    }
+    else if (!(await pathsEqual(packageRoot, registeredRoot))) {
+        log.appendText("stdout", `marketplace ${MARKETPLACE_NAME} registered at ${registeredRoot}; re-registering at ${packageRoot}`);
+        const removed = await mutationCommand(log, codexBin, ["plugin", "marketplace", "remove", MARKETPLACE_NAME], env);
+        if (commandFailed(removed)) {
+            fail("install-failed", `codex marketplace remove failed for ${MARKETPLACE_NAME} (registered at ${registeredRoot})`);
+        }
+        const added = await mutationCommand(log, codexBin, ["plugin", "marketplace", "add", packageRoot], env);
+        if (commandFailed(added)) {
+            fail("install-failed", `marketplace ${MARKETPLACE_NAME} was removed but re-adding failed.`, [
+                `recover with: ${codexBin} plugin marketplace add ${packageRoot}`,
+                `previous root (last known good): ${registeredRoot}`,
+            ]);
+        }
+    }
+    if (refreshMode === "remove-add") {
+        await mutationCommand(log, codexBin, ["plugin", "remove", PLUGIN_ID], env);
+    }
+    const pluginAdded = await mutationCommand(log, codexBin, ["plugin", "add", PLUGIN_ID], env);
+    if (commandFailed(pluginAdded)) {
+        fail("install-failed", `codex plugin add failed for ${PLUGIN_ID}`);
+    }
+    return codexInstallReceipt("verify with 'codex plugin list --json'.", refreshMode === "add-only"
+        ? "retry with SUPERPOWERS_INSTALL_REFRESH_MODE=remove-add"
+        : "");
 }
 async function runUninstall(input, env, log) {
     const { pluginPresent, marketplacePresent } = input;
     const codexBin = env.SUPERPOWERS_CODEX || "codex";
     await requireCodex(codexBin, env);
-    let entered = false;
-    try {
-        return await withWorkspace(tmpdir(), "superpowers-manager.adapter-uninstall.", async () => {
-            entered = true;
-            if (pluginPresent) {
-                const result = await mutationCommand(log, codexBin, ["plugin", "remove", PLUGIN_ID], env);
-                if (commandFailed(result)) {
-                    fail("uninstall-failed", `codex plugin remove failed for ${PLUGIN_ID}`);
-                }
-                log.appendText("stdout", `removed plugin ${PLUGIN_ID}`);
-            }
-            else {
-                log.appendText("stdout", "plugin not installed; skipping");
-            }
-            if (marketplacePresent) {
-                const result = await mutationCommand(log, codexBin, ["plugin", "marketplace", "remove", MARKETPLACE_NAME], env);
-                if (commandFailed(result)) {
-                    fail("uninstall-failed", `codex plugin marketplace remove failed for ${MARKETPLACE_NAME}`);
-                }
-                log.appendText("stdout", `removed marketplace ${MARKETPLACE_NAME}`);
-            }
-            else {
-                log.appendText("stdout", "marketplace not registered; skipping");
-            }
-            return {};
-        }, { onCleanupFailure: reportOrphanedWorkspace(log) });
+    if (pluginPresent) {
+        const result = await mutationCommand(log, codexBin, ["plugin", "remove", PLUGIN_ID], env);
+        if (commandFailed(result)) {
+            fail("uninstall-failed", `codex plugin remove failed for ${PLUGIN_ID}`);
+        }
+        log.appendText("stdout", `removed plugin ${PLUGIN_ID}`);
     }
-    catch (cause) {
-        if (!entered) {
-            fail("uninstall-failed", `cannot create adapter uninstall workspace under ${tmpdir()}`);
+    else {
+        log.appendText("stdout", "plugin not installed; skipping");
+    }
+    if (marketplacePresent) {
+        const result = await mutationCommand(log, codexBin, ["plugin", "marketplace", "remove", MARKETPLACE_NAME], env);
+        if (commandFailed(result)) {
+            fail("uninstall-failed", `codex plugin marketplace remove failed for ${MARKETPLACE_NAME}`);
         }
-        throw cause;
+        log.appendText("stdout", `removed marketplace ${MARKETPLACE_NAME}`);
+    }
+    else {
+        log.appendText("stdout", "marketplace not registered; skipping");
     }
+    return {};
 }
-async function runInspect(view, context, env, log) {
-    if (view === "update-control") {
-        return { view: "update-control", update_control: "managed" };
+function ownershipFromResources(pluginPresent, marketplacePresent, legacyPresent, conflicts) {
+    if (conflicts.some((item) => typeof item !== "string" ||
+        item.length === 0 ||
+        hasTerminalControl(item))) {
+        fail("malformed-result", "expected an array of strings at conflicts");
+    }
+    const managerPresent = pluginPresent || marketplacePresent;
+    const identityState = managerPresent
+        ? legacyPresent
+            ? "both"
+            : "manager"
+        : legacyPresent
+            ? "legacy"
+            : "neither";
+    return codexOwnershipInspection(identityState, { pluginPresent, marketplacePresent }, conflicts);
+}
+async function runOwnership(context, env, log) {
+    const codexBin = env.SUPERPOWERS_CODEX || "codex";
+    await requireCodex(codexBin, env);
+    const plugins = await listingCommand(log, codexBin, ["plugin", "list", "--json"], env);
+    if (commandFailed(plugins)) {
+        const stored = await storedStateAfterListingFailure(env, "inspect-failed", `cannot list Codex plugins via '${codexBin} plugin list --json'`);
+        const conflicts = await inspectCodexConflicts({ root: context.root, env }, stored.installedListingJson);
+        return ownershipFromResources(stored.managerPluginPresent, true, stored.legacyPluginPresent || stored.legacyMarketplaceRoot !== null, conflicts);
+    }
+    let managerPlugin;
+    let legacyPlugin;
+    let conflicts;
+    try {
+        managerPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", PLUGIN_ID);
+        legacyPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", LEGACY_PLUGIN_ID);
+        conflicts = await inspectCodexConflicts({ root: context.root, env }, plugins.stdout.toString("utf8"));
     }
-    if (view === "fingerprint") {
-        const codexBin = env.SUPERPOWERS_CODEX || "codex";
-        await requireCodex(codexBin, env);
-        let entered = false;
-        try {
-            return await withWorkspace(tmpdir(), "superpowers-manager.adapter-fingerprint.", async () => {
-                entered = true;
-                const listing = await listingCommand(log, codexBin, ["plugin", "list", "--json"], env);
-                if (commandFailed(listing)) {
-                    fail("inspect-failed", `cannot list Codex plugins via '${codexBin} plugin list --json'`);
-                }
-                let activeVersion;
-                try {
-                    activeVersion = activePluginVersionFromJson(listing.stdout, PLUGIN_ID);
-                }
-                catch {
-                    fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
-                }
-                if (activeVersion.length === 0) {
-                    return { view: "fingerprint", fingerprint: null };
-                }
-                let searchRoot = env.SUPERPOWERS_INSTALLED_SEARCH_ROOT;
-                if (!searchRoot) {
-                    if (env.HOME === undefined) {
-                        fail("inspect-failed", "cannot inspect active Codex plugin fingerprint without HOME");
-                    }
-                    searchRoot = join(env.HOME || "/", ".codex");
-                }
-                const activeRoot = installedRootForVersion(searchRoot, MARKETPLACE_NAME, "superpowers", activeVersion);
-                const fingerprint = await installedCommitFromRoot(activeRoot);
-                if (fingerprint.length === 0) {
-                    fail("inspect-failed", `cannot inspect active Codex plugin fingerprint under ${activeRoot}`);
-                }
-                return { view: "fingerprint", fingerprint };
-            }, { onCleanupFailure: reportOrphanedWorkspace(log) });
-        }
-        catch (cause) {
-            if (!entered) {
-                fail("inspect-failed", `cannot create adapter fingerprint workspace under ${tmpdir()}`);
-            }
-            throw cause;
-        }
+    catch {
+        fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
     }
-    if (view === "ownership") {
-        const codexBin = env.SUPERPOWERS_CODEX || "codex";
-        await requireCodex(codexBin, env);
-        let entered = false;
-        try {
-            return await withWorkspace(tmpdir(), "superpowers-manager.adapter-inspect.", async () => {
-                entered = true;
-                const plugins = await listingCommand(log, codexBin, ["plugin", "list", "--json"], env);
-                if (commandFailed(plugins)) {
-                    fail("inspect-failed", `cannot list Codex plugins via '${codexBin} plugin list --json'`);
-                }
-                const marketplaces = await listingCommand(log, codexBin, ["plugin", "marketplace", "list", "--json"], env);
-                if (commandFailed(marketplaces)) {
-                    fail("inspect-failed", `cannot list Codex marketplaces via '${codexBin} plugin marketplace list --json'`);
-                }
-                let managerPlugin;
-                let legacyPlugin;
-                let managerMarketplace;
-                let legacyMarketplace;
-                let conflicts;
-                try {
-                    managerPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", PLUGIN_ID);
-                    legacyPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", LEGACY_PLUGIN_ID);
-                    conflicts = await inspectCodexConflicts({ root: context.root, env }, plugins.stdout.toString("utf8"));
-                }
-                catch {
-                    fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
-                }
-                try {
-                    managerMarketplace = installedListingHas(marketplaces.stdout, "marketplaces", "name", MARKETPLACE_NAME);
-                    legacyMarketplace = installedListingHas(marketplaces.stdout, "marketplaces", "name", LEGACY_MARKETPLACE_NAME);
-                }
-                catch {
-                    fail("inspect-failed", `cannot parse output of '${codexBin} plugin marketplace list --json'`);
-                }
-                const managerPresent = managerPlugin || managerMarketplace;
-                const legacyPresent = legacyPlugin || legacyMarketplace;
-                return {
-                    view: "ownership",
-                    resources: {
-                        plugin: managerPlugin,
-                        marketplace: managerMarketplace,
-                    },
-                    legacy_resources: {
-                        plugin: legacyPlugin,
-                        marketplace: legacyMarketplace,
-                    },
-                    identity_state: managerPresent
-                        ? legacyPresent
-                            ? "both"
-                            : "manager"
-                        : legacyPresent
-                            ? "legacy"
-                            : "neither",
-                    conflicts: [...conflicts],
-                };
-            }, { onCleanupFailure: reportOrphanedWorkspace(log) });
-        }
-        catch (cause) {
-            if (!entered) {
-                fail("inspect-failed", `cannot create adapter inspect workspace under ${tmpdir()}`);
-            }
-            throw cause;
-        }
+    const marketplaces = await listingCommand(log, codexBin, ["plugin", "marketplace", "list", "--json"], env);
+    if (commandFailed(marketplaces)) {
+        const stored = await storedStateAfterListingFailure(env, "inspect-failed", `cannot list Codex marketplaces via '${codexBin} plugin marketplace list --json'`);
+        const conflicts = await inspectCodexConflicts({ root: context.root, env }, stored.installedListingJson);
+        return ownershipFromResources(stored.managerPluginPresent, true, stored.legacyPluginPresent || stored.legacyMarketplaceRoot !== null, conflicts);
     }
-    const unsupportedView = view;
-    fail("invalid-arguments", `unsupported inspect view: ${unsupportedView}`);
+    let managerMarketplace;
+    let legacyMarketplace;
+    try {
+        managerMarketplace = installedListingHas(marketplaces.stdout, "marketplaces", "name", MARKETPLACE_NAME);
+        legacyMarketplace = installedListingHas(marketplaces.stdout, "marketplaces", "name", LEGACY_MARKETPLACE_NAME);
+    }
+    catch {
+        fail("inspect-failed", `cannot parse output of '${codexBin} plugin marketplace list --json'`);
+    }
+    return ownershipFromResources(managerPlugin, managerMarketplace, legacyPlugin || legacyMarketplace, conflicts);
 }
 async function runCodexOperation(operation, context, execute) {
     const env = { ...process.env, ...context.env };
@@ -625,70 +501,73 @@ export function codexInstall(packageRoot, context) {
 export function codexRemove(input, context) {
     return runCodexOperation("uninstall", context, (env, log) => runUninstall(input, env, log));
 }
-export function codexInspect(view, context) {
-    return runCodexOperation("inspect", context, (env, log) => runInspect(view, context, env, log));
+export function codexInspectOwnership(context) {
+    return runCodexOperation("inspect", context, (env, log) => runOwnership(context, env, log));
 }
-export async function runAdapter(argv, context) {
-    const rawOperation = argv[0];
-    const operation = rawOperation || "adapter";
-    const args = argv.slice(1);
-    try {
-        if (rawOperation === undefined || rawOperation.length === 0) {
-            fail("invalid-arguments", "missing adapter operation");
-        }
-        else if (operation === "build") {
-            const flags = parseFlags(args, BUILD_FLAGS);
-            return codexBuild({
-                upstreamRoot: flags["--upstream-root"],
-                candidateRoot: flags["--candidate-root"],
-                requestedRef: flags["--requested-ref"],
-                resolvedRef: flags["--resolved-ref"],
-                commit: flags["--commit"],
-                managerVersion: flags["--manager-version"],
-                upstreamManifestVersion: flags["--upstream-manifest-version"],
-                fallbackManifest: flags["--fallback-manifest"],
-            }, context);
+export function codexInspectControl(context) {
+    return runCodexOperation("inspect", context, async () => codexControlInspection("managed"));
+}
+export function codexReadNativeState(context) {
+    return runCodexOperation("native-state", context, async (env, log) => {
+        const codexBin = env.SUPERPOWERS_CODEX || "codex";
+        await requireCodex(codexBin, env);
+        const plugins = await listingCommand(log, codexBin, ["plugin", "list", "--json"], env);
+        if (commandFailed(plugins)) {
+            const stored = await storedStateAfterListingFailure(env, "inspect-failed", `cannot list Codex plugins via '${codexBin} plugin list --json'`);
+            return {
+                marketplaceRoot: stored.managerMarketplaceRoot,
+                pluginPresent: stored.managerPluginPresent,
+                pluginEnabled: stored.managerPluginEnabled,
+                activeVersion: null,
+                activeRoot: null,
+            };
         }
-        else if (operation === "install") {
-            const flags = parseFlags(args, ["--package-root"]);
-            return codexInstall(flags["--package-root"], context);
+        let manager;
+        let activeVersion;
+        try {
+            const managers = codexInstalledPluginsFromJson(plugins.stdout).filter((plugin) => plugin.pluginId === PLUGIN_ID);
+            if (managers.length > 1)
+                fail("inspect-failed", "Codex manager plugin appears more than once");
+            manager = managers[0];
+            activeVersion =
+                manager === undefined
+                    ? ""
+                    : activePluginVersionFromJson(plugins.stdout, PLUGIN_ID);
         }
-        else if (operation === "uninstall") {
-            const flags = parseFlags(args, [
-                "--plugin-present",
-                "--marketplace-present",
-            ]);
-            const pluginPresent = flags["--plugin-present"];
-            const marketplacePresent = flags["--marketplace-present"];
-            if (pluginPresent !== "true" && pluginPresent !== "false") {
-                fail("invalid-arguments", "--plugin-present must be true or false");
-            }
-            if (marketplacePresent !== "true" && marketplacePresent !== "false") {
-                fail("invalid-arguments", "--marketplace-present must be true or false");
-            }
-            return codexRemove({
-                pluginPresent: pluginPresent === "true",
-                marketplacePresent: marketplacePresent === "true",
-            }, context);
+        catch (cause) {
+            if (cause instanceof AdapterFailure)
+                throw cause;
+            fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
         }
-        else if (operation === "inspect") {
-            const flags = parseFlags(args, ["--view"]);
-            const view = flags["--view"];
-            if (view !== "ownership" &&
-                view !== "update-control" &&
-                view !== "fingerprint") {
-                fail("invalid-arguments", `unsupported inspect view: ${view}`);
-            }
-            return codexInspect(view, context);
+        const marketplaces = await listingCommand(log, codexBin, ["plugin", "marketplace", "list", "--json"], env);
+        if (commandFailed(marketplaces)) {
+            const stored = await storedStateAfterListingFailure(env, "inspect-failed", `cannot list Codex marketplaces via '${codexBin} plugin marketplace list --json'`);
+            return {
+                marketplaceRoot: stored.managerMarketplaceRoot,
+                pluginPresent: stored.managerPluginPresent,
+                pluginEnabled: stored.managerPluginEnabled,
+                activeVersion: null,
+                activeRoot: null,
+            };
         }
-        else {
-            fail("unsupported-operation", `unsupported adapter operation: ${operation}`);
+        let marketplaceRoot;
+        try {
+            marketplaceRoot = marketplaceRootFromJson(marketplaces.stdout, MARKETPLACE_NAME, true);
         }
-    }
-    catch (cause) {
-        if (cause instanceof AdapterFailure) {
-            return failureResult(operation, cause.code, cause.message, cause.hints, []);
+        catch (cause) {
+            if (cause instanceof AdapterFailure)
+                throw cause;
+            fail("inspect-failed", `cannot parse output of '${codexBin} plugin marketplace list --json'`);
         }
-        throw cause;
-    }
+        const searchRoot = env.SUPERPOWERS_INSTALLED_SEARCH_ROOT || codexHome(env, process.cwd());
+        return {
+            marketplaceRoot: marketplaceRoot || null,
+            pluginPresent: manager !== undefined,
+            pluginEnabled: manager?.enabled === true,
+            activeVersion: activeVersion || null,
+            activeRoot: activeVersion
+                ? installedRootForVersion(searchRoot, MARKETPLACE_NAME, "superpowers", activeVersion)
+                : null,
+        };
+    });
 }