superpowers-manager 0.3.0 → 0.5.0

package/dist/commands/uninstall.js

@@ -3,61 +3,29 @@
 // and the adapter arrives through ctx.adapter.
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
-import { reportLegacyState, verifyUninstalledResources } from "../lifecycle.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
+import { runWithMutation } from "./mutation.js";
 import { replayOutcome } from "./probe.js";
-function presenceFlag(result, key) {
-    const outcome = result.outcome;
-    if (result.status !== 0 || !outcome.ok) {
-        return { kind: "call-failed" };
-    }
-    const value = outcome.result;
-    // Mirrors src/lifecycle.ts's verifyUninstalledResources: a missing or
-    // non-object `resources` falls THROUGH to the Boolean check rather than
-    // getting its own message, for parity with
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:70::expected`'s
-    // single "expected Boolean..." text on {}.
-    const resources = typeof value === "object" && value !== null && !Array.isArray(value)
-        ? value.resources
-        : undefined;
-    const bag = typeof resources === "object" &&
-        resources !== null &&
-        !Array.isArray(resources)
-        ? resources
-        : {};
-    const flag = bag[key];
-    if (typeof flag !== "boolean") {
-        return { kind: "malformed", key };
-    }
-    return { kind: "ok", value: flag };
-}
-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(" ")}`,
-        };
+        return { ok: false, message: failure.unexpected };
     }
-    // Clause 1: replay every outcome, on both the success and the failure
-    // path, before any decision -- collected here and replayed by the caller
-    // once gatherUninstall's try/catch has resolved, for the same EPIPE reason
-    // gatherProbe carries its outcomes out rather than writing in place
-    // (`src/commands/probe.ts:289::The outcomes are CARRIED OUT rather than replayed in place`).
     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,
         };
     }
-    return { ok: true, result };
+    return {
+        ok: true,
+        result: { status: result.status, outcome },
+    };
 }
 // withWorkspace throws for mkdtemp failure before the callback ever runs
 // ("cannot create workspace",
@@ -85,7 +53,7 @@ class GatherFailure extends Error {
 }
 // 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:280-281::readonly status: 0;`) and for the same
+// (`src/commands/probe.ts::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) {
@@ -108,106 +76,41 @@ async function gatherUninstall(ctx) {
                 status: 1,
                 outcomes,
                 message,
+                output: null,
             });
+            const adapterContext = { root: ctx.root, env };
             // Stage 1: inspect ownership, before removal.
-            const first = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
-            if (!first.ok)
-                return failed(first.message);
-            const pluginFlag = presenceFlag(first.result, "plugin");
-            if (pluginFlag.kind === "malformed") {
-                return failed(`expected a Boolean adapter result at resources.${pluginFlag.key}`);
-            }
-            if (pluginFlag.kind === "call-failed") {
-                // Unreachable via this call path: `first.ok` above already proved
-                // status === 0 && outcome.ok, the only inputs presenceFlag reads
-                // to decide this arm. Handled anyway so presenceFlag stays total
-                // and this switch stays exhaustive rather than assuming its caller
-                // always gates first.
-                return failed(null);
-            }
-            const marketplaceFlag = presenceFlag(first.result, "marketplace");
-            if (marketplaceFlag.kind === "malformed") {
-                return failed(`expected a Boolean adapter result at resources.${marketplaceFlag.key}`);
-            }
-            if (marketplaceFlag.kind === "call-failed") {
-                return failed(null);
-            }
-            // Stage 2: uninstall, with the two presence Booleans read above.
-            const uninstallStage = await invoke(ctx, env, [
-                "uninstall",
-                "--plugin-present",
-                String(pluginFlag.value),
-                "--marketplace-present",
-                String(marketplaceFlag.value),
-            ], outcomes);
-            if (!uninstallStage.ok)
-                return failed(uninstallStage.message);
+            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 second = await invoke(ctx, env, ["inspect", "--view", "ownership"], outcomes);
-            if (!second.ok)
-                return failed(second.message);
-            const verify = verifyUninstalledResources(second.result);
-            if (!verify.ok)
-                return failed(verify.message);
-            // identity_state comes from this SAME second inspection, matching
-            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:31::spw_adapter_result_get`'s spw_adapter_result_get read of the
-            // overwritten inspect_result. `second.ok` already proved this call
-            // succeeded, so outcome.ok is true here; the explicit check below is
-            // for TypeScript's narrowing (a local variable, not a re-derivation
-            // of that fact) rather than a live branch.
-            const secondOutcome = second.result.outcome;
-            if (!secondOutcome.ok)
-                return failed(null);
-            // Mirrors the inspect null/non-string branches
-            // (`src/commands/probe.ts:256-263::if (value === null || value === undefined) {`)
-            // and the fingerprint read
-            // (`src/lifecycle.ts:181-194::const raw = inspected.value.fingerprint;`):
-            // a JSON null or a missing key defaults to "" (the Python reader's own
-            // convention for a JSON null, scripts/core/provenance.sh's
-            // spw_json_get), but a present, non-null, NON-STRING value is a
-            // distinct, fail-closed "malformed" case with its own text -- never
-            // silently stringified.
-            // (A previous draft of this comment claimed parity with the shell's
-            // stringify-and-compare behaviour at
-            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:62::print(value`;
-            // that was wrong on inspection, and it cited these same two call sites
-            // as support even though both of them fail closed on a non-string value
-            // rather than stringifying it. AGENTS.md's
-            // fail-closed rule wins over shell parity here.)
-            const parsed = secondOutcome.result;
-            const identityRaw = parsed?.identity_state;
-            let identityState;
-            if (identityRaw === null || identityRaw === undefined) {
-                identityState = "";
-            }
-            else if (typeof identityRaw === "string") {
-                identityState = identityRaw;
-            }
-            else {
-                return failed("adapter returned a non-string identity_state for inspect --view ownership");
-            }
-            const verdict = reportLegacyState(identityState);
-            if (verdict.kind === "unknown")
-                return failed(verdict.message);
-            const lines = [];
-            // verdict.kind is "ok" or "report" here (reportLegacyState never
-            // returns "blocked" -- that arm belongs to requireNoLegacyState --
-            // but LegacyVerdict is one shared union, so this narrows rather than
-            // assumes).
-            if (verdict.kind !== "ok") {
-                lines.push(...verdict.lines);
+            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,
+                };
             }
-            // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/uninstall:34-35::complete`. The first line ports verbatim; the second
-            // changes scripts/prepare to npx superpowers-manager prepare (spec
-            // §3.6) -- a deliberate, observable divergence, recorded as a
-            // port-only entry in tests/migration-inventory/uninstall-commands.md.
-            lines.push("uninstall complete");
-            lines.push("note: local generated artifacts under plugins/superpowers/ and " +
-                ".cache/upstream/ were left in place; remove them manually or " +
-                "regenerate with npx superpowers-manager prepare.");
-            return { status: 0, outcomes, lines };
+            return {
+                status: 0,
+                outcomes,
+                output: ctx.adapter.presentation.renderRemovalCompletion(ownership, removalInput),
+            };
         }, {
             // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
             // so the UninstallOutcome the callback already computed still comes
@@ -232,6 +135,9 @@ async function gatherUninstall(ctx) {
     }
 }
 export async function runUninstall(argv, ctx) {
+    return await runWithMutation("uninstall", ctx, async (scoped) => performUninstall(argv, scoped));
+}
+async function performUninstall(argv, ctx) {
     // scripts/uninstall never reads "$@", so extra arguments are silently
     // ignored -- the same asymmetry runPrepare documents at its own
     // `void argv;`.
@@ -257,7 +163,7 @@ export async function runUninstall(argv, ctx) {
         // blindly.
         //
         // A cause outside ctx.adapter's AdapterFailure guard
-        // (`src/adapter.ts:1001::if (cause instanceof AdapterFailure) {`) does NOT
+        // (`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.
@@ -285,12 +191,19 @@ export async function runUninstall(argv, ctx) {
         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.lines) {
+        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) {

package/dist/commands/update.js

@@ -6,38 +6,20 @@
 // is also why update opens no temporary workspace of its own -- there is no
 // mutation here for one to protect.
 import { oneLine } from "../cli-arguments.js";
-import { requireManagedUpdateControl, requireNoLegacyState, } from "../lifecycle.js";
-import { formatPorcelain, gatherProbe, replayOutcome, } from "./probe.js";
+import { gatherProbe, replayOutcome } from "./probe.js";
 import { runInstall } from "./install.js";
 import { runPrepare } from "./prepare.js";
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:29-32::echo "$probe_output`'s `case ... *)` wildcard. Same unreachability shape as
-// src/commands/install.ts's renderUnknownProbeStatus: statusForCommits
-// (src/status.ts) can only ever return "needs prepare", "needs
-// install" or "current", so this branch is NOT reachable through runUpdate's
-// own call to gatherProbe today. ProbeFacts.status is typed `string`, not
-// that three-literal union, so 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 -- 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
-// runUpdate's own final `else` branch actually reaches and calls this
-// function, or that runUpdate 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/update:30-31::echo "$probe_output` -- `echo "$probe_output"` (stdout), then the error
-    // to stderr via an explicit `>&2`. This is a DIFFERENT mechanism from
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:30-31::printf`'s `spw_die`, even though both end up writing the
-    // porcelain to stdout and an `error: `-prefixed line to stderr: install's
-    // error text flows through spw_die's own `error: $*` formatting, while
-    // update's is spelled out inline in the shell literal already. The two
-    // command modules therefore each need their own case pinning this arm --
-    // one must not be inferred from the other.
-    ctx.stdout.write(formatPorcelain(facts));
-    ctx.stderr.write(`error: unknown probe status: ${facts.status}\n`);
+import { runWithMutation } from "./mutation.js";
+function writeOutput(output, ctx) {
+    for (const line of output.stdout)
+        ctx.stdout.write(`${line}\n`);
+    for (const line of output.stderr)
+        ctx.stderr.write(`${line}\n`);
 }
 export async function runUpdate(argv, ctx) {
+    return await runWithMutation("update", ctx, async (scoped) => performUpdate(argv, scoped));
+}
+async function performUpdate(argv, ctx) {
     // scripts/update never reads "$@", so extra arguments are silently
     // ignored -- the same asymmetry runPrepare and runInstall document.
     void argv;
@@ -52,7 +34,7 @@ export async function runUpdate(argv, ctx) {
         // install's NOTE line.
         //
         // This is a THIRD consumer of gatherProbe's throw channel --
-        // `src/commands/probe.ts:381-433::THREE exceptions, all inherited and none a regression:`'s
+        // `src/commands/probe.ts:469-527::THREE exceptions, all inherited and none a regression:`'s
         // runProbe catch is the first and src/commands/install.ts's runInstall catch
         // is the second. Because all three wrap the identical function, runProbe's
         // long comment there enumerates exactly what can reach this stream too; not
@@ -70,69 +52,32 @@ export async function runUpdate(argv, ctx) {
         return 1;
     }
     const facts = probe.facts;
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:9-10::identity_state=`. Guards the PROBE-derived value only, matching
-    // src/commands/install.ts's identical guard at `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:19-20::identity_state=$(spw_probe_field`: a
-    // probe that reports no identity state at all is a different failure from
-    // one that reports an unrecognised one, and requireNoLegacyState("") would
-    // otherwise reach its "unknown" arm and print a symptom rather than the
-    // actual cause.
-    if (facts.identityState.length === 0) {
-        ctx.stderr.write("error: probe did not report adapter identity state\n");
-        return 1;
-    }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:11::spw_require_no_legacy_state`.
-    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`);
+    if (facts.ownership.installEligibility.kind === "blocked") {
+        writeOutput(facts.ownership.installEligibility.output, ctx);
         return 1;
     }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:13-14::update_control=`. install checks only identity_state
-    // (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:20::report`); update checks update_control too -- the first of
-    // §4.4's two corrections. Both emptiness checks run before the switch, not
-    // just one.
-    if (facts.updateControl.length === 0) {
-        ctx.stderr.write("error: probe did not report adapter update-control capability\n");
+    if (facts.control.probeEligibility.kind === "blocked") {
+        writeOutput(facts.control.probeEligibility.output, ctx);
         return 1;
     }
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:16-34::case`, the four-way switch.
-    if (facts.status === "current") {
-        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:18::spw_require_managed_update_control` -- gated BEFORE printing anything. §4.4's second
-        // correction: an update that printed "manager is current" under an
-        // unsupported adapter would be asserting managed control it had not
-        // verified.
-        const managed = requireManagedUpdateControl(facts.updateControl);
-        if (!managed.ok) {
-            ctx.stderr.write(`error: ${managed.message}\n`);
-            return 1;
+    switch (facts.status) {
+        case "current": {
+            if (facts.control.mutationEligibility.kind === "blocked") {
+                writeOutput(facts.control.mutationEligibility.output, ctx);
+                return 1;
+            }
+            const rendered = ctx.adapter.presentation.renderProbe(facts);
+            ctx.stdout.write(rendered.porcelain);
+            ctx.stdout.write(`${ctx.adapter.presentation.currentNotice}\n`);
+            return 0;
         }
-        // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/update:19-20::printf`. Unlike install, which never lets the porcelain
-        // reach the terminal on a successful run (`git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/install:18::porcelain`'s
-        // probe_output=$(...) capture), update prints it here.
-        ctx.stdout.write(formatPorcelain(facts));
-        ctx.stdout.write("manager is current\n");
-        return 0;
-    }
-    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;
-        return await runInstall([], ctx);
-    }
-    if (facts.status === "needs install") {
-        return await runInstall([], ctx);
+        case "needs prepare": {
+            const prepareStatus = await runPrepare([], ctx);
+            if (prepareStatus !== 0)
+                return prepareStatus;
+            return await runInstall([], ctx);
+        }
+        case "needs install":
+            return await runInstall([], ctx);
     }
-    renderUnknownProbeStatus(facts, ctx);
-    return 1;
 }

package/dist/generated-plugin.js

@@ -14,7 +14,7 @@ export const DEFAULT_FS_DEPS = {
 // The Python's own SEMVER_RE (:15-22). Deliberately not SEMVER_BASE_SOURCE
 // from src/domain/refs.ts, which omits the `+build` component; widening the
 // shared constant would change TAG_RE and is out of scope.
-const SEMVER_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const SEMVER_RE = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const MANIFEST_JSON_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",
@@ -444,7 +444,7 @@ const REQUIRED_FILES = [
     "CODE_OF_CONDUCT.md",
 ];
 /** Python `sorted()` orders by code point; JavaScript's default sort does not. */
-function compareByCodePoint(left, right) {
+export function compareByCodePoint(left, right) {
     // `Array.from` splits by code point, exactly as spreading would; oxlint's
     // `no-misused-spread` rejects the spread form, and grapheme segmentation is
     // the wrong unit here — Python compares code points.
@@ -459,7 +459,7 @@ function compareByCodePoint(left, right) {
     }
     return leftPoints.length - rightPoints.length;
 }
-async function validateSkillFrontmatter(skillMd, skillName, errors, deps) {
+export async function validateSkillFrontmatter(skillMd, skillName, errors, deps) {
     let contents;
     try {
         contents = STRICT_DECODER.decode(await deps.readFile(skillMd));

package/dist/harness-compatibility.js

@@ -0,0 +1,13 @@
+export function activationBlock(value, allowExperimental) {
+    switch (value.kind) {
+        case "supported":
+            return null;
+        case "experimental":
+            return allowExperimental
+                ? null
+                : "experimental integration requires --allow-experimental";
+        case "unknown":
+        case "unsupported":
+            return value.reason;
+    }
+}

package/dist/harness.js

@@ -0,0 +1 @@
+export {};

package/dist/lifecycle.js

@@ -52,8 +52,7 @@ export function reportLegacyState(identityState) {
     }
     return unknownState(identityState);
 }
-import { hasTerminalControl } from "./adapter-result.js";
-import { commitMatches } from "./status.js";
+export { verifyInstalledFingerprint, } from "./codex-presentation.js";
 // Ported from
 // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:62-70::spw_require_managed_update_control`.
 // Both refusals reached spw_die in the shell, so both carry the `error: ` prefix
@@ -85,90 +84,6 @@ function readResult(adapterResult) {
     return { kind: "object", value: value };
 }
 // Ported from
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:87-124::spw_verify_installed_fingerprint`.
-// The shell performed the inspection itself at :91; a pure function cannot, so
-// the caller performs it and a failure arrives here as an AdapterResult with a
-// non-zero status.
-export function verifyInstalledFingerprint(desiredCommit, installResult, inspectResult) {
-    const inspected = readResult(inspectResult);
-    if (inspected.kind === "call-failed") {
-        return {
-            ok: false,
-            stdout: [],
-            stderr: [
-                "error: installed manager fingerprint inspection failed after install.",
-            ],
-        };
-    }
-    if (inspected.kind === "unusable") {
-        // A well-formed outcome whose `result` is not an object is the port's
-        // analogue of the shell's own split: the inspect call SUCCEEDED and only
-        // the content is unusable. This is the branch
-        // tests/unit/lifecycle.test.js's "an unparseable fingerprint result
-        // names parsing, not inspection" exercises. Spec §6.2.3 items 3 and 4.
-        return {
-            ok: false,
-            stdout: [],
-            stderr: [
-                "error: cannot parse installed manager fingerprint inspection result after install.",
-            ],
-        };
-    }
-    const raw = inspected.value.fingerprint;
-    // The Python reader printed the empty string for a JSON null, and
-    // `fingerprint` is null whenever no plugin version is active
-    // (`src/adapter.ts:820::fingerprint: null`). Anything non-string and non-null
-    // is unparseable.
-    //
-    // PORT-ONLY, and intentional. The shell cannot construct this trigger:
-    // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/provenance.sh:62::print(value`
-    // stringifies any non-null scalar, so a non-string fingerprint never reaches
-    // spw_verify_installed_fingerprint.
-    // The port CAN encounter the shape and must fail closed rather than
-    // coerce. Pinned by a test below and recorded in
-    // tests/migration-inventory/codex-state-units.md. Spec §6.2.3 item 3.
-    if (raw !== null && raw !== undefined && typeof raw !== "string") {
-        return {
-            ok: false,
-            stdout: [],
-            stderr: [
-                "error: cannot parse installed manager fingerprint inspection result after install.",
-            ],
-        };
-    }
-    const installedCommit = typeof raw === "string" ? raw : "";
-    // :99-100 printed both lines BEFORE deciding, on every path that got this
-    // far. Moving them into the success branch would silently drop them from the
-    // failure output an operator reads to diagnose the mismatch.
-    const stdout = [
-        `desired_commit=${desiredCommit}`,
-        `installed_commit=${installedCommit}`,
-    ];
-    if (installedCommit.length > 0 &&
-        commitMatches(desiredCommit, installedCommit)) {
-        return { ok: true, stdout: [...stdout, "manager updated"], stderr: [] };
-    }
-    // :106-113 — which hint key is read depends on whether a commit was
-    // detected at all, and the hint is optional in both directions.
-    const installed = readResult(installResult);
-    const hints = installed.kind === "object" ? installed.value.verification_hints : null;
-    let hint = "";
-    if (typeof hints === "object" && hints !== null && !Array.isArray(hints)) {
-        const key = installedCommit.length > 0 ? "mismatch" : "missing";
-        const value = hints[key];
-        if (typeof value === "string" && !hasTerminalControl(value))
-            hint = value;
-    }
-    const stderr = [
-        installedCommit.length > 0
-            ? "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 { ok: false, stdout, stderr };
-}
-// Ported from
 // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:126-141::spw_verify_uninstalled_resources`,
 // with the Boolean coercion of
 // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:58-73::spw_adapter_result_boolean`

package/dist/manifest-overlay.js

@@ -69,7 +69,7 @@ function setMember(entries, key, value) {
 }
 /**
  * Map strict-json's diagnostics onto the CPython wording the callers assert.
- * Repository policy at `AGENTS.md:90::most diagnostics are asserted as`
+ * Repository policy at `AGENTS.md:92::most diagnostics are asserted as`
  * freezes most of these diagnostics as complete-string contracts.
  */
 function translate(cause, source, path) {
@@ -82,7 +82,7 @@ function translate(cause, source, path) {
         return new SafetyError("manifest-overlay", `JSON nesting exceeds limit in ${path}`, { cause });
     }
     // strict-json reports `… at character N`
-    // (`src/strict-json.ts:305::at character ${this.index}`), a zero-based offset. CPython reports
+    // (`src/strict-json.ts:312::at character ${this.index}`), a zero-based offset. CPython reports
     // one-based line and column. Convert so the message keeps CPython's shape.
     // This does NOT claim the two parsers fail at the same place on the same
     // malformed input — see the spec.

package/dist/pi-compatibility.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { readArtifactFile, readArtifactObject, validateNativeSkill, } from "./artifact-tree.js";
+import { SEMVER_RE } from "./generated-plugin.js";
+import { validateSource } from "./selection.js";
+const OFFICIAL_SOURCES = new Set([
+    "https://github.com/obra/superpowers",
+    "https://github.com/obra/superpowers.git",
+    "ssh://git@github.com/obra/superpowers.git",
+    "git@github.com:obra/superpowers.git",
+]);
+export function samePiSource(left, right) {
+    validateSource(left);
+    validateSource(right);
+    return (left === right ||
+        (OFFICIAL_SOURCES.has(left) && OFFICIAL_SOURCES.has(right)));
+}
+export async function assessPiCompatibility(root, selection) {
+    try {
+        validateSource(selection.effectiveSource);
+        const official = OFFICIAL_SOURCES.has(selection.effectiveSource);
+        const pkg = await readArtifactObject(root, join(root, "package.json"));
+        if (pkg.name !== "superpowers" ||
+            pkg.type !== "module" ||
+            typeof pkg.version !== "string" ||
+            !SEMVER_RE.test(pkg.version))
+            throw new Error("package metadata");
+        const pi = pkg.pi;
+        if (!pi ||
+            typeof pi !== "object" ||
+            Array.isArray(pi) ||
+            Object.keys(pi).length !== 2 ||
+            JSON.stringify(pi.extensions) !== '["./.pi/extensions/superpowers.ts"]' ||
+            JSON.stringify(pi.skills) !== '["./skills"]')
+            throw new Error("resource declaration");
+        for (const key of [
+            "dependencies",
+            "optionalDependencies",
+            "peerDependencies",
+            "bundleDependencies",
+            "bundledDependencies",
+        ]) {
+            const value = pkg[key];
+            if (value !== undefined &&
+                (value === null ||
+                    typeof value !== "object" ||
+                    Object.keys(value).length !== 0))
+                throw new Error("runtime dependencies");
+        }
+        await validateNativeSkill(root);
+        const bootstrap = join(root, ".pi/extensions/superpowers.ts");
+        const bytes = await readArtifactFile(root, bootstrap, 4283);
+        if ((await lstat(bootstrap)).mode & 0o111 ||
+            bytes.length !== 4283 ||
+            createHash("sha256").update(bytes).digest("hex") !==
+                "39c27000c047f8a1399a76e032e4cd239d7bdb0be168a121f46a2ac719deaae0")
+            throw new Error("bootstrap implementation");
+        return {
+            kind: official ? "supported" : "experimental",
+            generation: "pi-native-bootstrap-v1",
+            reason: official
+                ? "qualified upstream-native Pi bootstrap"
+                : "qualified Pi mechanics from a custom source",
+        };
+    }
+    catch {
+        return {
+            kind: "unsupported",
+            reason: `Pi package does not match the qualified native bootstrap profile: ${root}`,
+        };
+    }
+}