superpowers-manager 0.3.0 → 0.5.0

package/dist/commands/install.js

@@ -4,62 +4,62 @@
 // and the adapter arrives through ctx.adapter.
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
-import { requireManagedUpdateControl, requireNoLegacyState, verifyInstalledFingerprint, } from "../lifecycle.js";
-import { generatedMetadataPath, readStrictProvenanceField, } from "../provenance.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
-import { formatPorcelain, gatherProbe, replayOutcome, } from "./probe.js";
+import { gatherProbe, replayOutcome, validInstalled, validOutput, } from "./probe.js";
 import { runPrepare } from "./prepare.js";
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:13::conflicting`, verbatim, and always first: the shell echoed it before
-// even invoking probe.
-const NOTE = "Note: remove or disable conflicting Superpowers providers yourself before" +
-    " relying on manager skills.\n";
-function readStringField(result, key, label) {
-    // Callers only reach this after invoke() has already proven
-    // `result.status === 0 && result.outcome.ok`; the guard below is for
-    // TypeScript's narrowing of `outcome.result`, not a live branch.
-    const outcome = result.outcome;
-    const parsed = outcome.ok
-        ? outcome.result
-        : null;
-    const raw = parsed?.[key];
-    if (raw === null || raw === undefined)
-        return { kind: "ok", value: "" };
-    if (typeof raw === "string")
-        return { kind: "ok", value: raw };
-    return {
-        kind: "malformed",
-        message: `adapter returned a non-string ${key} for ${label}`,
-    };
+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(ctx, env, argv, outcomes) {
+async function invoke(call, failure, outcomes, valid = () => true) {
     let result;
     try {
-        result = await ctx.adapter(argv, { root: ctx.root, env });
+        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: `cannot invoke Codex adapter for ${argv.join(" ")}`,
-            result: null,
-        };
+        return { ok: false, message: failure.unexpected, result: null };
     }
-    // Clause 1: replay every outcome, on both the success and the failure
-    // path, before any decision -- collected here and replayed by runInstall
-    // once gatherInstallStages's try/catch has resolved, for the same EPIPE
-    // reason gatherProbe carries its outcomes out rather than writing in place
-    // (src/commands/probe.ts).
     outcomes.push(result.outcome);
     const outcome = result.outcome;
     if (result.status !== 0 || !outcome.ok) {
         return {
             ok: false,
-            message: outcome.ok
-                ? `adapter reported a failure status for ${argv.join(" ")}`
-                : null,
+            message: outcome.ok ? failure.invalidStatus : null,
             result,
         };
     }
-    return { ok: true, result };
+    return {
+        ok: true,
+        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
@@ -84,7 +84,7 @@ class GatherFailure extends Error {
 // created via spw_make_workspace + spw_install_workspace_trap. Performs no
 // writes of its own -- same EPIPE-avoidance shape as gatherProbe and
 // src/commands/uninstall.ts's gatherUninstall.
-async function gatherInstallStages(ctx, desiredCommit) {
+async function gatherInstallStages(ctx, selection, artifact) {
     // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:38::tmp_parent=` -- ${TMPDIR:-/tmp}. Matches
     // src/commands/uninstall.ts's gatherUninstall.
     const parent = ctx.env.TMPDIR ?? tmpdir();
@@ -98,36 +98,61 @@ async function gatherInstallStages(ctx, desiredCommit) {
                 outcomes,
                 message,
             });
+            const adapterContext = { root: ctx.root, env };
             // Stage 1: inspect ownership, re-checked even though gatherProbe just
             // reported it. Mutation authority requires CURRENT, VALIDATED
             // evidence -- a probe's answer is neither by the time this runs.
-            const ownership = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
+            const ownershipFailure = ctx.adapter.presentation.callFailure("install-ownership", adapterContext);
+            const ownership = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure, outcomes);
             if (!ownership.ok)
                 return failed(ownership.message);
-            const identity = readStringField(ownership.result, "identity_state", "inspect --view ownership");
-            if (identity.kind === "malformed")
-                return failed(identity.message);
-            const legacy = requireNoLegacyState(identity.value);
-            if (legacy.kind === "blocked") {
-                return { kind: "blocked", outcomes, lines: legacy.lines };
+            const ownershipDecision = ownership.result.outcome.result.installEligibility;
+            if (ownershipDecision.kind === "blocked") {
+                return {
+                    kind: "blocked",
+                    outcomes,
+                    output: ownershipDecision.output,
+                };
             }
-            if (legacy.kind === "unknown")
-                return failed(legacy.message);
             // Stage 2: inspect update-control, re-checked for the same reason.
-            const updateControl = await invoke(ctx, env, ["inspect", "--view", "update-control"], outcomes);
-            if (!updateControl.ok)
-                return failed(updateControl.message);
-            const control = readStringField(updateControl.result, "update_control", "inspect --view update-control");
-            if (control.kind === "malformed")
+            const controlFailure = ctx.adapter.presentation.callFailure("install-control", adapterContext);
+            const control = await invoke(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure, outcomes);
+            if (!control.ok)
                 return failed(control.message);
-            const managed = requireManagedUpdateControl(control.value);
-            if (!managed.ok)
-                return failed(managed.message);
+            const mutationDecision = control.result.outcome.result.mutationEligibility;
+            if (mutationDecision.kind === "blocked") {
+                return {
+                    kind: "blocked",
+                    outcomes,
+                    output: mutationDecision.output,
+                };
+            }
             // Stage 3: the mutation itself. Nothing above may have issued this --
             // that is the whole point of stages 1 and 2 running first.
-            const install = await invoke(ctx, env, ["install", "--package-root", ctx.root], outcomes);
+            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, 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
@@ -137,32 +162,78 @@ async function gatherInstallStages(ctx, desiredCommit) {
             // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:91-94::spw_inspect_fingerprint`,
             // is what turns a failed inspection into "error: installed manager
             // fingerprint inspection failed after install."
-            // verifyInstalledFingerprint's "call-failed" arm
-            // (`src/lifecycle.ts:158::if (inspected.kind === "call-failed") {`)
-            // exists for exactly this and is reachable only from here. Returning
+            // renderInstallVerification's failed-inspection arm
+            // (`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.
-            const inspected = await invoke(ctx, env, ["inspect", "--view", "fingerprint"], outcomes);
-            let inspectResult;
-            if (inspected.ok) {
-                inspectResult = inspected.result;
+            // 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, validInstalled);
+            const inspection = inspected.result;
+            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}`]),
+                        ],
+                    };
+                }
             }
-            else {
-                if (inspected.result === null)
-                    return failed(inspected.message);
-                inspectResult = inspected.result;
-            }
-            const verdict = verifyInstalledFingerprint(desiredCommit, install.result, inspectResult);
+            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,
-                status: verdict.ok ? 0 : 1,
-                stdout: verdict.stdout,
-                stderr: verdict.stderr,
+                status: verified ? 0 : 1,
+                stdout: output.stdout,
+                stderr: output.stderr,
             };
         }, {
             // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
@@ -182,44 +253,15 @@ async function gatherInstallStages(ctx, desiredCommit) {
         throw new GatherFailure(cause, outcomes);
     }
 }
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:29-32::printf` kept its shell `case ... *)` wildcard even though the
-// three inputs the shell's own probe could ever emit were bounded by the same
-// three-way status.sh logic this port's statusForCommits (src/status.ts) now
-// owns exactly. statusForCommits can only ever return "needs prepare",
-// "needs install" or "current" -- so this branch is NOT reachable through
-// runInstall's own call to gatherProbe today. It stays anyway, because
-// ProbeFacts.status is typed `string`, not that three-literal union, and a
-// future caller that builds facts by hand (as this module's own unit test
-// does, directly) must still see it fail closed rather than silently
-// proceed.
-//
-// Exported specifically so a direct test can reach it. That is ONE STEP
-// FURTHER than
-// `src/commands/probe.ts:367-372::This guard is NOT the production path.`'s own
-// precedent: that comment licenses RETAINING an unreachable branch inside an
-// already-public function (runProbe was public before that comment existed),
-// not EXPORTING a new one. This module does the latter, deliberately, because
-// runInstall
-// itself has no way to construct the unreachable input. Not part of the
-// interface Task 5 or Task 8 consume.
-//
-// A test against this export proves the two writes below are correct for a
-// given `facts`. It does NOT prove that runInstall's own `else if` branch
-// actually reaches and calls this function, or that runInstall returns 1
-// afterward -- those are properties of the call site, not of this function,
-// and need their own coverage there.
-export function renderUnknownProbeStatus(facts, ctx) {
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:30-31::printf` -- the porcelain reaches the terminal ONLY here.
-    // Every other path swallows it, matching `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:18::porcelain`'s
-    // probe_output=$(...) capture.
-    ctx.stdout.write(formatPorcelain(facts));
-    ctx.stderr.write(`error: unknown probe status: ${facts.status}\n`);
-}
 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(NOTE);
     let probe;
     try {
         probe = await gatherProbe(ctx);
@@ -231,20 +273,20 @@ 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:399-433::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 :399-433:
-        //   1. :399-410 -- resolveRef splices git's own combined stdout+stderr
+        // stream too, including the three foreign-text exceptions at :251-296:
+        //   1. :251-262 -- resolveRef splices git's own combined stdout+stderr
         //      into its text. Reached on probe's DEFAULT path, which that comment
         //      defines as every invocation NOT resolving a saved pin: a 40-hex
         //      ref returns a "raw-commit" resolution at
         //      `src/upstream.ts:162-164::return { kind: "raw-commit"`
         //      before any git call, so it reaches no splice at all.
-        //   2. :411-423 -- src/selection-store.ts's read path interpolates the
+        //   2. :263-280 -- src/selection-store.ts's read path interpolates the
         //      caught error's own message, so Node errno prose can appear.
         //      AGENTS.md grandfathers that module's wording.
-        //   3. :424-433 -- a SPAWN-level git failure, a different channel from
+        //   3. :281-296 -- a SPAWN-level git failure, a different channel from
         //      exception 1's exit-status one: on the non-ENOENT arm of
         //      `src/git.ts:47-52::if (typeof failure.code === "string") {`, runGit
         //      rejects with "cannot run git: " followed by the Node spawn error's
@@ -263,72 +305,45 @@ export async function runInstall(argv, ctx) {
         return 1;
     }
     const facts = probe.facts;
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:19-20::identity_state=$(spw_probe_field`. Guards the PROBE-derived value only -- the
-    // re-inspection at :198 reads through readStringField, which already has
-    // its own "malformed" arm for a non-string value, and an empty string
-    // there is legitimately absent (the JSON-null convention), not an error.
-    // This check exists because a probe that reports no identity state at all
-    // is a different failure than one that reports an unrecognised one:
-    // requireNoLegacyState("") would otherwise reach its "unknown" arm and
-    // print "unknown adapter identity state: " (empty-suffixed), which names a
-    // symptom rather than the actual cause. Do NOT add a second copy of this
-    // check at :198 -- it guards a different value with a different failure
-    // mode.
-    if (facts.identityState.length === 0) {
-        ctx.stderr.write("error: probe did not report adapter identity state\n");
-        return 1;
-    }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:20-21::report`, run BEFORE the workspace is ever created and before
-    // any further adapter call -- a legacy identity is fatal on sight, not
-    // something worth spending a mutation attempt on.
-    const legacy = requireNoLegacyState(facts.identityState);
-    if (legacy.kind === "blocked") {
-        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:50-53::'Legacy superpowers-wrapper Codex state is`
-        // is a single printf writing three bare lines to stderr, no `error: `
-        // prefix; :54 is the `return 1` that follows it, reached without spw_die.
-        for (const line of legacy.lines)
-            ctx.stderr.write(`${line}\n`);
+    if (facts.ownership.installEligibility.kind === "blocked") {
+        writeOutput(facts.ownership.installEligibility.output, ctx);
         return 1;
     }
-    if (legacy.kind === "unknown") {
-        ctx.stderr.write(`error: ${legacy.message}\n`);
+    if (facts.resourceState === "recovery-required" &&
+        facts.control.probeEligibility.kind === "blocked") {
+        writeOutput(facts.control.probeEligibility.output, ctx);
         return 1;
     }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:22-33::status=`.
-    if (facts.status === "needs prepare") {
-        // Called as a FUNCTION: a failure propagates as a status, never through
-        // `set -eu`. runPrepare has already replayed its own outcomes and
-        // written its own diagnostics by the time it returns, so nothing further
-        // is written here on that path.
-        const prepareStatus = await runPrepare([], ctx);
-        if (prepareStatus !== 0)
-            return prepareStatus;
-    }
-    else if (facts.status !== "needs install" && facts.status !== "current") {
-        renderUnknownProbeStatus(facts, ctx);
-        return 1;
+    switch (facts.status) {
+        case "needs prepare": {
+            const prepareStatus = await runPrepare([], ctx);
+            if (prepareStatus !== 0)
+                return prepareStatus;
+            break;
+        }
+        case "needs install":
+            break;
+        case "current":
+            break;
     }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:35-36::spw_metadata_commit_or_empty`. The STRICT reader, never the lenient
-    // generatedCommitOrEmpty gatherProbe already used for facts.generatedCommit:
-    // a throw, an absent key, or a non-string value are all treated as absent
-    // here, matching spw_metadata_commit_or_empty's `|| true` plus the
-    // following `[ -n ]` check.
-    let desiredCommit = "";
+    let prepared;
     try {
-        const value = await readStrictProvenanceField(generatedMetadataPath(ctx.root), "commit");
-        if (typeof value === "string")
-            desiredCommit = value;
+        prepared = await ctx.adapter.readPrepared({ root: ctx.root, env: ctx.env });
     }
     catch {
-        // Absent, same as an undefined or non-string read.
+        ctx.stderr.write("error: cannot read prepared harness state\n");
+        return 1;
     }
-    if (desiredCommit.length === 0) {
-        ctx.stderr.write("error: generated metadata missing desired commit after prepare\n");
+    replayOutcome(prepared.outcome, ctx);
+    if (!prepared.outcome.ok)
+        return 1;
+    if (prepared.status !== 0) {
+        ctx.stderr.write("error: adapter reported a failure status for prepared harness inspection\n");
         return 1;
     }
     let stage;
     try {
-        stage = await gatherInstallStages(ctx, desiredCommit);
+        stage = await gatherInstallStages(ctx, facts.selection, prepared.outcome.result);
     }
     catch (cause) {
         const outcomes = cause instanceof GatherFailure ? cause.outcomes : [];
@@ -343,8 +358,7 @@ export async function runInstall(argv, ctx) {
         replayOutcome(each, ctx);
     let status;
     if (outcome.kind === "blocked") {
-        for (const line of outcome.lines)
-            ctx.stderr.write(`${line}\n`);
+        writeOutput(outcome.output, ctx);
         status = 1;
     }
     else if (outcome.kind === "failed") {
@@ -355,8 +369,8 @@ export async function runInstall(argv, ctx) {
     }
     else {
         // :99-100 printed both lines BEFORE deciding, on every path that got this
-        // far; verifyInstalledFingerprint already encodes that, so both arrays
-        // are written in order regardless of verdict.ok.
+        // far; the verified outcome already carries both renderer arrays, so they
+        // are written in order regardless of its status.
         for (const line of outcome.stdout)
             ctx.stdout.write(`${line}\n`);
         for (const line of outcome.stderr)

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;
+    }
+}