superpowers-manager 0.9.1 → 0.10.1

package/dist/commands/uninstall.js

@@ -1,91 +1,76 @@
 import { tmpdir } from "node:os";
 import { oneLine } from "../cli-arguments.js";
 import { withWorkspaceReporting, } from "../workspace.js";
-import { GatherFailure, invoke, writeOutput } from "./adapter-call.js";
+import { invoke, writeOutput } from "./adapter-call.js";
 import { runWithMutation } from "./mutation.js";
 import { replayOutcome } from "./probe.js";
-// Collect outcomes without writing so output failures cannot be classified as
-// inspection failures. Replay collected outcomes after gathering completes.
-async function gatherUninstall(ctx) {
+// Collect outcomes into the caller's array without writing, so output failures
+// cannot be classified as inspection failures. The caller replays them after
+// gathering, including when gathering throws.
+async function gatherUninstall(ctx, outcomes) {
     const parent = ctx.env.TMPDIR ?? tmpdir();
-    // Kept outside the workspace callback so a workspace failure preserves every
-    // outcome collected before it.
-    const outcomes = [];
-    try {
-        return await withWorkspaceReporting(parent, "superpowers-manager.uninstall.", async (workspace) => {
-            const env = { ...ctx.env, TMPDIR: workspace };
-            const failed = (message) => ({
-                status: 1,
-                outcomes,
-                message,
-                output: null,
-            });
-            const adapterContext = { root: ctx.root, env };
-            // Stage 1: inspect ownership, before removal.
-            const beforeFailure = ctx.adapter.presentation.callFailure("remove-ownership", adapterContext);
-            const before = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), beforeFailure, outcomes);
-            if (!before.ok)
-                return failed(before.message);
-            // Stage 2: remove, passing the private input through untouched.
-            const removalInput = before.result.outcome.result.removalInput;
-            const removeFailure = ctx.adapter.presentation.callFailure("remove", adapterContext, removalInput);
-            const removed = await invoke(() => ctx.adapter.remove(removalInput, adapterContext), removeFailure, outcomes);
-            if (!removed.ok)
-                return failed(removed.message);
-            // Stage 3: inspect ownership again. Everything below reads this
-            // post-removal state, not the inspection before removal.
-            const afterFailure = ctx.adapter.presentation.callFailure("post-remove", adapterContext);
-            const after = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), afterFailure, outcomes);
-            if (!after.ok)
-                return failed(after.message);
-            const ownership = after.result.outcome.result;
-            if (ownership.removalVerification.kind === "blocked") {
-                return {
-                    status: 1,
-                    outcomes,
-                    message: null,
-                    output: ownership.removalVerification.output,
-                };
-            }
+    return await withWorkspaceReporting(parent, "superpowers-manager.uninstall.", async (workspace) => {
+        const env = { ...ctx.env, TMPDIR: workspace };
+        const failed = (message) => ({
+            status: 1,
+            message,
+            output: null,
+        });
+        const adapterContext = { root: ctx.root, env };
+        // Stage 1: inspect ownership, before removal.
+        const beforeFailure = ctx.adapter.presentation.callFailure("remove-ownership", adapterContext);
+        const before = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), beforeFailure, outcomes);
+        if (!before.ok)
+            return failed(before.message);
+        // Stage 2: remove, passing the private input through untouched.
+        const removalInput = before.result.outcome.result.removalInput;
+        const removeFailure = ctx.adapter.presentation.callFailure("remove", adapterContext, removalInput);
+        const removed = await invoke(() => ctx.adapter.remove(removalInput, adapterContext), removeFailure, outcomes);
+        if (!removed.ok)
+            return failed(removed.message);
+        // Stage 3: inspect ownership again. Everything below reads this
+        // post-removal state, not the inspection before removal.
+        const afterFailure = ctx.adapter.presentation.callFailure("post-remove", adapterContext);
+        const after = await invoke(() => ctx.adapter.inspectOwnership(adapterContext), afterFailure, outcomes);
+        if (!after.ok)
+            return failed(after.message);
+        const ownership = after.result.outcome.result;
+        if (ownership.removalVerification.kind === "blocked") {
             return {
-                status: 0,
-                outcomes,
-                output: ctx.adapter.presentation.renderRemovalCompletion(ownership, removalInput),
+                status: 1,
+                message: null,
+                output: ownership.removalVerification.output,
             };
-        });
-    }
-    catch (cause) {
-        // Reachable only for mkdtemp failure, with nothing collected yet: the
-        // callback never throws (every ctx.adapter throw is caught inside
-        // invoke()), and a post-success cleanup failure comes back as
-        // cleanupWarning. Wrapping with `outcomes` anyway keeps the class total
-        // over its declared contract rather than assuming the callback's purity at
-        // the throw site.
-        throw new GatherFailure("uninstall gather failed", cause, outcomes);
-    }
+        }
+        return {
+            status: 0,
+            output: ctx.adapter.presentation.renderRemovalCompletion(ownership, removalInput),
+        };
+    });
 }
 export async function runUninstall(argv, ctx) {
     // argv is ignored: scripts/uninstall never reads "$@".
     return await runWithMutation("uninstall", ctx, async (scoped) => performUninstall(scoped));
 }
 async function performUninstall(ctx) {
+    // Owned here, not in gatherUninstall, so a gather throw still replays every
+    // outcome collected before it.
+    const outcomes = [];
     let run;
     try {
-        run = await gatherUninstall(ctx);
+        run = await gatherUninstall(ctx, outcomes);
     }
     catch (cause) {
         // Replay collected outcomes before reporting a gather failure. A
         // post-success cleanup failure arrives as cleanupWarning, not here.
-        const outcomes = cause instanceof GatherFailure ? cause.outcomes : [];
-        for (const outcome of outcomes)
-            replayOutcome(outcome, ctx);
-        const inner = cause instanceof GatherFailure ? cause.inner : cause;
-        ctx.stderr.write(`error: ${oneLine(inner)}\n`);
+        for (const each of outcomes)
+            replayOutcome(each, ctx);
+        ctx.stderr.write(`error: ${oneLine(cause)}\n`);
         return 1;
     }
     const { value: outcome, cleanupWarning } = run;
     // Replay before reporting a command-level result on either path.
-    for (const each of outcome.outcomes)
+    for (const each of outcomes)
         replayOutcome(each, ctx);
     let status;
     if (outcome.status === 1) {

package/dist/harnesses/hermes/harness.js

@@ -0,0 +1,36 @@
+import { displayPath } from "../../validator.js";
+import { installHermes, removeHermes } from "./install.js";
+import { hermesPaths } from "./paths.js";
+import { hermesPreparationLocation, inspectHermesPrepared, prepareHermesCandidate, readHermesPrepared, validateHermesPreparationBeforeFetch, } from "./prepare.js";
+import { hermesPresentation } from "./presentation.js";
+import { inspectHermesControl, inspectHermesInstalled, inspectHermesOwnership, } from "./state.js";
+function requirements(command, env) {
+    if (command !== "install" && command !== "update" && command !== "uninstall")
+        return [];
+    const executable = env.SUPERPOWERS_HERMES || "hermes";
+    return [
+        {
+            name: "hermes",
+            executable,
+            lookup: "explicit-path-or-path",
+            missingMessage: `required command not found: ${displayPath(executable)} — install Hermes Agent or set SUPERPOWERS_HERMES`,
+        },
+    ];
+}
+export const hermesHarness = {
+    preparationLocation: hermesPreparationLocation,
+    mutationRoots: async (ctx) => [
+        hermesPaths(ctx.env ?? {}, process.cwd()).hermesHome,
+    ],
+    validatePreparationBeforeFetch: validateHermesPreparationBeforeFetch,
+    prepareCandidate: prepareHermesCandidate,
+    inspectPrepared: inspectHermesPrepared,
+    readPrepared: readHermesPrepared,
+    inspectOwnership: inspectHermesOwnership,
+    inspectUpdateControl: inspectHermesControl,
+    inspectInstalled: inspectHermesInstalled,
+    install: installHermes,
+    remove: removeHermes,
+    requirements,
+    presentation: hermesPresentation,
+};

package/dist/harnesses/hermes/install.js

@@ -0,0 +1,235 @@
+import { cp, mkdir, mkdtemp, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { failureResult, successResult, } from "../../adapter-result.js";
+import { assertNoFollowType } from "../../safe-path.js";
+import { observeSnapshot } from "../../snapshot-package.js";
+import { displayPath } from "../../validator.js";
+import { runHermes } from "./native.js";
+import { projectPluginsEnabled, readHermesStatus } from "./observe.js";
+import { assertHermesStorageSafe, hermesPaths, } from "./paths.js";
+import { readHermesPackageAssessment, readHermesReceipt } from "./prepare.js";
+import { leftoverHermesPublication, observeHermesOwnership, otherSuperpowersManifests, } from "./state.js";
+const DEFAULTS = { run: runHermes };
+// Only hand-written diagnostics and bounded native exit statuses enter this type.
+class HermesStep extends Error {
+}
+async function native(run, args, ctx) {
+    const result = await run(args, ctx);
+    if (!result.outcome.ok || result.status !== 0) {
+        const reported = result.outcome.ok
+            ? undefined
+            : /^Hermes command exited with status ([0-9]{1,3})$/.exec(result.outcome.error.message)?.[1];
+        const status = reported !== undefined && Number(reported) <= 255
+            ? ` (exit status ${reported})`
+            : "";
+        throw new HermesStep(`hermes ${args.join(" ")} did not complete${status}`);
+    }
+}
+async function checkPublicationState(paths) {
+    const leftovers = await leftoverHermesPublication(paths);
+    if (leftovers.length > 0)
+        throw new HermesStep(`Hermes recovery required; inspect leftover publication material at ${displayPath(leftovers[0])}`);
+    const conflicts = await otherSuperpowersManifests(paths);
+    if (conflicts.length > 0)
+        throw new HermesStep(`Hermes discovers another plugin named superpowers at ${displayPath(conflicts[0])}`);
+}
+async function requireSnapshot(root, digest) {
+    const snapshot = await observeSnapshot(root, readHermesReceipt);
+    if (snapshot.kind !== "owned" || snapshot.digest !== digest)
+        throw new HermesStep("the Hermes snapshot changed during publication");
+}
+async function verifyRemoved(paths, ctx) {
+    if ((await observeHermesOwnership(paths)).kind !== "absent" ||
+        (await readHermesStatus(paths, ctx.env ?? {})) !== "not enabled")
+        throw new HermesStep("Hermes still lists Superpowers or its plugin directory is still present after removal");
+}
+async function rollback(publication, identity, previouslyEnabled, paths, ctx, run) {
+    await assertHermesStorageSafe(paths);
+    await assertNoFollowType(publication.container, ["directory"]);
+    const status = await readHermesStatus(paths, ctx.env ?? {});
+    if (publication.priorDigest !== undefined) {
+        if (publication.movedBackup) {
+            await requireSnapshot(publication.backup, publication.priorDigest);
+            if (publication.published) {
+                await requireSnapshot(paths.pluginRoot, identity);
+                await assertNoFollowType(publication.stage, ["missing"]);
+                await rename(paths.pluginRoot, publication.stage);
+                publication.published = false;
+            }
+            await assertNoFollowType(paths.pluginRoot, ["missing"]);
+            await rename(publication.backup, paths.pluginRoot);
+            publication.movedBackup = false;
+        }
+        await requireSnapshot(paths.pluginRoot, publication.priorDigest);
+        if (!previouslyEnabled && status === "enabled") {
+            if ((await otherSuperpowersManifests(paths)).length > 0)
+                throw new HermesStep("Hermes discovers another plugin named superpowers during rollback");
+            await native(run, ["plugins", "disable", "superpowers"], ctx);
+            if ((await readHermesStatus(paths, ctx.env ?? {})) !== "disabled")
+                throw new HermesStep("Hermes still enables Superpowers after rollback");
+        }
+    }
+    else if (publication.published) {
+        await requireSnapshot(paths.pluginRoot, identity);
+        if ((await otherSuperpowersManifests(paths)).length > 0)
+            throw new HermesStep("Hermes discovers another plugin named superpowers during rollback");
+        await native(run, ["plugins", "remove", "superpowers"], ctx);
+        await verifyRemoved(paths, ctx);
+        publication.published = false;
+    }
+    await rm(publication.container, { recursive: true, force: false });
+}
+async function settle(operation, message, action) {
+    try {
+        await action();
+        return successResult(operation, null, []);
+    }
+    catch {
+        return failureResult(operation, "settlement-failed", message, [], []);
+    }
+}
+export async function installHermes(artifact, ctx, deps = DEFAULTS) {
+    const operation = "install-hermes";
+    const paths = hermesPaths(ctx.env ?? {}, process.cwd());
+    let publication;
+    let previouslyEnabled = false;
+    try {
+        const ownership = await observeHermesOwnership(paths);
+        if (ownership.kind === "foreign")
+            throw new HermesStep("refusing to replace a foreign Hermes plugin directory; remove it manually");
+        await checkPublicationState(paths);
+        if (projectPluginsEnabled(ctx.env ?? {}))
+            throw new HermesStep("HERMES_ENABLE_PROJECT_PLUGINS is set; unset it before installing Superpowers");
+        if (artifact.root !== paths.preparedRoot)
+            throw new HermesStep("unexpected Hermes prepared root");
+        const assessment = await readHermesPackageAssessment(artifact.root);
+        if (assessment.receipt.digest !== artifact.identity ||
+            assessment.receipt.commit !== artifact.commit ||
+            assessment.compatibility.kind !== "supported")
+            throw new HermesStep("the Hermes prepared artifact changed before activation");
+        previouslyEnabled =
+            (await readHermesStatus(paths, ctx.env ?? {})) === "enabled";
+        await mkdir(paths.pluginsRoot, { recursive: true });
+        await assertHermesStorageSafe(paths);
+        const container = await mkdtemp(join(paths.managerRoot, "publish."));
+        const pending = {
+            container,
+            stage: join(container, "stage"),
+            backup: join(container, "backup"),
+            priorDigest: ownership.kind === "owned" ? ownership.digest : undefined,
+            movedBackup: false,
+            published: false,
+        };
+        publication = pending;
+        await cp(artifact.root, pending.stage, {
+            recursive: true,
+            verbatimSymlinks: true,
+            force: false,
+            errorOnExist: true,
+        });
+        const staged = await readHermesPackageAssessment(pending.stage);
+        if (staged.receipt.digest !== artifact.identity ||
+            staged.receipt.commit !== artifact.commit ||
+            staged.compatibility.kind !== "supported")
+            throw new HermesStep("the staged Hermes artifact changed");
+        // Keep backups outside plugins so Hermes discovery sees only the live copy.
+        if (ownership.kind === "owned") {
+            await requireSnapshot(paths.pluginRoot, ownership.digest);
+            await rename(paths.pluginRoot, pending.backup);
+            pending.movedBackup = true;
+        }
+        else
+            await assertNoFollowType(paths.pluginRoot, ["missing"]);
+        await rename(pending.stage, paths.pluginRoot);
+        pending.published = true;
+        if (!previouslyEnabled)
+            await native(deps.run, ["plugins", "enable", "superpowers"], ctx);
+        let settled = false;
+        return successResult(operation, {
+            missingVerificationOutput: {
+                stdout: [],
+                stderr: [
+                    "error: the Manager Hermes plugin is absent after activation",
+                ],
+            },
+            mismatchVerificationOutput: {
+                stdout: [],
+                stderr: [
+                    "error: the installed Hermes plugin does not match the prepared artifact; run `hermes plugins list` to inspect load errors",
+                ],
+            },
+            transaction: {
+                finalize: () => settle(operation, `Hermes activation succeeded but backup cleanup failed at ${displayPath(container)}`, async () => {
+                    if (settled)
+                        return;
+                    await assertHermesStorageSafe(paths);
+                    await assertNoFollowType(container, ["directory"]);
+                    await requireSnapshot(paths.pluginRoot, artifact.identity);
+                    if (pending.movedBackup)
+                        await requireSnapshot(pending.backup, pending.priorDigest);
+                    await rm(container, { recursive: true, force: false });
+                    settled = true;
+                }),
+                rollback: () => settle(operation, `Hermes rollback did not complete; the previous state may not be restored — inspect ${displayPath(container)}`, async () => {
+                    if (settled)
+                        return;
+                    await rollback(pending, artifact.identity, previouslyEnabled, paths, ctx, deps.run);
+                    settled = true;
+                }),
+            },
+        }, []);
+    }
+    catch (cause) {
+        const message = cause instanceof HermesStep
+            ? cause.message
+            : "cannot activate the Manager-owned Hermes installation";
+        let restored = true;
+        if (publication !== undefined) {
+            try {
+                if (publication.movedBackup || publication.published)
+                    await rollback(publication, artifact.identity, previouslyEnabled, paths, ctx, deps.run);
+                else {
+                    await assertNoFollowType(publication.container, ["directory"]);
+                    await rm(publication.container, { recursive: true, force: false });
+                }
+            }
+            catch {
+                restored = false;
+            }
+        }
+        return failureResult(operation, "install-failed", restored
+            ? message
+            : `${message}; the previous Hermes state may not be restored — inspect ${displayPath(publication.container)}`, [], []);
+    }
+}
+export async function removeHermes(input, ctx, deps = DEFAULTS) {
+    const operation = "remove-hermes";
+    const paths = hermesPaths(ctx.env ?? {}, process.cwd());
+    try {
+        const ownership = await observeHermesOwnership(paths);
+        if (input.ownership === "foreign" || ownership.kind === "foreign")
+            throw new HermesStep("refusing to remove a foreign Hermes plugin directory; remove it manually");
+        await checkPublicationState(paths);
+        const listed = (await readHermesStatus(paths, ctx.env ?? {})) !== "not enabled";
+        if (input.ownership !== ownership.kind || input.listed !== listed)
+            return failureResult(operation, "stale-ownership", "Hermes plugin state changed before removal; inspect it and retry", [], []);
+        if (ownership.kind === "absent") {
+            if (listed)
+                throw new HermesStep("refusing to remove an unverified Hermes activation entry without an owned plugin directory");
+            return successResult(operation, null, []);
+        }
+        await native(deps.run, ["plugins", "remove", "superpowers"], ctx);
+        try {
+            await verifyRemoved(paths, ctx);
+        }
+        catch {
+            return failureResult(operation, "removal-unverified", "Hermes still lists Superpowers or its plugin directory is still present after removal", [], []);
+        }
+        return successResult(operation, null, []);
+    }
+    catch (cause) {
+        return failureResult(operation, "remove-failed", cause instanceof HermesStep
+            ? cause.message
+            : "cannot remove the Manager-owned Hermes plugin", [], []);
+    }
+}

package/dist/harnesses/hermes/native.js

@@ -0,0 +1,40 @@
+import { basename, dirname } from "node:path";
+import { failureResult, } from "../../adapter-result.js";
+import { runIsolatedNative, } from "../../harness-command-result.js";
+import { BOUNDED_EXECUTABLE, runValidator } from "../../validator.js";
+import { hermesPaths } from "./paths.js";
+export async function runHermes(args, ctx, execute = runValidator) {
+    const invalidHome = () => failureResult("hermes-command", "invalid-home", "cannot resolve HERMES_HOME for Hermes command", [], []);
+    let home;
+    try {
+        home = hermesPaths(ctx.env ?? {}, process.cwd()).hermesHome;
+    }
+    catch {
+        return invalidHome();
+    }
+    let homeChanged = false;
+    const result = await runIsolatedNative("Hermes", (ctx.env ?? {}).SUPERPOWERS_HERMES || "hermes", ctx, async (executable, workspace, env, invocationCwd) => {
+        const childEnv = {
+            ...process.env,
+            ...env,
+            HERMES_HOME: home,
+            TMPDIR: workspace,
+        };
+        try {
+            if (hermesPaths(childEnv, invocationCwd).hermesHome !== home)
+                throw new Error("cannot resolve HERMES_HOME: child home changed");
+        }
+        catch {
+            homeChanged = true;
+            throw new Error("cannot resolve HERMES_HOME for Hermes command");
+        }
+        return await execute([
+            executable,
+            ...(basename(dirname(home)) === "profiles"
+                ? []
+                : ["--profile", "default"]),
+            ...args,
+        ], BOUNDED_EXECUTABLE, childEnv, workspace, invocationCwd);
+    });
+    return homeChanged ? invalidHome() : result;
+}

package/dist/harnesses/hermes/observe.js

@@ -0,0 +1,178 @@
+import { readdir, realpath, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { parseDocument } from "yaml";
+import { readArtifactFile } from "../../artifact-tree.js";
+import { compareByCodePoint } from "../../python-text.js";
+import { assertNoFollowType, classifyPathNoFollow, isAbsenceError, } from "../../safe-path.js";
+import { SafetyError } from "../../safety-error.js";
+const DECODER = new TextDecoder("utf-8", { fatal: true });
+function mapping(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        Object.getPrototypeOf(value) === Object.prototype);
+}
+function parseYaml(text, uniqueKeys = true) {
+    const document = parseDocument(text, { uniqueKeys, merge: true });
+    if (document.errors.length > 0 ||
+        document.warnings.some((warning) => warning.code === "TAG_RESOLVE_FAILED"))
+        throw new Error("YAML document");
+    return document.toJS();
+}
+async function configuration(root) {
+    await assertNoFollowType(root, ["directory", "missing"]);
+    const path = join(root, "config.yaml");
+    if ((await classifyPathNoFollow(path)) === "missing")
+        return null;
+    const value = parseYaml(DECODER.decode(await readArtifactFile(root, path))) ?? {};
+    if (!mapping(value))
+        throw new Error("configuration mapping");
+    return value;
+}
+async function managedDirectory(env, systemManagedDir) {
+    const configured = env.HERMES_MANAGED_DIR?.trim();
+    for (const path of configured
+        ? [configured, systemManagedDir]
+        : [systemManagedDir]) {
+        const kind = await classifyPathNoFollow(path);
+        if (kind === "directory")
+            return path;
+        if (kind === "symlink")
+            throw new Error("managed directory symlink");
+    }
+    return null;
+}
+function activationList(value) {
+    if (!Array.isArray(value))
+        return [];
+    if (value.some((item) => (item !== null && typeof item === "object") ||
+        (typeof item === "string" && item.includes("${"))))
+        throw new SafetyError("hermes-observe", "cannot determine Hermes plugin activation");
+    return value;
+}
+export async function readHermesStatus(paths, env, systemManagedDir = "/etc/hermes") {
+    let user;
+    try {
+        user = await configuration(paths.hermesHome);
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot inspect Hermes configuration", { cause });
+    }
+    try {
+        const directory = await managedDirectory(env, systemManagedDir);
+        const managed = directory === null ? null : await configuration(directory);
+        const plugins = managed?.plugins;
+        if (plugins !== undefined && plugins !== null && !mapping(plugins))
+            throw new Error("managed plugins shape");
+        if (mapping(plugins) &&
+            (Object.hasOwn(plugins, "enabled") || Object.hasOwn(plugins, "disabled")))
+            throw new Error("managed activation");
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot determine Hermes plugin activation", { cause });
+    }
+    const plugins = mapping(user?.plugins) ? user.plugins : {};
+    const enabled = activationList(plugins.enabled);
+    const disabled = activationList(plugins.disabled);
+    return disabled.includes("superpowers")
+        ? "disabled"
+        : enabled.includes("superpowers")
+            ? "enabled"
+            : "not enabled";
+}
+const FOREIGN_MANIFEST_DIRECTORIES = new Set([
+    ".claude-plugin",
+    ".codex-plugin",
+    ".cursor-plugin",
+    ".devin-plugin",
+    ".kimi-plugin",
+]);
+export async function findSuperpowersManifests(paths) {
+    try {
+        if ((await classifyPathNoFollow(paths.pluginsRoot)) === "missing")
+            return [];
+        const found = [];
+        async function scan(root, physicalRoot, depth) {
+            await assertNoFollowType(physicalRoot, ["directory"]);
+            for (const name of (await readdir(physicalRoot)).sort(compareByCodePoint)) {
+                if ((name.startsWith("__") && name.endsWith("__")) ||
+                    FOREIGN_MANIFEST_DIRECTORIES.has(name))
+                    continue;
+                const child = join(root, name);
+                const physicalChild = join(physicalRoot, name);
+                const kind = await classifyPathNoFollow(physicalChild);
+                if (kind === "symlink") {
+                    if (child === paths.pluginRoot)
+                        throw new Error("owned plugin directory symlink");
+                    try {
+                        if (!(await stat(physicalChild)).isDirectory())
+                            continue;
+                    }
+                    catch (cause) {
+                        if (isAbsenceError(cause))
+                            continue;
+                        throw cause;
+                    }
+                }
+                else if (kind !== "directory")
+                    continue;
+                const directory = await realpath(physicalChild);
+                let manifest = null;
+                for (const file of ["plugin.yaml", "plugin.yml", "plugin.json"]) {
+                    if ((await classifyPathNoFollow(join(directory, file))) !== "missing") {
+                        manifest = file;
+                        break;
+                    }
+                }
+                if (manifest === null) {
+                    if (depth === 0)
+                        await scan(child, directory, 1);
+                    continue;
+                }
+                const bytes = await readArtifactFile(directory, join(directory, manifest), 64 * 1024);
+                let value;
+                try {
+                    const text = DECODER.decode(bytes);
+                    if (manifest === "plugin.json")
+                        value = JSON.parse(text);
+                    else {
+                        const parsed = parseYaml(text, false);
+                        value =
+                            parsed === null ||
+                                parsed === undefined ||
+                                parsed === false ||
+                                parsed === 0 ||
+                                parsed === "" ||
+                                (Array.isArray(parsed) && parsed.length === 0) ||
+                                (parsed instanceof Set && parsed.size === 0) ||
+                                (parsed instanceof Map && parsed.size === 0) ||
+                                (Buffer.isBuffer(parsed) && parsed.length === 0)
+                                ? {}
+                                : parsed;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (!mapping(value))
+                    continue;
+                const pluginName = Object.hasOwn(value, "name")
+                    ? value.name
+                    : manifest === "plugin.json"
+                        ? undefined
+                        : basename(child);
+                if (pluginName === "superpowers")
+                    found.push(child);
+            }
+        }
+        await scan(paths.pluginsRoot, paths.pluginsRoot, 0);
+        return found.sort(compareByCodePoint);
+    }
+    catch (cause) {
+        throw new SafetyError("hermes-observe", "cannot inspect Hermes plugins", {
+            cause,
+        });
+    }
+}
+export function projectPluginsEnabled(env) {
+    return ["1", "true", "yes", "on"].includes((env.HERMES_ENABLE_PROJECT_PLUGINS ?? "").trim().toLowerCase());
+}