superpowers-manager 0.4.0 → 0.5.1

package/dist/commands/mutation.js

@@ -0,0 +1,71 @@
+import { computeEffectiveSelection } from "../effective-selection.js";
+import { upstreamCacheRoot } from "../upstream-workspace.js";
+import { SafetyError } from "../safety-error.js";
+import { isAbsolute } from "node:path";
+import { oneLine } from "../cli-arguments.js";
+export async function withMutation(command, ctx, action) {
+    // Selection validation precedes every adapter call and lock creation. A
+    // nested mutation receives the already resolved value and cannot observe a
+    // saved-selection change midway through one invocation.
+    const selection = command === "uninstall"
+        ? ctx.selection
+        : (ctx.selection ?? (await computeEffectiveSelection(ctx.root, ctx.env)));
+    const scoped = selection === undefined ? ctx : { ...ctx, selection };
+    const adapterContext = { root: ctx.root, env: ctx.env };
+    let location;
+    try {
+        location = ctx.adapter.preparationLocation(adapterContext);
+    }
+    catch (cause) {
+        throw new SafetyError("mutation", "cannot determine preparation location", {
+            cause,
+        });
+    }
+    if (!isAbsolute(location.destinationRoot))
+        throw new SafetyError("mutation", "adapter returned a non-absolute preparation destination");
+    if (!location.stagingLeaf ||
+        location.stagingLeaf === "." ||
+        location.stagingLeaf === ".." ||
+        location.stagingLeaf.includes("/") ||
+        location.stagingLeaf.includes("\\"))
+        throw new SafetyError("mutation", "adapter returned an invalid preparation staging leaf");
+    let mutationRoots;
+    try {
+        mutationRoots = await ctx.adapter.mutationRoots(adapterContext);
+        if (!Array.isArray(mutationRoots) ||
+            mutationRoots.some((root) => typeof root !== "string" || !isAbsolute(root)))
+            throw new Error("invalid roots");
+    }
+    catch (cause) {
+        throw new SafetyError("mutation", "cannot determine harness mutation resources", { cause });
+    }
+    const resources = [location.destinationRoot, ...mutationRoots];
+    if (command === "prepare") {
+        resources.push(upstreamCacheRoot(ctx.root, ctx.env, process.cwd()));
+    }
+    // The coordinator sorts each acquisition and refuses conflicts immediately.
+    // A nested prepare may add a cache lock that sorts before an outer target;
+    // it cannot deadlock because no acquisition waits, while already-held roots
+    // are reentrant for this invocation.
+    return await ctx.coordination.withResources(resources, async () => action(scoped));
+}
+export async function runWithMutation(command, ctx, action) {
+    let actionThrew = false;
+    try {
+        return await withMutation(command, ctx, async (scoped) => {
+            try {
+                return await action(scoped);
+            }
+            catch (cause) {
+                actionThrew = true;
+                throw cause;
+            }
+        });
+    }
+    catch (cause) {
+        if (actionThrew)
+            throw cause;
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
+        return 1;
+    }
+}

package/dist/commands/prepare.js

@@ -1,18 +1,20 @@
 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
-// (`src/hooks.ts:44::function hookError`).
+// (`src/harnesses/codex/hooks.ts:44::function hookError`).
 function prepareError(message, cause) {
     return new SafetyError("prepare", message, { cause });
 }
@@ -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.
@@ -335,8 +341,8 @@ export async function runPrepare(argv, ctx) {
         // failure (its cause is the shared runner's (src/validator.ts) captured
         // spawn error, which oneLine never reads -- it takes .message only);
         // readManifest's three hookError messages
-        // (`src/hooks.ts:113-138::readManifest`), pinned by
-        // `tests/unit/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
+        // (`src/harnesses/codex/hooks.ts:113-138::readManifest`), pinned by
+        // `tests/unit/harnesses/codex/hooks.test.ts:95::void test("readManifest diagnostics` as carrying no reader vocabulary or
         // errno; and SafetyErrors from gitSafeSource, writeProvenance, and
         // withWorkspace.
         //
@@ -376,7 +382,7 @@ export async function runPrepare(argv, ctx) {
         // only, so it bounds how much of that text lands, not what it may
         // contain.
         //
-        // runAdapter's closing `throw cause` (src/adapter.ts) does NOT arrive
+        // runAdapter's closing `throw cause` (src/harnesses/codex/adapter.ts) does NOT arrive
         // here -- the call site catches it and converts it to a hand-written
         // message per AGENTS.md's reader-diagnostics rule.
         //
@@ -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

@@ -11,7 +11,7 @@ export const PROBE_USAGE = "error: usage: superpowers-manager probe [--porcelain
 // silent diagnostics regression, not a simplification.
 //
 // Interpolating error.message and each hint is the sanctioned form (AGENTS.md):
-// src/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
+// src/harnesses/codex/adapter.ts has 52 `fail()` sites and none interpolates a caught error's
 // message, so the callee owns every failure reachable on this path. Those two
 // writes now live in writeAdapterFailure (src/adapter-result.ts), which
 // validates all three strings before the first of them reaches the stream.
@@ -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
@@ -41,17 +121,23 @@ export function replayOutcome(outcome, ctx) {
 // evidence and report it as success.
 //
 // It does still THROW for a non-AdapterFailure cause (runAdapter's closing
-// `throw cause`, src/adapter.ts). That is caught here rather than in runProbe's
+// `throw cause`, src/harnesses/codex/adapter.ts). That is caught here rather than in runProbe's
 // outer catch, because the two need different diagnostics -- see spec §3.3a.
 //
 // Reached through ctx.adapter, not a direct module-level dependency on the
 // adapter module: src/commands/prepare.ts and this module are the two the
 // injected double must observe, because install reaches the adapter through
 // gatherProbe and runPrepare. Spec §4.5.
-async function inspect(call, unexpected, invalidStatus) {
+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"
@@ -227,9 +377,9 @@ export async function runProbe(argv, ctx) {
         // which catches every failure and returns "".
         //
         // A non-AdapterFailure re-thrown by runAdapter's closing `throw cause`
-        // (src/adapter.ts) does NOT reach here: inspect() catches it and converts
+        // (src/harnesses/codex/adapter.ts) does NOT reach here: inspect() catches it and converts
         // it to a hand-written message per AGENTS.md's reader-diagnostics rule -- a
-        // rethrown cause is exactly the failure src/adapter.ts declined to own, so
+        // rethrown cause is exactly the failure src/harnesses/codex/adapter.ts declined to own, so
         // its text must never reach this stream. See §3.3a.
         //
         // gatherProbe performs no writes of its own, so this catch cannot also be
@@ -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

@@ -1,9 +1,10 @@
 // Ports scripts/uninstall. The shell sourced common.sh, provenance.sh,
-// lifecycle.sh and adapter.sh; the predicates now live in src/lifecycle.ts
+// lifecycle.sh and adapter.sh; the predicates now live in src/harnesses/codex/lifecycle.ts
 // and the adapter arrives through ctx.adapter.
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
 import { withWorkspace, workspaceRemovalFailure } from "../workspace.js";
+import { 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,
@@ -125,7 +126,7 @@ async function gatherUninstall(ctx) {
         // Reachable only for mkdtemp failure, with nothing collected yet: this
         // callback never throws -- every ctx.adapter throw is already caught
         // inside invoke(), and presenceFlag/verifyUninstalledResources/
-        // reportLegacyState are pure (src/lifecycle.ts's header comment) -- so a
+        // reportLegacyState are pure (src/harnesses/codex/lifecycle.ts's header comment) -- so a
         // post-success cleanup failure is handled by onCleanupFailure above and
         // cannot reach here. Wrapping with `outcomes` anyway keeps the class
         // total over its declared contract rather than assuming the callback's
@@ -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;`.
@@ -159,7 +163,7 @@ export async function runUninstall(argv, ctx) {
         // blindly.
         //
         // A cause outside ctx.adapter's AdapterFailure guard
-        // (`src/adapter.ts:973-999::async function runCodexOperation(`) does NOT
+        // (`src/harnesses/codex/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.

package/dist/commands/update.js

@@ -1,5 +1,5 @@
 // Ports scripts/update. The shell sourced common.sh and lifecycle.sh; the
-// predicates now live in src/lifecycle.ts. Unlike install and uninstall,
+// predicates now live in src/harnesses/codex/lifecycle.ts. Unlike install and uninstall,
 // update issues no ctx.adapter call of its own: every adapter interaction
 // this module needs already happens inside gatherProbe, runPrepare or
 // runInstall, each of which owns its own §4.2a-conformant invoke() gate. That
@@ -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/domain/refs.js

@@ -3,6 +3,10 @@ const SEMVER_BASE_SOURCE = "(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0-9]*)\\.(?:0|[1-9][0
     "(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?";
 export const SEMVER_BASE_RE = new RegExp(`^${SEMVER_BASE_SOURCE}$`);
 export const TAG_RE = new RegExp(`^v${SEMVER_BASE_SOURCE}$`);
+// The Python's own SEMVER_RE (:15-22). Deliberately not SEMVER_BASE_SOURCE
+// from this module, which omits the `+build` component; widening the shared
+// constant would change TAG_RE and is out of scope.
+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-]+)*)?$/;
 export const COMMIT_RE = /^[0-9a-f]{40}$/;
 export const COMMIT_INPUT_RE = /^[0-9A-Fa-f]{40}$/;
 export function isTagRef(value) {

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/{adapter.js → harnesses/codex/adapter.js}

@@ -4,19 +4,20 @@ import { constants } from "node:fs";
 import { access, copyFile, mkdir, readFile, realpath, stat, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { delimiter, isAbsolute, join } from "node:path";
-import { AdapterMessageLog, failureResult, successResult, } from "./adapter-result.js";
-import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./codex-json.js";
-import { oneLine } from "./cli-arguments.js";
-import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./codex-state.js";
+import { AdapterMessageLog, failureResult, successResult, } from "../../adapter-result.js";
+import { activePluginVersionFromJson, installedListingHas, marketplaceRootFromJson, } from "./json.js";
+import { CODEX_LEGACY_PLUGIN_ID, CODEX_MANAGER_PLUGIN_ID, inspectCodexConflicts, } from "./conflicts.js";
+import { oneLine } from "../../cli-arguments.js";
+import { installedCommitFromRoot, installedRootForVersion, pathsEqual, } from "./state.js";
 import { validateGeneratedPlugin } from "./generated-plugin.js";
 import { classifyHooks, materializeHooks, readManifest, } from "./hooks.js";
 import { applyManifestOverlay } from "./manifest-overlay.js";
-import { readCodexBuildSource } from "./provenance.js";
-import { isAcceptedSplitValue } from "./validate-generated-plugin-cli.js";
-import { withWorkspace, workspaceRemovalFailure } from "./workspace.js";
-const PLUGIN_ID = "superpowers@superpowers-manager";
+import { readCodexBuildSource } from "../../provenance.js";
+import { isAcceptedSplitValue } from "../../validate-generated-plugin-cli.js";
+import { withWorkspace, workspaceRemovalFailure } from "../../workspace.js";
+const PLUGIN_ID = CODEX_MANAGER_PLUGIN_ID;
 const MARKETPLACE_NAME = "superpowers-manager";
-const LEGACY_PLUGIN_ID = "superpowers@superpowers-wrapper";
+const LEGACY_PLUGIN_ID = CODEX_LEGACY_PLUGIN_ID;
 const LEGACY_MARKETPLACE_NAME = "superpowers-wrapper";
 class AdapterFailure extends Error {
     code;
@@ -88,7 +89,7 @@ function runCommand(file, args, env) {
         });
     });
 }
-// Exported only so tests/unit/adapter.test.js can assert the env scrub
+// Exported only so tests/unit/harnesses/codex/adapter.test.ts can assert the env scrub
 // directly. No production caller uses this name.
 export { runCommand as runCommandForTest };
 function commandFailed(result) {
@@ -280,7 +281,7 @@ async function runBuild(input, env, log) {
                 // path — three are the frozen CPython wording, and the fourth (the
                 // numeric-overflow diagnostic, which has no CPython oracle wording
                 // to match) now carries the path via its own rewrap in
-                // src/manifest-overlay.ts. Emit as-is, with no added prefix — a
+                // src/harnesses/codex/manifest-overlay.ts. Emit as-is, with no added prefix — a
                 // prefix here would double up the path these messages already
                 // name.
                 log.appendText("stderr", oneLine(cause));
@@ -486,7 +487,7 @@ async function runUninstall(input, env, log) {
         throw cause;
     }
 }
-async function runInspect(view, env, log) {
+async function runInspect(view, context, env, log) {
     if (view === "update-control") {
         return { view: "update-control", update_control: "managed" };
     }
@@ -552,9 +553,11 @@ async function runInspect(view, env, log) {
                 let legacyPlugin;
                 let managerMarketplace;
                 let legacyMarketplace;
+                let conflicts;
                 try {
                     managerPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", PLUGIN_ID);
                     legacyPlugin = installedListingHas(plugins.stdout, "installed", "pluginId", LEGACY_PLUGIN_ID);
+                    conflicts = await inspectCodexConflicts({ root: context.root, env }, plugins.stdout.toString("utf8"));
                 }
                 catch {
                     fail("inspect-failed", `cannot parse output of '${codexBin} plugin list --json'`);
@@ -585,6 +588,7 @@ async function runInspect(view, env, log) {
                         : legacyPresent
                             ? "legacy"
                             : "neither",
+                    conflicts: [...conflicts],
                 };
             }, { onCleanupFailure: reportOrphanedWorkspace(log) });
         }
@@ -622,7 +626,7 @@ export function codexRemove(input, context) {
     return runCodexOperation("uninstall", context, (env, log) => runUninstall(input, env, log));
 }
 export function codexInspect(view, context) {
-    return runCodexOperation("inspect", context, (env, log) => runInspect(view, env, log));
+    return runCodexOperation("inspect", context, (env, log) => runInspect(view, context, env, log));
 }
 export async function runAdapter(argv, context) {
     const rawOperation = argv[0];