superpowers-manager 0.3.0 → 0.4.0

package/dist/codex-presentation.js

@@ -0,0 +1,259 @@
+import { normalizeCodexInstall, normalizeCodexInstalled, } from "./codex-harness.js";
+import { displaySource } from "./selection.js";
+// One ordered table drives both formats, preserving the public human and
+// porcelain field order exposed through the harness presentation.
+export function fields(f) {
+    return [
+        { 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 },
+        {
+            key: "generated_commit",
+            label: "generated plugin commit",
+            value: f.generatedCommit,
+            absent: "not present",
+        },
+        {
+            key: "installed_commit",
+            label: "installed manager commit or fingerprint",
+            value: f.installedCommit,
+            absent: "not detected",
+        },
+        {
+            key: "identity_state",
+            label: "Codex identity state",
+            value: f.identityState,
+        },
+        { key: "status", label: "status", value: f.status },
+        {
+            key: "selection_origin",
+            label: "selection origin",
+            value: f.selectionOrigin,
+        },
+        { key: "selection_mode", label: "selection mode", value: f.selectionMode },
+        {
+            key: "upstream_source_origin",
+            label: "upstream source origin",
+            value: f.upstreamSourceOrigin,
+        },
+        {
+            key: "effective_source",
+            label: "effective source",
+            value: f.effectiveSource,
+        },
+        { key: "saved_mode", label: "saved mode", value: f.savedMode },
+        { key: "saved_source", label: "saved source", value: f.savedSource },
+        {
+            key: "saved_requested_ref",
+            label: "saved requested ref",
+            value: f.savedRequestedRef,
+        },
+        {
+            key: "saved_resolved_ref",
+            label: "saved resolved ref",
+            value: f.savedResolvedRef,
+        },
+        { key: "saved_commit", label: "saved commit", value: f.savedCommit },
+        { key: "update_control", label: "update control", value: f.updateControl },
+    ];
+}
+const NO_FACTS = {
+    requestedRef: "",
+    resolvedRef: "",
+    desiredCommit: "",
+    generatedCommit: "",
+    installedCommit: "",
+    identityState: "",
+    status: "",
+    selectionOrigin: "",
+    selectionMode: "",
+    upstreamSourceOrigin: "",
+    effectiveSource: "",
+    savedMode: "",
+    savedSource: "",
+    savedRequestedRef: "",
+    savedResolvedRef: "",
+    savedCommit: "",
+    updateControl: "",
+};
+export const PROBE_PORCELAIN_KEYS = fields(NO_FACTS).map((field) => field.key);
+export function formatPorcelain(f) {
+    return fields(f)
+        .map((field) => `${field.key}=${field.value}\n`)
+        .join("");
+}
+export function formatHuman(f) {
+    let text = fields(f)
+        .map((field) => {
+        const shown = field.value.length === 0 && field.absent !== undefined
+            ? field.absent
+            : field.value;
+        return `${field.label}: ${shown}\n`;
+    })
+        .join("");
+    if (f.selectionOrigin !== f.upstreamSourceOrigin) {
+        text +=
+            "warning: effective ref and source have mixed origins " +
+                `(ref: ${f.selectionOrigin}, source: ${f.upstreamSourceOrigin})\n`;
+    }
+    return text;
+}
+function verificationOutput(kind, hint) {
+    const stderr = [
+        kind === "mismatch"
+            ? "error: installed manager fingerprint does not match the prepared plugin after install."
+            : "error: installed manager fingerprint is not detectable after install.",
+    ];
+    if (hint.length > 0)
+        stderr.push(`hint: ${hint}`);
+    return { stdout: [], stderr };
+}
+export function codexInstallReceipt(missingHint, mismatchHint) {
+    return {
+        missingVerificationOutput: verificationOutput("missing", missingHint),
+        mismatchVerificationOutput: verificationOutput("mismatch", mismatchHint),
+    };
+}
+// Compatibility export target for src/lifecycle.ts. Delegate to the production
+// normalizers and renderer so the retained verdict cannot drift from commands.
+export function verifyInstalledFingerprint(desiredCommit, installResult, inspectResult) {
+    const receipt = normalizeCodexInstall(installResult);
+    const inspection = normalizeCodexInstalled(inspectResult, desiredCommit);
+    const output = codexPresentation.renderInstallVerification(desiredCommit, receipt, inspection);
+    const ok = inspection.status === 0 &&
+        inspection.outcome.ok &&
+        inspection.outcome.result.kind === "current";
+    return { ok, stdout: output.stdout, stderr: output.stderr };
+}
+function probeFacts(facts) {
+    const selection = facts.selection;
+    const saved = selection.saved;
+    return {
+        requestedRef: selection.requestedRef,
+        resolvedRef: selection.resolvedRef,
+        desiredCommit: selection.desiredCommit,
+        generatedCommit: facts.prepared.observedIdentity,
+        installedCommit: facts.installed.observedIdentity,
+        identityState: facts.ownership.presentationValue,
+        status: facts.status,
+        selectionOrigin: selection.selectionOrigin,
+        selectionMode: selection.selectionMode,
+        upstreamSourceOrigin: selection.upstreamSourceOrigin,
+        effectiveSource: displaySource(selection.effectiveSource),
+        savedMode: saved.saved_mode,
+        savedSource: saved.saved_source.length > 0 ? displaySource(saved.saved_source) : "",
+        savedRequestedRef: saved.saved_requested_ref,
+        savedResolvedRef: saved.saved_resolved_ref,
+        savedCommit: saved.saved_commit,
+        updateControl: facts.control.presentationValue,
+    };
+}
+function invocationFailure(argv) {
+    return {
+        unexpected: `cannot invoke Codex adapter for ${argv}`,
+        invalidStatus: `adapter reported a failure status for ${argv}`,
+    };
+}
+function callFailure(site, ctx, removalInput) {
+    switch (site) {
+        case "prepare":
+            return {
+                unexpected: "cannot build the generated plugin candidate",
+                invalidStatus: "adapter reported failure without an error outcome",
+            };
+        case "probe-installed":
+            return {
+                unexpected: "cannot inspect Codex adapter state for view fingerprint",
+                invalidStatus: "adapter reported a failure status for inspect --view fingerprint",
+            };
+        case "probe-ownership":
+            return {
+                unexpected: "cannot inspect Codex adapter state for view ownership",
+                invalidStatus: "adapter reported a failure status for inspect --view ownership",
+            };
+        case "probe-control":
+            return {
+                unexpected: "cannot inspect Codex adapter state for view update-control",
+                invalidStatus: "adapter reported a failure status for inspect --view update-control",
+            };
+        case "install-ownership":
+        case "remove-ownership":
+        case "post-remove":
+            return invocationFailure("inspect --view ownership");
+        case "install-control":
+            return invocationFailure("inspect --view update-control");
+        case "install":
+            return invocationFailure(`install --package-root ${ctx.root}`);
+        case "post-install":
+            return {
+                unexpected: "cannot invoke Codex adapter for inspect --view fingerprint",
+                invalidStatus: "installed manager fingerprint inspection failed after install.",
+            };
+        case "remove": {
+            const input = removalInput ?? {
+                pluginPresent: false,
+                marketplacePresent: false,
+            };
+            return invocationFailure(`uninstall --plugin-present ${String(input.pluginPresent)}` +
+                ` --marketplace-present ${String(input.marketplacePresent)}`);
+        }
+    }
+}
+export const codexPresentation = {
+    installNotice: "Note: remove or disable conflicting Superpowers providers yourself before" +
+        " relying on manager skills.",
+    currentNotice: "manager is current",
+    renderProbe(snapshot) {
+        const facts = probeFacts(snapshot);
+        return { human: formatHuman(facts), porcelain: formatPorcelain(facts) };
+    },
+    renderInstallVerification(desiredCommit, receipt, inspection) {
+        if (inspection.status !== 0 || !inspection.outcome.ok) {
+            const malformed = !inspection.outcome.ok &&
+                inspection.outcome.error.code === "malformed-result";
+            return {
+                stdout: [],
+                stderr: [
+                    malformed
+                        ? "error: cannot parse installed manager fingerprint inspection result after install."
+                        : "error: installed manager fingerprint inspection failed after install.",
+                ],
+            };
+        }
+        const observed = inspection.outcome.result.observedIdentity;
+        const stdout = [
+            `desired_commit=${desiredCommit}`,
+            `installed_commit=${observed}`,
+        ];
+        if (inspection.outcome.result.kind === "current") {
+            return { stdout: [...stdout, "manager updated"], stderr: [] };
+        }
+        if (receipt.status !== 0 || !receipt.outcome.ok) {
+            return {
+                stdout,
+                stderr: [
+                    inspection.outcome.result.kind === "absent"
+                        ? "error: installed manager fingerprint is not detectable after install."
+                        : "error: installed manager fingerprint does not match the prepared plugin after install.",
+                ],
+            };
+        }
+        const output = inspection.outcome.result.kind === "absent"
+            ? receipt.outcome.result.missingVerificationOutput
+            : receipt.outcome.result.mismatchVerificationOutput;
+        return { stdout, stderr: output.stderr };
+    },
+    renderRemovalCompletion(ownership) {
+        return {
+            stdout: [
+                ...ownership.postRemovalOutput.stdout,
+                "uninstall complete",
+                "note: local generated artifacts under plugins/superpowers/ and " +
+                    ".cache/upstream/ were left in place; remove them manually or " +
+                    "regenerate with npx superpowers-manager prepare.",
+            ],
+            stderr: ownership.postRemovalOutput.stderr,
+        };
+    },
+    callFailure,
+};

package/dist/commands/install.js

@@ -4,62 +4,36 @@
 // 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 } 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}`,
-    };
+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) {
     let result;
     try {
-        result = await ctx.adapter(argv, { root: ctx.root, env });
+        result = await call();
     }
     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 },
+    };
 }
 // withWorkspace can throw AFTER its callback has already returned a fully
 // computed StageOutcome: a post-success cleanup failure discards that return
@@ -84,7 +58,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,34 +72,39 @@ 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 installFailure = ctx.adapter.presentation.callFailure("install", adapterContext);
+            const install = await invoke(() => ctx.adapter.install(artifact, adapterContext), installFailure, outcomes);
             if (!install.ok)
                 return failed(install.message);
             // Stage 4: inspect fingerprint, to verify the mutation actually took.
@@ -137,32 +116,34 @@ 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:306::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;
+            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);
             }
-            else {
-                if (inspected.result === null)
-                    return failed(inspected.message);
-                inspectResult = inspected.result;
-            }
-            const verdict = verifyInstalledFingerprint(desiredCommit, install.result, inspectResult);
+            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 &&
+                inspection.outcome.ok &&
+                inspection.outcome.result.kind === "current";
             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 +163,11 @@ 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) {
     // scripts/install never reads "$@", so extra arguments are silently
     // ignored -- the same asymmetry runPrepare and runUninstall document.
     void argv;
-    ctx.stdout.write(NOTE);
+    ctx.stdout.write(`${ctx.adapter.presentation.installNotice}\n`);
     let probe;
     try {
         probe = await gatherProbe(ctx);
@@ -231,20 +179,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:251-309::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 +211,40 @@ 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");
+    if (facts.ownership.installEligibility.kind === "blocked") {
+        writeOutput(facts.ownership.installEligibility.output, ctx);
         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`);
-        return 1;
-    }
-    if (legacy.kind === "unknown") {
-        ctx.stderr.write(`error: ${legacy.message}\n`);
-        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 +259,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 +270,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)