superpowers-manager 0.4.0 → 0.5.0

package/dist/commands/prepare.js

@@ -1,14 +1,16 @@
 import { mkdir, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, sep } from "node:path";
 import { atomicReplaceDir } from "../atomic.js";
 import { oneLine } from "../cli-arguments.js";
 import { computeEffectiveSelection } from "../effective-selection.js";
 import { runGit } from "../git.js";
 import { SafetyError } from "../safety-error.js";
 import { fetchExactCommit, gitSafeSource } from "../upstream.js";
+import { upstreamCacheRoot } from "../upstream-workspace.js";
 import { BOUNDED_EXECUTABLE, UNBOUNDED_LEGACY, launchFailureMessage, resolveValidator, runValidator, displayPath, } from "../validator.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
 import { replayOutcome } from "./probe.js";
+import { runWithMutation } from "./mutation.js";
 // Every message this module writes is hand-written here. The cause is attached
 // for debuggability and never reaches a stream: oneLine (src/cli-arguments.ts)
 // reads .message only. Same arrangement as hookError
@@ -93,10 +95,8 @@ async function gatherPrepare(ctx) {
     // getcwd(3) returns the physical path, so this matches `pwd -P` without a
     // realpath call.
     const cwd = process.cwd();
-    const configuredCache = env.SUPERPOWERS_CACHE_DIR || join(ctx.root, ".cache", "upstream");
-    const cacheParent = isAbsolute(configuredCache)
-        ? configuredCache
-        : resolve(cwd, configuredCache);
+    const cache = upstreamCacheRoot(ctx.root, env, cwd);
+    const cacheParent = dirname(cache);
     const adapterContext = { root: ctx.root, env };
     let location;
     try {
@@ -114,7 +114,6 @@ async function gatherPrepare(ctx) {
     const pluginRoot = location.destinationRoot;
     const additionalValidator = env.SUPERPOWERS_VALIDATOR || "";
     const executableValidator = env.SUPERPOWERS_VALIDATOR_EXECUTABLE || "";
-    const cache = join(cacheParent, "superpowers");
     const tmpParent = dirname(pluginRoot);
     await owned(`cannot create directory: ${tmpParent}`, () => mkdir(tmpParent, { recursive: true }));
     let cleanupWarning = null;
@@ -127,7 +126,7 @@ async function gatherPrepare(ctx) {
             message,
         });
         const candidate = join(workspace, location.stagingLeaf);
-        const selection = await computeEffectiveSelection(ctx.root, env);
+        const selection = ctx.selection ?? (await computeEffectiveSelection(ctx.root, env));
         let prefetch;
         try {
             prefetch =
@@ -211,6 +210,9 @@ async function gatherPrepare(ctx) {
         if (prepared.outcome.result.commit !== selection.desiredCommit) {
             return failed("adapter returned an unexpected preparation commit");
         }
+        if (prepared.outcome.result.compatibility.kind === "unsupported") {
+            return failed(prepared.outcome.result.compatibility.reason);
+        }
         let validator = NO_VALIDATOR_OUTPUT;
         if (additionalValidator.length > 0) {
             // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/prepare:108::[ -f "$additional_validator` — `[ -f ]`.
@@ -284,11 +286,12 @@ async function gatherPrepare(ctx) {
         // The swap must run inside the workspace callback: withWorkspace removes
         // the workspace on return, and the candidate lives in it.
         //
-        // atomicReplaceDir's outer catch (`src/atomic.ts:208-215::if (cause`) wraps every
-        // non-SafetyError into a SafetyError, so the callee owns every failure on
-        // this path and re-emitting its own diagnostic is the sanctioned form of
-        // interpolation. The hand-written prefix carries the live root, which the
-        // callee's message does not.
+        // atomicReplaceDir delegates to beginDirectoryPublication, whose outer
+        // catch (`src/atomic.ts:341-348::if (cause`) wraps every non-SafetyError
+        // into a SafetyError, so the callee owns every failure on this path and
+        // re-emitting its own diagnostic is the sanctioned form of interpolation.
+        // The hand-written prefix carries the live root, which the callee's message
+        // does not.
         try {
             await atomicReplaceDir(candidate, pluginRoot);
         }
@@ -319,6 +322,9 @@ async function gatherPrepare(ctx) {
     return { outcome, cleanupWarning };
 }
 export async function runPrepare(argv, ctx) {
+    return await runWithMutation("prepare", ctx, async (scoped) => performPrepare(argv, scoped));
+}
+async function performPrepare(argv, ctx) {
     // scripts/prepare never reads "$@", so extra arguments are ignored. This is a
     // deliberate asymmetry with probe, whose shell original rejected unknown
     // arguments and whose arity therefore moved into parseArgs in slice 2.
@@ -412,7 +418,7 @@ export async function runPrepare(argv, ctx) {
         // completed 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. Mirrors
-        // `src/commands/install.ts:395-403::if (cleanupWarning`.
+        // `src/commands/install.ts:546-554::if (cleanupWarning`.
         ctx.stderr.write(`error: ${cleanupWarning}\n`);
         return 1;
     }

package/dist/commands/probe.js

@@ -33,6 +33,86 @@ export function replayOutcome(outcome, ctx) {
     // stored, so scanning it here would re-check a population that cannot fail.
     writeAdapterFailure(ctx, outcome);
 }
+function record(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : null;
+}
+export function validOutput(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        Array.isArray(candidate.stdout) &&
+        candidate.stdout.every((line) => typeof line === "string") &&
+        Array.isArray(candidate.stderr) &&
+        candidate.stderr.every((line) => typeof line === "string"));
+}
+function validDecision(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        (candidate.kind === "allowed" ||
+            (candidate.kind === "blocked" && validOutput(candidate.output))));
+}
+function validCompatibility(value) {
+    const candidate = record(value);
+    if (candidate === null ||
+        typeof candidate.reason !== "string" ||
+        (candidate.kind !== "unknown" &&
+            candidate.kind !== "supported" &&
+            candidate.kind !== "experimental" &&
+            candidate.kind !== "unsupported"))
+        return false;
+    return ((candidate.kind !== "supported" && candidate.kind !== "experimental") ||
+        typeof candidate.generation === "string");
+}
+function validPreparedArtifact(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        typeof candidate.root === "string" &&
+        typeof candidate.commit === "string" &&
+        typeof candidate.identity === "string" &&
+        validCompatibility(candidate.compatibility));
+}
+function validPrepared(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        typeof candidate.observedIdentity === "string" &&
+        validCompatibility(candidate.compatibility) &&
+        (candidate.kind === "needs-prepare" ||
+            (candidate.kind === "current" &&
+                validPreparedArtifact(candidate.artifact))));
+}
+export function validInstalled(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        (candidate.kind === "current" ||
+            candidate.kind === "mismatch" ||
+            candidate.kind === "absent") &&
+        typeof candidate.observedIdentity === "string" &&
+        (candidate.kind !== "absent" || candidate.observedIdentity === ""));
+}
+function validOwnership(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        validDecision(candidate.installEligibility) &&
+        Object.prototype.hasOwnProperty.call(candidate, "removalInput") &&
+        validDecision(candidate.removalVerification) &&
+        validOutput(candidate.postRemovalOutput) &&
+        typeof candidate.presentationValue === "string" &&
+        (candidate.presentationConflicts === undefined ||
+            (Array.isArray(candidate.presentationConflicts) &&
+                candidate.presentationConflicts.every((conflict) => typeof conflict === "string"))));
+}
+function validControl(value) {
+    const candidate = record(value);
+    return (candidate !== null &&
+        validDecision(candidate.probeEligibility) &&
+        validDecision(candidate.mutationEligibility) &&
+        typeof candidate.presentationValue === "string" &&
+        (candidate.recoveryState === undefined ||
+            (candidate.recoveryState === "required" &&
+                candidate.probeEligibility.kind === "blocked" &&
+                candidate.mutationEligibility.kind === "blocked")));
+}
 // `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
@@ -48,10 +128,16 @@ export function replayOutcome(outcome, ctx) {
 // 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) {
+async function inspect(call, unexpected, invalidStatus, valid) {
     let result;
     try {
         result = await call();
+        if (!result ||
+            !Number.isInteger(result.status) ||
+            !result.outcome ||
+            typeof result.outcome.ok !== "boolean" ||
+            !Array.isArray(result.outcome.messages))
+            return { ok: false, result: null, message: invalidStatus };
     }
     catch {
         return { ok: false, result: null, message: unexpected };
@@ -67,6 +153,14 @@ async function inspect(call, unexpected, invalidStatus) {
             message: outcome.ok ? invalidStatus : null,
         };
     }
+    try {
+        if (!valid(outcome.result)) {
+            return { ok: false, result, message: invalidStatus };
+        }
+    }
+    catch {
+        return { ok: false, result, message: invalidStatus };
+    }
     return { ok: true, result: { status: result.status, outcome } };
 }
 // Runs every step that can throw or fail closed, returning the outcome as
@@ -86,35 +180,84 @@ async function inspect(call, unexpected, invalidStatus) {
 // 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 selection = ctx.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)
+    let resources;
+    try {
+        resources = [
+            ctx.adapter.preparationLocation(adapterContext).destinationRoot,
+            ...(await ctx.adapter.mutationRoots(adapterContext)),
+        ];
+    }
+    catch {
+        resources = null;
+    }
+    const before = resources === null
+        ? []
+        : await ctx.coordination.observeResources(resources);
+    const collect = async (call, unexpected, invalidStatus, valid, replaySuccess = true) => {
+        const result = await inspect(call, unexpected, invalidStatus, valid);
+        if (result.result !== null && (replaySuccess || !result.result.outcome.ok))
             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");
+    const prepared = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection", validPrepared);
     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);
+    const installed = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus, validInstalled);
     if (!installed.ok) {
         return { status: 1, outcomes, message: installed.message };
     }
+    if (resources === null)
+        return {
+            status: 1,
+            outcomes,
+            message: "cannot determine harness observation resources",
+        };
     const ownershipFailure = failure("probe-ownership");
-    const ownership = await collect(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure.unexpected, ownershipFailure.invalidStatus);
+    const ownership = await collect(() => ctx.adapter.inspectOwnership(adapterContext), ownershipFailure.unexpected, ownershipFailure.invalidStatus, validOwnership);
     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);
+    const control = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, validControl);
     if (!control.ok) {
         return { status: 1, outcomes, message: control.message };
     }
+    const preparedAfter = await collect(() => ctx.adapter.inspectPrepared(selection, adapterContext), "cannot inspect prepared harness state", "adapter reported a failure status for prepared harness inspection", validPrepared, false);
+    if (!preparedAfter.ok)
+        return { status: 1, outcomes, message: preparedAfter.message };
+    const installedAfter = await collect(() => ctx.adapter.inspectInstalled(selection, adapterContext), installedFailure.unexpected, installedFailure.invalidStatus, validInstalled, false);
+    if (!installedAfter.ok)
+        return { status: 1, outcomes, message: installedAfter.message };
+    const controlAfter = await collect(() => ctx.adapter.inspectUpdateControl(adapterContext), controlFailure.unexpected, controlFailure.invalidStatus, validControl, false);
+    if (!controlAfter.ok)
+        return { status: 1, outcomes, message: controlAfter.message };
+    const after = await ctx.coordination.observeResources(resources);
+    if (JSON.stringify(before) !== JSON.stringify(after) ||
+        JSON.stringify(prepared.result.outcome.result) !==
+            JSON.stringify(preparedAfter.result.outcome.result) ||
+        JSON.stringify(installed.result.outcome.result) !==
+            JSON.stringify(installedAfter.result.outcome.result) ||
+        JSON.stringify(control.result.outcome.result) !==
+            JSON.stringify(controlAfter.result.outcome.result)) {
+        return {
+            status: 1,
+            outcomes,
+            message: "harness state changed during observation; retry for a coherent probe",
+        };
+    }
+    const unavailable = after.find((observation) => observation.state === "busy" || observation.state === "uninspectable");
+    if (unavailable)
+        return {
+            status: 1,
+            outcomes,
+            message: `harness resource is ${unavailable.state}: ${unavailable.resource}`,
+        };
     const preparedState = prepared.result.outcome.result;
     const installedState = installed.result.outcome.result;
     return {
@@ -126,6 +269,13 @@ export async function gatherProbe(ctx) {
             installed: installedState,
             ownership: ownership.result.outcome.result,
             control: control.result.outcome.result,
+            compatibility: preparedState.compatibility,
+            resources: after,
+            resourceState: control.result.outcome.result.recoveryState === "required"
+                ? "recovery-required"
+                : after.some((observation) => observation.state === "owned")
+                    ? "owned"
+                    : "idle",
             status: preparedState.kind !== "current"
                 ? "needs prepare"
                 : installedState.kind !== "current"
@@ -253,5 +403,5 @@ export async function runProbe(argv, ctx) {
     }
     const rendered = ctx.adapter.presentation.renderProbe(outcome.facts);
     ctx.stdout.write(porcelain ? rendered.porcelain : rendered.human);
-    return 0;
+    return outcome.facts.resourceState === "recovery-required" ? 1 : 0;
 }

package/dist/commands/uninstall.js

@@ -4,6 +4,7 @@
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
+import { runWithMutation } from "./mutation.js";
 import { replayOutcome } from "./probe.js";
 async function invoke(call, failure, outcomes) {
     let result;
@@ -52,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:114-117::readonly facts: ProbeSnapshot<R>;`) 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,7 +109,7 @@ async function gatherUninstall(ctx) {
             return {
                 status: 0,
                 outcomes,
-                output: ctx.adapter.presentation.renderRemovalCompletion(ownership),
+                output: ctx.adapter.presentation.renderRemovalCompletion(ownership, removalInput),
             };
         }, {
             // Suppresses withWorkspace's throw on a POST-SUCCESS cleanup failure,
@@ -134,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;`.

package/dist/commands/update.js

@@ -9,6 +9,7 @@ import { oneLine } from "../cli-arguments.js";
 import { gatherProbe, replayOutcome } from "./probe.js";
 import { runInstall } from "./install.js";
 import { runPrepare } from "./prepare.js";
+import { runWithMutation } from "./mutation.js";
 function writeOutput(output, ctx) {
     for (const line of output.stdout)
         ctx.stdout.write(`${line}\n`);
@@ -16,6 +17,9 @@ function writeOutput(output, ctx) {
         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;
@@ -30,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:251-309::THREE exceptions, all inherited and none a regression:`'s
+        // `src/commands/probe.ts:469-527::THREE exceptions, all inherited and none a regression:`'s
         // runProbe catch is the first 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

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/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:91::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) {

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}`,
+        };
+    }
+}

package/dist/pi-harness.js

@@ -0,0 +1,63 @@
+import { failureResult, successResult } from "./adapter-result.js";
+import { classifyPathNoFollow } from "./safe-path.js";
+import { installPi, removePi } from "./pi-install.js";
+import { piPaths } from "./pi-paths.js";
+import { inspectPiPrepared, piPreparationLocation, preparePiCandidate, readPiPrepared, } from "./pi-prepare.js";
+import { piPresentation } from "./pi-presentation.js";
+import { inspectPiControl, inspectPiInstalled, inspectPiOwnership, } from "./pi-state.js";
+export const piHarness = {
+    preparationLocation: piPreparationLocation,
+    mutationRoots: async (ctx) => [
+        piPaths(ctx.env ?? {}, process.cwd()).agentDir,
+    ],
+    validatePreparationBeforeFetch: async () => successResult("validate-pi-preparation", null, []),
+    prepareCandidate: preparePiCandidate,
+    inspectPrepared: inspectPiPrepared,
+    readPrepared: readPiPrepared,
+    inspectOwnership: inspectPiOwnership,
+    async inspectUpdateControl(ctx) {
+        const paths = piPaths(ctx.env ?? {}, process.cwd());
+        try {
+            if ((await classifyPathNoFollow(paths.recoveryRoot)) !== "missing") {
+                const decision = {
+                    kind: "blocked",
+                    output: {
+                        stdout: [],
+                        stderr: [
+                            `error: Pi recovery required; preserve material at ${paths.recoveryRoot} for manual resolution`,
+                        ],
+                    },
+                };
+                return successResult("inspect-pi-control", {
+                    probeEligibility: decision,
+                    mutationEligibility: decision,
+                    presentationValue: `recovery required at ${paths.recoveryRoot}`,
+                    recoveryState: "required",
+                }, []);
+            }
+        }
+        catch {
+            return failureResult("inspect-pi-control", "invalid-state", `cannot inspect Pi recovery state at ${paths.recoveryRoot}`, [], []);
+        }
+        return await inspectPiControl(ctx);
+    },
+    inspectInstalled: inspectPiInstalled,
+    install: installPi,
+    remove: removePi,
+    requirements(command, env) {
+        if (command !== "install" &&
+            command !== "update" &&
+            command !== "uninstall")
+            return [];
+        const executable = env.SUPERPOWERS_PI || "pi";
+        return [
+            {
+                name: "pi",
+                executable,
+                lookup: "explicit-path-or-path",
+                missingMessage: `required command not found: ${executable} — install the Pi CLI or set SUPERPOWERS_PI`,
+            },
+        ];
+    },
+    presentation: piPresentation,
+};