superpowers-manager 0.4.0 → 0.5.0

package/dist/codex-conflicts.js

@@ -0,0 +1,99 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { codexInstalledPluginsFromJson, } from "./codex-json.js";
+export const CODEX_MANAGER_PLUGIN_ID = "superpowers@superpowers-manager";
+export const CODEX_LEGACY_PLUGIN_ID = "superpowers@superpowers-wrapper";
+const SUPERPOWERS_PLUGIN_PREFIX = "superpowers@";
+const DISPLAYABLE_PLUGIN_ID = /^superpowers@[A-Za-z0-9][A-Za-z0-9._-]*/;
+const NATIVE_ROUTE = ".agents/skills/superpowers";
+const NATIVE_ROUTE_CONFLICT = `native Codex skills route ~/${NATIVE_ROUTE} has indeterminate activity`;
+function isMissingPath(cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause)) {
+        return false;
+    }
+    return cause.code === "ENOENT" || cause.code === "ENOTDIR";
+}
+function isUnmanagedPluginId(pluginId) {
+    if (pluginId === CODEX_MANAGER_PLUGIN_ID ||
+        pluginId === CODEX_LEGACY_PLUGIN_ID) {
+        return false;
+    }
+    return (pluginId.startsWith(SUPERPOWERS_PLUGIN_PREFIX) &&
+        pluginId.length > SUPERPOWERS_PLUGIN_PREFIX.length);
+}
+function displayablePluginId(pluginId) {
+    return pluginId.length <= 256 &&
+        DISPLAYABLE_PLUGIN_ID.exec(pluginId)?.[0] === pluginId
+        ? pluginId
+        : "";
+}
+function unmanagedPluginConflict(plugin) {
+    if (!isUnmanagedPluginId(plugin.pluginId))
+        return "";
+    const displayId = displayablePluginId(plugin.pluginId);
+    const subject = displayId.length > 0
+        ? `Codex plugin ${displayId}`
+        : "Codex plugin with a non-displayable Superpowers identity";
+    if (plugin.installed === true && plugin.enabled === true) {
+        return `active ${subject}`;
+    }
+    if ((plugin.installed === true && plugin.enabled === false) ||
+        (plugin.installed === false && plugin.enabled === false)) {
+        return "";
+    }
+    return `${subject} has indeterminate activity`;
+}
+async function nativeRouteConflict(ctx) {
+    const home = ctx.env?.HOME;
+    if (home === undefined || home.length === 0)
+        return NATIVE_ROUTE_CONFLICT;
+    const route = join(home, ".agents", "skills", "superpowers");
+    const asset = join(route, "using-superpowers", "SKILL.md");
+    let routeIsSymlink;
+    try {
+        routeIsSymlink = (await lstat(route)).isSymbolicLink();
+    }
+    catch (cause) {
+        return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+    }
+    if (!routeIsSymlink) {
+        try {
+            await lstat(asset);
+        }
+        catch (cause) {
+            return isMissingPath(cause) ? "" : NATIVE_ROUTE_CONFLICT;
+        }
+    }
+    try {
+        const resolvedAsset = await realpath(asset);
+        if (!(await stat(resolvedAsset)).isFile())
+            return NATIVE_ROUTE_CONFLICT;
+        const contents = await readFile(resolvedAsset, "utf8");
+        const lines = contents.split(/\r?\n/u);
+        if (lines[0] !== "---")
+            return "";
+        const end = lines.indexOf("---", 1);
+        if (end < 0 ||
+            !lines
+                .slice(1, end)
+                .some((line) => /^name:[ \t]+using-superpowers[ \t]*$/u.test(line))) {
+            return "";
+        }
+    }
+    catch {
+        return NATIVE_ROUTE_CONFLICT;
+    }
+    return NATIVE_ROUTE_CONFLICT;
+}
+export async function inspectCodexConflicts(ctx, installedListing) {
+    const conflicts = new Set();
+    for (const plugin of codexInstalledPluginsFromJson(installedListing)) {
+        const conflict = unmanagedPluginConflict(plugin);
+        if (conflict.length > 0)
+            conflicts.add(conflict);
+    }
+    const nativeConflict = await nativeRouteConflict(ctx);
+    if (nativeConflict.length > 0)
+        conflicts.add(nativeConflict);
+    return [...conflicts];
+}

package/dist/codex-harness.js

@@ -1,8 +1,10 @@
+import { join, resolve } from "node:path";
 import { failureResult, hasTerminalControl, successResult, } from "./adapter-result.js";
 import { codexInspect, codexInstall, codexRemove, } from "./adapter.js";
 import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./codex-prepare.js";
 import { codexInstallReceipt, codexPresentation, } from "./codex-presentation.js";
 import { reportLegacyState, requireManagedUpdateControl, requireNoLegacyState, verifyUninstalledResources, } from "./lifecycle.js";
+import { SafetyError } from "./safety-error.js";
 import { commitMatches } from "./status.js";
 function preserveFailure(result) {
     if (result.outcome.ok) {
@@ -40,6 +42,23 @@ function resourceFlag(result, key) {
     const value = bag[key];
     return typeof value === "boolean" ? value : null;
 }
+function conflictDescriptions(result) {
+    const raw = result.conflicts;
+    if (raw === null || raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return null;
+    const descriptions = [];
+    for (const item of raw) {
+        if (typeof item !== "string" ||
+            item.length === 0 ||
+            hasTerminalControl(item)) {
+            return null;
+        }
+        descriptions.push(item);
+    }
+    return descriptions;
+}
 function installDecision(legacy) {
     switch (legacy.kind) {
         case "ok":
@@ -87,7 +106,11 @@ export function normalizeCodexOwnership(result) {
         return malformed(result, "adapter returned a non-string identity_state for inspect --view ownership");
     }
     const identityState = identity.value;
-    const installEligibility = identityState.length === 0
+    const conflicts = conflictDescriptions(record);
+    if (conflicts === null) {
+        return malformed(result, "expected an array of strings at conflicts");
+    }
+    const legacyEligibility = identityState.length === 0
         ? {
             kind: "blocked",
             output: {
@@ -96,6 +119,19 @@ export function normalizeCodexOwnership(result) {
             },
         }
         : installDecision(requireNoLegacyState(identityState));
+    const installEligibility = legacyEligibility.kind === "blocked" || conflicts.length === 0
+        ? legacyEligibility
+        : {
+            kind: "blocked",
+            output: {
+                stdout: [],
+                stderr: [
+                    "Conflicting unmanaged Superpowers Codex resources require manual resolution:",
+                    ...conflicts.map((conflict) => `- ${conflict}`),
+                    "Remove or disable each resource manually, then retry.",
+                ],
+            },
+        };
     const verification = verifyUninstalledResources(result);
     const legacyReport = reportLegacyState(identityState);
     let removalVerification;
@@ -132,6 +168,7 @@ export function normalizeCodexOwnership(result) {
         removalVerification,
         postRemovalOutput,
         presentationValue: identityState,
+        presentationConflicts: conflicts,
     }, result.outcome.messages);
 }
 export function normalizeCodexControl(result) {
@@ -243,8 +280,21 @@ function requirements(command, env) {
         },
     ];
 }
+async function mutationRoots(ctx) {
+    const env = ctx.env ?? {};
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.length > 0) {
+        return [resolve(configured)];
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0) {
+        throw new SafetyError("codex-harness", "cannot determine Codex state root without HOME");
+    }
+    return [join(resolve(home), ".codex")];
+}
 export const codexHarness = {
     preparationLocation: codexPreparationLocation,
+    mutationRoots,
     validatePreparationBeforeFetch: validateCodexPreparationBeforeFetch,
     prepareCandidate: prepareCodexCandidate,
     inspectPrepared: inspectCodexPrepared,

package/dist/codex-json.js

@@ -59,6 +59,13 @@ function hasTerminalControl(value) {
 export function installedListingHas(raw, arrayKey, field, value) {
     return checkedItems(raw, ACCEPT_CONSTANTS, arrayKey, field).some((item) => item[field] === value);
 }
+export function codexInstalledPluginsFromJson(raw) {
+    return checkedItems(raw, ACCEPT_CONSTANTS, "installed", "pluginId").map((item) => ({
+        pluginId: item.pluginId,
+        installed: typeof item.installed === "boolean" ? item.installed : null,
+        enabled: typeof item.enabled === "boolean" ? item.enabled : null,
+    }));
+}
 export function marketplaceRootFromJson(raw, marketplaceName) {
     const items = checkedItems(raw, ACCEPT_CONSTANTS, "marketplaces", "name");
     const match = items.find((item) => item.name === marketplaceName);

package/dist/codex-prepare.js

@@ -2,9 +2,11 @@ import { cp, mkdir, rm, stat } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import { failureResult, successResult, } from "./adapter-result.js";
 import { codexBuild } from "./adapter.js";
-import { commitMatches } from "./domain/fingerprint.js";
+import { ARTIFACT_RECEIPT } from "./artifact-tree.js";
+import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./codex-compatibility.js";
 import { readManifest } from "./hooks.js";
-import { generatedCommitOrEmpty, generatedMetadataPath, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
+import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
+import { classifyPathNoFollow } from "./safe-path.js";
 import { SafetyError } from "./safety-error.js";
 import { manifestVersionForRef } from "./upstream-version.js";
 // Order is inherited from the original prepare command; the first miss wins.
@@ -27,6 +29,12 @@ const RESOLUTION_KINDS = [
     "ref",
     "raw-commit",
 ];
+function unassessedCompatibility() {
+    return {
+        kind: "unknown",
+        reason: "Codex compatibility assessment is not available",
+    };
+}
 function prepareError(message, cause) {
     return new SafetyError("prepare", message, { cause });
 }
@@ -166,26 +174,66 @@ export async function prepareCodexCandidate(input, ctx) {
     if (built.status !== 0) {
         return failureResult("build", "invalid-status", "adapter reported failure without an error outcome", [], built.outcome.messages);
     }
-    return successResult(built.outcome.operation, { root: input.candidateRoot, commit: input.selection.desiredCommit }, built.outcome.messages);
+    const compatibility = await assessCodexCompatibility(input.upstreamRoot, input.selection);
+    if (compatibility.kind === "supported") {
+        try {
+            await writeCodexAssessment(input.candidateRoot, input.selection, (await regularFileExists(join(input.upstreamRoot, ".codex-plugin/plugin.json")))
+                ? "upstream"
+                : "fallback");
+        }
+        catch {
+            return failureResult("prepare", "assessment-failed", `cannot record Codex compatibility assessment: ${input.candidateRoot}`, [], built.outcome.messages);
+        }
+    }
+    return successResult(built.outcome.operation, {
+        root: input.candidateRoot,
+        commit: input.selection.desiredCommit,
+        compatibility,
+        identity: input.selection.desiredCommit,
+    }, built.outcome.messages);
 }
 export async function inspectCodexPrepared(selection, ctx) {
-    const observedIdentity = await generatedCommitOrEmpty(ctx.root);
-    if (!commitMatches(selection.desiredCommit, observedIdentity)) {
-        return successResult("inspect-prepared", { kind: "needs-prepare", observedIdentity }, []);
+    const root = codexPreparationLocation(ctx).destinationRoot;
+    const observedIdentity = await readGeneratedCommitLenient(join(root, ".superpowers-upstream.json"));
+    const compatibility = unassessedCompatibility();
+    try {
+        if ((await classifyPathNoFollow(join(root, ARTIFACT_RECEIPT))) === "missing")
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility,
+            }, []);
+        const artifact = await readCodexAssessment(root);
+        const source = await readStrictProvenanceField(join(artifact.root, ".superpowers-upstream.json"), "source");
+        if (artifact.commit === selection.desiredCommit &&
+            source === selection.effectiveSource) {
+            if (artifact.compatibility.kind === "supported")
+                return successResult("inspect-prepared", {
+                    kind: "current",
+                    artifact,
+                    observedIdentity,
+                    compatibility: artifact.compatibility,
+                }, []);
+            return successResult("inspect-prepared", {
+                kind: "needs-prepare",
+                observedIdentity,
+                compatibility: artifact.compatibility,
+            }, []);
+        }
+    }
+    catch {
+        return failureResult("inspect-prepared", "invalid-assessment", `cannot inspect Codex prepared artifact: ${root}`, [], []);
     }
     return successResult("inspect-prepared", {
-        kind: "current",
-        artifact: {
-            root: join(ctx.root, "plugins", "superpowers"),
-            commit: observedIdentity,
-        },
+        kind: "needs-prepare",
         observedIdentity,
+        compatibility,
     }, []);
 }
 export async function readCodexPrepared(ctx) {
     let commit = "";
     try {
-        const value = await readStrictProvenanceField(generatedMetadataPath(ctx.root), "commit");
+        const value = await readStrictProvenanceField(join(codexPreparationLocation(ctx).destinationRoot, ".superpowers-upstream.json"), "commit");
         if (typeof value === "string")
             commit = value;
     }
@@ -195,5 +243,13 @@ export async function readCodexPrepared(ctx) {
     if (commit.length === 0) {
         return failureResult("read-prepared", "missing-commit", "generated metadata missing desired commit after prepare", [], []);
     }
-    return successResult("read-prepared", { root: join(ctx.root, "plugins", "superpowers"), commit }, []);
+    try {
+        const artifact = await readCodexAssessment(codexPreparationLocation(ctx).destinationRoot);
+        if (artifact.compatibility.kind !== "supported")
+            throw new Error("unsupported profile");
+        return successResult("read-prepared", artifact, []);
+    }
+    catch {
+        return failureResult("read-prepared", "invalid-assessment", "generated Codex compatibility assessment is missing or invalid", [], []);
+    }
 }

package/dist/codex-presentation.js

@@ -4,6 +4,7 @@ import { displaySource } from "./selection.js";
 // porcelain field order exposed through the harness presentation.
 export function fields(f) {
     return [
+        { key: "harness", label: "harness", value: f.harness },
         { key: "requested_ref", label: "requested ref", value: f.requestedRef },
         { key: "resolved_ref", label: "resolved ref", value: f.resolvedRef },
         { key: "desired_commit", label: "desired commit", value: f.desiredCommit },
@@ -58,6 +59,7 @@ export function fields(f) {
     ];
 }
 const NO_FACTS = {
+    harness: "codex",
     requestedRef: "",
     resolvedRef: "",
     desiredCommit: "",
@@ -129,6 +131,7 @@ function probeFacts(facts) {
     const selection = facts.selection;
     const saved = selection.saved;
     return {
+        harness: "codex",
         requestedRef: selection.requestedRef,
         resolvedRef: selection.resolvedRef,
         desiredCommit: selection.desiredCommit,
@@ -205,7 +208,27 @@ export const codexPresentation = {
     currentNotice: "manager is current",
     renderProbe(snapshot) {
         const facts = probeFacts(snapshot);
-        return { human: formatHuman(facts), porcelain: formatPorcelain(facts) };
+        const conflicts = snapshot.ownership.presentationConflicts ?? [];
+        const additional = [
+            ["installation_state", snapshot.installed.kind],
+            ["resource_state", snapshot.resourceState ?? "idle"],
+            ["compatibility", snapshot.compatibility.kind],
+            ["compatibility_reason", snapshot.compatibility.reason],
+        ];
+        return {
+            human: formatHuman(facts) +
+                additional
+                    .map(([key, value]) => `${key.replaceAll("_", " ")}: ${value}\n`)
+                    .join("") +
+                conflicts
+                    .map((conflict) => `ownership conflict: ${conflict}\n`)
+                    .join(""),
+            porcelain: formatPorcelain(facts) +
+                additional.map(([key, value]) => `${key}=${value}\n`).join("") +
+                conflicts
+                    .map((conflict) => `ownership_conflict=${conflict}\n`)
+                    .join(""),
+        };
     },
     renderInstallVerification(desiredCommit, receipt, inspection) {
         if (inspection.status !== 0 || !inspection.outcome.ok) {

package/dist/commands/install.js

@@ -5,18 +5,38 @@
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
-import { gatherProbe, replayOutcome } from "./probe.js";
+import { gatherProbe, replayOutcome, validInstalled, validOutput, } from "./probe.js";
 import { runPrepare } from "./prepare.js";
+import { runWithMutation } from "./mutation.js";
+import { activationBlock } from "../harness-compatibility.js";
 function writeOutput(output, ctx) {
     for (const line of output.stdout)
         ctx.stdout.write(`${line}\n`);
     for (const line of output.stderr)
         ctx.stderr.write(`${line}\n`);
 }
-async function invoke(call, failure, outcomes) {
+async function invoke(call, failure, outcomes, valid = () => true) {
     let result;
     try {
         result = await call();
+        if (!result ||
+            !Number.isInteger(result.status) ||
+            !result.outcome ||
+            typeof result.outcome.ok !== "boolean" ||
+            typeof result.outcome.operation !== "string" ||
+            !Array.isArray(result.outcome.messages) ||
+            !result.outcome.messages.every((message) => message &&
+                (message.channel === "stdout" || message.channel === "stderr") &&
+                typeof message.text === "string") ||
+            (result.outcome.ok
+                ? result.outcome.error !== null || !valid(result.outcome.result)
+                : !result.outcome.error ||
+                    typeof result.outcome.error.code !== "string" ||
+                    typeof result.outcome.error.message !== "string" ||
+                    !Array.isArray(result.outcome.error.hints) ||
+                    !result.outcome.error.hints.every((hint) => typeof hint === "string"))) {
+            return { ok: false, message: failure.invalidStatus, result: null };
+        }
     }
     catch {
         return { ok: false, message: failure.unexpected, result: null };
@@ -35,6 +55,12 @@ async function invoke(call, failure, outcomes) {
         result: { status: result.status, outcome },
     };
 }
+function validReceipt(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        validOutput(value.missingVerificationOutput) &&
+        validOutput(value.mismatchVerificationOutput));
+}
 // withWorkspace can throw AFTER its callback has already returned a fully
 // computed StageOutcome: a post-success cleanup failure discards that return
 // value entirely and rejects instead, UNLESS an `onCleanupFailure` reporter is
@@ -103,10 +129,30 @@ async function gatherInstallStages(ctx, selection, artifact) {
             }
             // Stage 3: the mutation itself. Nothing above may have issued this --
             // that is the whole point of stages 1 and 2 running first.
+            const activationFailure = activationBlock(artifact.compatibility, ctx.options.allowExperimental);
+            if (activationFailure !== null)
+                return failed(activationFailure);
             const installFailure = ctx.adapter.presentation.callFailure("install", adapterContext);
-            const install = await invoke(() => ctx.adapter.install(artifact, adapterContext), installFailure, outcomes);
+            const install = await invoke(() => ctx.adapter.install(artifact, adapterContext), installFailure, outcomes, validReceipt);
             if (!install.ok)
                 return failed(install.message);
+            let transaction;
+            try {
+                const candidate = install.result.outcome.result.transaction;
+                if (candidate !== undefined) {
+                    if (candidate === null || typeof candidate !== "object")
+                        throw new Error("invalid transaction");
+                    const finalize = candidate.finalize.bind(candidate);
+                    const rollback = candidate.rollback.bind(candidate);
+                    if (typeof finalize !== "function" ||
+                        typeof rollback !== "function")
+                        throw new Error("invalid transaction");
+                    transaction = { finalize, rollback };
+                }
+            }
+            catch {
+                return failed("invalid installation transaction receipt; preserve recovery material for manual resolution");
+            }
             // Stage 4: inspect fingerprint, to verify the mutation actually took.
             //
             // Deliberately NOT short-circuited on `!inspected.ok`, unlike stages
@@ -117,27 +163,71 @@ async function gatherInstallStages(ctx, selection, artifact) {
             // is what turns a failed inspection into "error: installed manager
             // fingerprint inspection failed after install."
             // renderInstallVerification's failed-inspection arm
-            // (`src/codex-presentation.ts:306::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
+            // (`src/codex-presentation.ts:332::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
             // exists for this result-bearing path; the lifecycle compatibility
             // export delegates through the same arm. Returning
             // failed() instead reported the adapter's own generic diagnostic and
             // dropped the post-install verification claim -- a mutation had
             // already been issued at stage 3,
             // so "the install could not be verified" is the contract, not "an
-            // adapter call failed". A ctx.adapter THROW is the one case with no
-            // result to verify against, and keeps the short-circuit.
+            // adapter call failed". A ctx.adapter THROW has no result to render.
+            // A pending transaction still rolls back before reporting that failure.
             const inspectionFailure = ctx.adapter.presentation.callFailure("post-install", adapterContext);
-            const inspected = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes);
-            if (!inspected.ok && inspected.result === null) {
-                return failed(inspected.message);
-            }
+            const inspected = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes, validInstalled);
             const inspection = inspected.result;
-            if (inspection === null)
-                return failed(null);
-            const output = ctx.adapter.presentation.renderInstallVerification(selection.desiredCommit, install.result, inspection);
-            const verified = inspection.status === 0 &&
+            const verified = inspection !== null &&
+                inspection.status === 0 &&
                 inspection.outcome.ok &&
                 inspection.outcome.result.kind === "current";
+            if (transaction !== undefined) {
+                const operation = verified ? "finalize" : "rollback";
+                const settlement = await invoke(() => (verified ? transaction.finalize() : transaction.rollback()), {
+                    unexpected: `installation ${operation} did not complete; preserve recovery material for manual resolution`,
+                    invalidStatus: `installation ${operation} returned an invalid result; preserve recovery material for manual resolution`,
+                }, outcomes, (value) => value === null);
+                if (!verified) {
+                    const restored = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes, validInstalled);
+                    const restoration = restored.ok
+                        ? `installed state after rollback: ${restored.result.outcome.result.kind}; identity=${restored.result.outcome.result.observedIdentity}`
+                        : "installed state after rollback could not be inspected";
+                    const message = !settlement.ok
+                        ? settlement.message
+                        : !inspected.ok
+                            ? inspected.message
+                            : "installation could not be verified";
+                    return {
+                        kind: "verified",
+                        outcomes,
+                        status: 1,
+                        stdout: [],
+                        stderr: [
+                            ...(message === null ? [] : [`error: ${message}`]),
+                            restoration,
+                        ],
+                    };
+                }
+                if (!settlement.ok) {
+                    const actual = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes, validInstalled);
+                    return {
+                        kind: "verified",
+                        outcomes,
+                        status: 1,
+                        stdout: [],
+                        stderr: [
+                            "error: installation was verified, but transaction cleanup did not complete; preserve recovery material for manual resolution",
+                            actual.ok
+                                ? `installed state after failed finalization: ${actual.result.outcome.result.kind}; identity=${actual.result.outcome.result.observedIdentity}`
+                                : "installed state after failed finalization could not be inspected",
+                            ...(settlement.message === null
+                                ? []
+                                : [`error: ${settlement.message}`]),
+                        ],
+                    };
+                }
+            }
+            if (inspection === null)
+                return failed(inspected.ok ? null : inspected.message);
+            const output = ctx.adapter.presentation.renderInstallVerification(selection.desiredCommit, install.result, inspection);
             return {
                 kind: "verified",
                 outcomes,
@@ -164,10 +254,14 @@ async function gatherInstallStages(ctx, selection, artifact) {
     }
 }
 export async function runInstall(argv, ctx) {
+    if (ctx.adapter.presentation.installNotice !== "")
+        ctx.stdout.write(`${ctx.adapter.presentation.installNotice}\n`);
+    return await runWithMutation("install", ctx, async (scoped) => performInstall(argv, scoped));
+}
+async function performInstall(argv, ctx) {
     // scripts/install never reads "$@", so extra arguments are silently
     // ignored -- the same asymmetry runPrepare and runUninstall document.
     void argv;
-    ctx.stdout.write(`${ctx.adapter.presentation.installNotice}\n`);
     let probe;
     try {
         probe = await gatherProbe(ctx);
@@ -179,7 +273,7 @@ export async function runInstall(argv, ctx) {
         // runs only after this try/catch has resolved.
         //
         // This is a SECOND consumer of gatherProbe's throw channel --
-        // `src/commands/probe.ts:251-309::THREE exceptions, all inherited and none a regression:`'s
+        // `src/commands/probe.ts:469-527::THREE exceptions, all inherited and none a regression:`'s
         // runProbe catch is the first. Because both consumers wrap the identical
         // function, its long comment there enumerates exactly what can reach THIS
         // stream too, including the three foreign-text exceptions at :251-296:
@@ -215,6 +309,11 @@ export async function runInstall(argv, ctx) {
         writeOutput(facts.ownership.installEligibility.output, ctx);
         return 1;
     }
+    if (facts.resourceState === "recovery-required" &&
+        facts.control.probeEligibility.kind === "blocked") {
+        writeOutput(facts.control.probeEligibility.output, ctx);
+        return 1;
+    }
     switch (facts.status) {
         case "needs prepare": {
             const prepareStatus = await runPrepare([], ctx);

package/dist/commands/mutation.js

@@ -0,0 +1,71 @@
+import { computeEffectiveSelection } from "../effective-selection.js";
+import { upstreamCacheRoot } from "../upstream-workspace.js";
+import { SafetyError } from "../safety-error.js";
+import { isAbsolute } from "node:path";
+import { oneLine } from "../cli-arguments.js";
+export async function withMutation(command, ctx, action) {
+    // Selection validation precedes every adapter call and lock creation. A
+    // nested mutation receives the already resolved value and cannot observe a
+    // saved-selection change midway through one invocation.
+    const selection = command === "uninstall"
+        ? ctx.selection
+        : (ctx.selection ?? (await computeEffectiveSelection(ctx.root, ctx.env)));
+    const scoped = selection === undefined ? ctx : { ...ctx, selection };
+    const adapterContext = { root: ctx.root, env: ctx.env };
+    let location;
+    try {
+        location = ctx.adapter.preparationLocation(adapterContext);
+    }
+    catch (cause) {
+        throw new SafetyError("mutation", "cannot determine preparation location", {
+            cause,
+        });
+    }
+    if (!isAbsolute(location.destinationRoot))
+        throw new SafetyError("mutation", "adapter returned a non-absolute preparation destination");
+    if (!location.stagingLeaf ||
+        location.stagingLeaf === "." ||
+        location.stagingLeaf === ".." ||
+        location.stagingLeaf.includes("/") ||
+        location.stagingLeaf.includes("\\"))
+        throw new SafetyError("mutation", "adapter returned an invalid preparation staging leaf");
+    let mutationRoots;
+    try {
+        mutationRoots = await ctx.adapter.mutationRoots(adapterContext);
+        if (!Array.isArray(mutationRoots) ||
+            mutationRoots.some((root) => typeof root !== "string" || !isAbsolute(root)))
+            throw new Error("invalid roots");
+    }
+    catch (cause) {
+        throw new SafetyError("mutation", "cannot determine harness mutation resources", { cause });
+    }
+    const resources = [location.destinationRoot, ...mutationRoots];
+    if (command === "prepare") {
+        resources.push(upstreamCacheRoot(ctx.root, ctx.env, process.cwd()));
+    }
+    // The coordinator sorts each acquisition and refuses conflicts immediately.
+    // A nested prepare may add a cache lock that sorts before an outer target;
+    // it cannot deadlock because no acquisition waits, while already-held roots
+    // are reentrant for this invocation.
+    return await ctx.coordination.withResources(resources, async () => action(scoped));
+}
+export async function runWithMutation(command, ctx, action) {
+    let actionThrew = false;
+    try {
+        return await withMutation(command, ctx, async (scoped) => {
+            try {
+                return await action(scoped);
+            }
+            catch (cause) {
+                actionThrew = true;
+                throw cause;
+            }
+        });
+    }
+    catch (cause) {
+        if (actionThrew)
+            throw cause;
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+}