superpowers-manager 0.4.0 → 0.5.1

package/dist/artifact-tree.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { assertExistingContained, assertNoFollowType, assertSymlinkTargetContained, } from "./safe-path.js";
+import { SafetyError } from "./safety-error.js";
+import { parseStrictJson } from "./strict-json.js";
+import { compareByCodePoint } from "./python-text.js";
+import { DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "./skill-validation.js";
+export const ARTIFACT_RECEIPT = ".superpowers-manager.json";
+export const ARTIFACT_DIGEST_RE = /^[a-f0-9]{64}$/;
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export function addArtifactHashField(hash, bytes) {
+    const length = Buffer.alloc(8);
+    length.writeBigUInt64BE(BigInt(bytes.byteLength));
+    hash.update(length);
+    hash.update(bytes);
+}
+export async function readArtifactFile(root, path, limit = 1024 * 1024) {
+    try {
+        await assertExistingContained(root, path);
+        await assertNoFollowType(path, ["regular-file"]);
+        if ((await lstat(path)).size > limit)
+            throw new Error("size");
+        const bytes = await readFile(path);
+        if (bytes.length > limit)
+            throw new Error("size");
+        return bytes;
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `cannot read bounded artifact file: ${path}`, { cause });
+    }
+}
+export async function readArtifactObject(root, path) {
+    try {
+        const value = parseStrictJson(await readArtifactFile(root, path), {
+            duplicateKeys: "reject",
+            nonStandardConstants: "reject",
+            maxDepth: 64,
+        });
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("object");
+        return value;
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `invalid artifact JSON object: ${path}`, {
+            cause,
+        });
+    }
+}
+export async function validateNativeSkill(root) {
+    const path = join(root, "skills", "using-superpowers", "SKILL.md");
+    await readArtifactFile(root, path);
+    const errors = [];
+    await validateSkillFrontmatter(path, "using-superpowers", errors, DEFAULT_FS_DEPS);
+    if (errors.length)
+        throw new SafetyError("artifact", `invalid native bootstrap skill: ${path}`);
+}
+export async function digestArtifactTree(root) {
+    try {
+        await assertNoFollowType(root, ["directory"]);
+        const paths = [];
+        async function visit(relative) {
+            for (const bytes of await readdir(join(root, relative), {
+                encoding: "buffer",
+            })) {
+                const name = DECODER.decode(bytes);
+                const path = relative ? `${relative}/${name}` : name;
+                if (path === ARTIFACT_RECEIPT)
+                    continue;
+                paths.push(path);
+                if ((await lstat(join(root, path))).isDirectory())
+                    await visit(path);
+            }
+        }
+        await visit("");
+        const hash = createHash("sha256");
+        for (const path of paths.sort(compareByCodePoint)) {
+            const absolute = join(root, path), info = await lstat(absolute);
+            let kind, contents;
+            if (info.isDirectory()) {
+                kind = "directory";
+                contents = Buffer.alloc(0);
+            }
+            else if (info.isFile()) {
+                kind = "file";
+                contents = await readFile(absolute);
+            }
+            else if (info.isSymbolicLink()) {
+                await assertSymlinkTargetContained(root, absolute);
+                kind = "link";
+                contents = await readlink(absolute, { encoding: "buffer" });
+                DECODER.decode(contents);
+            }
+            else
+                throw new Error("entry type");
+            for (const bytes of [
+                Buffer.from(kind),
+                Buffer.from(path),
+                Buffer.from(String(info.isFile() ? info.mode & 0o111 : 0)),
+                contents,
+            ])
+                addArtifactHashField(hash, bytes);
+        }
+        return hash.digest("hex");
+    }
+    catch (cause) {
+        throw new SafetyError("artifact", `cannot digest artifact tree: ${root}`, {
+            cause,
+        });
+    }
+}

package/dist/atomic.js

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { constants, lstat, open, readFile, rename, rm, unlink, } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { SafetyError } from "./safety-error.js";
 export async function atomicWriteFile(path, bytes, options) {
     const renamePath = options.hooks?.rename ?? rename;
@@ -92,18 +92,52 @@ async function chooseBackup(live) {
     }
     throw new SafetyError("atomic", "cannot choose unique backup path");
 }
-export async function atomicReplaceDir(candidate, live, options = {}) {
+async function validateRequestedBackup(backup, candidate, live) {
+    const resolvedBackup = resolve(backup);
+    const resolvedCandidate = resolve(candidate);
+    const resolvedLive = resolve(live);
+    const prefix = `.${basename(resolvedLive)}.bak.`;
+    if (dirname(resolvedBackup) !== dirname(resolvedLive) ||
+        !basename(resolvedBackup).startsWith(prefix) ||
+        basename(resolvedBackup).length === prefix.length ||
+        resolvedBackup === resolvedCandidate ||
+        resolvedBackup === resolvedLive ||
+        (await exists(backup))) {
+        throw new Error("invalid directory backup path");
+    }
+}
+async function directoryIdentity(path) {
+    const details = await lstat(path);
+    return { dev: details.dev, ino: details.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function publicationFailure(message, cause) {
+    return new SafetyError("atomic", message, {
+        cause,
+        details: { phase: "post-replacement" },
+    });
+}
+export async function beginDirectoryPublication(candidate, live, options = {}) {
     const renamePath = options.hooks?.rename ?? rename;
     const removePath = options.hooks?.rm ?? rm;
     let backupCreated = false;
+    let backupIdentity = null;
     let phase = "pre-replacement";
     try {
-        const backup = await chooseBackup(live);
+        const backup = options.backupPath ?? (await chooseBackup(live));
+        if (options.backupPath !== undefined) {
+            await validateRequestedBackup(backup, candidate, live);
+        }
         if (await exists(live)) {
+            backupIdentity = await directoryIdentity(live);
             await renamePath(live, backup);
             backupCreated = true;
         }
+        let publishedIdentity;
         try {
+            publishedIdentity = await directoryIdentity(candidate);
             await renamePath(candidate, live);
             phase = "post-replacement";
         }
@@ -125,14 +159,72 @@ export async function atomicReplaceDir(candidate, live, options = {}) {
             await removePath(candidate, { recursive: true, force: true });
             throw new SafetyError("atomic", "directory activation failed; previous tree restored", { cause, details: { phase: "pre-replacement" } });
         }
-        if (backupCreated) {
+        const retainedBackup = backupCreated ? backup : null;
+        const retainedBackupIdentity = backupCreated ? backupIdentity : null;
+        let settled = false;
+        const claimSettlement = () => {
+            if (settled) {
+                throw publicationFailure("directory publication already settled", new Error("publication already settled"));
+            }
+            settled = true;
+        };
+        const requireRetainedBackup = async (action) => {
+            if (retainedBackup === null)
+                return;
+            let currentIdentity;
             try {
-                await removePath(backup, { recursive: true, force: true });
+                currentIdentity = await directoryIdentity(retainedBackup);
             }
             catch (cause) {
-                throw new SafetyError("atomic", `directory replacement succeeded but backup cleanup failed at ${backup}`, { cause, details: { phase: "post-replacement" } });
+                throw publicationFailure(`directory ${action} refused because backup changed unexpectedly at ${retainedBackup}`, cause);
             }
-        }
+            if (retainedBackupIdentity === null ||
+                !sameIdentity(currentIdentity, retainedBackupIdentity)) {
+                throw publicationFailure(`directory ${action} refused because backup changed unexpectedly at ${retainedBackup}`, new Error("retained backup directory identity changed"));
+            }
+        };
+        return {
+            live,
+            backup: retainedBackup,
+            async finalize() {
+                claimSettlement();
+                if (retainedBackup === null)
+                    return;
+                await requireRetainedBackup("finalization");
+                try {
+                    await removePath(retainedBackup, { recursive: true, force: true });
+                }
+                catch (cause) {
+                    throw publicationFailure(`directory replacement succeeded but backup cleanup failed at ${retainedBackup}`, cause);
+                }
+            },
+            async rollback() {
+                claimSettlement();
+                await requireRetainedBackup("rollback");
+                let currentIdentity;
+                try {
+                    currentIdentity = await directoryIdentity(live);
+                }
+                catch (cause) {
+                    throw publicationFailure(`directory rollback refused because live tree changed unexpectedly at ${live}`, cause);
+                }
+                if (!sameIdentity(currentIdentity, publishedIdentity)) {
+                    throw publicationFailure(`directory rollback refused because live tree changed unexpectedly at ${live}`, new Error("published directory identity changed"));
+                }
+                try {
+                    await removePath(live, { recursive: true, force: true });
+                    if (retainedBackup !== null) {
+                        await renamePath(retainedBackup, live);
+                    }
+                }
+                catch (cause) {
+                    const message = retainedBackup === null
+                        ? "directory rollback failed with no prior tree"
+                        : `directory rollback failed; backup preserved at ${retainedBackup}`;
+                    throw publicationFailure(message, cause);
+                }
+            },
+        };
     }
     catch (cause) {
         if (cause instanceof SafetyError)
@@ -140,3 +232,7 @@ export async function atomicReplaceDir(candidate, live, options = {}) {
         throw new SafetyError("atomic", "directory replacement failed", { cause, details: { phase } });
     }
 }
+export async function atomicReplaceDir(candidate, live, options = {}) {
+    const pending = await beginDirectoryPublication(candidate, live, options);
+    await pending.finalize();
+}

package/dist/cli-arguments.js

@@ -1,5 +1,42 @@
 export class UsageError extends Error {
 }
+export function extractHarnessOptions(command, argv) {
+    let harness = "codex";
+    let targeted = false;
+    let allowExperimental = false;
+    const args = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--harness" || token.startsWith("--harness=")) {
+            if (command === "pin" ||
+                command === "unpin" ||
+                command === "track-latest")
+                throw new UsageError("harness targeting is not available for shared selection commands");
+            if (targeted)
+                throw new UsageError("duplicate option: --harness");
+            targeted = true;
+            const value = token === "--harness"
+                ? argv[++index]
+                : token.slice("--harness=".length);
+            if (!value || value.startsWith("--"))
+                throw new UsageError("option --harness requires a value");
+            if (value !== "codex" && value !== "pi")
+                throw new UsageError(`unknown harness: ${value}`);
+            harness = value;
+        }
+        else if (token === "--allow-experimental") {
+            if (command !== "install" && command !== "update")
+                throw new UsageError("--allow-experimental is only available for install or update");
+            if (allowExperimental)
+                throw new UsageError("duplicate option: --allow-experimental");
+            allowExperimental = true;
+        }
+        else {
+            args.push(token);
+        }
+    }
+    return { options: { harness, allowExperimental }, args };
+}
 export function parseFlags(argv, names) {
     const allowed = new Set(names);
     const result = {};

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { oneLine } from "./cli-arguments.js";
-import { codexHarness } from "./codex-harness.js";
+import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
+import { codexHarness } from "./harnesses/codex/harness.js";
+import { piHarness } from "./harnesses/pi/harness.js";
+import { createResourceCoordinator } from "./resource-lock.js";
 import { runInstall } from "./commands/install.js";
 import { runPin } from "./commands/pin.js";
 import { runPrepare } from "./commands/prepare.js";
@@ -85,14 +87,28 @@ function isMain(moduleFilename, argvPath) {
 function parseArgs(argv) {
     const first = argv[0];
     if (argv.length === 0)
-        return { kind: "run", cmd: "update", args: [] };
+        return {
+            kind: "run",
+            cmd: "update",
+            args: [],
+            options: { harness: "codex", allowExperimental: false },
+        };
     if (first === "--help" || first === "-h")
         return { kind: "help" };
     if (first === "--version")
         return { kind: "version" };
     if (first && SUBCOMMANDS.includes(first)) {
         const command = first;
-        const args = argv.slice(1);
+        let extracted;
+        try {
+            extracted = extractHarnessOptions(command, argv.slice(1));
+        }
+        catch (cause) {
+            if (cause instanceof UsageError)
+                return { kind: "usage-error", message: cause.message };
+            throw cause;
+        }
+        const { args, options } = extracted;
         if (command === "pin" && args.length !== 1) {
             return {
                 kind: "usage-error",
@@ -128,7 +144,7 @@ function parseArgs(argv) {
                 message: "usage: superpowers-manager probe [--porcelain]",
             };
         }
-        return { kind: "run", cmd: command, args };
+        return { kind: "run", cmd: command, args, options };
     }
     return { kind: "usage-error", message: `unknown subcommand: ${first}` };
 }
@@ -232,6 +248,14 @@ function usage() {
         "  update     probe, then prepare/install only if needed (default when no subcommand)",
         "  uninstall  remove the manager plugin and marketplace from Codex",
         "",
+        "Target one invocation (default: codex; selection commands are shared):",
+        "  probe --harness pi [--porcelain]",
+        "  prepare --harness pi",
+        "  install --harness pi [--allow-experimental]",
+        "  update --harness pi [--allow-experimental]",
+        "  uninstall --harness pi",
+        "  --harness=codex and --harness=pi are also accepted after the command.",
+        "",
         "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
         "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",
         "SUPERPOWERS_CONFIG_DIR, XDG_CONFIG_HOME,",
@@ -264,11 +288,22 @@ async function main() {
         console.error(usage());
         process.exit(2);
     }
-    const pf = preflight(parsed.cmd, process.env, process.platform);
+    const status = parsed.options.harness === "pi"
+        ? await dispatch(piHarness, parsed)
+        : await dispatch(codexHarness, parsed);
+    process.exit(status);
+}
+async function dispatch(adapter, parsed) {
+    const root = resolvePackageRoot(import.meta.filename);
+    if (!root) {
+        console.error("error: cannot resolve the superpowers-manager package root");
+        return 1;
+    }
+    const pf = preflightFor(parsed.cmd, process.env, process.platform, adapter);
     if (!pf.ok) {
         for (const e of pf.errors)
             console.error(`error: ${e}`);
-        process.exit(1);
+        return 1;
     }
     // Dispatch is no longer a branch: slice 4b flipped the last spawned command,
     // so every subcommand runs here, and slice 6 deleted the DISPATCH table whose
@@ -281,15 +316,17 @@ async function main() {
     const handler = IN_PROCESS_HANDLERS[parsed.cmd];
     if (!handler) {
         console.error(`error: no in-process handler registered for: ${parsed.cmd}`);
-        process.exit(1);
+        return 1;
     }
     const ctx = {
         root,
         env: process.env,
         stdout: process.stdout,
         stderr: process.stderr,
+        options: parsed.options,
+        coordination: createResourceCoordinator(),
         // The ONLY production binding of a concrete harness implementation.
-        adapter: codexHarness,
+        adapter,
     };
     let status;
     try {
@@ -300,11 +337,11 @@ async function main() {
         // failures and returns a status code (see src/commands/unpin.ts). This
         // re-emits a subordinate module's own diagnostic if one somehow escapes.
         console.error(`error: ${oneLine(cause)}`);
-        process.exit(1);
+        return 1;
     }
-    process.exit(status);
+    return status;
 }
-export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, commandRequirementsFor, preflight, preflightFor, usage, main, };
+export { resolvePackageRoot, isMain, parseArgs, findTool, commandRequirements, commandRequirementsFor, preflight, preflightFor, usage, dispatch, main, };
 if (isMain(import.meta.filename, process.argv[1])) {
     main().catch((cause) => {
         console.error(`error: ${oneLine(cause)}`);

package/dist/commands/install.js

@@ -1,22 +1,42 @@
 // Ports scripts/install. The shell sourced common.sh, provenance.sh,
 // status.sh, lifecycle.sh and adapter.sh; the predicates now live in
-// src/lifecycle.ts, the generated-metadata read lives in src/provenance.ts,
+// src/harnesses/codex/lifecycle.ts, the generated-metadata read lives in src/provenance.ts,
 // and the adapter arrives through ctx.adapter.
 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/harnesses/codex/presentation.ts:329::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);