superpowers-manager 0.6.0 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # Superpowers Manager
 
-Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex and the Pi coding agent. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
+Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex, the Pi coding agent, and OpenCode. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
 
 > Unofficial community integration. Not affiliated with the `obra/superpowers` maintainers.
 
@@ -8,11 +8,11 @@ Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from
 
 Start with the latest stable release by default, or choose the upstream version that works for you. There is no background updater.
 
-| What you want | How to choose it |
-|---|---|
-| Stay on a known-good version | `pin` a release tag or full 40-character commit SHA |
+| What you want                          | How to choose it                                                              |
+| -------------------------------------- | ----------------------------------------------------------------------------- |
+| Stay on a known-good version           | `pin` a release tag or full 40-character commit SHA                           |
 | Try an upstream fix before its release | Set `SUPERPOWERS_REF` to a branch or other resolvable ref for that invocation |
-| Return to the latest stable release | Save `track-latest`, then explicitly install or update |
+| Return to the latest stable release    | Save `track-latest`, then explicitly install or update                        |
 
 For example, save a release pin and install it for your agent:
 
@@ -21,7 +21,7 @@ npx superpowers-manager pin v6.1.1
 npx superpowers-manager install --harness codex
 ```
 
-Use `--harness pi` for Pi. The pin is shared by both agents, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
+Use `--harness pi` for Pi or `--harness opencode` for OpenCode. The pin is shared by all harnesses, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
 
 To try a branch, replace `feature/foo` with an existing upstream branch:
 
@@ -42,7 +42,7 @@ See [version selection](https://github.com/j7an/superpowers-manager/blob/main/do
 
 ## Start with your agent
 
-The two harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
+The three harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
 
 ### Codex
 
@@ -71,6 +71,19 @@ after a successful install, activating update, or removal. See the
 [Pi reference](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md)
 for compatibility, experimental opt-in, and recovery behavior.
 
+### OpenCode
+
+```sh
+npx superpowers-manager install --harness opencode
+npx superpowers-manager probe --harness opencode
+npx superpowers-manager update --harness opencode
+```
+
+OpenCode installs a separately validated, Manager-owned frozen snapshot. Restart
+OpenCode after a successful install, activating update, or removal. See the
+[OpenCode reference](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md)
+for global configuration, conflicts, and recovery behavior.
+
 To remove a Manager-owned installation, choose one harness explicitly:
 
 ### Uninstall Codex
@@ -85,25 +98,26 @@ npx superpowers-manager uninstall --harness codex
 npx superpowers-manager uninstall --harness pi
 ```
 
+### Uninstall OpenCode
+
+```sh
+npx superpowers-manager uninstall --harness opencode
+```
+
 The manager never removes another Superpowers provider. See the [ownership guidance](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#provider-ownership) before switching providers.
 
 ## Shared selection and lifecycle
 
-The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex or Pi; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
+The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex, Pi, or OpenCode; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
 
-| Command | Purpose |
-|---|---|
-| `prepare` | Build and validate the selected harness's prepared output |
-| `install` | Apply the shared selection to the selected harness |
-| `probe` | Inspect the selected harness without mutation |
-| `update` | Explicitly refresh the selected harness when needed and verify it |
-| `uninstall` | Remove only Manager-owned state from the selected harness |
+See [targeted lifecycle commands](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#targeted-lifecycle) for preparation, inspection, installation, updates, and removal.
 
-Use `--harness codex` or `--harness pi` with each targeted lifecycle command.
+Use `--harness codex`, `--harness pi`, or `--harness opencode` with each targeted lifecycle command.
 
 ```text
 shared selection -> prepare / inspect / activate Codex
                  -> prepare / inspect / activate Pi
+                 -> prepare / inspect / activate OpenCode
 ```
 
 The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md) and [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md).
@@ -113,16 +127,18 @@ The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs
 The installed package requires Node >=24. Native source, tests, and packaging tooling require Node >=24.12.0. Every other requirement is command-specific and is checked before dispatch. This table is derived from production by `tests/bin/readme-requirements.test.ts`.
 
 <!-- requirements:begin -->
-| Command | git | Codex CLI (default) | Pi CLI (`--harness pi`) |
-|---|---|---|---|
-| `pin` | yes | no | no |
-| `track-latest` | no | no | no |
-| `unpin` | no | no | no |
-| `prepare` | yes | no | no |
-| `probe` | yes | yes | no |
-| `install` | yes | yes | yes |
-| `update` | yes | yes | yes |
-| `uninstall` | no | yes | yes |
+
+| Command        | git | Codex CLI (default) | Pi CLI (`--harness pi`) | OpenCode CLI (`--harness opencode`) |
+| -------------- | --- | ------------------- | ----------------------- | ----------------------------------- |
+| `pin`          | yes | no                  | no                      | no                                  |
+| `track-latest` | no  | no                  | no                      | no                                  |
+| `unpin`        | no  | no                  | no                      | no                                  |
+| `prepare`      | yes | no                  | no                      | no                                  |
+| `probe`        | yes | yes                 | no                      | no                                  |
+| `install`      | yes | yes                 | yes                     | yes                                 |
+| `update`       | yes | yes                 | yes                     | yes                                 |
+| `uninstall`    | no  | yes                 | yes                     | no                                  |
+
 <!-- requirements:end -->
 
 Generated Codex manifests preserve upstream JSON number tokens while rejecting non-finite decimal or exponent values.

package/dist/adapter-result.js

@@ -133,6 +133,9 @@ export function failureResult(operation, code, message, hints, messages) {
         },
     };
 }
+export function inspectionFailure(operation, subject) {
+    return failureResult(operation, "invalid-state", `cannot inspect ${subject}`, [], []);
+}
 export function hasTerminalControl(value) {
     for (const character of value) {
         const code = character.codePointAt(0);
@@ -148,10 +151,8 @@ export function hasTerminalControl(value) {
 // every command replays through -- wrote these three strings to the terminal
 // unfiltered.
 //
-// NOT requireProtocolString: that one message
-// ("protocol strings must not contain terminal control characters") names no
-// member, and D8b requires the thrown message to name the failing one. So this
-// scans with the predicate underneath it instead.
+// This scans with the predicate underneath it because D8b requires the thrown
+// message to name the failing member.
 //
 // Order is code, then message, then hints by ascending index, so the thrown
 // message is a function of the outcome rather than of iteration order.
@@ -197,8 +198,3 @@ export function writeAdapterFailure(ctx, outcome) {
         ctx.stderr.write(`hint: ${hint}\n`);
     }
 }
-export function requireProtocolString(value) {
-    if (hasTerminalControl(value)) {
-        throw new Error("protocol strings must not contain terminal control characters");
-    }
-}

package/dist/atomic.js

@@ -1,12 +1,12 @@
 import { randomBytes } from "node:crypto";
-import { constants, lstat, open, readFile, rename, rm, unlink, } from "node:fs/promises";
+import { constants, lstat, open, rename, rm, unlink } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
+import { isErrno } from "./safe-path.js";
 import { SafetyError } from "./safety-error.js";
 export async function atomicWriteFile(path, bytes, options) {
     const renamePath = options.hooks?.rename ?? rename;
     let handle;
     let temporary;
-    let phase = "pre-replacement";
     try {
         for (let attempt = 0; attempt < 100; attempt += 1) {
             const suffix = randomBytes(8).toString("hex");
@@ -36,17 +36,10 @@ export async function atomicWriteFile(path, bytes, options) {
         await options.validate(temporary);
         await renamePath(temporary, path);
         temporary = undefined;
-        phase = "post-replacement";
-        await options.hooks?.afterReplace?.(path);
         await fsyncDirectoryBestEffort(dirname(path));
     }
     catch (cause) {
-        let finalBytes;
-        if (phase === "post-replacement") {
-            finalBytes = await readFile(path).catch(() => undefined);
-        }
-        const details = finalBytes === undefined ? { phase } : { phase, finalBytes };
-        throw new SafetyError("atomic", `atomic file write failed during ${phase}`, { cause, details });
+        throw new SafetyError("atomic", "atomic file write failed during pre-replacement", { cause, details: { phase: "pre-replacement" } });
     }
     finally {
         if (handle !== undefined) {
@@ -76,11 +69,8 @@ async function exists(path) {
         return true;
     }
     catch (cause) {
-        if (cause instanceof Error &&
-            "code" in cause &&
-            cause.code === "ENOENT") {
+        if (isErrno(cause, "ENOENT"))
             return false;
-        }
         throw cause;
     }
 }

package/dist/cli-arguments.js

@@ -20,7 +20,7 @@ export function extractHarnessOptions(command, argv) {
                 : token.slice("--harness=".length);
             if (!value || value.startsWith("--"))
                 throw new UsageError("option --harness requires a value");
-            if (value !== "codex" && value !== "pi")
+            if (value !== "codex" && value !== "pi" && value !== "opencode")
                 throw new UsageError(`unknown harness: ${value}`);
             harness = value;
         }
@@ -37,32 +37,6 @@ export function extractHarnessOptions(command, argv) {
     }
     return { options: { harness, allowExperimental }, args };
 }
-export function parseFlags(argv, names) {
-    const allowed = new Set(names);
-    const result = {};
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        if (!token.startsWith("--"))
-            throw new UsageError(`unexpected argument: ${token}`);
-        const separator = token.indexOf("=");
-        const name = separator === -1 ? token.slice(2) : token.slice(2, separator);
-        if (!allowed.has(name))
-            throw new UsageError(`unknown option: --${name}`);
-        const value = separator === -1 ? argv[index + 1] : token.slice(separator + 1);
-        if (value === undefined || (separator === -1 && value.startsWith("--"))) {
-            throw new UsageError(`option --${name} requires a value`);
-        }
-        result[name] = value;
-        if (separator === -1)
-            index += 1;
-    }
-    for (const name of names) {
-        if (!Object.hasOwn(result, name)) {
-            throw new UsageError(`required option is missing: --${name}`);
-        }
-    }
-    return result;
-}
 export function oneLine(value) {
     const message = value instanceof Error ? value.message : String(value);
     return message.replace(/[\r\n]+/g, " ");

package/dist/cli.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
 import { codexHarness } from "./harnesses/codex/harness.js";
 import { piHarness } from "./harnesses/pi/harness.js";
+import { openCodeHarness } from "./harnesses/opencode/harness.js";
 import { createResourceCoordinator } from "./resource-lock.js";
 import { runInstall } from "./commands/install.js";
 import { runPin } from "./commands/pin.js";
@@ -47,7 +48,7 @@ const IN_PROCESS_HANDLERS = {
 // per adapter call
 // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:37-44::--response "$response_file" --result "$result_file" \`);
 // the in-process path no longer uses that adapter-response validator.
-// No command has a Python requirement in commandRequirements(env).
+// No command has a Python requirement in requirementsFor().
 // No command requires a POSIX shell any more.
 const SHARED_COMMAND_REQUIREMENTS = {
     pin: ["git"],
@@ -178,38 +179,22 @@ function sharedRequirement(name) {
         missingMessage: `required command not found: ${name} — install ${name} and re-run`,
     };
 }
-function commandRequirementsFor(env, adapter) {
-    const forCommand = (command) => {
-        const shared = SHARED_COMMAND_REQUIREMENTS[command].map(sharedRequirement);
-        return [...shared, ...adapter.requirements(command, env)];
-    };
-    return {
-        pin: forCommand("pin"),
-        "track-latest": forCommand("track-latest"),
-        unpin: forCommand("unpin"),
-        prepare: forCommand("prepare"),
-        probe: forCommand("probe"),
-        install: forCommand("install"),
-        update: forCommand("update"),
-        uninstall: forCommand("uninstall"),
-    };
-}
-function commandRequirements(env) {
-    return Object.fromEntries(SUBCOMMANDS.map((command) => [
-        command,
-        commandRequirementsFor(env, codexHarness)[command].map((requirement) => requirement.name),
-    ]));
+function requirementsFor(command, env, adapter) {
+    return [
+        ...SHARED_COMMAND_REQUIREMENTS[command].map(sharedRequirement),
+        ...adapter.requirements(command, env),
+    ];
 }
 // Preflight; never touches Codex state. It is the union of two exported
 // accessors: configurationErrors (validator configuration) and
-// commandRequirements (tool availability), both specific to the selected
+// requirementsFor (tool availability), both specific to the selected
 // command. No command requires a POSIX shell: slice 4b flipped the last
 // spawned command in-process, so there is no shell to discover.
-function preflightFor(cmd, env, platform, adapter) {
+function preflight(cmd, env, platform, adapter) {
     const errors = [...configurationErrors(cmd, env)];
     if (errors.length > 0)
         return { ok: false, errors };
-    for (const requirement of commandRequirementsFor(env, adapter)[cmd]) {
+    for (const requirement of requirementsFor(cmd, env, adapter)) {
         const found = requirement.lookup === "explicit-path-or-path" &&
             requirement.executable.includes(path.sep)
             ? fs.existsSync(requirement.executable)
@@ -221,9 +206,6 @@ function preflightFor(cmd, env, platform, adapter) {
         return { ok: false, errors };
     return { ok: true };
 }
-function preflight(cmd, env, platform) {
-    return preflightFor(cmd, env, platform, codexHarness);
-}
 function usage() {
     return [
         "usage: superpowers-manager [command] [args...]",
@@ -241,19 +223,20 @@ function usage() {
         "  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.",
+        "  probe --harness opencode [--porcelain]",
+        "  prepare --harness opencode",
+        "  install --harness opencode [--allow-experimental]",
+        "  update --harness opencode [--allow-experimental]",
+        "  uninstall --harness opencode",
+        "  --harness=codex, --harness=pi, and --harness=opencode 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,",
         "SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE,",
-        "SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE",
+        "SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE,",
+        "SUPERPOWERS_OPENCODE",
         "",
         "SUPERPOWERS_VALIDATOR is removed; unset it and use",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE with an executable validator.",
@@ -283,9 +266,11 @@ async function main() {
         console.error(usage());
         process.exit(2);
     }
-    const status = parsed.options.harness === "pi"
-        ? await dispatch(piHarness, parsed)
-        : await dispatch(codexHarness, parsed);
+    const status = parsed.options.harness === "opencode"
+        ? await dispatch(openCodeHarness, parsed)
+        : parsed.options.harness === "pi"
+            ? await dispatch(piHarness, parsed)
+            : await dispatch(codexHarness, parsed);
     process.exit(status);
 }
 async function dispatch(adapter, parsed) {
@@ -294,7 +279,7 @@ async function dispatch(adapter, parsed) {
         console.error("error: cannot resolve the superpowers-manager package root");
         return 1;
     }
-    const pf = preflightFor(parsed.cmd, process.env, process.platform, adapter);
+    const pf = preflight(parsed.cmd, process.env, process.platform, adapter);
     if (!pf.ok) {
         for (const e of pf.errors)
             console.error(`error: ${e}`);
@@ -336,7 +321,7 @@ async function dispatch(adapter, parsed) {
     }
     return status;
 }
-export { resolvePackageRoot, isMain, parseArgs, commandRequirements, commandRequirementsFor, preflight, usage, main, };
+export { resolvePackageRoot, isMain, parseArgs, requirementsFor, preflight, usage, main, };
 if (isMain(import.meta.filename, process.argv[1])) {
     main().catch((cause) => {
         console.error(`error: ${oneLine(cause)}`);

package/dist/commands/adapter-call.js

@@ -0,0 +1,28 @@
+export async function callAdapter(call, failure) {
+    let result;
+    try {
+        result = await call();
+    }
+    catch {
+        return { ok: false, result: null, message: failure.unexpected };
+    }
+    const outcome = result.outcome;
+    if (result.status !== 0 || !outcome.ok)
+        return {
+            ok: false,
+            result,
+            message: outcome.ok ? failure.invalidStatus : null,
+        };
+    return { ok: true, result: { status: result.status, outcome } };
+}
+// Preserve outcomes collected before gathering throws so command catches can
+// replay them before reporting the underlying failure.
+export class GatherFailure extends Error {
+    inner;
+    outcomes;
+    constructor(message, inner, outcomes) {
+        super(message);
+        this.inner = inner;
+        this.outcomes = outcomes;
+    }
+}

package/dist/commands/install.js

@@ -1,92 +1,35 @@
-// Ports scripts/install. The shell sourced common.sh, provenance.sh,
-// status.sh, lifecycle.sh and adapter.sh; the predicates now live in
-// 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, validInstalled, validOutput, } from "./probe.js";
+import { GatherFailure, callAdapter, } from "./adapter-call.js";
+import { gatherProbe, replayOutcome } from "./probe.js";
 import { runPrepare } from "./prepare.js";
 import { runWithMutation } from "./mutation.js";
 import { activationBlock } from "../harness-compatibility.js";
-function writeOutput(output, ctx) {
+export 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, 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 };
+async function invoke(call, failure, outcomes, acceptValue) {
+    let result = await callAdapter(call, failure);
+    if (result.ok && acceptValue !== undefined) {
+        try {
+            if (!acceptValue(result.result.outcome.result))
+                result = { ok: false, result: null, message: failure.invalidStatus };
+        }
+        catch {
+            result = { ok: false, result: null, message: failure.invalidStatus };
         }
     }
-    catch {
-        return { ok: false, message: failure.unexpected, result: null };
-    }
-    outcomes.push(result.outcome);
-    const outcome = result.outcome;
-    if (result.status !== 0 || !outcome.ok) {
-        return {
-            ok: false,
-            message: outcome.ok ? failure.invalidStatus : null,
-            result,
-        };
-    }
-    return {
-        ok: true,
-        result: { status: result.status, outcome },
-    };
-}
-function validReceipt(value) {
-    return (value !== null &&
-        typeof value === "object" &&
-        validOutput(value.missingVerificationOutput) &&
-        validOutput(value.mismatchVerificationOutput));
-}
-// withWorkspace can throw AFTER its callback has already returned a fully
-// computed StageOutcome: a post-success cleanup failure discards that return
-// value entirely and rejects instead, UNLESS an `onCleanupFailure` reporter is
-// supplied -- which gatherInstallStages below does, precisely so this class
-// stays reserved for mkdtemp failure (nothing collected yet) and the
-// callback's own throw (never reachable here; see gatherInstallStages).
-// Carries the outcomes collected so far so runInstall's catch can still
-// replay them instead of discarding them with a bare re-throw. Same shape as
-// src/commands/uninstall.ts's GatherFailure, duplicated for the same reason
-// invoke() is: no shared dependency between the two modules.
-class GatherFailure extends Error {
-    inner;
-    outcomes;
-    constructor(inner, outcomes) {
-        super("install gather failed");
-        this.inner = inner;
-        this.outcomes = outcomes;
-    }
+    if (result.result !== null)
+        outcomes.push(result.result.outcome);
+    return result;
 }
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:44-58::TMPDIR=`, wrapped in the temporary workspace scripts/install
-// 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.
+// Collect outcomes without writing so output failures cannot be classified as
+// inspection failures. Replay collected outcomes after gathering completes.
 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();
     const outcomes = [];
     let cleanupWarning = null;
@@ -133,7 +76,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
             if (activationFailure !== null)
                 return failed(activationFailure);
             const installFailure = ctx.adapter.presentation.callFailure("install", adapterContext);
-            const install = await invoke(() => ctx.adapter.install(artifact, adapterContext), installFailure, outcomes, validReceipt);
+            const install = await invoke(() => ctx.adapter.install(artifact, adapterContext), installFailure, outcomes);
             if (!install.ok)
                 return failed(install.message);
             let transaction;
@@ -163,7 +106,7 @@ 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/harnesses/codex/presentation.ts:305::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
+            // (`src/harnesses/codex/presentation.ts:280::if (inspection.status !== 0 || !inspection.outcome.ok) {`)
             // exists for this result-bearing path. Returning
             // failed() instead reported the adapter's own generic diagnostic and
             // dropped the post-install verification claim -- a mutation had
@@ -172,7 +115,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
             // adapter call failed". A ctx.adapter THROW has no result to render.
             // A pending transaction still rolls back before reporting that failure.
             const inspectionFailure = ctx.adapter.presentation.callFailure("post-install", adapterContext);
-            const inspected = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes, validInstalled);
+            const inspected = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes);
             const inspection = inspected.result;
             const verified = inspection !== null &&
                 inspection.status === 0 &&
@@ -185,7 +128,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
                     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 restored = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes);
                     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";
@@ -216,7 +159,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
                     };
                 }
                 if (!settlement.ok) {
-                    const actual = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes, validInstalled);
+                    const actual = await invoke(() => ctx.adapter.inspectInstalled(selection, adapterContext), inspectionFailure, outcomes);
                     return {
                         kind: "verified",
                         outcomes,
@@ -259,7 +202,7 @@ async function gatherInstallStages(ctx, selection, artifact) {
         // Reachable only for mkdtemp failure (nothing collected yet) -- the
         // callback above never throws, so a post-success cleanup failure is
         // already handled by onCleanupFailure and cannot reach here.
-        throw new GatherFailure(cause, outcomes);
+        throw new GatherFailure("install gather failed", cause, outcomes);
     }
 }
 export async function runInstall(argv, ctx) {
@@ -276,31 +219,8 @@ async function performInstall(argv, ctx) {
         probe = await gatherProbe(ctx);
     }
     catch (cause) {
-        // gatherProbe performs no writes of its own (src/commands/probe.ts), so
-        // this catch cannot also be reached by an EPIPE from install's own
-        // output: the NOTE line above already left the try, and everything below
-        // runs only after this try/catch has resolved.
-        //
-        // This is a SECOND consumer of gatherProbe's throw channel --
-        // `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:
-        //   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. :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. :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
-        //      own message.
-        // Not repeated in full here; read it there.
+        // Gathering does not write, so this catch cannot misclassify an output
+        // failure. oneLine() bounds any inherited diagnostic to one line.
         ctx.stderr.write(`error: ${oneLine(cause)}\n`);
         return 1;
     }

package/dist/commands/pin.js

@@ -17,7 +17,7 @@ async function attemptPin(requested, ctx) {
     // 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
+    // `src/selection-store.ts:99::return validateRecord`). Calling loadSavedSelection here preserves
     // `git show 349fe2ed405b371ec2de1347bb3fc50c6bc15dc4:scripts/pin:26-27::read`'s read-then-resolve-then-write shape, so this command
     // stays fail-closed on its own terms rather than solely by depending on the
     // store's internals.