superpowers-manager 0.9.1 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # Superpowers Manager
 
-Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex, the Pi coding agent, OpenCode, and Claude Code. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
+Install [`obra/superpowers`](https://github.com/obra/superpowers) directly from upstream for Codex, the Pi coding agent, OpenCode, Claude Code, and Hermes Agent. Stay on a known-good release or commit, try a branch, and upgrade when you choose—without waiting for a marketplace copy to catch up.
 
 > Unofficial community integration. Not affiliated with the `obra/superpowers` maintainers.
 
@@ -21,7 +21,7 @@ npx superpowers-manager pin v6.1.1
 npx superpowers-manager install --harness codex
 ```
 
-Use `--harness pi` for Pi, `--harness opencode` for OpenCode, or `--harness claude-code` for Claude Code. The pin is shared by all harnesses, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
+Use `--harness pi` for Pi, `--harness opencode` for OpenCode, `--harness claude-code` for Claude Code, or `--harness hermes` for Hermes Agent. The pin is shared by all harnesses, but each installation changes only when you run its `install` or `update` command. A saved pin keeps subsequent installs and updates on that version unless you change or override the selection.
 
 To try a branch, replace `feature/foo` with an existing upstream branch:
 
@@ -42,7 +42,7 @@ See [version selection](https://github.com/j7an/superpowers-manager/blob/main/do
 
 ## Start with your agent
 
-The four harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
+The five harnesses share upstream selection, while each has independent prepared and installed state. Omitting `--harness` selects Codex.
 
 ### Codex
 
@@ -97,6 +97,18 @@ Restart Claude Code or run `/reload-plugins` after an install, activating update
 or removal. See the [Claude Code reference](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md)
 for conflicts, hooks, and recovery.
 
+### Hermes Agent
+
+```sh
+npx superpowers-manager install --harness hermes
+npx superpowers-manager probe --harness hermes
+npx superpowers-manager update --harness hermes
+```
+
+Restart Hermes sessions after an install, activating update, or removal. See
+the [Hermes Agent reference](https://github.com/j7an/superpowers-manager/blob/main/docs/hermes.md)
+for plugin layout, compatibility, route switching, and recovery.
+
 To remove a Manager-owned installation, choose one harness explicitly:
 
 ### Uninstall Codex
@@ -123,24 +135,31 @@ npx superpowers-manager uninstall --harness opencode
 npx superpowers-manager uninstall --harness claude-code
 ```
 
+### Uninstall Hermes Agent
+
+```sh
+npx superpowers-manager uninstall --harness hermes
+```
+
 The manager never removes another Superpowers provider. See the [ownership guidance](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#provider-ownership) before switching providers.
 
 ## Shared selection and lifecycle
 
-The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex, Pi, OpenCode, or Claude Code; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
+The [selection commands above](#choose-what-you-run) save shared upstream intent. They do not activate Codex, Pi, OpenCode, Claude Code, or Hermes Agent; run the selected harness's `install` or `update` to apply that choice. `unpin` restores the packaged fallback policy.
 
 See [targeted lifecycle commands](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md#targeted-lifecycle) for preparation, inspection, installation, updates, and removal.
 
-Use `--harness codex`, `--harness pi`, `--harness opencode`, or `--harness claude-code` with each targeted lifecycle command.
+Use `--harness codex`, `--harness pi`, `--harness opencode`, `--harness claude-code`, or `--harness hermes` with each targeted lifecycle command.
 
 ```text
 shared selection -> prepare / inspect / activate Codex
                  -> prepare / inspect / activate Pi
                  -> prepare / inspect / activate OpenCode
                  -> prepare / inspect / activate Claude Code
+                 -> prepare / inspect / activate Hermes Agent
 ```
 
-The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md), [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md), [OpenCode snapshots](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md), and [Claude Code marketplace registration](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md).
+The [usage reference](https://github.com/j7an/superpowers-manager/blob/main/docs/usage.md) covers version selection, precedence, offline behavior, `prepare`, validators, and every lifecycle command. The harness references cover [Codex registration and hooks](https://github.com/j7an/superpowers-manager/blob/main/docs/codex.md), [Pi snapshots and recovery](https://github.com/j7an/superpowers-manager/blob/main/docs/pi.md), [OpenCode snapshots](https://github.com/j7an/superpowers-manager/blob/main/docs/opencode.md), [Claude Code marketplace registration](https://github.com/j7an/superpowers-manager/blob/main/docs/claude-code.md), and [Hermes Agent plugin support](https://github.com/j7an/superpowers-manager/blob/main/docs/hermes.md).
 
 ## Requirements and platforms
 
@@ -148,16 +167,16 @@ The installed package requires Node >=24. Native source, tests, and packaging to
 
 <!-- requirements:begin -->
 
-| Command        | git | Codex CLI (default) | Pi CLI (`--harness pi`) | OpenCode CLI (`--harness opencode`) | Claude Code CLI (`--harness claude-code`) |
-| -------------- | --- | ------------------- | ----------------------- | ----------------------------------- | ----------------------------------------- |
-| `pin`          | yes | no                  | no                      | no                                  | no                                        |
-| `track-latest` | no  | no                  | no                      | no                                  | no                                        |
-| `unpin`        | no  | no                  | no                      | no                                  | no                                        |
-| `prepare`      | yes | no                  | no                      | no                                  | no                                        |
-| `probe`        | yes | yes                 | no                      | no                                  | yes                                       |
-| `install`      | yes | yes                 | yes                     | yes                                 | yes                                       |
-| `update`       | yes | yes                 | yes                     | yes                                 | yes                                       |
-| `uninstall`    | no  | yes                 | yes                     | no                                  | yes                                       |
+| Command        | git | Codex CLI (default) | Pi CLI (`--harness pi`) | OpenCode CLI (`--harness opencode`) | Claude Code CLI (`--harness claude-code`) | Hermes Agent CLI (`--harness hermes`) |
+| -------------- | --- | ------------------- | ----------------------- | ----------------------------------- | ----------------------------------------- | ------------------------------------- |
+| `pin`          | yes | no                  | no                      | no                                  | no                                        | no                                    |
+| `track-latest` | no  | no                  | no                      | no                                  | no                                        | no                                    |
+| `unpin`        | no  | no                  | no                      | no                                  | no                                        | no                                    |
+| `prepare`      | yes | no                  | no                      | no                                  | no                                        | no                                    |
+| `probe`        | yes | yes                 | no                      | no                                  | yes                                       | no                                    |
+| `install`      | yes | yes                 | yes                     | yes                                 | yes                                       | yes                                   |
+| `update`       | yes | yes                 | yes                     | yes                                 | yes                                       | yes                                   |
+| `uninstall`    | no  | yes                 | yes                     | no                                  | yes                                       | yes                                   |
 
 <!-- requirements:end -->
 

package/dist/cli-arguments.js

@@ -23,7 +23,8 @@ export function extractHarnessOptions(command, argv) {
             if (value !== "codex" &&
                 value !== "pi" &&
                 value !== "opencode" &&
-                value !== "claude-code")
+                value !== "claude-code" &&
+                value !== "hermes")
                 throw new UsageError(`unknown harness: ${value}`);
             harness = value;
         }

package/dist/cli.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { extractHarnessOptions, oneLine, UsageError } from "./cli-arguments.js";
 import { codexHarness } from "./harnesses/codex/harness.js";
 import { claudeCodeHarness } from "./harnesses/claude-code/harness.js";
+import { hermesHarness } from "./harnesses/hermes/harness.js";
 import { piHarness } from "./harnesses/pi/harness.js";
 import { openCodeHarness } from "./harnesses/opencode/harness.js";
 import { createResourceCoordinator } from "./resource-lock.js";
@@ -214,7 +215,7 @@ function usage() {
         "  install --harness opencode [--allow-experimental]",
         "  update --harness opencode [--allow-experimental]",
         "  uninstall --harness opencode",
-        "  --harness=codex, --harness=pi, --harness=opencode, and --harness=claude-code are also accepted after the command.",
+        "  --harness=codex, --harness=pi, --harness=opencode, --harness=claude-code, and --harness=hermes are also accepted after the command.",
         "",
         "Environment overrides (used by in-process commands): SUPERPOWERS_REF,",
         "SUPERPOWERS_UPSTREAM_URL, SUPERPOWERS_CODEX, SUPERPOWERS_CACHE_DIR,",
@@ -222,7 +223,7 @@ function usage() {
         "SUPERPOWERS_PLUGIN_ROOT, SUPERPOWERS_MANIFEST_TEMPLATE,",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE,",
         "SUPERPOWERS_INSTALLED_SEARCH_ROOT, SUPERPOWERS_INSTALL_REFRESH_MODE,",
-        "SUPERPOWERS_OPENCODE, SUPERPOWERS_CLAUDE_CODE, CLAUDE_CONFIG_DIR",
+        "SUPERPOWERS_OPENCODE, SUPERPOWERS_CLAUDE_CODE, CLAUDE_CONFIG_DIR, SUPERPOWERS_HERMES, HERMES_HOME",
         "",
         "SUPERPOWERS_VALIDATOR is removed; unset it and use",
         "SUPERPOWERS_VALIDATOR_EXECUTABLE with an executable validator.",
@@ -252,13 +253,15 @@ async function main() {
         console.error(usage());
         process.exit(2);
     }
-    const status = parsed.options.harness === "claude-code"
-        ? await dispatch(claudeCodeHarness, parsed, root)
-        : parsed.options.harness === "opencode"
-            ? await dispatch(openCodeHarness, parsed, root)
-            : parsed.options.harness === "pi"
-                ? await dispatch(piHarness, parsed, root)
-                : await dispatch(codexHarness, parsed, root);
+    const status = parsed.options.harness === "hermes"
+        ? await dispatch(hermesHarness, parsed, root)
+        : parsed.options.harness === "claude-code"
+            ? await dispatch(claudeCodeHarness, parsed, root)
+            : parsed.options.harness === "opencode"
+                ? await dispatch(openCodeHarness, parsed, root)
+                : parsed.options.harness === "pi"
+                    ? await dispatch(piHarness, parsed, root)
+                    : await dispatch(codexHarness, parsed, root);
     process.exit(status);
 }
 async function dispatch(adapter, parsed, root) {

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());
+}