superpowers-manager 0.5.0 → 0.5.2

package/dist/{generated-plugin.js → harnesses/codex/generated-plugin.js}

@@ -1,20 +1,9 @@
-import { lstat, readdir, readFile, readlink, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { posix } from "node:path";
-import { COMMIT_RE } from "./domain/refs.js";
-import { pythonSplitlines, pythonStrip } from "./python-text.js";
-import { parseStrictJson } from "./strict-json.js";
-export const DEFAULT_FS_DEPS = {
-    lstat,
-    stat,
-    readdir,
-    readlink,
-    readFile,
-};
-// 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.
-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-]+)*)?$/;
+import { COMMIT_RE, SEMVER_RE } from "../../domain/refs.js";
+import { compareByCodePoint, pythonStrip } from "../../python-text.js";
+import { DEFAULT_FS_DEPS, validateSkillFrontmatter, } from "../../skill-validation.js";
+import { parseStrictJson } from "../../strict-json.js";
 const MANIFEST_JSON_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",
@@ -50,7 +39,7 @@ function decodePathBytes(bytes) {
  * syscall, so a string carrying one would open a different file than the
  * caller named. CPython raises `UnicodeEncodeError` instead.
  */
-export function hasUnpairedSurrogate(value) {
+function hasUnpairedSurrogate(value) {
     for (let index = 0; index < value.length; index += 1) {
         const unit = value.charCodeAt(index);
         if (unit >= 0xd800 && unit <= 0xdbff) {
@@ -443,61 +432,6 @@ const REQUIRED_FILES = [
     "README.md",
     "CODE_OF_CONDUCT.md",
 ];
-/** Python `sorted()` orders by code point; JavaScript's default sort does not. */
-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.
-    const leftPoints = Array.from(left);
-    const rightPoints = Array.from(right);
-    const shared = Math.min(leftPoints.length, rightPoints.length);
-    for (let index = 0; index < shared; index += 1) {
-        const a = leftPoints[index].codePointAt(0);
-        const b = rightPoints[index].codePointAt(0);
-        if (a !== b)
-            return a - b;
-    }
-    return leftPoints.length - rightPoints.length;
-}
-export async function validateSkillFrontmatter(skillMd, skillName, errors, deps) {
-    let contents;
-    try {
-        contents = STRICT_DECODER.decode(await deps.readFile(skillMd));
-    }
-    catch {
-        errors.push(`skill \`${skillName}\` has unreadable UTF-8 \`SKILL.md\``);
-        return;
-    }
-    if (contents === "") {
-        errors.push(`skill \`${skillName}\` has empty \`SKILL.md\``);
-        return;
-    }
-    const lines = pythonSplitlines(contents);
-    if (lines.length === 0 || lines[0] !== "---") {
-        errors.push(`skill \`${skillName}\` must start with \`---\``);
-        return;
-    }
-    const closingIndex = lines.indexOf("---", 1);
-    if (closingIndex === -1) {
-        errors.push(`skill \`${skillName}\` frontmatter is not closed`);
-        return;
-    }
-    const frontmatter = lines.slice(1, closingIndex);
-    for (const key of ["name", "description"]) {
-        const matches = frontmatter.filter((line) => line.startsWith(`${key}:`));
-        if (matches.length !== 1) {
-            errors.push(`skill \`${skillName}\` frontmatter must contain exactly one top-level \`${key}:\``);
-            continue;
-        }
-        const value = pythonStrip(matches[0].slice(matches[0].indexOf(":") + 1));
-        if (value === "" ||
-            value === "''" ||
-            value === '""' ||
-            value.startsWith("#")) {
-            errors.push(`skill \`${skillName}\` frontmatter field \`${key}\` must be non-empty`);
-        }
-    }
-}
 async function validateHookSubtree(pluginRoot, hooksRoot, errors, deps) {
     let resolvedRoot;
     try {
@@ -513,9 +447,9 @@ async function validateHookSubtree(pluginRoot, hooksRoot, errors, deps) {
             isLink = (await inspectLink(path, deps)) === "symlink";
         }
         catch {
-            // The `src/generated-plugin.ts:667::isLink =` probe reaches the first catch bounded by `src/generated-plugin.ts:672-676::let rawTarget`; the `src/generated-plugin.ts:678::rawTarget = decodePathBytes` readlink reaches the same site text.
-            // The three probes sharing the *subtree* string are `src/generated-plugin.ts:711::resolvedDirectory =`, `src/generated-plugin.ts:721::children =`, and
-            // `src/generated-plugin.ts:730::deps, true)) === "directory"`, not this one.
+            // The `src/harnesses/codex/generated-plugin.ts:583::isLink =` probe reaches the first catch bounded by `src/harnesses/codex/generated-plugin.ts:592::let rawTarget`; the `src/harnesses/codex/generated-plugin.ts:594::rawTarget = decodePathBytes` readlink reaches the same site text.
+            // The three probes sharing the *subtree* string are `src/harnesses/codex/generated-plugin.ts:627::resolvedDirectory =`, `src/harnesses/codex/generated-plugin.ts:637::children =`, and
+            // `src/harnesses/codex/generated-plugin.ts:646::deps, true)) === "directory"`, not this one.
             errors.push(`generated hook symlink could not be inspected: ${path}`);
             return false;
         }

package/dist/{codex-harness.js → harnesses/codex/harness.js}

@@ -1,11 +1,13 @@
-import { join, resolve } from "node:path";
-import { failureResult, hasTerminalControl, successResult, } from "./adapter-result.js";
-import { codexInspect, codexInstall, codexRemove, } from "./adapter.js";
-import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./codex-prepare.js";
-import { codexInstallReceipt, codexPresentation, } from "./codex-presentation.js";
+import { failureResult, hasTerminalControl, successResult, } from "../../adapter-result.js";
+import { codexInspect, codexInstall, } from "./adapter.js";
+import { codexPreparationLocation, inspectCodexPrepared, prepareCodexCandidate, readCodexPrepared, validateCodexPreparationBeforeFetch, } from "./prepare.js";
+import { codexInstallReceipt, codexPresentation } from "./presentation.js";
 import { reportLegacyState, requireManagedUpdateControl, requireNoLegacyState, verifyUninstalledResources, } from "./lifecycle.js";
-import { SafetyError } from "./safety-error.js";
-import { commitMatches } from "./status.js";
+import { commitMatches } from "../../status.js";
+import { codexHome, codexPaths } from "./paths.js";
+import { installCodexMarketplace, removeCodexMarketplace, } from "./publication.js";
+import { readCodexRecovery } from "./recovery.js";
+import { inspectCodexInstallation } from "./state.js";
 function preserveFailure(result) {
     if (result.outcome.ok) {
         throw new Error("cannot preserve a successful adapter result as failure");
@@ -281,16 +283,34 @@ function requirements(command, env) {
     ];
 }
 async function mutationRoots(ctx) {
-    const env = ctx.env ?? {};
-    const configured = env.CODEX_HOME;
-    if (configured !== undefined && configured.length > 0) {
-        return [resolve(configured)];
+    return [codexHome(ctx.env ?? {}, process.cwd())];
+}
+async function inspectCodexUpdateControl(ctx) {
+    const normalized = normalizeCodexControl(await codexInspect("update-control", ctx));
+    if (!normalized.outcome.ok)
+        return normalized;
+    const paths = codexPaths(ctx.env ?? {}, process.cwd());
+    let diagnostic = null;
+    try {
+        if ((await readCodexRecovery(paths)) !== null) {
+            diagnostic = `Codex recovery required; preserve material at ${paths.recoveryRoot} for manual resolution`;
+        }
     }
-    const home = env.HOME;
-    if (home === undefined || home.length === 0) {
-        throw new SafetyError("codex-harness", "cannot determine Codex state root without HOME");
+    catch {
+        diagnostic = `cannot inspect Codex recovery state at ${paths.recoveryRoot}`;
     }
-    return [join(resolve(home), ".codex")];
+    if (diagnostic === null)
+        return normalized;
+    const decision = {
+        kind: "blocked",
+        output: { stdout: [], stderr: [`error: ${diagnostic}`] },
+    };
+    return successResult(normalized.outcome.operation, {
+        probeEligibility: decision,
+        mutationEligibility: decision,
+        presentationValue: diagnostic,
+        recoveryState: "required",
+    }, normalized.outcome.messages);
 }
 export const codexHarness = {
     preparationLocation: codexPreparationLocation,
@@ -300,13 +320,11 @@ export const codexHarness = {
     inspectPrepared: inspectCodexPrepared,
     readPrepared: readCodexPrepared,
     inspectOwnership: async (ctx) => normalizeCodexOwnership(await codexInspect("ownership", ctx)),
-    inspectUpdateControl: async (ctx) => normalizeCodexControl(await codexInspect("update-control", ctx)),
-    inspectInstalled: async (selection, ctx) => normalizeCodexInstalled(await codexInspect("fingerprint", ctx), selection.desiredCommit),
-    install: async (_artifact, ctx) => {
-        return normalizeCodexInstallForContext(await codexInstall(ctx.root, ctx), ctx);
-    },
+    inspectUpdateControl: inspectCodexUpdateControl,
+    inspectInstalled: inspectCodexInstallation,
+    install: async (artifact, ctx) => installCodexMarketplace(artifact, ctx, async (root, context) => normalizeCodexInstallForContext(await codexInstall(root, context), context)),
     remove: async (input, ctx) => {
-        const result = await codexRemove(input, ctx);
+        const result = await removeCodexMarketplace(input, ctx);
         if (!result.outcome.ok)
             return preserveFailure(result);
         if (result.status !== 0) {

package/dist/{hooks.js → harnesses/codex/hooks.js}

@@ -1,10 +1,10 @@
 import { copyFile, cp, mkdir, readdir, readFile, readlink, stat, symlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { assertExistingContained, assertProspectiveContained, classifyPathNoFollow, } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson } from "./strict-json.js";
+import { assertExistingContained, assertProspectiveContained, classifyPathNoFollow, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson } from "../../strict-json.js";
 // Annotated, not `as const`, matching
-// `src/provenance.ts:20::export const PROVENANCE_STRICT_PROFILE` and
+// `src/provenance.ts:20::const PROVENANCE_STRICT_PROFILE` and
 // `src/selection-store.ts:19::const SELECTION_JSON_PROFILE`. The annotation
 // rejects a misspelled or unsupported profile field here rather than at the
 // parseStrictJson call.
@@ -77,11 +77,11 @@ export async function readManifest(path) {
     catch {
         // Deliberately drops the cause on both branches. `detail(cause)` on the
         // read branch surfaced a raw errno (`ENOENT: … open '<path>'`), which the
-        // `hook classification failed:` site in src/adapter.ts re-emits onto the
+        // `hook classification failed:` site in src/harnesses/codex/adapter.ts re-emits onto the
         // terminal these commands write to; the parse branch surfaced
-        // strict-json's own wording under a prefix src/manifest-overlay.ts also
+        // strict-json's own wording under a prefix src/harnesses/codex/manifest-overlay.ts also
         // uses with CPython wording.
-        // Same text as the `cannot read manifest JSON in` site in src/adapter.ts.
+        // Same text as the `cannot read manifest JSON in` site in src/harnesses/codex/adapter.ts.
         throw hookError(`cannot read manifest JSON in ${path}`);
     }
     let parsed;

package/dist/{codex-json.js → harnesses/codex/json.js}

@@ -1,5 +1,5 @@
-import { SafetyError } from "./safety-error.js";
-import { parseStrictJson, } from "./strict-json.js";
+import { SafetyError } from "../../safety-error.js";
+import { parseStrictJson, } from "../../strict-json.js";
 const ACCEPT_CONSTANTS = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "accept",
@@ -66,9 +66,13 @@ export function codexInstalledPluginsFromJson(raw) {
         enabled: typeof item.enabled === "boolean" ? item.enabled : null,
     }));
 }
-export function marketplaceRootFromJson(raw, marketplaceName) {
+export function marketplaceRootFromJson(raw, marketplaceName, requireUnique = false) {
     const items = checkedItems(raw, ACCEPT_CONSTANTS, "marketplaces", "name");
-    const match = items.find((item) => item.name === marketplaceName);
+    const matches = items.filter((item) => item.name === marketplaceName);
+    if (requireUnique && matches.length > 1) {
+        fail("marketplace appears more than once");
+    }
+    const match = matches[0];
     if (match === undefined)
         return "";
     if (typeof match.root !== "string" || match.root.length === 0) {

package/dist/{lifecycle.js → harnesses/codex/lifecycle.js}

@@ -52,7 +52,7 @@ export function reportLegacyState(identityState) {
     }
     return unknownState(identityState);
 }
-export { verifyInstalledFingerprint, } from "./codex-presentation.js";
+export { verifyInstalledFingerprint } from "./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
@@ -101,7 +101,7 @@ export function verifyUninstalledResources(inspectResult) {
     // rather than getting its own message.
     // `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/adapter.sh:70::expected`
     // emits "expected Boolean adapter result at resources.plugin" for input {} —
-    // the input tests/unit/lifecycle.test.js's "a non-object resources falls
+    // the input tests/unit/harnesses/codex/lifecycle.test.ts's "a non-object resources falls
     // through to the Boolean message" exercises — so a distinct "not an object"
     // message here would be a port-only divergence. Parity, not divergence. Spec
     // §6.2.3 item 3.

package/dist/{manifest-overlay.js → harnesses/codex/manifest-overlay.js}

@@ -1,6 +1,6 @@
-import { escapeNonAscii, formatPythonNumber } from "./python-json-format.js";
-import { SafetyError } from "./safety-error.js";
-import { isRawNumber, isRawObject, parseStrictJsonPreservingNumbers, } from "./strict-json.js";
+import { escapeNonAscii, formatPythonNumber, } from "../../python-json-format.js";
+import { SafetyError } from "../../safety-error.js";
+import { isRawNumber, isRawObject, parseStrictJsonPreservingNumbers, } from "../../strict-json.js";
 const OVERLAY_PROFILE = {
     duplicateKeys: "last-wins",
     nonStandardConstants: "reject",
@@ -12,7 +12,7 @@ const OVERLAY_PROFILE = {
  * Byte-for-byte equivalent to the CPython implementation this replaces:
  * `json.dump(data, f, indent=2, allow_nan=False)` plus a trailing newline.
  * The byte-parity evidence lives in
- * `tests/baseline/manifest-overlay-parity.test.js` (tracked as
+ * `tests/baseline/harnesses/codex/manifest-overlay-parity.test.ts` (tracked as
  * `MANIFEST-READER-OVERLAY-01` in `docs/baseline/traceability.md`) against
  * the fixtures under `tests/fixtures/baseline/overlay-parity/`. Known,
  * deliberate divergences from strict byte parity are recorded in

package/dist/harnesses/codex/marketplace.js

@@ -0,0 +1,148 @@
+import { copyFile, cp, lstat, mkdir, readdir, rm, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
+import { assertNoFollowType, classifyPathNoFollow } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { readCodexAssessment } from "./compatibility.js";
+const MARKETPLACE_PATH = ".agents/plugins/marketplace.json";
+const PLUGIN_PATH = "plugins/superpowers";
+function inspectionError(root, cause) {
+    return new SafetyError("codex-marketplace", `cannot inspect owned Codex marketplace: ${root}`, { cause });
+}
+function validateMarketplace(value) {
+    const plugins = value.plugins;
+    if (!Array.isArray(plugins) || plugins.length !== 1) {
+        throw new Error("marketplace plugins");
+    }
+    const plugin = plugins[0];
+    if (plugin === null || typeof plugin !== "object" || Array.isArray(plugin)) {
+        throw new Error("marketplace plugin");
+    }
+    const source = plugin.source;
+    if (plugin.name !== "superpowers" ||
+        source === null ||
+        typeof source !== "object" ||
+        Array.isArray(source) ||
+        source.source !== "local" ||
+        source.path !== "./plugins/superpowers") {
+        throw new Error("marketplace source");
+    }
+}
+async function requireEntries(root, expected) {
+    const actual = await readdir(root);
+    if (actual.length !== expected.length ||
+        actual.some((entry) => !expected.includes(entry))) {
+        throw new Error("tree entries");
+    }
+}
+async function readMarketplace(root) {
+    try {
+        await assertNoFollowType(root, ["directory"]);
+        const before = await lstat(root);
+        await requireEntries(root, [".agents", "plugins", ARTIFACT_RECEIPT]);
+        await assertNoFollowType(join(root, ".agents"), ["directory"]);
+        await assertNoFollowType(join(root, "plugins"), ["directory"]);
+        await assertNoFollowType(join(root, ARTIFACT_RECEIPT), ["regular-file"]);
+        await requireEntries(join(root, ".agents"), ["plugins"]);
+        await requireEntries(join(root, ".agents", "plugins"), [
+            "marketplace.json",
+        ]);
+        await requireEntries(join(root, "plugins"), ["superpowers"]);
+        const pluginRoot = join(root, PLUGIN_PATH);
+        await assertNoFollowType(pluginRoot, ["directory"]);
+        validateMarketplace(await readArtifactObject(root, join(root, MARKETPLACE_PATH)));
+        const receipt = await readArtifactObject(root, join(root, ARTIFACT_RECEIPT));
+        if (receipt.schema !== 1 ||
+            receipt.manager !== "superpowers-manager" ||
+            receipt.harness !== "codex" ||
+            receipt.generation !== "codex-marketplace-v1" ||
+            typeof receipt.digest !== "string" ||
+            !ARTIFACT_DIGEST_RE.test(receipt.digest)) {
+            throw new Error("receipt");
+        }
+        const digest = await digestArtifactTree(root);
+        if (digest !== receipt.digest)
+            throw new Error("digest");
+        const artifact = await readCodexAssessment(pluginRoot);
+        const after = await lstat(root);
+        if (before.dev !== after.dev || before.ino !== after.ino) {
+            throw new Error("root changed");
+        }
+        return {
+            root,
+            dev: before.dev,
+            ino: before.ino,
+            digest,
+            artifact,
+        };
+    }
+    catch (cause) {
+        throw inspectionError(root, cause);
+    }
+}
+async function removeOwnedCandidate(root, identity) {
+    try {
+        await assertNoFollowType(root, ["directory"]);
+        const current = await lstat(root);
+        if (current.dev !== identity.dev || current.ino !== identity.ino)
+            return;
+        await rm(root, { recursive: true });
+    }
+    catch {
+        // A candidate that cannot still be proven as ours must remain untouched.
+    }
+}
+export async function stageCodexMarketplace(artifact, packageRoot, candidateRoot) {
+    let candidateIdentity = null;
+    try {
+        const assessed = await readCodexAssessment(artifact.root);
+        if (assessed.commit !== artifact.commit)
+            throw new Error("artifact commit");
+        const sourceDigest = await digestArtifactTree(artifact.root);
+        await assertNoFollowType(candidateRoot, ["missing"]);
+        await mkdir(candidateRoot, { mode: 0o700 });
+        const candidate = await lstat(candidateRoot);
+        candidateIdentity = { dev: candidate.dev, ino: candidate.ino };
+        await mkdir(join(candidateRoot, ".agents", "plugins"), { recursive: true });
+        await mkdir(join(candidateRoot, "plugins"), { recursive: true });
+        await copyFile(join(packageRoot, MARKETPLACE_PATH), join(candidateRoot, MARKETPLACE_PATH), 0);
+        await cp(artifact.root, join(candidateRoot, PLUGIN_PATH), {
+            dereference: false,
+            errorOnExist: true,
+            force: false,
+            recursive: true,
+            verbatimSymlinks: true,
+        });
+        const copied = await readCodexAssessment(join(candidateRoot, PLUGIN_PATH));
+        if (copied.commit !== artifact.commit ||
+            (await digestArtifactTree(copied.root)) !== sourceDigest) {
+            throw new Error("copied artifact");
+        }
+        validateMarketplace(await readArtifactObject(candidateRoot, join(candidateRoot, MARKETPLACE_PATH)));
+        const receipt = {
+            schema: 1,
+            manager: "superpowers-manager",
+            harness: "codex",
+            generation: "codex-marketplace-v1",
+            digest: await digestArtifactTree(candidateRoot),
+        };
+        await writeFile(join(candidateRoot, ARTIFACT_RECEIPT), JSON.stringify(receipt) + "\n", { flag: "wx" });
+        return await readMarketplace(candidateRoot);
+    }
+    catch (cause) {
+        if (candidateIdentity !== null) {
+            await removeOwnedCandidate(candidateRoot, candidateIdentity);
+        }
+        throw new SafetyError("codex-marketplace", `cannot stage owned Codex marketplace: ${candidateRoot}`, { cause });
+    }
+}
+export async function readCodexMarketplace(root) {
+    try {
+        if ((await classifyPathNoFollow(root)) === "missing")
+            return null;
+    }
+    catch (cause) {
+        throw inspectionError(root, cause);
+    }
+    return await readMarketplace(root);
+}

package/dist/harnesses/codex/paths.js

@@ -0,0 +1,97 @@
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { assertNoFollowType, canonicalizeProspectivePath, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+export function codexHome(env, cwd) {
+    const configured = env.CODEX_HOME;
+    if (configured !== undefined && configured.length > 0) {
+        return resolve(cwd, configured);
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0) {
+        throw new SafetyError("codex-paths", "cannot determine Codex state root without HOME");
+    }
+    return join(resolve(cwd, home), ".codex");
+}
+export function codexPaths(env, cwd) {
+    const root = codexHome(env, cwd);
+    const managerRoot = join(root, "superpowers-manager");
+    const marketplaceRoot = join(managerRoot, "marketplace");
+    return {
+        codexHome: root,
+        managerRoot,
+        preparedRoot: join(managerRoot, "prepared"),
+        marketplaceRoot,
+        publishedPluginRoot: join(marketplaceRoot, "plugins", "superpowers"),
+        recoveryRoot: join(managerRoot, "recovery"),
+    };
+}
+function overlaps(a, b) {
+    const inside = (root, leaf) => {
+        const suffix = relative(root, leaf);
+        return (suffix === "" ||
+            (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(`..${sep}`)));
+    };
+    return inside(a, b) || inside(b, a);
+}
+function separationError() {
+    return new SafetyError("codex-paths", "preparation overlaps Codex published or recovery storage", { details: { kind: "overlap" } });
+}
+async function inspectRoot(path, root) {
+    try {
+        await assertNoFollowType(path, ["directory", "missing"]);
+        return await canonicalizeProspectivePath(path);
+    }
+    catch (cause) {
+        throw new SafetyError("codex-paths", `cannot inspect ${root} root: ${path}`, { cause, details: { kind: "inspection", root, path } });
+    }
+}
+export function codexPathFailureDetails(cause) {
+    if (!(cause instanceof SafetyError) || cause.module !== "codex-paths") {
+        return null;
+    }
+    const details = cause.details;
+    if (details === null || typeof details !== "object" || !("kind" in details)) {
+        return null;
+    }
+    if (details.kind === "overlap")
+        return { kind: "overlap" };
+    if (details.kind !== "inspection" ||
+        !("root" in details) ||
+        !("path" in details) ||
+        (details.root !== "preparation" &&
+            details.root !== "marketplace" &&
+            details.root !== "recovery") ||
+        typeof details.path !== "string") {
+        return null;
+    }
+    return { kind: "inspection", root: details.root, path: details.path };
+}
+export async function assertCodexPreparationSeparate(preparedRoot, paths) {
+    const recovery = await inspectRoot(paths.recoveryRoot, "recovery");
+    const marketplace = await inspectRoot(paths.marketplaceRoot, "marketplace");
+    let prepared;
+    try {
+        prepared = await inspectRoot(preparedRoot, "preparation");
+    }
+    catch (cause) {
+        const failure = codexPathFailureDetails(cause);
+        if (failure?.kind !== "inspection" || failure.root !== "preparation") {
+            throw cause;
+        }
+        try {
+            const canonical = await canonicalizeProspectivePath(preparedRoot);
+            if (overlaps(canonical, marketplace) || overlaps(canonical, recovery)) {
+                throw separationError();
+            }
+        }
+        catch (resolutionCause) {
+            if (codexPathFailureDetails(resolutionCause)?.kind === "overlap") {
+                throw resolutionCause;
+            }
+        }
+        throw cause;
+    }
+    if (overlaps(prepared, marketplace) || overlaps(prepared, recovery)) {
+        throw separationError();
+    }
+}

package/dist/{codex-prepare.js → harnesses/codex/prepare.js}

@@ -1,14 +1,16 @@
 import { cp, mkdir, rm, stat } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
-import { failureResult, successResult, } from "./adapter-result.js";
+import { failureResult, successResult, } from "../../adapter-result.js";
 import { codexBuild } from "./adapter.js";
-import { ARTIFACT_RECEIPT } from "./artifact-tree.js";
-import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./codex-compatibility.js";
+import { ARTIFACT_RECEIPT } from "../../artifact-tree.js";
+import { assessCodexCompatibility, readCodexAssessment, writeCodexAssessment, } from "./compatibility.js";
 import { readManifest } from "./hooks.js";
-import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "./provenance.js";
-import { classifyPathNoFollow } from "./safe-path.js";
-import { SafetyError } from "./safety-error.js";
-import { manifestVersionForRef } from "./upstream-version.js";
+import { readGeneratedCommitLenient, readStrictProvenanceField, writeProvenance, } from "../../provenance.js";
+import { classifyPathNoFollow } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+import { manifestVersionForRef } from "../../upstream-version.js";
+import { assertCodexPreparationSeparate, codexPathFailureDetails, codexPaths, } from "./paths.js";
+import { readCodexRecovery } from "./recovery.js";
 // Order is inherited from the original prepare command; the first miss wins.
 const REQUIRED_UPSTREAM = [
     { path: "skills", label: "skills/" },
@@ -75,7 +77,7 @@ async function copyPathIfPresent(source, destination) {
     await owned(`cannot clear candidate path: ${destination}`, () => rm(destination, { recursive: true, force: true }));
     await owned(`cannot copy upstream path into candidate: ${source}`, () => cp(source, destination, { recursive: true, verbatimSymlinks: true }));
 }
-export function resolveFromCwd(value, cwd) {
+function resolveFromCwd(value, cwd) {
     return isAbsolute(value) ? value : resolve(cwd, value);
 }
 function manifestTemplate(ctx) {
@@ -86,11 +88,41 @@ function manifestTemplate(ctx) {
 export function codexPreparationLocation(ctx) {
     const env = ctx.env ?? {};
     return {
-        destinationRoot: resolveFromCwd(env.SUPERPOWERS_PLUGIN_ROOT || join(ctx.root, "plugins", "superpowers"), process.cwd()),
+        destinationRoot: env.SUPERPOWERS_PLUGIN_ROOT !== undefined &&
+            env.SUPERPOWERS_PLUGIN_ROOT.length > 0
+            ? resolveFromCwd(env.SUPERPOWERS_PLUGIN_ROOT, process.cwd())
+            : codexPaths(env, process.cwd()).preparedRoot,
         stagingLeaf: "superpowers",
     };
 }
 export async function validateCodexPreparationBeforeFetch(ctx) {
+    const paths = codexPaths(ctx.env ?? {}, process.cwd());
+    const preparedRoot = codexPreparationLocation(ctx).destinationRoot;
+    try {
+        await assertCodexPreparationSeparate(preparedRoot, paths);
+    }
+    catch (cause) {
+        const failure = codexPathFailureDetails(cause);
+        if (failure?.kind === "inspection") {
+            if (failure.root === "recovery") {
+                return failureResult("prepare", "recovery-required", `cannot inspect Codex recovery state at ${paths.recoveryRoot}`, [], []);
+            }
+            return failureResult("prepare", "prepare-failed", failure.root === "marketplace"
+                ? `cannot inspect Codex marketplace storage at ${paths.marketplaceRoot}`
+                : `cannot inspect Codex preparation root at ${preparedRoot}`, [], []);
+        }
+        return failureResult("prepare", failure?.kind === "overlap" ? "preparation-overlap" : "prepare-failed", failure?.kind === "overlap"
+            ? `Codex preparation overlaps Codex published or recovery storage: ${preparedRoot}`
+            : `cannot validate Codex preparation storage separation at ${preparedRoot}`, [], []);
+    }
+    try {
+        if ((await readCodexRecovery(paths)) !== null) {
+            return failureResult("prepare", "recovery-required", `Codex recovery is required before preparation; preserve material at ${paths.recoveryRoot}`, [], []);
+        }
+    }
+    catch {
+        return failureResult("prepare", "recovery-required", `cannot inspect Codex recovery state at ${paths.recoveryRoot}`, [], []);
+    }
     const template = manifestTemplate(ctx);
     if (!(await regularFileExists(template))) {
         return failureResult("prepare", "missing-template", `missing fallback manifest template: ${template}`, [], []);

package/dist/{codex-presentation.js → harnesses/codex/presentation.js}

@@ -1,8 +1,8 @@
-import { normalizeCodexInstall, normalizeCodexInstalled, } from "./codex-harness.js";
-import { displaySource } from "./selection.js";
+import { normalizeCodexInstall, normalizeCodexInstalled } from "./harness.js";
+import { displaySource } from "../../selection.js";
 // One ordered table drives both formats, preserving the public human and
 // porcelain field order exposed through the harness presentation.
-export function fields(f) {
+function fields(f) {
     return [
         { key: "harness", label: "harness", value: f.harness },
         { key: "requested_ref", label: "requested ref", value: f.requestedRef },
@@ -116,7 +116,7 @@ export function codexInstallReceipt(missingHint, mismatchHint) {
         mismatchVerificationOutput: verificationOutput("mismatch", mismatchHint),
     };
 }
-// Compatibility export target for src/lifecycle.ts. Delegate to the production
+// Compatibility export target for src/harnesses/codex/lifecycle.ts. Delegate to the production
 // normalizers and renderer so the retained verdict cannot drift from commands.
 export function verifyInstalledFingerprint(desiredCommit, installResult, inspectResult) {
     const receipt = normalizeCodexInstall(installResult);
@@ -251,17 +251,18 @@ export const codexPresentation = {
         if (inspection.outcome.result.kind === "current") {
             return { stdout: [...stdout, "manager updated"], stderr: [] };
         }
+        const missing = inspection.outcome.result.kind === "absent" || observed.length === 0;
         if (receipt.status !== 0 || !receipt.outcome.ok) {
             return {
                 stdout,
                 stderr: [
-                    inspection.outcome.result.kind === "absent"
+                    missing
                         ? "error: installed manager fingerprint is not detectable after install."
                         : "error: installed manager fingerprint does not match the prepared plugin after install.",
                 ],
             };
         }
-        const output = inspection.outcome.result.kind === "absent"
+        const output = missing
             ? receipt.outcome.result.missingVerificationOutput
             : receipt.outcome.result.mismatchVerificationOutput;
         return { stdout, stderr: output.stderr };