superpowers-manager 0.2.0 → 0.4.0

package/dist/commands/probe.js

@@ -0,0 +1,257 @@
+import { assertFailureWritable, writeAdapterFailure, } from "../adapter-result.js";
+import { oneLine } from "../cli-arguments.js";
+import { computeEffectiveSelection } from "../effective-selection.js";
+export const PROBE_USAGE = "error: usage: superpowers-manager probe [--porcelain]\n";
+// Ports scripts/core/validate-adapter-response.py's replay (:235-238) and its
+// error/hint block (:269-272). The shell ran that validator on EVERY adapter
+// response, so adapter messages reached the operator on their declared streams
+// in array order, and a controlled failure printed `error:` plus one `hint:`
+// per hint. DIAG-ADAPTER-01 retains that contract
+// (docs/baseline/protocol-disposition.md); dropping it here would be a
+// silent diagnostics regression, not a simplification.
+//
+// Interpolating error.message and each hint is the sanctioned form (AGENTS.md):
+// src/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
+// message, so the callee owns every failure reachable on this path. Those two
+// writes now live in writeAdapterFailure (src/adapter-result.ts), which
+// validates all three strings before the first of them reaches the stream.
+//
+// This writes to ctx, so it MUST NOT be called from inside gatherProbe's try
+// -- see the ProbeOutcome note below.
+export function replayOutcome(outcome, ctx) {
+    // Hoisted ABOVE the message loop, and that ordering is the point: a failure
+    // whose code, message, or a hint carries a terminal control character must
+    // leave both streams untouched, not the context lines followed by nothing.
+    // Returns immediately on a succeeding outcome.
+    assertFailureWritable(outcome);
+    for (const message of outcome.messages) {
+        const stream = message.channel === "stdout" ? ctx.stdout : ctx.stderr;
+        stream.write(`${message.text}\n`);
+    }
+    // The message loop stays unguarded on purpose: D8b scopes the check to code,
+    // message, and hints, and AdapterMessageLog escapes message text before it is
+    // stored, so scanning it here would re-check a population that cannot fail.
+    writeAdapterFailure(ctx, outcome);
+}
+// `runAdapter` reports a CONTROLLED failure by RETURN VALUE, not by throwing
+// (`src/adapter-result.ts:32-35::export interface AdapterResult`). The shell got
+// fail-closed behaviour for free: spw_invoke_adapter returned 1 and
+// scripts/probe ran under `set -eu`.
+// Omitting the status check here would read a failed inspection as absent
+// evidence and report it as success.
+//
+// It does still THROW for a non-AdapterFailure cause (runAdapter's closing
+// `throw cause`, src/adapter.ts). That is caught here rather than in runProbe's
+// outer catch, because the two need different diagnostics -- see spec §3.3a.
+//
+// Reached through ctx.adapter, not a direct module-level dependency on the
+// adapter module: src/commands/prepare.ts and this module are the two the
+// injected double must observe, because install reaches the adapter through
+// gatherProbe and runPrepare. Spec §4.5.
+async function inspect(call, unexpected, invalidStatus) {
+    let result;
+    try {
+        result = await call();
+    }
+    catch {
+        return { ok: false, result: null, message: unexpected };
+    }
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok) {
+        // The `outcome.ok && status !== 0` combination cannot arise from
+        // successResult/failureResult, so it gets its own hand-written message
+        // rather than falling through to a replay that would print nothing.
+        return {
+            ok: false,
+            result,
+            message: outcome.ok ? invalidStatus : null,
+        };
+    }
+    return { ok: true, result: { status: result.status, outcome } };
+}
+// Runs every step that can throw or fail closed, returning the outcome as
+// data. It performs no writes of its own, so nothing inside runProbe's try can
+// raise EPIPE — the same shape as src/commands/unpin.ts's attemptUnpin.
+//
+// The outcomes are CARRIED OUT rather than replayed in place, for that same
+// reason: replayOutcome writes to ctx, and a write inside this try could
+// raise EPIPE and be caught and relabelled as a selection failure. runProbe
+// replays them, in collection order, after the try/catch has resolved. The
+// operator-visible result is identical -- probe emits nothing else until the
+// very end -- and the EPIPE hazard never exists.
+// Exported for src/commands/install.ts and src/commands/update.ts, which need
+// probe's FACTS rather than its rendering. The historical
+// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:39-41::spw_probe_field`
+// implementation awk-parsed the porcelain back into fields; that round trip is
+// gone.
+export async function gatherProbe(ctx) {
+    // Order mirrors `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:24-40::spw_compute_effective_selection` exactly.
+    const selection = await computeEffectiveSelection(ctx.root, ctx.env);
+    const outcomes = [];
+    const adapterContext = { root: ctx.root, env: ctx.env };
+    const collect = async (call, unexpected, invalidStatus) => {
+        const result = await inspect(call, unexpected, invalidStatus);
+        if (result.result !== null)
+            outcomes.push(result.result.outcome);
+        return result;
+    };
+    const prepared = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection");
+    if (!prepared.ok) {
+        return { status: 1, outcomes, message: prepared.message };
+    }
+    const failure = (site) => ctx.adapter.presentation.callFailure(site, adapterContext);
+    const installedFailure = failure("probe-installed");
+    const installed = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus);
+    if (!installed.ok) {
+        return { status: 1, outcomes, message: installed.message };
+    }
+    const ownershipFailure = failure("probe-ownership");
+    const ownership = await collect(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure.unexpected, ownershipFailure.invalidStatus);
+    if (!ownership.ok) {
+        return { status: 1, outcomes, message: ownership.message };
+    }
+    const controlFailure = failure("probe-control");
+    const control = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus);
+    if (!control.ok) {
+        return { status: 1, outcomes, message: control.message };
+    }
+    const preparedState = prepared.result.outcome.result;
+    const installedState = installed.result.outcome.result;
+    return {
+        status: 0,
+        outcomes,
+        facts: {
+            selection,
+            prepared: preparedState,
+            installed: installedState,
+            ownership: ownership.result.outcome.result,
+            control: control.result.outcome.result,
+            status: preparedState.kind !== "current"
+                ? "needs prepare"
+                : installedState.kind !== "current"
+                    ? "needs install"
+                    : "current",
+        },
+    };
+}
+export async function runProbe(argv, ctx) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/probe:42::porcelain` tested only `[ "${1:-}" = "--porcelain" ]`, so a typo'd
+    // flag silently produced human output. Rejecting it is a deliberate
+    // narrowing, recorded as a port-only entry in
+    // tests/migration-inventory/probe.md.
+    //
+    // This guard is NOT the production path. src/cli.ts's parseArgs rejects the
+    // same inputs first, before preflight, with the usage block the CLI's other
+    // usage errors carry — exactly the arrangement track-latest and unpin have,
+    // where the in-module check is an unreachable-from-CLI duplicate. It stays
+    // because runProbe is also called directly by tests and by any future
+    // in-process caller that has not been through parseArgs.
+    const porcelain = argv.length === 1 && argv[0] === "--porcelain";
+    if (!porcelain && argv.length !== 0) {
+        ctx.stderr.write(PROBE_USAGE);
+        return 2;
+    }
+    let outcome;
+    try {
+        outcome = await gatherProbe(ctx);
+    }
+    catch (cause) {
+        // Hand-written messages, per AGENTS.md's reader-diagnostics rule. Reachable
+        // here: the selectionErrors validateSource raises
+        // (`src/selection.ts:137::malformed`, :140, requireSingleLineString at :77),
+        // reached from
+        // computeEffectiveSelection's validateSource call
+        // (src/effective-selection.ts); the ones validateRecord raises
+        // (`src/selection.ts:198::integer`, :219, requireObject at :47, requireExactKeys at
+        // :64, validatePinnedRecord at :170-183), reached from
+        // `src/selection-store.ts:103::return validateRecord` on the read path; the
+        // selectionErrors requireAbsolute and selectionConfigDir
+        // (src/effective-selection.ts) raise
+        // for a non-absolute or missing config directory; readConfigRef's `cannot
+        // read packaged upstream ref <path>` (src/upstream.ts); and resolveRef's own
+        // two no-match diagnostics, `no stable semver tag found for latest-release`
+        // and `cannot resolve upstream ref: <ref>` (src/upstream.ts). normalizeSaved
+        // (`src/selection.ts:222-241::normalizeSaved`) throws nothing at all.
+        //
+        // THREE exceptions, all inherited and none a regression:
+        //   1. resolveRef splices git's combined stdout+stderr into its own text
+        //      (its three `cannot query upstream ...` throws, src/upstream.ts),
+        //      reached via computeEffectiveSelection's resolveRef call
+        //      (src/effective-selection.ts). The packaged ref is `latest-release`,
+        //      which resolveRef answers with an ls-remote, so an ordinary unpinned
+        //      run reaches this rather than only an exotic corner -- though not
+        //      every unpinned run does: resolveRef's COMMIT_INPUT_RE branch returns
+        //      before any runGit call, so a 40-hex requested ref splices nothing.
+        //      Pinned by
+        //      `tests/unit/upstream.test.ts:453::void test("resolveRef reports a query failure for latest`,
+        //      :471, and :483.
+        //   2. The
+        //      `src/selection-store.ts:120-124::cause.module === "selection") {`
+        //      site (same shape at :49, :86, :98) is the module AGENTS.md's
+        //      `src/selection-store.ts` bullet grandfathers:
+        //      it interpolates the caught error's own message, so Node errno
+        //      prose can reach this stream. Reached on the READ path only, via
+        //      loadSavedSelection (src/effective-selection.ts) ->
+        //      readSelectionState
+        //      (`src/selection-store.ts:149::export async function readSelectionState`).
+        //      This module's four write-only interpolating sites -- ensureStateDirectory
+        //      (:172), finalStateDiagnostic (:197), and the two in
+        //      writeSelectionState's own catch (:225, :231) -- are all
+        //      unreachable from probe, which never writes.
+        //   3. Every runGit call site inside resolveRef (src/upstream.ts) can
+        //      reject instead of resolving. On the non-ENOENT arm of
+        //      `src/git.ts:47-52::if (typeof`, runGit builds the message
+        //      "cannot run git: " followed by the Node spawn error's own message
+        //      (:51) and rejects with a SafetyError carrying it (:52), so that
+        //      Node spawn-level text reaches ctx.stderr through this catch. The
+        //      ENOENT arm (:50) is hand-written and carries nothing. A non-zero
+        //      *exit status* is handled by exception 1 above; this is the
+        //      *spawn-level* case, where runGit throws rather than returning a
+        //      status.
+        //
+        // oneLine() at this catch collapses each of exceptions 1 and 3 -- the two
+        // carrying git-derived text -- to a single line. It collapses CR/LF only,
+        // so it bounds how much of that text lands, not what it may contain.
+        //
+        // fetchExactCommit is deliberately NOT in this list, unlike prepare's
+        // fetchExactCommit exception, which runPrepare's catch block documents.
+        // Its only callers are `src/upstream-cli.ts:83::await fetchExactCommit` and
+        // gatherPrepare's own call in src/commands/prepare.ts (git grep -n
+        // fetchExactCommit -- src/ is the check that keeps "only" true), so probe
+        // never reaches it and
+        // its splice sites cannot appear on this stream. Do not add it back by
+        // symmetry with prepare.
+        //
+        // generatedCommitOrEmpty is not in this list either: it cannot throw at
+        // all. It (src/provenance.ts) delegates to readGeneratedCommitLenient,
+        // which catches every failure and returns "".
+        //
+        // A non-AdapterFailure re-thrown by runAdapter's closing `throw cause`
+        // (src/adapter.ts) does NOT reach here: inspect() catches it and converts
+        // it to a hand-written message per AGENTS.md's reader-diagnostics rule -- a
+        // rethrown cause is exactly the failure src/adapter.ts declined to own, so
+        // its text must never reach this stream. See §3.3a.
+        //
+        // gatherProbe performs no writes of its own, so this catch cannot also be
+        // reached by an EPIPE from probe's own output — every write below runs
+        // only after this try/catch has resolved.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    // Replay first, on both paths: the shell validator replayed every response's
+    // messages whether or not that response was a failure at
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/validate-adapter-response.py:268::replay(messages)`.
+    for (const each of outcome.outcomes)
+        replayOutcome(each, ctx);
+    if (outcome.status === 1) {
+        // null means replayOutcome already emitted the adapter's own `error:`
+        // and `hint:` lines for the failing outcome.
+        if (outcome.message !== null) {
+            ctx.stderr.write(`error: ${outcome.message}\n`);
+        }
+        return 1;
+    }
+    const rendered = ctx.adapter.presentation.renderProbe(outcome.facts);
+    ctx.stdout.write(porcelain ? rendered.porcelain : rendered.human);
+    return 0;
+}

package/dist/commands/track-latest.js

@@ -0,0 +1,44 @@
+import { oneLine } from "../cli-arguments.js";
+import { selectionStatePath, loadSavedSelection, UPSTREAM_URL_DEFAULT, } from "../effective-selection.js";
+import { validateSource } from "../selection.js";
+import { writeSelectionState } from "../selection-store.js";
+export async function runTrackLatest(argv, ctx) {
+    if (argv.length !== 0) {
+        ctx.stderr.write("error: usage: superpowers-manager track-latest\n");
+        return 2;
+    }
+    try {
+        // Read first. This is a deliberate redundant boundary check, not the
+        // enforcing guard: writeSelectionState below already refuses to overwrite
+        // a corrupt existing record on its own (src/selection-store.ts's
+        // writeSelectionState calls readSelectionState on the same path before
+        // writing, under "Invalid existing state must block overwrite" —
+        // readSelectionState's own readOpenedRecord/parseRecordBytes is what
+        // validates an existing record, via validateRecord at
+        // `src/selection-store.ts:103::return validateRecord`). Calling loadSavedSelection here preserves
+        // `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/track-latest:20-21::read`'s read-then-write shape, so this command
+        // stays fail-closed on its own terms rather than solely by depending on
+        // the store's internals.
+        await loadSavedSelection(ctx.env);
+        const source = ctx.env.SUPERPOWERS_UPSTREAM_URL || UPSTREAM_URL_DEFAULT;
+        validateSource(source);
+        await writeSelectionState(selectionStatePath(ctx.env), {
+            schema_version: 1,
+            mode: "track-latest",
+            source,
+        });
+    }
+    catch (cause) {
+        // Every throw reachable here is a hand-written SafetyError from
+        // loadSavedSelection, validateSource, selectionStatePath, or
+        // writeSelectionState — re-emitting a subordinate module's own
+        // diagnostic is the sanctioned form of interpolation (see AGENTS.md's
+        // diagnostics convention). The try ends here, before the stdout write
+        // below: an EPIPE from that write must never be caught and relabelled
+        // as one of those modules' own diagnostics.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    ctx.stdout.write("saved upstream selection: latest stable release\n");
+    return 0;
+}

package/dist/commands/uninstall.js

@@ -0,0 +1,217 @@
+// Ports scripts/uninstall. The shell sourced common.sh, provenance.sh,
+// lifecycle.sh and adapter.sh; the predicates now live in src/lifecycle.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 { replayOutcome } from "./probe.js";
+async function invoke(call, failure, outcomes) {
+    let result;
+    try {
+        result = await call();
+    }
+    catch {
+        return { ok: false, message: failure.unexpected };
+    }
+    outcomes.push(result.outcome);
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok) {
+        return {
+            ok: false,
+            message: outcome.ok ? failure.invalidStatus : null,
+        };
+    }
+    return {
+        ok: true,
+        result: { status: result.status, outcome },
+    };
+}
+// withWorkspace throws for mkdtemp failure before the callback ever runs
+// ("cannot create workspace",
+// `src/workspace.ts:120::throw new SafetyError("workspace", "cannot create workspace"`).
+// A bare re-throw would silently drop every outcome collected before that
+// point -- a narrow
+// DIAG-ADAPTER-01 regression the shell never had, since it replayed each
+// adapter response as it went rather than batching replay to the end. This
+// carries the outcomes collected so far alongside the original cause, so
+// runUninstall's catch can still replay them before reporting the cause.
+//
+// The post-success cleanup failure no longer reaches here: onCleanupFailure
+// below suppresses withWorkspace's throw for that case and records the
+// warning as data, so the computed UninstallOutcome survives it. The
+// outcome-carrying is still load-bearing for mkdtemp, and the shape stays
+// identical to src/commands/install.ts's GatherFailure.
+class GatherFailure extends Error {
+    inner;
+    outcomes;
+    constructor(inner, outcomes) {
+        super("uninstall gather failed");
+        this.inner = inner;
+        this.outcomes = outcomes;
+    }
+}
+// Every step that can throw or fail closed, returning the outcome as data and
+// performing NO writes. Same shape as gatherProbe
+// (`src/commands/probe.ts:114-117::readonly facts: ProbeSnapshot<R>;`) and for the same
+// reason: a write inside this try could raise EPIPE, be caught here, and be
+// relabelled as a domain failure.
+async function gatherUninstall(ctx) {
+    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:20-21::TMPDIR=` exported TMPDIR="$uninstall_workspace" so every
+    // child confined its temporary files to the tree the workspace trap
+    // removed. The AdapterContext passed to ctx.adapter below does the same.
+    const parent = ctx.env.TMPDIR ?? tmpdir();
+    // Declared OUTSIDE the withWorkspace callback (rather than inside, as an
+    // earlier draft had it) so the catch below -- which wraps the ENTIRE
+    // withWorkspace call, not just the callback -- can still see whatever was
+    // collected before a workspace throw. Both `mkdtemp` failure (nothing
+    // collected yet) and a post-success cleanup failure (everything the
+    // callback collected) reach this same array.
+    const outcomes = [];
+    let cleanupWarning = null;
+    try {
+        const outcome = await withWorkspace(parent, "superpowers-manager.uninstall.", async (workspace) => {
+            const env = { ...ctx.env, TMPDIR: workspace };
+            const failed = (message) => ({
+                status: 1,
+                outcomes,
+                message,
+                output: null,
+            });
+            const adapterContext = { root: ctx.root, env };
+            // Stage 1: inspect ownership, before removal.
+            const beforeFailure = ctx.adapter.presentation.callFailure("remove-ownership", adapterContext);
+            const before = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), beforeFailure, outcomes);
+            if (!before.ok)
+                return failed(before.message);
+            // Stage 2: remove, passing the private input through untouched.
+            const removalInput = before.result.outcome.result.removalInput;
+            const removeFailure = ctx.adapter.presentation.callFailure("remove", adapterContext, removalInput);
+            const removed = await invoke(() => ctx.adapter.remove(removalInput, adapterContext), removeFailure, outcomes);
+            if (!removed.ok)
+                return failed(removed.message);
+            // Stage 3: inspect ownership AGAIN. This overwrites the first
+            // inspection (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:29-30::spw_verify_uninstalled_resources`), so everything below reads the
+            // POST-uninstall state, not the pre-uninstall one read above.
+            const afterFailure = ctx.adapter.presentation.callFailure("post-remove", adapterContext);
+            const after = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), afterFailure, outcomes);
+            if (!after.ok)
+                return failed(after.message);
+            const ownership = after.result.outcome.result;
+            if (ownership.removalVerification.kind === "blocked") {
+                return {
+                    status: 1,
+                    outcomes,
+                    message: null,
+                    output: ownership.removalVerification.output,
+                };
+            }
+            return {
+                status: 0,
+                outcomes,
+                output: ctx.adapter.presentation.renderRemovalCompletion(ownership),
+            };
+        }, {
+            // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
+            // so the UninstallOutcome the callback already computed still comes
+            // back as `outcome` instead of being discarded. Runs synchronously,
+            // as the option requires (src/workspace.ts).
+            onCleanupFailure: (path) => {
+                cleanupWarning = workspaceRemovalFailure(path);
+            },
+        });
+        return { outcome, cleanupWarning };
+    }
+    catch (cause) {
+        // Reachable only for mkdtemp failure, with nothing collected yet: this
+        // callback never throws -- every ctx.adapter throw is already caught
+        // inside invoke(), and presenceFlag/verifyUninstalledResources/
+        // reportLegacyState are pure (src/lifecycle.ts's header comment) -- so a
+        // post-success cleanup failure is handled by onCleanupFailure above and
+        // cannot reach here. Wrapping with `outcomes` anyway keeps the class
+        // total over its declared contract rather than assuming the callback's
+        // purity at the throw site.
+        throw new GatherFailure(cause, outcomes);
+    }
+}
+export async function runUninstall(argv, ctx) {
+    // scripts/uninstall never reads "$@", so extra arguments are silently
+    // ignored -- the same asymmetry runPrepare documents at its own
+    // `void argv;`.
+    void argv;
+    let run;
+    try {
+        run = await gatherUninstall(ctx);
+    }
+    catch (cause) {
+        // gatherUninstall throws exactly one shape: GatherFailure, wrapping
+        // withWorkspace's "cannot create workspace" SafetyError
+        // (`src/workspace.ts:120::throw new SafetyError("workspace", "cannot create workspace"`),
+        // alongside whatever outcomes were collected before that throw -- none,
+        // for that cause. Replaying first, before
+        // reporting the cause, keeps the arm honest for any outcome-bearing
+        // throw the class is declared to carry (DIAG-ADAPTER-01). The
+        // post-success cleanup failure no longer arrives here: gatherUninstall's
+        // onCleanupFailure records it as `cleanupWarning` and the computed
+        // outcome survives, which is what `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:34-35::complete` did. The
+        // `instanceof` guard is defensive rather than load-bearing --
+        // gatherUninstall's own catch is the only thing that can throw here, and
+        // it always wraps -- but this catch does not assume that invariant
+        // blindly.
+        //
+        // A cause outside ctx.adapter's AdapterFailure guard
+        // (`src/adapter.ts:973-999::async function runCodexOperation(`) does NOT
+        // reach here: invoke() catches it inside gatherUninstall and converts it
+        // to a hand-written message carried as UninstallOutcome data, exactly as
+        // src/commands/probe.ts's inspect() does for the same cause.
+        //
+        // gatherUninstall performs no writes of its own, so this catch cannot
+        // also be reached by an EPIPE from uninstall's own output -- every write
+        // below runs only after this try/catch has resolved.
+        const outcomes = cause instanceof GatherFailure ? cause.outcomes : [];
+        for (const outcome of outcomes)
+            replayOutcome(outcome, ctx);
+        const inner = cause instanceof GatherFailure ? cause.inner : cause;
+        ctx.stderr.write(`error: ${oneLine(inner)}\n`);
+        return 1;
+    }
+    const { outcome, cleanupWarning } = run;
+    // Replay first, on both paths: the shell validator replayed every
+    // response's messages whether or not that response was a failure
+    // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/validate-adapter-response.py:268::replay(messages)`).
+    for (const each of outcome.outcomes)
+        replayOutcome(each, ctx);
+    let status;
+    if (outcome.status === 1) {
+        // null means replayOutcome already emitted the adapter's own error:
+        // and hint: lines for the failing outcome.
+        if (outcome.message !== null) {
+            ctx.stderr.write(`error: ${outcome.message}\n`);
+        }
+        if (outcome.output !== null) {
+            for (const line of outcome.output.stdout)
+                ctx.stdout.write(`${line}\n`);
+            for (const line of outcome.output.stderr)
+                ctx.stderr.write(`${line}\n`);
+        }
+        status = 1;
+    }
+    else {
+        for (const line of outcome.output.stdout)
+            ctx.stdout.write(`${line}\n`);
+        for (const line of outcome.output.stderr)
+            ctx.stderr.write(`${line}\n`);
+        status = 0;
+    }
+    if (cleanupWarning !== null) {
+        // Mirrors src/commands/install.ts's closing arm. A leaked workspace is
+        // reported even when the domain outcome above was a success: the
+        // uninstall and its verification already completed against the adapter
+        // before cleanup ran, so it is not being reported as unverified -- but
+        // something did still go wrong, and AGENTS.md's fail-closed rule extends
+        // to it. The operator keeps "uninstall complete", which is the one line
+        // telling them whether the removal they asked for happened.
+        ctx.stderr.write(`error: ${cleanupWarning}\n`);
+        return 1;
+    }
+    return status;
+}

package/dist/commands/unpin.js

@@ -0,0 +1,95 @@
+import { lstat, unlink } from "node:fs/promises";
+import { oneLine } from "../cli-arguments.js";
+import { selectionStatePath } from "../effective-selection.js";
+import { selectionError } from "../selection.js";
+import { readConfigRef } from "../upstream.js";
+const NOT_REGULAR = "selection state path is not a regular file; remove it manually after inspecting";
+// Runs every step that can throw or fail closed, returning the outcome as
+// data instead of writing it — see UnpinOutcome above for why.
+async function attemptUnpin(ctx) {
+    const statePath = selectionStatePath(ctx.env);
+    // The packaged fallback ignores an active SUPERPOWERS_REF: `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/unpin:12::spw_config_ref`
+    // cleared it deliberately so the reported value is the packaged one.
+    const fallback = await readConfigRef(ctx.root, {
+        ...ctx.env,
+        SUPERPOWERS_REF: "",
+    });
+    // Only a validated ENOENT means "absent". Treating every errno as absence
+    // turns EACCES or ENOTDIR into `no saved upstream selection` and exit 0 —
+    // reporting unverifiable state as success, which the fail-closed rule forbids.
+    // The shell could not draw this distinction ([ -e ] cannot), so this is a
+    // deliberate narrowing beyond parity, recorded as a port-only inventory entry.
+    const inspect = async (path) => {
+        try {
+            return await lstat(path);
+        }
+        catch (cause) {
+            if (cause.code === "ENOENT")
+                return null;
+            throw selectionError(`cannot inspect selection state: ${path}`);
+        }
+    };
+    let removed = false;
+    const info = await inspect(statePath);
+    if (info !== null) {
+        if (!info.isFile()) {
+            return { status: 1, message: `${NOT_REGULAR}: ${statePath}` };
+        }
+        try {
+            await unlink(statePath);
+        }
+        catch {
+            return {
+                status: 1,
+                message: `cannot remove selection state: ${statePath}`,
+            };
+        }
+        removed = true;
+    }
+    // Same classification on the verification read: an EACCES here must not be
+    // read as "successfully absent".
+    if ((await inspect(statePath)) !== null) {
+        return {
+            status: 1,
+            message: `selection state remains after removal attempt: ${statePath}`,
+        };
+    }
+    return { status: 0, removed, fallback };
+}
+export async function runUnpin(argv, ctx) {
+    if (argv.length !== 0) {
+        ctx.stderr.write("error: usage: superpowers-manager unpin\n");
+        return 2;
+    }
+    let outcome;
+    try {
+        outcome = await attemptUnpin(ctx);
+    }
+    catch (cause) {
+        // Every throw reachable here is a hand-written SafetyError from
+        // selectionStatePath, readConfigRef, or inspect() inside attemptUnpin —
+        // re-emitting a subordinate module's own diagnostic is the sanctioned
+        // form of interpolation (see AGENTS.md's diagnostics convention).
+        // attemptUnpin performs no writes of its own (see UnpinOutcome above),
+        // so this catch cannot also be reached by an EPIPE from a write this
+        // function made itself — the write below runs only after this try/catch
+        // has already resolved.
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+    if (outcome.status === 1) {
+        ctx.stderr.write(`error: ${outcome.message}\n`);
+        return 1;
+    }
+    const { removed, fallback } = outcome;
+    ctx.stdout.write(removed
+        ? `removed saved upstream selection; packaged fallback is ${fallback}\n`
+        : `no saved upstream selection; packaged fallback is ${fallback}\n`);
+    if (ctx.env.SUPERPOWERS_REF) {
+        ctx.stdout.write("note: active SUPERPOWERS_REF override remains effective\n");
+    }
+    if (ctx.env.SUPERPOWERS_UPSTREAM_URL) {
+        ctx.stdout.write("note: active SUPERPOWERS_UPSTREAM_URL override remains effective\n");
+    }
+    return 0;
+}