@atbash/cli 0.5.15-dev.0 → 0.5.15-dev.10

package/dist/commands/setup.js

@@ -43,6 +43,18 @@ exports.resolveKeySource = resolveKeySource;
 exports.keyFileContents = keyFileContents;
 exports.isJsonc = isJsonc;
 exports.mergeOpenclawConfig = mergeOpenclawConfig;
+exports.detectIndent = detectIndent;
+exports.serializeLike = serializeLike;
+exports.detectMcpClients = detectMcpClients;
+exports.findHermesPython = findHermesPython;
+exports.wantedRuntime = wantedRuntime;
+exports.mergeHermesEnabledPlugins = mergeHermesEnabledPlugins;
+exports.hermesGatewayRunning = hermesGatewayRunning;
+exports.hermesPluginState = hermesPluginState;
+exports.pythonInstallStrategy = pythonInstallStrategy;
+exports.mergeHermesEnv = mergeHermesEnv;
+exports.hadInlineKey = hadInlineKey;
+exports.mergeMcpServer = mergeMcpServer;
 exports.buildPlan = buildPlan;
 exports.lineDiff = lineDiff;
 exports.renderPlan = renderPlan;
@@ -55,8 +67,9 @@ const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const jsonc = __importStar(require("jsonc-parser"));
+const yaml_1 = require("yaml");
 const sdk_1 = require("@atbash/sdk");
-const connect_1 = require("./connect");
+const atbash_targets_1 = require("../shared/atbash-targets");
 /**
  * `atbash setup` — the write half of onboarding.
  *
@@ -84,9 +97,11 @@ const connect_1 = require("./connect");
  *  2. It never writes the private key into an MCP client config. The documented
  *     `@atbash/mcp` wiring passes the key as an `ATBASH_AGENT_PRIVKEY` env value
  *     inside e.g. `claude_desktop_config.json` — a file people screenshot, sync
- *     and share. That package has no key-file fallback today (verified against
- *     the published 0.1.3), so MCP clients are REPORTED with the snippet to add
- *     by hand rather than silently seeded with a secret.
+ *     and share, and that package has no key-file fallback (verified against the
+ *     published 0.1.3). So the entry setup writes points at `atbash mcp`, which
+ *     reads the 0600 key file and passes the key to the server through the child
+ *     environment. The config file itself gets NO credential — and an entry that
+ *     was hand-wired with one has it removed.
  *  3. It never edits application source. Code-level integrations (LangChain,
  *     LangGraph, AutoGen, Eliza, the SDK boundary) are the owner's to write.
  *  4. It never rewrites a config file that uses comments or trailing commas.
@@ -118,8 +133,51 @@ const HERMES_AGENT_REL = [".hermes", "hermes-agent"];
  * is already governed and must not be given a second, duplicate entry.
  */
 const OPENCLAW_PKG = "@atbash/atbash-openclaw";
-const OPENCLAW_ENTRY = "openclaw";
+/**
+ * The entry key `@atbash/atbash-openclaw` registers as.
+ *
+ * ⚠️ It is `atbash-openclaw`, NOT `openclaw`. `openclaw` is the id of the RETIRED
+ * `@atbash-plugin/openclaw` package, and the published docs are explicit about
+ * what happens if you use it: "the plugin id here is `atbash-openclaw`, so a
+ * leftover `openclaw` entry silently configures nothing." Earlier releases of
+ * this command wrote `openclaw`, so every config they produced was inert — no
+ * error, no warning, just a plugin reading a config block nobody looks at.
+ */
+const OPENCLAW_ENTRY = "atbash-openclaw";
+/** Installs of the earlier `@atbash/atbash-plugin` register under this. */
 const OPENCLAW_LEGACY_ENTRY = "atbash-plugin";
+/** The retired `@atbash-plugin/openclaw` id — inert if left in a config. */
+const OPENCLAW_RETIRED_ENTRY = "openclaw";
+/**
+ * The npm tag to install, chosen from the deployment the agent was onboarded on.
+ *
+ * The judge endpoint and chain ids are NOT configurable at runtime — they come
+ * from the SDK the plugin bundles, so the tag is an environment choice. Verified
+ * on the registry: the two tarballs' plugin code is byte-identical and only
+ * `package.json` differs —
+ *
+ *   0.1.14        → @atbash/sdk@0.7.0        → https://atbash.ai            BRID 0163241D…
+ *   0.1.14-dev.0  → @atbash/sdk@0.10.5-dev.0 → …dev-two.vercel.app          BRID 02668C52…
+ *
+ * Install the wrong one and it loads cleanly, fires its hook, and fails every
+ * judge call because the agent does not exist on the chain that build targets.
+ * The docs warn that a resolving org name is not proof the build is right, since
+ * org names are not unique across environments — so this is derived from --host
+ * and nothing else.
+ */
+function openclawPackageForHost(endpoint) {
+    if (!endpoint)
+        return OPENCLAW_PKG; // no host given: production is the safe default
+    let hostname = "";
+    try {
+        hostname = new URL(endpoint).hostname.toLowerCase();
+    }
+    catch {
+        return OPENCLAW_PKG;
+    }
+    const isProduction = hostname === "atbash.ai" || hostname === "www.atbash.ai";
+    return isProduction ? OPENCLAW_PKG : `${OPENCLAW_PKG}@dev`;
+}
 /** File modes: 0700 for the key directory, 0600 for the key itself. */
 const DIR_MODE = 0o700;
 const KEY_MODE = 0o600;
@@ -208,7 +266,45 @@ function normalizePrivkey(raw) {
     const clean = raw.replace(/^0x/i, "").trim().toLowerCase();
     return (0, sdk_1.isValidPrivateKey)(clean) ? clean : "";
 }
-/** Files in a directory that plausibly hold an Atbash agent key, newest first. */
+/** Only sniff the contents of small files — a key file is a few hundred bytes. */
+const MAX_SNIFF_BYTES = 8 * 1024;
+/** Bound the content-sniff so `--keys-dir ~` cannot turn into a directory crawl. */
+const MAX_SNIFF_FILES = 60;
+/** Newest-first, so a freshly downloaded key wins over one from last month. */
+function newestFirst(files) {
+    return files
+        .map((file) => {
+        let mtime = 0;
+        try {
+            mtime = fs.statSync(file).mtimeMs;
+        }
+        catch { /* unreadable — sorts last */ }
+        return { file, mtime };
+    })
+        .sort((a, b) => b.mtime - a.mtime)
+        .map((e) => e.file);
+}
+/**
+ * Files in a directory that plausibly hold an Atbash agent key, newest first.
+ *
+ * TWO PASSES, and the second one is the point.
+ *
+ * By name first — `guard-client-key`, `agent-keys-*.txt` and friends — because
+ * matching the name is cheap and unambiguous. But a name-only match is a cliff:
+ * rename the download, or export from a wallet UI that picks its own filename,
+ * and the operator gets "no key file found" while the key sits right there in the
+ * directory they explicitly pointed at.
+ *
+ * So if no name matches, read the small files and keep the ones that actually
+ * PARSE as key material. That is a narrow test — `privkey=`, the documented JSON
+ * shape, or a file that is nothing but a 64-hex key — not "contains something
+ * hex-looking", so an unrelated file does not get mistaken for an identity.
+ *
+ * Reading files the operator did not name individually is justified by the flag
+ * itself: `--keys-dir` is an explicit instruction to look in that directory. It
+ * is bounded to small regular files and a file count, nothing is transmitted, and
+ * the caller prints WHICH file it used before doing anything with it.
+ */
 function keyCandidatesInDir(dir) {
     let names;
     try {
@@ -217,21 +313,31 @@ function keyCandidatesInDir(dir) {
     catch {
         return [];
     }
-    const matches = names.filter((n) => n === "guard-client-key" ||
+    const byName = names.filter((n) => n === "guard-client-key" ||
         /^agent-keys-.*\.txt$/i.test(n) ||
         /^atbash.*(key|keys).*\.(txt|json)$/i.test(n));
-    return matches
-        .map((n) => path.join(dir, n))
-        .map((file) => {
-        let mtime = 0;
+    if (byName.length)
+        return newestFirst(byName.map((n) => path.join(dir, n)));
+    const byContent = [];
+    let examined = 0;
+    for (const name of names) {
+        if (examined >= MAX_SNIFF_FILES)
+            break;
+        const file = path.join(dir, name);
         try {
-            mtime = fs.statSync(file).mtimeMs;
+            const stat = fs.statSync(file);
+            if (!stat.isFile() || stat.size === 0 || stat.size > MAX_SNIFF_BYTES)
+                continue;
         }
-        catch { /* unreadable — sorts last */ }
-        return { file, mtime };
-    })
-        .sort((a, b) => b.mtime - a.mtime)
-        .map((e) => e.file);
+        catch {
+            continue;
+        }
+        examined++;
+        const text = readTextFile(file);
+        if (text !== null && parseKeyMaterial(text))
+            byContent.push(file);
+    }
+    return newestFirst(byContent);
 }
 /**
  * Read a secret from the terminal without echoing it.
@@ -247,23 +353,56 @@ function keyCandidatesInDir(dir) {
 async function promptForKeyOrPath() {
     const { createInterface } = await Promise.resolve().then(() => __importStar(require("node:readline")));
     return new Promise((resolveP) => {
-        const input = process.stdin;
-        const rl = createInterface({ input, output: process.stdout, terminal: true });
-        // Mute the echo so a pasted key does not sit on screen (or in a scrollback
-        // buffer that gets screenshotted). A pasted path is muted too; that is a
-        // small cost against leaving a private key visible.
-        const asMutable = rl;
         const prompt = "Paste the agent's private key, or the path to its key file: ";
-        asMutable._writeToOutput = function (s) {
-            if (s.includes(prompt))
-                asMutable.output?.write(s);
-            else if (s === "\r\n" || s === "\n")
-                asMutable.output?.write(s);
-            // every other keystroke echo is dropped
+        // Write the prompt ourselves, THEN suppress every subsequent write.
+        //
+        // The obvious implementation compares each write against the prompt text and
+        // lets that one through — but a pasted value containing the prompt as a
+        // substring would then be echoed to the terminal, which is exactly the
+        // failure this mute exists to prevent. Emitting the prompt up front means the
+        // suppressor never has to decide what a write IS: after this point, nothing
+        // is echoed, unconditionally.
+        process.stdout.write(prompt);
+        const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        rl._writeToOutput = () => {
+            /* nothing typed after the prompt is ever echoed */
         };
-        rl.question(prompt, (answer) => { rl.close(); resolveP(answer.trim()); });
+        rl.question("", (answer) => {
+            rl.close();
+            // readline's own newline was suppressed along with everything else, so the
+            // next line of output would otherwise land on the prompt line.
+            process.stdout.write("\n");
+            resolveP(answer.trim());
+        });
     });
 }
+/**
+ * Interpret whatever someone typed at the prompt: a raw key, a file, or a
+ * directory to search. Shared by the "no key found" prompt and the "use the
+ * existing key?" prompt so both accept the same things — an operator who can
+ * paste a path in one place should not find it rejected in the other.
+ */
+async function keyFromAnswer(answer, home) {
+    const direct = parseKeyMaterial(answer);
+    if (direct)
+        return { material: direct, from: "key entered at the prompt" };
+    const asPath = expandHome(answer, home);
+    if (!exists(asPath))
+        return null;
+    let isDir = false;
+    try {
+        isDir = fs.statSync(asPath).isDirectory();
+    }
+    catch {
+        return null;
+    }
+    const file = isDir ? keyCandidatesInDir(asPath)[0] : asPath;
+    if (!file)
+        return null;
+    const text = readTextFile(file);
+    const material = text === null ? null : parseKeyMaterial(text);
+    return material ? { material, from: `${file} (given at the prompt)` } : null;
+}
 /**
  * Find the agent key, trying every way an owner could plausibly have it.
  *
@@ -297,7 +436,15 @@ async function resolveKeySource(opts) {
         const dir = expandHome(opts.keysDir, home);
         const candidates = keyCandidatesInDir(dir);
         if (!candidates.length) {
-            return { error: `No agent key file found in ${dir} (looked for guard-client-key and agent-keys-*.txt).` };
+            return {
+                error: [
+                    `No agent key found in ${dir}.`,
+                    "Looked for guard-client-key / agent-keys-*.txt by name, then read the small",
+                    "files there to see if any parsed as an agent key. Neither found one.",
+                    "Point at the file directly with --key-file, or paste the key with no flags",
+                    "at all and setup will prompt for it.",
+                ].join("\n"),
+            };
         }
         return fromFile(candidates[0], "--keys-dir");
     }
@@ -309,11 +456,39 @@ async function resolveKeySource(opts) {
             return { material, from: "ATBASH_AGENT_KEY" };
     }
     // 5. Already in the canonical place — a re-run, or a machine set up before.
+    //
+    // This used to be taken SILENTLY, and that was a trap. A machine that has ever
+    // governed one agent already has a key here, so onboarding a SECOND agent
+    // picked up the first one's key and then failed registration against a pubkey
+    // the operator never chose:
+    //
+    //   Agent key source: existing key file (~/.config/atbash/guard-client-key)
+    //   That agent is not registered on this deployment.
+    //
+    // which reads as "onboarding is broken" rather than "I used a different key
+    // than you meant". So when there is someone to ask, ask — and make the existing
+    // key the easy answer for the common case (a genuine re-run) without making it
+    // the only answer.
     const keyFile = path.join(home, ...KEY_FILE_REL);
     if (exists(keyFile)) {
         const found = fromFile(keyFile, "existing key file");
-        if (!("error" in found))
-            return found;
+        if (!("error" in found)) {
+            if (!opts.allowPrompt)
+                return found; // non-interactive: same as before
+            const existingPub = (0, sdk_1.derivePublicKey)(found.material.privkey);
+            process.stdout.write(`\n  This machine already has an agent key at ${keyFile}\n` +
+                `  Public key: ${existingPub}\n`);
+            const useExisting = await confirm("  Use that key? [Y/n] ", true);
+            if (useExisting)
+                return found;
+            const answer = await promptForKeyOrPath();
+            if (!answer)
+                return { error: "No key provided." };
+            const supplied = await keyFromAnswer(answer, home);
+            if (supplied)
+                return supplied;
+            return { error: "That is neither a 64-hex private key nor a path that exists." };
+        }
     }
     // 6. The CLI's own config, populated by `atbash set agent-key`.
     const fromConfig = (0, sdk_1.resolve)("agentKey");
@@ -327,20 +502,9 @@ async function resolveKeySource(opts) {
         const answer = await promptForKeyOrPath();
         if (!answer)
             return { error: "No key provided." };
-        const direct = parseKeyMaterial(answer);
-        if (direct)
-            return { material: direct, from: "interactive prompt" };
-        const asPath = expandHome(answer, home);
-        if (exists(asPath)) {
-            const stat = fs.statSync(asPath);
-            if (stat.isDirectory()) {
-                const candidates = keyCandidatesInDir(asPath);
-                if (candidates.length)
-                    return fromFile(candidates[0], "directory given at the prompt");
-                return { error: `No agent key file found in ${asPath}.` };
-            }
-            return fromFile(asPath, "file given at the prompt");
-        }
+        const supplied = await keyFromAnswer(answer, home);
+        if (supplied)
+            return supplied;
         return { error: "That is neither a 64-hex private key nor a path that exists." };
     }
     return {
@@ -391,54 +555,553 @@ function isJsonc(text) {
  * `<your-username>` placeholder that people paste verbatim, producing a path that
  * does not exist and a plugin that never loads.
  */
-function mergeOpenclawConfig(config, home) {
+function mergeOpenclawConfig(config, home, orgName) {
     const out = { ...config };
     const plugins = { ...(isRecord(out.plugins) ? out.plugins : {}) };
-    // Which key is this install governed under? Keep an existing legacy entry
-    // where it is instead of adding a second one.
     const entries = { ...(isRecord(plugins.entries) ? plugins.entries : {}) };
-    const entryKey = OPENCLAW_LEGACY_ENTRY in entries && !(OPENCLAW_ENTRY in entries)
-        ? OPENCLAW_LEGACY_ENTRY
-        : OPENCLAW_ENTRY;
+    // Which entry is this install governed under, and does one already exist?
+    const legacy = OPENCLAW_LEGACY_ENTRY in entries;
+    const modern = OPENCLAW_ENTRY in entries;
+    const entryKey = legacy && !modern ? OPENCLAW_LEGACY_ENTRY : OPENCLAW_ENTRY;
+    const existing = isRecord(entries[entryKey]) ? entries[entryKey] : null;
+    // ⚠️ AN EXISTING ENTRY IS TOUCHED AS LITTLE AS POSSIBLE.
+    //
+    // This function used to assert the full documented shape onto whatever it
+    // found, which broke a real machine: a legacy `atbash-plugin` install accepts
+    // only `config` and `enabled`, so writing the `hooks` block that the NEW
+    // `openclaw` entry documents made the whole file invalid —
+    //
+    //   Invalid config at ~/.openclaw/openclaw.json:
+    //     - plugins.entries.atbash-plugin: Unrecognized key: "hooks"
+    //
+    // and OpenClaw then refused to load any config at all. It also added a
+    // `load.paths` entry pointing at `extensions/openclaw` on a box whose plugin
+    // lives in `extensions/atbash-plugin`, and rewrote an absolute
+    // `chromiaSecretPath` to a `~` one for no gain.
+    //
+    // A plugin that is already installed and registered does not need `allow`,
+    // `load` or `hooks` re-declared — it is working. The only thing setup has any
+    // business changing is that it is switched on and pointed at the right key.
+    if (existing) {
+        const existingConfig = isRecord(existing.config) ? existing.config : {};
+        const repaired = { ...existing };
+        // ONE exception to leaving an existing entry alone: remove a `hooks` block
+        // from a LEGACY entry.
+        //
+        // Legacy `atbash-plugin` accepts only `config` and `enabled`. An earlier
+        // release of this command wrote the NEW entry's `hooks` block onto it, and
+        // OpenClaw then rejects the entire file —
+        //
+        //   Invalid config: plugins.entries.atbash-plugin: Unrecognized key: "hooks"
+        //
+        // refusing to load ANY config, which also makes `openclaw plugins install`
+        // exit 1. "Touch as little as possible" is the right rule, but it must not
+        // mean stepping politely around damage this tool caused: a later run would
+        // leave the machine broken forever and report nothing wrong. Only ever
+        // removes the key on the legacy entry, where it is invalid by definition —
+        // never on the modern `openclaw` entry, which documents it.
+        if (entryKey === OPENCLAW_LEGACY_ENTRY && "hooks" in repaired)
+            delete repaired.hooks;
+        entries[entryKey] = {
+            ...repaired,
+            enabled: true,
+            config: {
+                ...existingConfig,
+                enabled: true,
+                enforceDecision: true,
+                ...keyPathUpdate(existingConfig, home),
+                ...orgNameUpdate(existingConfig, orgName),
+            },
+        };
+        plugins.entries = entries;
+        out.plugins = plugins;
+        return out;
+    }
+    // No entry yet — write the shape the published plugin documents, in full.
     const allow = Array.isArray(plugins.allow) ? [...plugins.allow] : [];
     if (!allow.includes(entryKey))
         allow.push(entryKey);
     plugins.allow = allow;
     const load = { ...(isRecord(plugins.load) ? plugins.load : {}) };
-    const extensionPath = path.join(home, ...OPENCLAW_EXTENSIONS_REL, OPENCLAW_ENTRY);
+    const extensionPath = path.join(home, ...OPENCLAW_EXTENSIONS_REL, entryKey);
     const paths = Array.isArray(load.paths) ? [...load.paths] : [];
     if (!paths.includes(extensionPath))
         paths.push(extensionPath);
     load.paths = paths;
     plugins.load = load;
-    // Preserve any unrelated fields the owner set on the entry (debug, custom
-    // hooks); only the fields Atbash owns are asserted.
-    const existing = isRecord(entries[entryKey]) ? entries[entryKey] : {};
-    const existingConfig = isRecord(existing.config) ? existing.config : {};
-    const existingHooks = isRecord(existing.hooks) ? existing.hooks : {};
     entries[entryKey] = {
-        ...existing,
         enabled: true,
         config: {
-            ...existingConfig,
             enabled: true,
             enforceDecision: true,
-            // The path, not the key. This is the whole point of the canonical location.
             chromiaSecretPath: `~/${KEY_FILE_REL.join("/")}`,
+            ...(orgName?.trim() ? { orgName: orgName.trim() } : {}),
         },
-        hooks: {
-            ...existingHooks,
-            allowConversationAccess: true,
-            allowPromptInjection: true,
-        },
+        hooks: { allowConversationAccess: true, allowPromptInjection: true },
     };
     plugins.entries = entries;
     out.plugins = plugins;
     return out;
 }
+/**
+ * The key-path field, but only when it actually needs changing.
+ *
+ * `/Users/me/.config/atbash/guard-client-key` and `~/.config/atbash/guard-client-key`
+ * are the same file, and the plugin expands `~`. Rewriting one into the other is
+ * a diff the operator has to read and approve for no behavioural change, so an
+ * existing value that already resolves to the canonical key file is left exactly
+ * as they wrote it.
+ */
+/**
+ * `orgName`, but only when we have one and it differs from what is there.
+ *
+ * The plugin resolves WHICH CHAIN to query from this, so it is required for orgs
+ * on a private chain and harmless otherwise. It cannot be derived on the machine
+ * — it has to match the dashboard exactly — so it arrives via --org-name, which
+ * the post-deploy screen fills in because the browser already knows it.
+ *
+ * Never overwrites an existing value with nothing: a run without the flag must
+ * not silently strip an orgName someone already has working.
+ */
+function orgNameUpdate(existingConfig, orgName) {
+    const wanted = orgName?.trim();
+    if (!wanted)
+        return {};
+    return existingConfig.orgName === wanted ? {} : { orgName: wanted };
+}
+function keyPathUpdate(existingConfig, home) {
+    const canonical = path.join(home, ...KEY_FILE_REL);
+    const current = existingConfig.chromiaSecretPath;
+    if (typeof current === "string" && path.resolve(expandHome(current.trim(), home)) === path.resolve(canonical)) {
+        return {};
+    }
+    return { chromiaSecretPath: `~/${KEY_FILE_REL.join("/")}` };
+}
 function isRecord(v) {
     return !!v && typeof v === "object" && !Array.isArray(v);
 }
+/**
+ * Detect the indentation a JSON file already uses, so a merge does not reformat
+ * the parts it did not touch.
+ *
+ * Without this, `JSON.stringify(obj, null, 2)` re-indents a tab-indented or
+ * 4-space config from top to bottom. The RESULT is still correct, but the diff
+ * shown for approval becomes every line in the file, which buries the two lines
+ * that actually changed — and the operator's own formatting choice is collateral
+ * damage in a file we were asked to make one addition to.
+ *
+ * Falls back to two spaces, which is what the published docs show.
+ */
+function detectIndent(text) {
+    if (!text)
+        return 2;
+    // First line that is indented under an opening brace/bracket tells us the unit.
+    const match = text.match(/\n([ \t]+)\S/);
+    if (!match)
+        return 2;
+    const indent = match[1];
+    return indent.startsWith("\t") ? "\t" : indent.length;
+}
+/**
+ * Serialize a merged config the way the file was already written: same
+ * indentation, and a trailing newline only if the original had one.
+ */
+function serializeLike(original, value) {
+    const body = JSON.stringify(value, null, detectIndent(original));
+    // A file that ended without a newline keeps ending without one. Trivial, but it
+    // is one more line of unexplained diff for someone reviewing the change.
+    const trailing = original === null || original.endsWith("\n") ? "\n" : "";
+    return body + trailing;
+}
+/**
+ * The MCP server entry setup writes into a client's config.
+ *
+ * Note what is NOT here: an `env` block. The published `@atbash/mcp` wiring
+ * carries the agent's private key in one, because that package reads only
+ * ATBASH_AGENT_PRIVKEY. Going through `atbash mcp` instead means the launcher
+ * reads the 0600 key file and passes the key to the server in the child process
+ * environment, so this entry holds no credential and the client's config file is
+ * no more sensitive after setup runs than it was before.
+ *
+ * Deliberately NOT pinned to an exact CLI version: unlike the one-shot connector
+ * command, this entry persists in the operator's config and is re-executed every
+ * time the client starts. Pinning here would freeze their MCP server at whatever
+ * version happened to be current on the day they ran setup.
+ */
+const MCP_SERVER_ENTRY = { command: "npx", args: ["--yes", "@atbash/cli", "mcp"] };
+const MCP_SERVER_NAME = "atbash";
+/**
+ * MCP client configs present under this home directory.
+ *
+ * Paths come from the shared MCP_CONFIGS so the writer and the scanner cannot
+ * drift: a client the scan reports but setup cannot find would look like a bug in
+ * whichever of the two the operator happened to trust.
+ */
+function detectMcpClients(home) {
+    const out = [];
+    const seen = new Set();
+    for (const { label, segs } of atbash_targets_1.MCP_CONFIGS) {
+        if (seen.has(label))
+            continue;
+        const file = path.join(home, ...segs);
+        if (!exists(file))
+            continue;
+        seen.add(label);
+        // Read which key this file already uses rather than assuming. VS Code's
+        // mcp.json uses `servers`; writing `mcpServers` into it would be ignored.
+        const existing = readJsonLoose(file);
+        const serversKey = existing && isRecord(existing.servers) && !isRecord(existing.mcpServers) ? "servers" : "mcpServers";
+        out.push({ label, file, format: "json", serversKey });
+    }
+    // Claude Code and Codex are special-cased in the scanner too — same paths.
+    const claudeCode = path.join(home, ".claude.json");
+    if (exists(claudeCode))
+        out.push({ label: "Claude Code", file: claudeCode, format: "json", serversKey: "mcpServers" });
+    const codex = path.join(home, ".codex", "config.toml");
+    if (exists(codex))
+        out.push({ label: "Codex", file: codex, format: "toml", serversKey: "mcpServers" });
+    return out;
+}
+/** Tolerant read used only to sniff an existing file's shape. */
+function readJsonLoose(file) {
+    const text = readTextFile(file);
+    if (text === null)
+        return null;
+    const value = jsonc.parse(text, [], { allowTrailingComma: true, disallowComments: false });
+    return isRecord(value) ? value : null;
+}
+/**
+ * Add the Atbash server to a client config's server map, in place.
+ *
+ * A merge, like the OpenClaw one: every server the operator already configured
+ * stays exactly as it is. An existing `atbash` entry is REPLACED rather than
+ * merged field-by-field — a stale `env` block carrying a private key from the old
+ * hand-written wiring is precisely what we want gone, and preserving it would
+ * defeat the point of routing through the launcher.
+ */
+/** The Hermes plugin, and the exact version the wiring is written against. */
+const HERMES_PKG = "atbash-hermes-plugin";
+const HERMES_VERSION = "0.4.5";
+/** The name Hermes lists this plugin under, and the allow-list entry. */
+const HERMES_PLUGIN_ENTRY = "atbash-hermes-plugin";
+/**
+ * Find the Python interpreter that actually runs Hermes.
+ *
+ * This is the difference between installing the plugin and only appearing to.
+ * `pip install atbash-hermes-plugin` puts the package wherever the *shell's*
+ * `pip` points — commonly a system or conda Python — while Hermes typically runs
+ * from its own virtualenv. The install succeeds, prints nothing alarming, and the
+ * plugin is invisible to Hermes forever. Nobody can debug that from the output.
+ *
+ * The launcher knows the answer. A pip-installed console script begins with a
+ * shebang naming the interpreter that created it:
+ *
+ *   $ head -1 $(command -v hermes)
+ *   #!/Users/me/.hermes/hermes-agent/venv/bin/python3
+ *
+ * So resolve `hermes`, read its first line, and use that interpreter directly via
+ * `-m pip`. Falls back to the conventional venv location under ~/.hermes, then to
+ * null — and a null becomes a printed command rather than a guess, because a
+ * wrong guess here is the silent failure this whole function exists to avoid.
+ */
+function findHermesPython(home) {
+    const viable = (candidate) => {
+        try {
+            return fs.statSync(candidate).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    // 1. The launcher's own shebang — authoritative, but only for a real run.
+    //
+    // `--home <dir>` exists so a dry run can be hermetic (the release checklist
+    // depends on it). A PATH lookup ignores it entirely: under `--home /tmp/fake`
+    // this would find the operator's ACTUAL hermes and plan an install into their
+    // real virtualenv. So the shebang route is skipped whenever `home` is not the
+    // machine's own home — the caller then falls through to the venv path under the
+    // given home, which is correctly scoped.
+    const realHome = process.env.HOME || os.homedir();
+    const scoped = path.resolve(home) !== path.resolve(realHome);
+    const which = scoped
+        ? { status: 1, stdout: "" }
+        : (0, child_process_1.spawnSync)(process.platform === "win32" ? "where" : "which", ["hermes"], { encoding: "utf8" });
+    const launcher = which.status === 0 ? which.stdout.split(/\r?\n/)[0]?.trim() : "";
+    if (launcher && viable(launcher)) {
+        const firstLine = (readTextFile(launcher) ?? "").split(/\r?\n/)[0] ?? "";
+        const shebang = firstLine.startsWith("#!") ? firstLine.slice(2).trim() : "";
+        // `#!/usr/bin/env python3` names no path; anything else should be absolute.
+        const interpreter = shebang.split(/\s+/).filter((part) => !part.endsWith("/env"))[0] ?? "";
+        if (/python[0-9.]*$/.test(interpreter) && viable(interpreter)) {
+            return { python: interpreter, how: `shebang of ${launcher}` };
+        }
+    }
+    // 2. The conventional venv Hermes ships with.
+    for (const name of ["python3", "python"]) {
+        const candidate = path.join(home, ".hermes", "hermes-agent", "venv", "bin", name);
+        if (viable(candidate))
+            return { python: candidate, how: "Hermes virtualenv under ~/.hermes" };
+    }
+    return null;
+}
+/** Same rule as buildPlan's `wanted`: an empty --runtime list means everything. */
+function wantedRuntime(id, only) {
+    return only.length === 0 || only.includes(id);
+}
+/**
+ * Add the plugin to Hermes' opt-in allow-list at `plugins.enabled` in
+ * `~/.hermes/config.yaml`.
+ *
+ * WHY NOT `hermes plugins enable`: that command cannot accept this plugin, on
+ * this version, ever. `_plugin_exists` (hermes_cli/plugins_cmd.py) looks only for
+ * a DIRECTORY in the user plugins dir or a bundled dir — it never consults entry
+ * points. Meanwhile the runtime loader (`plugins.py:_scan_entry_points`) does
+ * discover them. So Hermes will happily LOAD a pip-installed plugin but refuses
+ * to put one on the allow-list it requires, and since plugins are opt-in, a
+ * package that cannot get onto the list can never load. Running that command
+ * exits 1 with "not installed or bundled". Writing the list entry directly is the
+ * only route that works.
+ *
+ * A LINE MERGE, not a parse-and-reserialize. config.yaml is tens of kilobytes of
+ * heavily commented configuration; round-tripping it through a YAML emitter would
+ * strip every comment and reflow the file. So this inserts the one line needed and
+ * leaves every other byte alone — the same discipline as the .env merge.
+ */
+function mergeHermesEnabledPlugins(existing, plugin = HERMES_PLUGIN_ENTRY) {
+    const lines = existing === null ? [] : existing.split("\n");
+    // Already on the list? Then there is nothing to do.
+    const pluginsAt = lines.findIndex((l) => /^plugins:\s*(#.*)?$/.test(l));
+    if (pluginsAt !== -1) {
+        // Walk the plugins block (indented lines) looking for `enabled:` and its items.
+        let enabledAt = -1;
+        let end = lines.length;
+        for (let i = pluginsAt + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.trim() === "" || line.startsWith("#"))
+                continue;
+            if (!/^\s/.test(line)) {
+                end = i;
+                break;
+            } // dedented — block over
+            if (/^\s+enabled:\s*(#.*)?$/.test(line))
+                enabledAt = i;
+        }
+        if (enabledAt !== -1) {
+            // Collect the list items under `enabled:` and bail if ours is there.
+            const itemIndent = (lines[enabledAt].match(/^\s*/)?.[0] ?? "  ") + "  ";
+            let last = enabledAt;
+            for (let i = enabledAt + 1; i < end; i++) {
+                if (/^\s*-\s+/.test(lines[i])) {
+                    if (lines[i].replace(/^\s*-\s+/, "").trim().replace(/^["']|["']$/g, "") === plugin)
+                        return existing;
+                    last = i;
+                }
+                else if (lines[i].trim() !== "")
+                    break;
+            }
+            lines.splice(last + 1, 0, `${itemIndent}- ${plugin}`);
+            return lines.join("\n");
+        }
+        // A plugins block with no `enabled:` key — add one inside it.
+        lines.splice(pluginsAt + 1, 0, "  enabled:", `    - ${plugin}`);
+        return lines.join("\n");
+    }
+    // No plugins block at all — which is the default, and means nothing loads.
+    const out = existing === null ? [] : [...lines];
+    if (out.length && out[out.length - 1].trim() !== "")
+        out.push("");
+    out.push("# Added by `atbash setup` - Hermes loads only plugins on this allow-list");
+    out.push("plugins:", "  enabled:", `    - ${plugin}`);
+    let text = out.join("\n");
+    if (!text.endsWith("\n"))
+        text += "\n";
+    return text;
+}
+/**
+ * Is a Hermes gateway service running, and therefore restartable?
+ *
+ * "Restart Hermes" only means something when there is a service to bounce.
+ * Hermes has two shapes: `hermes` starts an interactive chat session, and
+ * `hermes gateway install` registers a launchd/systemd background service. A
+ * setup command must not conflate them —
+ *
+ *  - with a service running, `hermes gateway restart` picks up the new config and
+ *    is worth doing for the operator;
+ *  - without one, there is nothing to restart. The plugin loads the next time
+ *    they run `hermes`, and anything we "restarted" would either be a no-op or,
+ *    worse, an interactive session someone is in the middle of using.
+ *
+ * `gateway status` exits 0 either way, so the state comes from its text.
+ */
+function hermesGatewayRunning() {
+    const probe = (0, child_process_1.spawnSync)("hermes", ["gateway", "status"], { encoding: "utf8" });
+    if (probe.status !== 0 || typeof probe.stdout !== "string")
+        return false;
+    // "✗ Gateway is not running" vs a running report.
+    return !/not\s+running/i.test(probe.stdout);
+}
+/**
+ * Is Hermes CONFIGURED to load the plugin?
+ *
+ * This used to shell out to `hermes plugins list` and look for an atbash row —
+ * a signal that can never be true. `_discover_all_plugins` (plugins_cmd.py) walks
+ * plugin DIRECTORIES only: bundled, user, project. It never scans entry points,
+ * exactly like the `_plugin_exists` gate behind `plugins enable`. So a
+ * pip-installed plugin is invisible to both, and the check reported "not picked
+ * up" while everything was in fact correct — then told the operator to run the
+ * enable command that cannot work. Advising a known-impossible fix is worse than
+ * saying nothing.
+ *
+ * The two facts that actually decide it are both on disk:
+ *
+ *   1. the package is importable by the interpreter that runs Hermes, and
+ *   2. its name is on the `plugins.enabled` allow-list in config.yaml, which is
+ *      what the RUNTIME loader (`plugins.py:_scan_entry_points`) honours.
+ *
+ * "configured" is as far as a setup command can honestly go. Proof of loading is
+ * a line in the agent log after Hermes next starts, which is why the caller points
+ * at that rather than claiming enforcement.
+ */
+function hermesPluginState(home) {
+    const venvBase = path.join(home, ".hermes", "hermes-agent", "venv", "lib");
+    let installed = false;
+    try {
+        installed = fs.readdirSync(venvBase, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .some((e) => exists(venvBase, e.name, "site-packages", "atbash_hermes_plugin"));
+    }
+    catch {
+        return "unknown";
+    }
+    const configYaml = readTextFile(path.join(home, ".hermes", "config.yaml"));
+    if (configYaml === null)
+        return installed ? "not-enabled" : "not-installed";
+    let enabled = false;
+    try {
+        const parsed = (0, yaml_1.parse)(configYaml);
+        const list = parsed?.plugins?.enabled;
+        enabled = Array.isArray(list) && list.some((n) => String(n).trim() === HERMES_PLUGIN_ENTRY);
+    }
+    catch {
+        return "unknown";
+    }
+    if (!installed)
+        return "not-installed";
+    return enabled ? "configured" : "not-enabled";
+}
+/**
+ * How to install a Python package into a specific interpreter on THIS machine.
+ *
+ * `<python> -m pip install` is the obvious answer and it is frequently wrong: a
+ * venv created by `uv venv` has no pip at all (that is uv's default), so the
+ * command fails with
+ *
+ *   /path/venv/bin/python3: No module named pip
+ *
+ * after setup has already written every config file — which is exactly what
+ * happened on a real Hermes box. So probe, in order of what suits the venv:
+ *
+ *  1. `uv pip install --python <python>` when uv is present. Correct for a
+ *     uv-created venv and fast; uv is also what created most pip-less venvs.
+ *  2. `<python> -m pip install` when pip actually answers.
+ *  3. Neither — hand it over, with `ensurepip` named, rather than planning a
+ *     command that is known in advance to fail.
+ */
+function pythonInstallStrategy(python, pkg) {
+    const uv = (0, child_process_1.spawnSync)(process.platform === "win32" ? "where" : "which", ["uv"], { stdio: "ignore" });
+    if (uv.status === 0) {
+        return {
+            kind: "exec",
+            command: "uv",
+            args: ["pip", "install", "--python", python, pkg],
+            how: "uv, targeting the interpreter that runs Hermes",
+        };
+    }
+    const pip = (0, child_process_1.spawnSync)(python, ["-m", "pip", "--version"], { stdio: "ignore" });
+    if (pip.status === 0) {
+        return { kind: "exec", command: python, args: ["-m", "pip", "install", pkg], how: "pip in the interpreter that runs Hermes" };
+    }
+    return {
+        kind: "manual",
+        why: `${python} has no pip (a venv created by \`uv venv\` has none by default) and uv is not on PATH, so setup cannot install into it. Bootstrap pip, then install:`,
+        snippet: [`${python} -m ensurepip --upgrade`, `${python} -m pip install ${pkg}`].join("\n"),
+    };
+}
+/**
+ * The env vars the Hermes plugin documents, merged into an existing `.env`.
+ *
+ * A `.env` is line-oriented and hand-maintained, so this is a line merge rather
+ * than a parse-and-reserialize: keys Atbash owns are replaced in place (keeping
+ * their position), keys it does not own are never touched, and anything else in
+ * the file — comments, blank lines, unrelated settings, ordering — survives
+ * exactly as written. Reformatting someone's .env to add four lines would be a
+ * poor trade.
+ *
+ * Values are from the published plugin README (PyPI atbash-hermes-plugin 0.4.5).
+ * `ATBASH_ORG_NAME` is deliberately NOT written: its value is the operator's org,
+ * which this command has no reliable way to know, and a wrong org sends the SDK
+ * at the wrong chain. It is called out in the manual step instead.
+ */
+function mergeHermesEnv(existing) {
+    const desired = {
+        ATBASH_KEY_PATH: "$HOME/.config/atbash/guard-client-key",
+        ATBASH_ENFORCE_DECISION: "true",
+    };
+    const lines = existing === null ? [] : existing.split("\n");
+    const seen = new Set();
+    const out = lines.map((line) => {
+        const match = line.match(/^\s*(?:export\s+)?([A-Z_][A-Z0-9_]*)\s*=/);
+        const key = match?.[1];
+        if (!key || !(key in desired) || seen.has(key))
+            return line;
+        seen.add(key);
+        // Already correct — keep the operator's own formatting rather than rewriting.
+        if (line.trim() === `${key}=${desired[key]}`)
+            return line;
+        return `${key}=${desired[key]}`;
+    });
+    const missing = Object.entries(desired).filter(([key]) => !seen.has(key));
+    if (missing.length) {
+        // Separate the block we add from whatever came before it.
+        if (out.length && out[out.length - 1].trim() !== "")
+            out.push("");
+        // ASCII-only comment on purpose: .env files are read by many different
+        // parsers and a stray multi-byte dash is a free way to trip a strict one.
+        if (existing !== null)
+            out.push("# Added by `atbash setup` - Atbash Hermes plugin");
+        for (const [key, value] of missing)
+            out.push(`${key}=${value}`);
+    }
+    let text = out.join("\n");
+    if (!text.endsWith("\n"))
+        text += "\n";
+    return text;
+}
+/**
+ * Does this config's existing Atbash entry carry a key in its `env` block?
+ *
+ * True means the operator hand-wired it from the published docs and their private
+ * key is sitting in that file today. Setup takes it out, but the backup it writes
+ * first still has it — so this exists to make that sayable rather than silently
+ * relocating the leak.
+ */
+function hadInlineKey(config, serversKey = "mcpServers") {
+    const servers = isRecord(config[serversKey]) ? config[serversKey] : undefined;
+    const entry = servers && isRecord(servers[MCP_SERVER_NAME]) ? servers[MCP_SERVER_NAME] : undefined;
+    const env = entry && isRecord(entry.env) ? entry.env : undefined;
+    if (!env)
+        return false;
+    // Any 64-hex value, under any key name — not just the documented one, since a
+    // hand-edited config may well have renamed it.
+    return Object.values(env).some((v) => typeof v === "string" && /^(0x)?[0-9a-fA-F]{64}$/.test(v.trim()));
+}
+function mergeMcpServer(config, serversKey = "mcpServers") {
+    const out = { ...config };
+    const servers = { ...(isRecord(out[serversKey]) ? out[serversKey] : {}) };
+    servers[MCP_SERVER_NAME] = { ...MCP_SERVER_ENTRY, args: [...MCP_SERVER_ENTRY.args] };
+    out[serversKey] = servers;
+    return out;
+}
 /** Is `openclaw` runnable on this machine? Decides install-for-you vs print-it. */
 function hasExecutable(command) {
     const probe = (0, child_process_1.spawnSync)(process.platform === "win32" ? "where" : "which", [command], { stdio: "ignore" });
@@ -453,7 +1116,7 @@ function hasExecutable(command) {
  * writes a config for a plugin they do not have.
  */
 function buildPlan(args) {
-    const { home, privkey, pubkey, noInstall, only } = args;
+    const { home, privkey, pubkey, noInstall, only, orgName, endpoint } = args;
     const steps = [];
     const notes = [];
     const found = [];
@@ -466,7 +1129,33 @@ function buildPlan(args) {
     const alreadyThisKey = currentKeyFile !== null && parseKeyMaterial(currentKeyFile)?.privkey === privkey;
     if (!alreadyThisKey) {
         if (currentKeyFile !== null) {
-            notes.push(`${keyFile} already holds a DIFFERENT agent key. It will be backed up before being replaced — check that you meant to re-point this machine at another agent.`);
+            // The outgoing key belongs to a real agent that this machine may still be
+            // governing. A `.atbash-bak` preserves the bytes but not the identity — six
+            // months later nobody knows which agent `guard-client-key.atbash-bak` was.
+            // So archive it under its own public key: recoverable, self-identifying,
+            // and a path a runtime config can point at directly if this box needs to
+            // run two agents (both OpenClaw's `chromiaSecretPath` and Hermes'
+            // `ATBASH_KEY_PATH` take an explicit path).
+            const outgoing = parseKeyMaterial(currentKeyFile);
+            const outgoingPub = outgoing ? (0, sdk_1.derivePublicKey)(outgoing.privkey) : null;
+            if (outgoingPub) {
+                const archive = path.join(home, ".config", "atbash", "keys", `${outgoingPub}.key`);
+                if (!exists(archive)) {
+                    steps.push({
+                        kind: "write",
+                        label: `Archive the agent key already on this machine (${outgoingPub.slice(0, 12)}…)`,
+                        file: archive,
+                        mode: KEY_MODE,
+                        before: null,
+                        after: currentKeyFile,
+                        secret: true,
+                    });
+                }
+                notes.push(`${keyFile} currently holds a DIFFERENT agent (${outgoingPub.slice(0, 12)}…). It is archived to ~/.config/atbash/keys/${outgoingPub.slice(0, 12)}….key before being replaced, so that agent is recoverable — but every integration on this machine reading the default path will switch to the new agent.`);
+            }
+            else {
+                notes.push(`${keyFile} holds something this command could not parse as an agent key. It will be backed up before being replaced.`);
+            }
         }
         steps.push({
             kind: "write",
@@ -489,14 +1178,25 @@ function buildPlan(args) {
         if (wanted("openclaw")) {
             if (!noInstall) {
                 if (hasExecutable("openclaw")) {
-                    steps.push({ kind: "exec", label: `Install ${OPENCLAW_PKG}`, command: "openclaw", args: ["plugins", "install", OPENCLAW_PKG] });
+                    const spec = openclawPackageForHost(endpoint);
+                    steps.push({
+                        kind: "exec",
+                        label: spec.endsWith("@dev")
+                            ? `Install ${spec} — the development build, matching the deployment this agent was onboarded on`
+                            : `Install ${spec} — the production build`,
+                        command: "openclaw",
+                        args: ["plugins", "install", spec],
+                    });
+                    if (spec.endsWith("@dev")) {
+                        notes.push("The plugin's judge endpoint and chain ids come from the SDK it bundles, so the npm tag is an environment choice. This agent was onboarded on a development deployment, so the `@dev` build is the matching one — the production build would load, fire its hook, and fail every judge call because the agent does not exist on the chain it targets.");
+                    }
                 }
                 else {
                     steps.push({
                         kind: "manual",
                         label: "Install the OpenClaw plugin",
                         detail: "The `openclaw` command is not on this machine's PATH, so the plugin cannot be installed for you. Run this wherever the OpenClaw CLI lives:",
-                        snippet: `openclaw plugins install ${OPENCLAW_PKG}`,
+                        snippet: `openclaw plugins install ${openclawPackageForHost(endpoint)}`,
                     });
                 }
             }
@@ -507,7 +1207,7 @@ function buildPlan(args) {
                     kind: "manual",
                     label: `Enable the plugin in ${openclawConfigFile}`,
                     detail: "That file uses comments or trailing commas, and rewriting it as strict JSON would delete them. Merge this into the existing `plugins` object by hand — keep any other plugins already in `allow` and `entries`:",
-                    snippet: JSON.stringify(mergeOpenclawConfig((jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false }) ?? {}), home), null, 2),
+                    snippet: JSON.stringify(mergeOpenclawConfig((jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false }) ?? {}), home, orgName), null, 2),
                 });
             }
             else {
@@ -522,7 +1222,7 @@ function buildPlan(args) {
                         notes.push(`${openclawConfigFile} is not valid JSON — it will be backed up and rewritten from scratch, which loses whatever was in it. Fix the file first if it holds configuration you need.`);
                     }
                 }
-                const after = JSON.stringify(mergeOpenclawConfig(current, home), null, 2) + "\n";
+                const after = serializeLike(raw, mergeOpenclawConfig(current, home, orgName));
                 if (raw !== after) {
                     steps.push({
                         kind: "write",
@@ -547,47 +1247,188 @@ function buildPlan(args) {
     // judged. Setup places the key file and says so; it does not pretend to wire it.
     if (exists(home, ...HERMES_AGENT_REL)) {
         found.push("Hermes");
-        notes.push("Hermes is installed here. It shares this agent's skills and signing key, but the Atbash hook lives in the OpenClaw gateway — actions driven through the Hermes API are NOT judged, even while the OpenClaw side reports enforcing. Route that work through OpenClaw, or guard it in code with @atbash/sdk.");
-    }
-    // ── 4. MCP clients: detected and reported, never seeded.
-    // The documented @atbash/mcp wiring carries the private key as an
-    // ATBASH_AGENT_PRIVKEY env value inside the client's own config file, and that
-    // package has no key-file fallback (checked against the published 0.1.3). We
-    // will not write a private key into a file people share and sync, so this is
-    // the one place setup deliberately stays manual.
-    const mcpClients = [];
-    const seenClients = new Set();
-    for (const { label, segs } of connect_1.MCP_CONFIGS) {
-        if (seenClients.has(label))
-            continue;
-        if (exists(home, ...segs)) {
-            seenClients.add(label);
-            mcpClients.push(`${label} (${path.join(home, ...segs)})`);
-        }
-    }
-    // Claude Code and Codex live outside MCP_CONFIGS in the scanner too — same paths.
-    if (exists(home, ".claude.json"))
-        mcpClients.push(`Claude Code (${path.join(home, ".claude.json")})`);
-    if (exists(home, ".codex", "config.toml"))
-        mcpClients.push(`Codex (${path.join(home, ".codex", "config.toml")})`);
-    if (mcpClients.length) {
-        found.push(`${mcpClients.length} MCP client config${mcpClients.length === 1 ? "" : "s"}`);
-        steps.push({
-            kind: "manual",
-            label: `Optional: expose Atbash as an MCP server to ${mcpClients.length} detected client${mcpClients.length === 1 ? "" : "s"}`,
-            detail: [
-                `Detected: ${mcpClients.join(", ")}.`,
-                "",
-                "This step is NOT done for you, on purpose. The published @atbash/mcp wiring takes the agent's private key as an ATBASH_AGENT_PRIVKEY value inside the client's own config file, and that package has no key-file fallback today. Atbash will not write your private key into a file that gets synced, shared and screenshotted.",
-                "",
-                "If you want it anyway, add this yourself and fill in the key — and treat that config file as a secret from then on:",
-            ].join("\n"),
-            snippet: JSON.stringify({
-                mcpServers: {
-                    atbash: { command: "npx", args: ["-y", "@atbash/mcp"], env: { ATBASH_AGENT_PRIVKEY: "<your agent private key>" } },
-                },
-            }, null, 2),
-        });
+        if (wanted("hermes")) {
+            const envFile = path.join(home, ".hermes", ".env");
+            const raw = readTextFile(envFile);
+            const merged = mergeHermesEnv(raw);
+            if (merged !== raw) {
+                steps.push({
+                    kind: "write",
+                    label: raw === null
+                        ? "Create ~/.hermes/.env pointing the Hermes plugin at the agent key"
+                        : "Point the Hermes plugin at the agent key in ~/.hermes/.env (a merge — your other settings are kept)",
+                    file: envFile,
+                    before: raw,
+                    after: merged,
+                });
+            }
+            else {
+                notes.push(`${envFile} already points the Hermes plugin at this key — left untouched.`);
+            }
+            const hermesConfig = path.join(home, ".hermes", "config.yaml");
+            const rawConfig = readTextFile(hermesConfig);
+            const withPlugin = mergeHermesEnabledPlugins(rawConfig);
+            if (withPlugin !== rawConfig) {
+                steps.push({
+                    kind: "write",
+                    label: rawConfig === null
+                        ? "Create ~/.hermes/config.yaml enabling the plugin"
+                        : "Add the plugin to Hermes' enabled allow-list in ~/.hermes/config.yaml",
+                    file: hermesConfig,
+                    before: rawConfig,
+                    after: withPlugin,
+                });
+                notes.push("Hermes loads ONLY plugins on the `plugins.enabled` allow-list, so installing the package is not enough. `hermes plugins enable` cannot add it — that command only recognises plugin directories, not pip-installed entry points — so setup writes the list entry directly.");
+            }
+            else if (rawConfig !== null) {
+                notes.push(`${hermesConfig} already has the plugin on its enabled list — left untouched.`);
+            }
+            // Only a running gateway service can be restarted for them. An interactive
+            // session cannot, and must not be — see hermesGatewayRunning.
+            const restartable = hasExecutable("hermes") && hermesGatewayRunning();
+            // The Python package must land in the interpreter that RUNS Hermes, not
+            // whichever pip the shell happens to resolve. When we can identify that
+            // interpreter we install into it directly; when we cannot, we hand the
+            // command over rather than guess, because guessing wrong installs
+            // successfully and governs nothing.
+            if (!noInstall) {
+                const hermesPython = findHermesPython(home);
+                if (hermesPython) {
+                    const spec = `${HERMES_PKG}==${HERMES_VERSION}`;
+                    const strategy = pythonInstallStrategy(hermesPython.python, spec);
+                    if (strategy.kind === "exec") {
+                        steps.push({
+                            kind: "exec",
+                            label: `Install ${HERMES_PKG} via ${strategy.how} (interpreter found via ${hermesPython.how})`,
+                            command: strategy.command,
+                            args: strategy.args,
+                        });
+                    }
+                    else {
+                        steps.push({
+                            kind: "manual",
+                            label: "Install the Hermes plugin",
+                            detail: strategy.why,
+                            snippet: strategy.snippet,
+                        });
+                    }
+                    // The plugin pins atbash-sdk==0.4.5, which constrains cryptography — on
+                    // a venv with a newer one this install is a DOWNGRADE of a shared
+                    // dependency. Say so; it is the kind of thing that breaks the host app
+                    // and is invisible in a list of file writes.
+                    notes.push(`Installing ${HERMES_PKG} may change shared Python dependencies in that venv (it pins atbash-sdk==${HERMES_VERSION}, which constrains cryptography). Check the resolver output before confirming if Hermes depends on newer versions.`);
+                    // Installing is not enabling. Hermes keeps plugins off until told
+                    // otherwise, so without this the hook is never registered and the
+                    // agent is not governed — while every file on disk says it is.
+                    // Ordered after the install because `enable` needs the package present.
+                }
+                else {
+                    steps.push({
+                        kind: "manual",
+                        label: "Install the Hermes plugin",
+                        detail: [
+                            "The `hermes` launcher is not on this machine's PATH, so setup cannot tell which Python interpreter runs Hermes — and installing into the wrong one succeeds while governing nothing.",
+                            "",
+                            "Run this with the interpreter Hermes uses (if it runs in a virtualenv, that venv's python):",
+                        ].join("\n"),
+                        snippet: `/path/to/hermes/venv/bin/python -m pip install ${HERMES_PKG}==${HERMES_VERSION}`,
+                    });
+                }
+            }
+            if (restartable) {
+                steps.push({
+                    kind: "exec",
+                    label: "Restart the Hermes gateway so it loads the plugin",
+                    command: "hermes",
+                    args: ["gateway", "restart"],
+                });
+            }
+            else {
+                notes.push("No Hermes gateway service is running, so there is nothing to restart — the plugin loads the next time you start Hermes. (If you run it as a service, `hermes gateway install` then `hermes gateway restart`.)");
+            }
+            notes.push("Confirm the hook registered after Hermes next starts: `tail -n 50 ~/.hermes/logs/agent.log | grep -i atbash`. `hermes plugins list` will not show it — that listing only walks plugin directories.");
+            notes.push("ATBASH_ENFORCE_DECISION=true is fail-closed: if Atbash cannot be reached, the Hermes tool call is blocked rather than allowed.");
+            notes.push("ATBASH_ORG_NAME is not set for you — it decides which chain the SDK uses, and a wrong value points at the wrong one. Add it to ~/.hermes/.env yourself if your org needs it.");
+        }
+    }
+    // ── 4. MCP clients.
+    //
+    // This used to be a manual step, and the reason was specific: `@atbash/mcp`
+    // reads its identity from ATBASH_AGENT_PRIVKEY with no key-file fallback, so
+    // the documented wiring puts a raw private key inside the client's own config —
+    // `claude_desktop_config.json` and friends, files that get synced between
+    // machines and pasted into help requests. Automating that would have meant the
+    // automation's whole job was planting a secret somewhere worse.
+    //
+    // `atbash mcp` removes the reason. The client spawns the launcher, which reads
+    // the key from the 0600 file and hands it to the server through the child
+    // environment only. The config entry carries NO credential, so it is safe to
+    // write — and a config with no secret in it is strictly better than the one the
+    // operator would have hand-written from the docs.
+    if (wanted("mcp")) {
+        for (const client of detectMcpClients(home)) {
+            found.push(client.label);
+            if (client.format !== "json") {
+                // TOML (Codex) — @iarna/toml can round-trip values but not comments, and
+                // a config.toml is usually hand-maintained. Print it instead.
+                steps.push({
+                    kind: "manual",
+                    label: `Add Atbash to ${client.label}`,
+                    detail: `${client.file} is TOML, and rewriting it would drop any comments in it. Add this table by hand:`,
+                    snippet: ["[mcp_servers.atbash]", 'command = "npx"', 'args = ["--yes", "@atbash/cli", "mcp"]'].join("\n"),
+                });
+                continue;
+            }
+            const raw = readTextFile(client.file);
+            if (raw !== null && isJsonc(raw)) {
+                steps.push({
+                    kind: "manual",
+                    label: `Add Atbash to ${client.label}`,
+                    detail: `${client.file} uses comments or trailing commas, and rewriting it as strict JSON would delete them. Merge this in by hand — note it holds no key, so the file stays as non-secret as it is today:`,
+                    snippet: JSON.stringify({ mcpServers: { atbash: MCP_SERVER_ENTRY } }, null, 2),
+                });
+                continue;
+            }
+            let current = {};
+            if (raw !== null) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    if (isRecord(parsed))
+                        current = parsed;
+                }
+                catch {
+                    notes.push(`${client.file} is not valid JSON, so it was left alone. Fix the file and re-run to wire ${client.label}.`);
+                    continue;
+                }
+            }
+            const after = serializeLike(raw, mergeMcpServer(current, client.serversKey));
+            if (raw !== after) {
+                // A hand-wired entry from the old documented shape carries the private key
+                // in an `env` block. Replacing it REMOVES that secret from the live config
+                // — good — but the backup we are about to take still contains it, and an
+                // operator who does not know that has simply moved the leak to a new file.
+                if (hadInlineKey(current, client.serversKey)) {
+                    notes.push(`${client.file} currently holds your private key in an env block. Setup replaces that entry with the keyless launcher, but the .atbash-bak it leaves behind WILL still contain the key — delete that backup once you have confirmed the client works.`);
+                }
+                steps.push({
+                    kind: "write",
+                    label: `Add Atbash as an MCP server in ${client.label} (a merge — existing servers are kept${hadInlineKey(current, client.serversKey) ? ", and your key is removed from this file" : ""})`,
+                    file: client.file,
+                    before: raw,
+                    after,
+                });
+            }
+            else {
+                notes.push(`${client.label} already has the Atbash MCP server — left untouched.`);
+            }
+        }
+        if (found.some((f) => f !== "OpenClaw" && f !== "Hermes")) {
+            notes.push("Restart any MCP client that was changed — clients read their server list at startup.");
+            // A client whose first launch of the server takes ~12s can report a startup
+            // timeout that looks like a broken config. Say so, so the first thing an
+            // operator does is retry rather than undo the wiring.
+            notes.push("The first time a client starts the Atbash server it takes ~10-15s while npx caches the package; after that it is about a second. If a client reports a startup timeout on the very first try, start it again.");
+        }
     }
     if (!found.length) {
         notes.push("No OpenClaw, Hermes or MCP client configuration was found under this home directory. The key file is still placed, so an SDK-level integration in your own code will find it — but nothing on this machine is wired to a runtime.");
@@ -771,10 +1612,27 @@ function applyPlan(plan) {
             continue;
         const label = `${step.command} ${step.args.join(" ")}`;
         const run = (0, child_process_1.spawnSync)(step.command, step.args, { stdio: "inherit" });
-        if (run.status === 0)
+        // Three distinct outcomes, and they used to collapse into one misleading
+        // message. `spawnSync` reports a binary it could not launch via `.error` with
+        // `status` left null — so an ENOENT printed "exited on a signal", which reads
+        // like the plugin installer crashed rather than "that command is not here".
+        // The distinction matters because only one of them is the operator's to fix,
+        // and the fix is to run it somewhere the CLI exists.
+        if (run.error) {
+            const missing = run.error.code === "ENOENT";
+            result.failures.push(missing
+                ? `${step.command} is not on this machine's PATH, so \`${label}\` did not run. Everything else above was applied — run that one command wherever the ${step.command} CLI lives.`
+                : `${label} could not start: ${run.error.message}`);
+        }
+        else if (run.status === 0) {
             result.ran.push(label);
-        else
-            result.failures.push(`${label} exited ${run.status ?? "on a signal"}`);
+        }
+        else if (run.signal) {
+            result.failures.push(`${label} was killed by ${run.signal}`);
+        }
+        else {
+            result.failures.push(`${label} exited with code ${run.status}`);
+        }
     }
     return result;
 }
@@ -795,12 +1653,19 @@ async function verifyRegistration(privkey, endpoint) {
         return { state: "unknown", reason: err instanceof Error ? err.message : String(err) };
     }
 }
-/** y/N confirmation. Anything but an explicit yes is a no. */
-async function confirm(question) {
+/**
+ * Confirmation prompt. Defaults to NO — anything but an explicit yes is a no —
+ * except where `defaultYes` is set, which is only for questions where the safe
+ * answer is also the common one (reusing the key already on this machine).
+ */
+async function confirm(question, defaultYes = false) {
     const { createInterface } = await Promise.resolve().then(() => __importStar(require("node:readline")));
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const answer = await new Promise((r) => rl.question(question, (a) => { rl.close(); r(a); }));
-    return /^y(es)?$/i.test(answer.trim());
+    const trimmed = answer.trim();
+    if (!trimmed)
+        return defaultYes;
+    return /^y(es)?$/i.test(trimmed);
 }
 // ── The command ─────────────────────────────────────────────────────────────
 function registerSetupCommand(program) {
@@ -812,6 +1677,7 @@ function registerSetupCommand(program) {
         .option("--keys-dir <dir>", "Directory holding the key file, e.g. ~/Downloads")
         .option("--host <url>", "Atbash deployment to check the agent's registration against")
         .option("--runtime <ids...>", "Only configure these runtimes (currently: openclaw)")
+        .option("--org-name <name>", "Organization the agent was onboarded under, exactly as the dashboard shows it — the plugin resolves which chain to query from this")
         .option("--dry-run", "Show exactly which files would change, and the diffs, then exit WITHOUT writing anything")
         .option("-y, --yes", "Do not ask for confirmation before writing")
         .option("--no-install", "Do not install any package; write the key file and configs only")
@@ -852,7 +1718,7 @@ function registerSetupCommand(program) {
         console.log(chalk_1.default.dim(`\n  Agent key source: ${keySource.from}`));
         // ── Registration check. Only the public key crosses the network.
         if (!opts.skipVerify) {
-            const endpoint = (opts.host || (0, sdk_1.resolve)("judgeEndpoint") || connect_1.DEFAULT_HOST || sdk_1.DEFAULT_ENDPOINT).replace(/\/$/, "");
+            const endpoint = (opts.host || (0, sdk_1.resolve)("judgeEndpoint") || atbash_targets_1.DEFAULT_HOST || sdk_1.DEFAULT_ENDPOINT).replace(/\/$/, "");
             let hostname = "";
             try {
                 hostname = new URL(endpoint).hostname.toLowerCase();
@@ -864,7 +1730,8 @@ function registerSetupCommand(program) {
             // An unrecognized host could answer "registered" for any key, which is
             // exactly the confirmation this check exists to provide. Exact hostname
             // match, never a suffix — "atbash.ai.evil.com" must not pass.
-            if (!connect_1.KNOWN_HOSTS.has(hostname) && !opts.allowUnrecognizedHost) {
+            const recognizedHost = atbash_targets_1.KNOWN_HOSTS.has(hostname);
+            if (!recognizedHost && !opts.allowUnrecognizedHost) {
                 console.error(chalk_1.default.red(`\n  ${hostname} is not a recognized Atbash deployment.`) +
                     chalk_1.default.dim("\n  Re-run with --allow-unrecognized-host if you meant to point at a self-hosted instance,\n  or with --skip-verify to configure this machine without any network call.\n"));
                 process.exit(1);
@@ -872,7 +1739,21 @@ function registerSetupCommand(program) {
             const verdict = await verifyRegistration(privkey, endpoint);
             if (verdict.state === "unregistered") {
                 console.error(chalk_1.default.red("\n  That agent is not registered on this deployment.") +
-                    chalk_1.default.dim(`\n  Public key: ${pubkey}\n  Finish onboarding first — wiring a runtime to an unregistered agent leaves it\n  looking governed while the plugin can never get a verdict.\n`));
+                    chalk_1.default.dim(`\n  Public key:  ${pubkey}\n  Key came from: ${keySource.from}\n`));
+                // The likeliest cause is not "you skipped onboarding" — it is "this is a
+                // key you did not choose". Say so when the key was found rather than
+                // supplied, because the fix is completely different.
+                if (/existing key file|atbash config/.test(keySource.from)) {
+                    console.error(chalk_1.default.yellow("  This is a key that was already on this machine, not one you supplied.") +
+                        chalk_1.default.dim("\n  If you are onboarding a DIFFERENT agent, pass its key explicitly:" +
+                            "\n    --key <64-hex>        the key shown in the browser" +
+                            "\n    --keys-dir ~/Downloads    the key file you saved" +
+                            "\n  Or re-run and answer 'n' when asked whether to use the existing key.\n"));
+                }
+                else {
+                    console.error(chalk_1.default.dim("  Finish onboarding first — wiring a runtime to an unregistered agent leaves it\n" +
+                        "  looking governed while the plugin can never get a verdict.\n"));
+                }
                 process.exit(1);
             }
             if (verdict.state === "unknown") {
@@ -883,9 +1764,22 @@ function registerSetupCommand(program) {
                     return;
                 }
             }
-            else {
+            else if (recognizedHost) {
                 console.log(chalk_1.default.green(`  Agent is registered on ${hostname}.`));
             }
+            else {
+                // --allow-unrecognized-host is a real bypass, and its most dangerous
+                // property is that the check still PRINTS a reassuring answer. A host
+                // chosen by an attacker returns "registered" for any key at all, so a
+                // "✓ registered" line here would be the attacker's own claim wearing
+                // Atbash's voice. Never let that line stand unqualified: say the answer
+                // came from an unvouched-for server, so a talked-into-it operator sees
+                // the one thing that would tell them something is wrong.
+                console.log(chalk_1.default.yellow(`  ${hostname} answered "registered" — but this is NOT a recognized Atbash deployment.`));
+                console.log(chalk_1.default.yellow("  A registration check against an unrecognized host proves nothing: any server") +
+                    chalk_1.default.yellow("\n  can answer \"registered\" for any key. Treat this as UNVERIFIED."));
+                console.log(chalk_1.default.dim(`  Recognized deployments: ${[...atbash_targets_1.KNOWN_HOSTS].join(", ")}`));
+            }
         }
         // ── Plan, show, then (maybe) apply.
         const plan = buildPlan({
@@ -894,7 +1788,18 @@ function registerSetupCommand(program) {
             pubkey,
             noInstall: opts.install === false,
             only: opts.runtime ?? [],
+            orgName: opts.orgName,
+            // The same host the registration check used, so the plugin build and the
+            // chain the agent lives on cannot disagree.
+            endpoint: opts.host || (0, sdk_1.resolve)("judgeEndpoint") || atbash_targets_1.DEFAULT_HOST,
         });
+        // Private-chain orgs need it and it cannot be derived here, so say so
+        // rather than writing a config that resolves the wrong chain in silence.
+        if (!opts.orgName?.trim() && plan.found.includes("OpenClaw")) {
+            console.log(chalk_1.default.dim("\n  No --org-name given. The OpenClaw plugin resolves which chain to query from it,") +
+                chalk_1.default.dim("\n  so add it yourself if your org is on a private chain (harmless otherwise):") +
+                chalk_1.default.dim("\n    plugins.entries.atbash-openclaw.config.orgName\n"));
+        }
         renderPlan(plan, pubkey);
         const changes = plan.steps.filter((s) => s.kind === "write" || s.kind === "exec");
         if (dryRun) {
@@ -933,6 +1838,36 @@ function registerSetupCommand(program) {
             process.exitCode = 1;
             return;
         }
+        // ── Check, do not assume.
+        //
+        // Every step reporting success is not the same as the runtime having
+        // picked the plugin up, and this command used to print "Done" on the
+        // strength of the former. On a real machine the install succeeded, the
+        // entry point was correct, and Hermes still listed nothing — so the agent
+        // was ungoverned behind a green summary. Where a runtime can be asked, ask.
+        if (plan.found.includes("Hermes") && wantedRuntime("hermes", opts.runtime ?? [])) {
+            const state = hermesPluginState(home);
+            if (state === "configured") {
+                console.log(chalk_1.default.green("\n  Hermes is configured to load the plugin.") +
+                    chalk_1.default.dim("\n  It takes effect on the next Hermes start. Confirm the hook registered:") +
+                    chalk_1.default.dim("\n    tail -n 50 ~/.hermes/logs/agent.log | grep -i atbash") +
+                    chalk_1.default.dim("\n  (`hermes plugins list` will NOT show it — that listing only walks plugin") +
+                    chalk_1.default.dim("\n  directories and cannot see a pip-installed one.)\n"));
+            }
+            else if (state === "not-enabled") {
+                console.log(chalk_1.default.yellow("\n  The plugin is installed but NOT on Hermes' enabled allow-list — this agent is not governed.") +
+                    chalk_1.default.dim("\n  Hermes loads only what is listed. Add it to ~/.hermes/config.yaml:") +
+                    chalk_1.default.dim("\n    plugins:\n      enabled:\n        - " + HERMES_PLUGIN_ENTRY + "\n"));
+                process.exitCode = 1;
+                return;
+            }
+            else if (state === "not-installed") {
+                console.log(chalk_1.default.yellow("\n  The plugin is not installed in the interpreter that runs Hermes — this agent is not governed.\n"));
+                process.exitCode = 1;
+                return;
+            }
+            // "unknown": nothing readable to judge by, so claim nothing.
+        }
         console.log(chalk_1.default.green("\n  Done.") + chalk_1.default.dim(" Restart the runtime so it loads the hook, then re-scan this machine"));
         console.log(chalk_1.default.dim("  from the agent's page in the dashboard to confirm it reports as enforcing.\n"));
     });