@atbash/cli 0.6.0-dev.1 → 0.6.1-dev.2

package/dist/commands/setup.js

@@ -42,7 +42,22 @@ exports.keyCandidatesInDir = keyCandidatesInDir;
 exports.resolveKeySource = resolveKeySource;
 exports.keyFileContents = keyFileContents;
 exports.isJsonc = isJsonc;
+exports.openclawEntryDecision = openclawEntryDecision;
 exports.mergeOpenclawConfig = mergeOpenclawConfig;
+exports.openclawInstallState = openclawInstallState;
+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.openclawPatchPayload = openclawPatchPayload;
 exports.buildPlan = buildPlan;
 exports.lineDiff = lineDiff;
 exports.renderPlan = renderPlan;
@@ -53,10 +68,13 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const win_exec_1 = require("../shared/win-exec");
 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");
+const openclaw_runtime_1 = require("../shared/openclaw-runtime");
 /**
  * `atbash setup` — the write half of onboarding.
  *
@@ -84,9 +102,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.
@@ -109,17 +129,160 @@ const OPENCLAW_CONFIG_REL = [".openclaw", "openclaw.json"];
 const OPENCLAW_EXTENSIONS_REL = [".openclaw", "extensions"];
 const HERMES_AGENT_REL = [".hermes", "hermes-agent"];
 /**
- * The OpenClaw plugin, and the entry key it registers itself as.
+ * The OpenClaw plugin package.
  *
- * The entry key really is `openclaw` — that is what `@atbash/atbash-openclaw`
- * registers as, not a copy-paste slip. Installs of the earlier
- * `@atbash/atbash-plugin` register under `atbash-plugin`, and the dashboard's
- * capability scan recognizes BOTH. So an existing config carrying the legacy key
- * is already governed and must not be given a second, duplicate entry.
+ * The doc comment here used to assert "the entry key really is `openclaw` … not
+ * a copy-paste slip", which directly contradicts OPENCLAW_ENTRY three lines
+ * below and was the belief that made every config an earlier release wrote inert.
+ * Installs of the earlier `@atbash/atbash-plugin` register under
+ * `atbash-plugin`, and the dashboard's capability scan recognizes both that and
+ * `atbash-openclaw` — so an existing config carrying the legacy key 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";
+/**
+ * Drop the `hooks` block from a plugin entry.
+ *
+ * ⚠️ WHETHER `hooks` IS VALID DEPENDS ON THE OPENCLAW VERSION, and this note
+ * used to state the 2026.2.x answer as a fact about OpenClaw itself.
+ *
+ * On 2026.2.1 it is not a key at all, and an unrecognized entry key is fatal —
+ * verified by feeding a generated config through OPENCLAW_CONFIG_PATH:
+ *
+ *   - plugins.entries.atbash-openclaw: Unrecognized key: "hooks"
+ *
+ * Rejecting means refusing to load ANY config, which also makes
+ * `openclaw plugins install` exit 1. But the key was ADDED later. Straight out
+ * of 2026.6.6's own `openclaw config schema`, an entry accepts
+ * `enabled | hooks | subagent | llm | config`, and `hooks` accepts
+ * `allowPromptInjection | allowConversationAccess | timeoutMs | timeouts`.
+ *
+ * We still strip it and never write it, now on evidence rather than on the claim
+ * above:
+ *
+ *  1. Nothing under `hooks` is required — the schema's `required` list is empty.
+ *  2. It gates hook FAMILIES this plugin does not use. `allowConversationAccess`
+ *     covers `before_agent_run`, `llm_input`, `llm_output`, `agent_end` and
+ *     friends; `allowPromptInjection` covers `before_prompt_build`. The plugin
+ *     registers exactly one hook, `before_tool_call`, which is in neither
+ *     (verified by grepping the installed plugin, not by reading its README).
+ *  3. Writing it would break every 2026.2.x machine for no gain, and those are
+ *     real — the reference box for these attestations is one.
+ *
+ * ⚠️ RE-CHECK IF THE PLUGIN EVER ADDS A SECOND HOOK. The schema says
+ * "Non-bundled plugins must opt in explicitly", so a new conversation-reading
+ * hook would be silently denied on 2026.6.6+ with no config error to notice: the
+ * plugin would load, still gate tool calls, and quietly see nothing else.
+ */
+function stripInvalidHooks(entry, supported = false) {
+    // ⚠️ ONLY WHERE THE KEY IS ACTUALLY INVALID. This used to delete `hooks`
+    // unconditionally, which is right on 2026.2.x — where an unrecognized entry key
+    // makes OpenClaw refuse the whole config — and destructive on 2026.6.6+, where
+    // the key is valid, optional and undeprecated.
+    //
+    // `hooks.timeoutMs` bounds this plugin's hook latency "without changing plugin
+    // code". An operator who sets it has made a deliberate choice, and silently
+    // removing it on the next run is not repair — it also contradicts the rule
+    // stated further down this file: an existing entry is touched as little as
+    // possible.
+    //
+    // Defaults to `false` (strip), so a caller that cannot determine support gets
+    // the fail-safe behaviour. A lost timeout value is a far smaller harm than a
+    // config OpenClaw will not load at all.
+    if (!supported && "hooks" in entry)
+        delete entry.hooks;
+    return entry;
+}
+/**
+ * The one hook permission worth WRITING: deny this plugin prompt mutation.
+ *
+ * WHY THIS IS NOT DECORATION. `allowPromptInjection` DEFAULTS TO ALLOWED for
+ * non-bundled plugins — OpenClaw's plugin-hooks docs say so in as many words
+ * ("It defaults to allowed") — so without this key the guard holds permission to
+ * mutate prompts via `before_prompt_build`, `agent_turn_prepare`,
+ * `heartbeat_prompt_contribution` and durable next-turn injections. It uses none
+ * of them: it registers exactly one hook, `before_tool_call`.
+ *
+ * The gate is enforced by OPENCLAW, not by the plugin, so the denial holds even
+ * if the plugin or one of its dependencies is compromised — and it bundles a
+ * fair few (`@atbash/sdk`, the whole `@opentelemetry` tree). A guard being
+ * visibly constrained by the runtime it guards is the right posture, and it is
+ * auditable: someone reading the config can see the boundary stops at tool calls.
+ *
+ * ⚠️ It does NOT affect `before_tool_call` — "No conversation-access opt-in is
+ * needed for `before_tool_call`", and this gate covers prompt-mutation hooks
+ * only. There is no functional risk to what the plugin actually does.
+ *
+ * ⚠️ AND WE DELIBERATELY DO NOT WRITE `allowConversationAccess: false`. That one
+ * already defaults to denied ("Non-bundled plugins must opt in explicitly"), so
+ * writing it changes nothing — and writing keys that change nothing is exactly
+ * the habit that produced this file's worst bugs: the entry schema is
+ * `additionalProperties: false`, so every key we write is a liability we then own
+ * on every OpenClaw version. It would also silently deny a future
+ * conversation-reading hook, with an explicit `false` in the config to mislead
+ * whoever debugs it.
+ */
+const HOOK_PERMISSIONS = { allowPromptInjection: false };
+/**
+ * Add the denial without disturbing anything the operator set.
+ *
+ * Fills the key in only when it is ABSENT. An operator who wrote
+ * `allowPromptInjection: true` meant it, and overriding a deliberate choice is
+ * not this command's business — "touch an existing entry as little as possible"
+ * applies to permissions too. Their `timeoutMs`/`timeouts` are untouched either
+ * way.
+ */
+function withHookPermissions(entry, supported) {
+    if (!supported)
+        return entry;
+    const existing = isRecord(entry.hooks) ? entry.hooks : {};
+    return { ...entry, hooks: { ...HOOK_PERMISSIONS, ...existing } };
+}
+/** 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 +371,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 +418,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 +458,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 +541,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 +561,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 +607,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 {
@@ -383,62 +652,865 @@ function isJsonc(text) {
  *
  * A MERGE, not a replacement — that distinction is the whole reason this command
  * exists. Other plugins already in `allow`, `load.paths` and `entries` are
- * preserved, and an entry from the legacy `@atbash/atbash-plugin` install is
- * updated where it stands rather than being shadowed by a duplicate: the
- * dashboard scan recognizes both keys, so two entries would mean two hooks.
+ * preserved.
+ *
+ * WHICH entry is governed depends on what is being installed. When this run
+ * installs `@atbash/atbash-openclaw` — every run that is not `--no-install` —
+ * the plugin that ends up on disk registers as `atbash-openclaw`, so that is the
+ * entry that gets the config, and a legacy `atbash-plugin` entry is STOOD DOWN
+ * rather than configured. Only a `--no-install` run on a box whose sole entry is
+ * the legacy one keeps writing to the legacy key: there, nothing is arriving to
+ * replace it, and switching it off would leave the machine unguarded.
  *
  * `load.paths` gets the real absolute extension path. The published docs show a
  * `<your-username>` placeholder that people paste verbatim, producing a path that
  * does not exist and a plugin that never loads.
  */
-function mergeOpenclawConfig(config, home) {
+/**
+ * WHICH entry this run governs, and whether a legacy one is being stood down.
+ *
+ * Extracted so the hand-merge and the `openclaw config patch` payload cannot
+ * disagree. Two implementations of this decision is exactly how a build ended up
+ * writing the modern plugin's `orgName` onto the LEGACY entry — whose schema is
+ * closed and has no such field — so OpenClaw rejected the whole file and the run
+ * broke its own install step.
+ *
+ * An entry is not the only way the legacy plugin is present: `plugins.installs`
+ * records it independently, and an installed, allowed plugin loads with its
+ * defaults whether or not anyone wrote an entry for it.
+ */
+function openclawEntryDecision(config, opts = {}) {
+    const installsModern = opts.installsModern !== false;
+    const plugins = isRecord(config.plugins) ? config.plugins : {};
+    const entries = isRecord(plugins.entries) ? plugins.entries : {};
+    const installs = isRecord(plugins.installs) ? plugins.installs : {};
+    const legacy = OPENCLAW_LEGACY_ENTRY in entries || OPENCLAW_LEGACY_ENTRY in installs;
+    const modern = OPENCLAW_ENTRY in entries;
+    // Only a --no-install run on a box whose sole entry is the legacy one keeps
+    // writing to the legacy key: there, nothing is arriving to replace it, and
+    // switching it off would leave the machine unguarded.
+    const useLegacy = !installsModern && legacy && !modern;
+    return {
+        entryKey: useLegacy ? OPENCLAW_LEGACY_ENTRY : OPENCLAW_ENTRY,
+        useLegacy,
+        legacy,
+        standDownLegacy: !useLegacy && legacy,
+    };
+}
+function mergeOpenclawConfig(config, home, orgName, opts = {}) {
+    const installsModern = opts.installsModern !== false;
+    // Whether THIS machine's OpenClaw accepts `hooks` on a plugin entry. Probed
+    // from `openclaw config schema` by the caller; absent means "assume not", which
+    // is the fail-safe direction. See stripInvalidHooks.
+    const hooksSupported = opts.hooksSupported === true;
     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;
-    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 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,
+    // Which entry is this install governed under, and does one already exist?
+    //
+    // ⚠️ `legacy && !modern` used to be enough to pick the legacy key, and it broke
+    // a real machine. Setup installs `@atbash/atbash-openclaw`, then wrote that
+    // plugin's config — `orgName` included — onto the LEGACY `atbash-plugin`
+    // entry. The legacy plugin's manifest declares `"additionalProperties": false`
+    // and knows no `orgName`, so OpenClaw rejected the whole file —
+    //
+    //   Invalid config at ~/.openclaw/openclaw.json:
+    //     - plugins.entries.atbash-plugin.config: invalid config: <root>:
+    //       must NOT have additional properties
+    //
+    // — refused to load any config, and `openclaw plugins install` then exited 1.
+    // The run broke its own install step and half-applied, while the plugin it did
+    // install sat there with no config at all.
+    //
+    // An entry is not the only way the legacy plugin is present: `plugins.installs`
+    // records it independently, and a plugin that is installed and allowed loads
+    // with its defaults whether or not anyone wrote an entry for it.
+    const { entryKey, useLegacy, legacy } = openclawEntryDecision(config, { installsModern });
+    const existing = isRecord(entries[entryKey]) ? entries[entryKey] : null;
+    // Stand the legacy plugin down when the modern one is taking over. Two live
+    // entries means two hooks, so every tool call would be judged twice — against
+    // two different SDK versions.
+    //
+    // The entry is reduced to `{ enabled: false }`. Leaving its `config` behind as
+    // a way back looks considerate and is not: OpenClaw then warns
+    //
+    //   - plugins.entries.atbash-plugin: plugin disabled (not in allowlist) but
+    //     config is present
+    //
+    // on EVERY config load, and it loads many times per command — a real machine
+    // printed that line hundreds of times for a single `openclaw plugins install`,
+    // burying the output the operator was reading. The way back is the timestamped
+    // `.atbash-bak` this command already writes beside the file.
+    if (!useLegacy && legacy) {
+        entries[OPENCLAW_LEGACY_ENTRY] = { enabled: false };
+    }
+    // ⚠️ 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 rewrote an
+    // absolute `chromiaSecretPath` to a `~` one for no gain.
+    //
+    // A plugin that is already installed and registered does not need `load`
+    // re-declared — it is working. The only thing setup has any business changing
+    // is that it is switched on, allowed, and pointed at the right key.
+    if (existing) {
+        const existingConfig = isRecord(existing.config) ? existing.config : {};
+        // The exception to leaving an existing entry alone: strip `hooks`. "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.
+        const repaired = withHookPermissions(stripInvalidHooks({ ...existing }, hooksSupported), hooksSupported);
+        entries[entryKey] = {
+            ...repaired,
+            enabled: true,
+            config: {
+                ...existingConfig,
+                enabled: true,
+                enforceDecision: true,
+                ...keyPathUpdate(existingConfig, home),
+                // `orgName` exists only in the modern plugin's configSchema. The legacy
+                // one closes with `"additionalProperties": false`, so writing it there
+                // invalidates the entire file — the failure this whole branch guards.
+                ...(entryKey === OPENCLAW_LEGACY_ENTRY ? {} : orgNameUpdate(existingConfig, orgName)),
+            },
+        };
+        plugins.entries = entries;
+        // An allowlist that does not name this entry means the plugin never loads,
+        // however well configured it is — the modern entry arriving on a box whose
+        // `allow` still says only `atbash-plugin` is exactly that. Only ever an
+        // adjustment to a list that already exists: conjuring one where there was
+        // none would newly restrict every other plugin on the machine.
+        const reconciled = reconcileAllow(plugins.allow, entryKey, !useLegacy && legacy);
+        if (reconciled)
+            plugins.allow = reconciled;
+        const prunedLoad = pruneRetiredLoadPath(plugins.load, home);
+        if (prunedLoad)
+            plugins.load = prunedLoad;
+        out.plugins = plugins;
+        return out;
+    }
+    // No entry yet — configure the ENTRY, and nothing else.
+    //
+    // ⚠️ THIS IS THE FRESH-INSTALL PATH, AND IT USED TO CREATE BOTH
+    // `plugins.allow` AND `plugins.load.paths`. That is the config a reporter got
+    // on a clean OpenClaw 2026.6.6, which then refused to load it:
+    //
+    //   - plugins.load.paths: plugin path not found:
+    //     /Users/me/.openclaw/extensions/atbash-openclaw
+    //   - plugins.allow: plugins.allow now gates bundled provider discovery by
+    //     default; run "openclaw doctor --fix" …
+    //
+    // `load.paths` was the fatal half, and note WHY it could never have worked: it
+    // named `~/.openclaw/extensions/<id>`, which is the 2026.2.x plugin store.
+    // 2026.6.x installs plugins as npm dependencies of `~/.openclaw` — into
+    // `~/.openclaw/node_modules` — and leaves `extensions/` empty. So we wrote a
+    // path OpenClaw was never going to create, and a `load.paths` entry naming a
+    // missing directory fails the ENTIRE config, which then takes down the
+    // `openclaw plugins install` in this very same run. The command broke its own
+    // install step and left behind a dangling entry that `openclaw doctor --fix`
+    // then offers to delete — silently un-governing the agent.
+    //
+    // Neither key is ours to write:
+    //
+    //  - `openclaw plugins install` records where it put the plugin and loads from
+    //    that record. The location has moved twice in six months across four
+    //    channels; we cannot know it and must not guess it.
+    //  - `allow` only matters if the operator KEEPS such a list, and newer builds
+    //    have repurposed it to gate bundled provider discovery. Creating one where
+    //    there was none newly restricts every other plugin on the machine — a side
+    //    effect nobody asked this command for.
+    //
+    // Existing lists are still MAINTAINED, here and in the branch above, because an
+    // `allow` list that omits this entry means the plugin never loads however well
+    // configured it is. Adjust what is there; conjure nothing.
+    const reconciledAllow = reconcileAllow(plugins.allow, entryKey, !useLegacy && legacy);
+    if (reconciledAllow)
+        plugins.allow = reconciledAllow;
+    // A retired path is still pruned when present: that entry is fatal on every
+    // version, so removing it is repair rather than assertion.
+    const prunedLoad = pruneRetiredLoadPath(plugins.load, home);
+    if (prunedLoad)
+        plugins.load = prunedLoad;
+    // `orgName` is the modern plugin's field. This branch can still land on the
+    // legacy key — a `--no-install` run against a box where the old plugin is in
+    // `plugins.installs` but nobody ever wrote it an entry — and its configSchema
+    // is closed, so the field would invalidate the file.
+    //
+    // No `hooks` block: see OPENCLAW_ENTRY_KEYS. It is not a key OpenClaw has.
+    entries[entryKey] = withHookPermissions({
         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("/")}`,
+            ...(entryKey !== OPENCLAW_LEGACY_ENTRY && orgName?.trim() ? { orgName: orgName.trim() } : {}),
         },
-        hooks: {
-            ...existingHooks,
-            allowConversationAccess: true,
-            allowPromptInjection: true,
-        },
-    };
+    }, hooksSupported);
     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 };
+}
+/**
+ * `plugins.allow`, adjusted — or `undefined` when there is no list to adjust.
+ *
+ * OpenClaw loads a plugin only if the allowlist names it, so an entry that is
+ * perfectly configured under a name the list does not carry does nothing at all.
+ * That is the state a legacy box lands in the moment the modern entry appears:
+ * `allow` still reads `["atbash-plugin"]`.
+ *
+ * Returns `undefined` rather than a fresh array when no list exists, because an
+ * allowlist conjured out of nothing does not just permit this plugin — it newly
+ * restricts every other plugin on the machine.
+ */
+function reconcileAllow(current, entryKey, dropLegacy) {
+    if (!Array.isArray(current))
+        return undefined;
+    const allow = current.filter((name) => !(dropLegacy && String(name) === OPENCLAW_LEGACY_ENTRY));
+    if (!allow.some((name) => String(name) === entryKey))
+        allow.push(entryKey);
+    return allow;
+}
+/**
+ * `plugins.load`, with a path pointing at the retired plugin id dropped.
+ *
+ * `@atbash-plugin/openclaw` registered as `openclaw` and no longer publishes, so
+ * `<home>/.openclaw/extensions/openclaw` is a directory that cannot exist. A
+ * `load.paths` entry naming a missing directory is not inert — OpenClaw fails
+ * the whole config on it:
+ *
+ *   - plugins.load.paths: plugin: plugin path not found:
+ *     /Users/me/.openclaw/extensions/openclaw
+ *
+ * which then takes down `openclaw plugins install` along with everything else.
+ * Only ever removes that one exact path; any other path is the operator's.
+ */
+function pruneRetiredLoadPath(current, home) {
+    if (!isRecord(current))
+        return undefined;
+    if (!Array.isArray(current.paths))
+        return current;
+    const retired = path.join(home, ...OPENCLAW_EXTENSIONS_REL, OPENCLAW_RETIRED_ENTRY);
+    const paths = current.paths.filter((p) => typeof p !== "string" || path.resolve(expandHome(p.trim(), home)) !== path.resolve(retired));
+    return paths.length === current.paths.length ? current : { ...current, paths };
+}
+/**
+ * What `openclaw plugins install` would actually do with this spec.
+ *
+ * ⚠️ That command cannot overwrite. If the extension directory is there it
+ * aborts —
+ *
+ *   plugin already exists: ~/.openclaw/extensions/atbash-openclaw
+ *   (delete it first)
+ *
+ * — and exits 1. A plan that lists the install unconditionally therefore fails
+ * on its SECOND run against the same machine, and setup then reports "this
+ * machine is NOT fully wired" about a machine that is completely wired. Setup is
+ * meant to be re-runnable; a step that can only ever succeed once is not.
+ *
+ * There is no `plugins uninstall` in OpenClaw 2026.2.1 — the subcommands are
+ * list/info/enable/disable/install/update/doctor — so the way to refresh an
+ * existing install is `plugins update <id>`, which re-resolves the recorded spec
+ * and reports "up to date" when there is nothing to do.
+ */
+/**
+ * The plugin version recorded by a 2026.7.x npm-project install, if there is one.
+ *
+ * `openclaw plugins install` creates `~/.openclaw/npm/projects/<mangled>/` whose
+ * package.json pins the plugin exactly:
+ *
+ *   dependencies: { "@atbash/atbash-openclaw": "0.1.14-dev.0" }
+ *
+ * The directory name is derived from the package name (`@atbash/atbash-openclaw`
+ * → `atbash-atbash-openclaw-<hash>`), which is how the plugin is told apart from
+ * `@opentelemetry/api`, a dependency OpenClaw adds to every one of these projects.
+ */
+function openclawNpmProjectVersion(home) {
+    const mangle = (name) => name.replace(/^@/, "").replace(/[/]/g, "-");
+    const projectsDir = path.join(home, ".openclaw", "npm", "projects");
+    let projects = [];
+    try {
+        projects = fs.readdirSync(projectsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return undefined;
+    }
+    for (const project of projects) {
+        const raw = readTextFile(path.join(projectsDir, project, "package.json"));
+        if (raw === null)
+            continue;
+        let deps = {};
+        try {
+            const parsed = JSON.parse(raw);
+            deps = isRecord(parsed.dependencies) ? parsed.dependencies : {};
+        }
+        catch {
+            continue;
+        }
+        for (const [name, version] of Object.entries(deps)) {
+            if (!project.startsWith(mangle(name)))
+                continue;
+            if (name !== OPENCLAW_PKG && name !== OPENCLAW_ENTRY)
+                continue;
+            if (typeof version === "string")
+                return version;
+        }
+    }
+    return undefined;
+}
+function openclawInstallState(home, spec) {
+    // ── The 2026.7.x layout FIRST: it is what a current install produces, and it
+    // is authoritative whenever it is present.
+    //
+    // ⚠️ THIS FUNCTION USED TO READ ONLY `extensions/` + `plugins.installs`, and on
+    // a real 2026.7.1 machine that produced actively harmful advice. That machine
+    // carried BOTH a stale `extensions/atbash-openclaw` left from the 2026.2.x era
+    // AND the real install under `npm/projects/`. The old code saw the stale
+    // directory (installed = true), found no `plugins.installs` record — 2026.7.x
+    // keeps that in `~/.openclaw/state/openclaw.sqlite` — and concluded "a
+    // different, unidentifiable build is installed". Setup then told the operator
+    // to `rm -rf ~/.openclaw/extensions/atbash-openclaw` and reinstall, on a
+    // machine whose plugin was installed, correct, and loading. The release
+    // immediately before had planned a plain `plugins update` for the same box.
+    const projectVersion = openclawNpmProjectVersion(home);
+    if (projectVersion) {
+        // The npm project records a VERSION, not the `@dev`/plain TAG that was asked
+        // for, so compare lineage the way verifyOpenclawPlugin does: a `-dev.` build
+        // satisfies `@dev` and only that. Comparing the literal spec string here
+        // would report every correct install as a mismatch.
+        const wantsDev = /@dev$/.test(spec);
+        return { installed: true, sameSpec: wantsDev === /-dev\./.test(projectVersion), version: projectVersion };
+    }
+    if (!exists(path.join(home, ...OPENCLAW_EXTENSIONS_REL, OPENCLAW_ENTRY))) {
+        return { installed: false, sameSpec: false };
+    }
+    const raw = readTextFile(path.join(home, ...OPENCLAW_CONFIG_REL));
+    let record = null;
+    if (raw !== null) {
+        const parsed = jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false });
+        const installs = isRecord(parsed) && isRecord(parsed.plugins) ? parsed.plugins.installs : null;
+        if (isRecord(installs) && isRecord(installs[OPENCLAW_ENTRY])) {
+            record = installs[OPENCLAW_ENTRY];
+        }
+    }
+    return {
+        installed: true,
+        // No record means an install this command did not make and cannot identify.
+        // Treated as a mismatch: telling someone to `update` a plugin whose origin
+        // is unknown could quietly keep them on a build for the wrong chain.
+        sameSpec: typeof record?.spec === "string" && record.spec === spec,
+        version: typeof record?.version === "string" ? record.version : undefined,
+    };
+}
+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, win_exec_1.spawnPortable)("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;
+}
+/** The exec-step id the OpenClaw config write depends on. See Step.requires. */
+const OPENCLAW_INSTALL_ID = "openclaw-install";
+/**
+ * The change we want, expressed as a PATCH rather than a whole file.
+ *
+ * `openclaw config patch` merges objects recursively and validates in one write,
+ * so this is intent — "this entry should exist and look like this" — instead of
+ * "here are the complete new bytes of your config". That difference is what makes
+ * it survive the things that kept defeating us from outside: OpenClaw's own
+ * format changes, key renames, comment preservation, file permissions, its
+ * migrations, and the fact that it rewrites `openclaw.json` on its own (a machine
+ * in the field carried three `openclaw.json.clobbered.<timestamp>` files).
+ *
+ * ⚠️ DO NOT call `config patch --dry-run` from buildPlan to preview this. It is
+ * NOT side-effect free: running it triggers OpenClaw's state migrations, which
+ * wrote `~/.openclaw/update-check.json.migrated` and moved config-health state
+ * into SQLite on the machine this was developed on. `atbash setup --dry-run`
+ * promises that nothing is written, and that promise has to hold for OpenClaw's
+ * housekeeping too. The preview stays a merge we compute ourselves.
+ */
+function openclawPatchPayload(args) {
+    const entries = {
+        [args.entryKey]: {
+            enabled: true,
+            // See HOOK_PERMISSIONS: `allowPromptInjection` defaults to ALLOWED, so
+            // without this the guard holds a prompt-mutation permission it never uses.
+            // `config patch` merges recursively, so an operator's own `hooks` keys
+            // (timeoutMs/timeouts) survive alongside it.
+            ...(args.hooksSupported ? { hooks: { ...HOOK_PERMISSIONS } } : {}),
+            config: {
+                enabled: true,
+                enforceDecision: true,
+                chromiaSecretPath: args.keyPath,
+                ...(args.entryKey !== OPENCLAW_LEGACY_ENTRY && args.orgName?.trim() ? { orgName: args.orgName.trim() } : {}),
+            },
+        },
+    };
+    // Two live entries means two hooks and every tool call judged twice against two
+    // different SDKs, so the handover happens in the SAME patch as the new entry —
+    // never as a second write that could land on its own.
+    if (args.standDownLegacy)
+        entries[OPENCLAW_LEGACY_ENTRY] = { enabled: false };
+    return `${JSON.stringify({ plugins: { entries } }, null, 2)}\n`;
+}
 /** 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 +1525,13 @@ 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;
+    // Capability, never a version comparison. A version table is what went stale
+    // and produced a config that broke a fresh machine.
+    const canPatch = Boolean(args.openclaw?.caps.patch);
+    // Probed, never inferred: `hooks` is unknown on 2026.2.1 and valid on 2026.6.6+,
+    // so the same key is fatal on one build and legitimate on the other.
+    const hooksSupported = args.openclaw?.hooksSupported === true;
     const steps = [];
     const notes = [];
     const found = [];
@@ -466,7 +1544,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,26 +1593,118 @@ 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);
+                    const installed = openclawInstallState(home, spec);
+                    if (!installed.installed) {
+                        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],
+                            id: OPENCLAW_INSTALL_ID,
+                        });
+                    }
+                    else if (installed.sameSpec) {
+                        // Already the right package: refresh it rather than re-installing.
+                        // `plugins install` would abort with "plugin already exists" and take
+                        // the whole run down with it — see openclawInstallState.
+                        steps.push({
+                            kind: "exec",
+                            label: `Update ${spec} to the newest build under its tag (installed: ${installed.version ?? "unknown"})`,
+                            command: "openclaw",
+                            // Deliberately NOT tagged with OPENCLAW_INSTALL_ID: the plugin is
+                            // already on disk here, so the config entry refers to something real
+                            // whether or not this refresh succeeds. Gating the config on an
+                            // update would withhold a correct config over a failed download.
+                            args: ["plugins", "update", OPENCLAW_ENTRY],
+                        });
+                    }
+                    else {
+                        // A DIFFERENT spec is installed — typically the production build on a
+                        // machine onboarded against a dev deployment, or the reverse. This is
+                        // not cosmetic: the judge endpoint and chain ids come from the SDK the
+                        // plugin bundles, so the wrong build fails every judge call against a
+                        // chain this agent is not on. It cannot be fixed by `update`, which
+                        // re-resolves the spec already recorded, and 2026.2.1 has no
+                        // `plugins uninstall`, so the directory has to go by hand.
+                        steps.push({
+                            kind: "manual",
+                            label: `Replace the installed OpenClaw plugin with ${spec}`,
+                            detail: `A different build is installed${installed.version ? ` (${installed.version})` : ""} and OpenClaw cannot overwrite it — \`plugins install\` aborts with "plugin already exists", and \`plugins update\` would only re-resolve the spec it already has. The plugin's judge endpoint and chain ids come from the SDK it bundles, so the wrong build fails every judge call. Remove it and install the right one:`,
+                            snippet: `rm -rf ${path.join(home, ...OPENCLAW_EXTENSIONS_REL, OPENCLAW_ENTRY)}\nopenclaw 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)}`,
                     });
                 }
             }
             const raw = readTextFile(openclawConfigFile);
+            // The config entry must not be written unless the plugin it names is going
+            // to exist. `requires` is set only for a FRESH install — see Step.requires
+            // for what a dangling entry costs.
+            const requires = steps.some((s) => s.kind === "exec" && s.id === OPENCLAW_INSTALL_ID)
+                ? OPENCLAW_INSTALL_ID
+                : undefined;
+            // Hand the merge to OpenClaw where it can do it: one validated write, in
+            // its own current format, whatever that has become.
+            //
+            // The entry decision comes from the SAME function the hand-merge uses, so
+            // the two paths cannot pick different keys — see openclawEntryDecision.
+            let parsedForDecision = {};
+            if (raw !== null) {
+                try {
+                    const p = isJsonc(raw)
+                        ? jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false })
+                        : JSON.parse(raw);
+                    if (isRecord(p))
+                        parsedForDecision = p;
+                }
+                catch {
+                    /* an unparseable config decides nothing; treat it as empty */
+                }
+            }
+            const decision = openclawEntryDecision(parsedForDecision, { installsModern: !noInstall });
+            const patchPayload = canPatch
+                ? openclawPatchPayload({
+                    entryKey: decision.entryKey,
+                    orgName,
+                    keyPath: `~/${KEY_FILE_REL.join("/")}`,
+                    standDownLegacy: decision.standDownLegacy,
+                    hooksSupported,
+                })
+                : undefined;
             if (raw !== null && isJsonc(raw)) {
-                // Rewriting this would delete the owner's comments. Print instead.
-                steps.push({
-                    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),
-                });
+                // A config with comments or trailing commas. Rewriting it as strict JSON
+                // deletes the operator's comments, so we never do that.
+                //
+                // But `openclaw config patch` can edit this file WITHOUT losing them —
+                // it is OpenClaw's own JSON5-aware writer. So where that exists, the
+                // operator gets one command instead of a hand-merge, and this stops
+                // being the awkward case.
+                steps.push(patchPayload
+                    ? {
+                        kind: "manual",
+                        label: `Enable the plugin in ${openclawConfigFile}`,
+                        detail: "That file uses comments or trailing commas, so Atbash will not rewrite it — doing so as strict JSON would delete them. OpenClaw can apply the change itself and keep your comments. Run this (it validates before writing, and changes nothing else):",
+                        snippet: `openclaw config patch --stdin <<'JSON'\n${patchPayload.trimEnd()}\nJSON`,
+                    }
+                    : {
+                        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 `entries`:",
+                        snippet: JSON.stringify(mergeOpenclawConfig((jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false }) ?? {}), home, orgName, { installsModern: !noInstall, hooksSupported }), null, 2),
+                    });
             }
             else {
                 let current = {};
@@ -522,16 +1718,37 @@ 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, { installsModern: !noInstall, hooksSupported }));
                 if (raw !== after) {
                     steps.push({
                         kind: "write",
                         label: raw === null
                             ? "Create ~/.openclaw/openclaw.json with the plugin enabled"
-                            : "Enable the plugin in ~/.openclaw/openclaw.json (a merge — existing plugins are kept)",
+                            : patchPayload
+                                ? "Enable the plugin in ~/.openclaw/openclaw.json (OpenClaw applies and validates the merge itself)"
+                                : "Enable the plugin in ~/.openclaw/openclaw.json (a merge — existing plugins are kept)",
                         file: openclawConfigFile,
                         before: raw,
                         after,
+                        ...(requires ? { requires } : {}),
+                        // The diff above is the merge WE compute, and it is what the operator
+                        // approves. Where OpenClaw can apply the change itself we send it the
+                        // equivalent patch instead of these bytes, so the result is validated
+                        // and written in OpenClaw's own current format. The two agree on
+                        // content; OpenClaw may differ on formatting, and its formatting is
+                        // the correct one.
+                        ...(patchPayload
+                            ? {
+                                applyVia: {
+                                    command: "openclaw",
+                                    args: ["config", "patch", "--stdin"],
+                                    payload: patchPayload,
+                                    // Pin the target so the patch cannot land on a different
+                                    // config than the one this step names — see applyVia.env.
+                                    env: { OPENCLAW_CONFIG_PATH: openclawConfigFile },
+                                },
+                            }
+                            : {}),
                     });
                 }
                 else {
@@ -547,47 +1764,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.");
@@ -743,17 +2101,57 @@ function backupFile(file) {
     fs.copyFileSync(file, target);
     return target;
 }
-/** Execute the plan. Writes first, then commands, so a failed install still
- *  leaves a correct config and key file behind for a manual retry. */
-function applyPlan(plan) {
-    const result = { written: [], backups: [], ran: [], failures: [] };
-    for (const step of plan.steps) {
-        if (step.kind !== "write")
-            continue;
+/**
+ * Execute the plan, in the order that cannot leave a half-wired machine.
+ *
+ *   1. Independent writes — the key file above all. Safe on their own, useful
+ *      even if everything after fails, and required by the plugin at load.
+ *   2. Commands — the plugin install, so the plugin id EXISTS on disk.
+ *   3. Dependent writes — the plugin config, now that it refers to something
+ *      real. Skipped outright if its install failed (see Step.requires).
+ *   4. Verify, and roll back anything we broke (see verify).
+ *
+ * ⚠️ THE ORDER IS THE FIX, and it is the reverse of what this function used to
+ * do. "Writes first, then commands, so a failed install still leaves a correct
+ * config behind" sounds prudent and produces the single worst outcome available:
+ * a config entry for a plugin that is not installed, which OpenClaw reports as a
+ * stale reference and offers to delete via `doctor --fix` — silently un-governing
+ * the agent — and which on 2026.2.x helped make the config unloadable, killing
+ * the install that would have fixed it.
+ */
+function applyPlan(plan, opts = {}) {
+    const result = { written: [], backups: [], ran: [], failures: [], skipped: [], rolledBack: [] };
+    /** Backup path per file, so a verify failure can put the original back. */
+    const backupOf = new Map();
+    const writeStep = (step) => {
         try {
             const backup = backupFile(step.file);
-            if (backup)
+            if (backup) {
                 result.backups.push(backup);
+                backupOf.set(step.file, backup);
+            }
+            // Hand the change to the runtime where the plan says to — it merges and
+            // validates in its own format, which is the whole point.
+            if (step.applyVia) {
+                const run = (0, win_exec_1.spawnPortable)(step.applyVia.command, step.applyVia.args, {
+                    input: step.applyVia.payload,
+                    encoding: "utf8",
+                    timeout: 120000,
+                    env: { ...process.env, ...(step.applyVia.env ?? {}) },
+                });
+                const out = `${run.stdout ?? ""}${run.stderr ?? ""}`.trim();
+                if (run.error || run.status !== 0) {
+                    // Do NOT silently fall back to writing the file ourselves. The runtime
+                    // refusing the change is information — usually that the config is
+                    // invalid for a reason we did not cause — and overwriting the file by
+                    // hand would bury it and destroy whatever the runtime was protecting.
+                    result.failures.push(`${step.applyVia.command} ${step.applyVia.args.join(" ")} did not apply the change to ${step.file}` +
+                        (out ? `:\n      ${out.split("\n").join("\n      ")}` : `: ${run.error?.message ?? `exit ${run.status}`}`));
+                    return;
+                }
+                result.written.push(step.file);
+                return;
+            }
             fs.mkdirSync(path.dirname(step.file), { recursive: true, mode: step.mode === KEY_MODE ? DIR_MODE : undefined });
             fs.writeFileSync(step.file, step.after, step.mode ? { mode: step.mode } : {});
             // writeFileSync's mode is ignored for a file that already existed, so
@@ -765,16 +2163,88 @@ function applyPlan(plan) {
         catch (err) {
             result.failures.push(`${step.file}: ${err instanceof Error ? err.message : String(err)}`);
         }
+    };
+    // ── 1. Writes that depend on nothing.
+    for (const step of plan.steps) {
+        if (step.kind === "write" && !step.requires)
+            writeStep(step);
     }
+    // ── 2. Commands, recording which ones a dependent write may rely on.
+    const succeeded = new Set();
     for (const step of plan.steps) {
         if (step.kind !== "exec")
             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)
+        const run = (0, win_exec_1.spawnPortable)(step.command, step.args, { stdio: "inherit" });
+        // 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"}`);
+            if (step.id)
+                succeeded.add(step.id);
+        }
+        else if (run.signal) {
+            result.failures.push(`${label} was killed by ${run.signal}`);
+        }
+        else {
+            result.failures.push(`${label} exited with code ${run.status}`);
+        }
+    }
+    // ── 3. Writes that needed one of those commands to have worked.
+    for (const step of plan.steps) {
+        if (step.kind !== "write" || !step.requires)
+            continue;
+        if (!succeeded.has(step.requires)) {
+            // The whole point: no config for a plugin that is not there. Say what was
+            // NOT done and why, because silence here reads as success.
+            result.skipped.push(`${step.file} was left unchanged: it configures something the step above did not manage to install, ` +
+                `and a config entry for a missing plugin is worse than none — the runtime reports it as stale and ` +
+                `offers to delete it. Fix the failure above and re-run; nothing needs undoing first.`);
+            continue;
+        }
+        writeStep(step);
+    }
+    // ── 4. Verify, and undo what we broke.
+    //
+    // Only files WE wrote in this run, and only when the runtime can actually
+    // answer. A `valid: false` on a file we did not touch is someone else's
+    // problem to fix and not ours to revert.
+    if (opts.verify) {
+        for (const file of [...new Set(result.written)]) {
+            const verdict = opts.verify(file);
+            if (!verdict || verdict.valid)
+                continue;
+            const backup = backupOf.get(file);
+            if (!backup) {
+                // Nothing to restore to — the file did not exist before this run. Deleting
+                // it would be the honest inverse, but a config we created and a config the
+                // runtime created are indistinguishable by now, so say so instead of
+                // guessing. Leaving a file we cannot vouch for, unmentioned, is the one
+                // outcome that is not allowed.
+                result.failures.push(`${file} did not validate after being written, and there was no previous version to restore:\n      ${verdict.problems}`);
+                continue;
+            }
+            try {
+                fs.copyFileSync(backup, file);
+                result.rolledBack.push(file);
+                result.written = result.written.filter((f) => f !== file);
+                result.failures.push(`${file} did not validate after being written, so the original was restored from ${backup}:\n      ${verdict.problems}`);
+            }
+            catch (err) {
+                result.failures.push(`${file} did not validate AND could not be restored from ${backup} (${err instanceof Error ? err.message : String(err)}). ` +
+                    `The backup is still on disk — put it back by hand before starting the runtime.`);
+            }
+        }
     }
     return result;
 }
@@ -790,7 +2260,7 @@ async function verifyRegistration(privkey, endpoint) {
     try {
         const atbash = new sdk_1.Atbash(privkey, {
             endpoint,
-            blockchainRid: (0, sdk_1.resolve)("blockchainRid") || undefined,
+            network: (0, sdk_1.resolve)("defaultChainNetwork") || undefined,
             orgName: (0, sdk_1.resolve)("orgName") || undefined,
         });
         return (await atbash.checkAgentExists()) ? { state: "registered" } : { state: "unregistered" };
@@ -799,12 +2269,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) {
@@ -816,12 +2293,14 @@ 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")
         .option("--skip-verify", "Do not check the agent's registration (no network calls at all)")
         .option("--allow-unrecognized-host", "Permit a --host that is not a known Atbash deployment")
         .option("--home <dir>", "Home directory to configure (for testing)")
+        .option("--replace-key", "Consent to changing which agent this machine signs as, when --key names a different agent than the one already here (needed for non-interactive runs)")
         .action(async (opts) => {
         const home = opts.home || process.env.HOME || os.homedir();
         const dryRun = !!opts.dryRun;
@@ -854,9 +2333,62 @@ function registerSetupCommand(program) {
             process.exit(1);
         }
         console.log(chalk_1.default.dim(`\n  Agent key source: ${keySource.from}`));
+        // ── Replacing this machine's AGENT IDENTITY is its own decision.
+        //
+        // Everything else this command does is additive: a config entry, a plugin,
+        // a key file where there was none. This one is a substitution, and it is
+        // the only change here that alters WHO the machine is. After it, every
+        // integration reading the default key path signs as a different on-chain
+        // agent, so tool calls are attributed to someone else — including tool
+        // calls made by work that was already running.
+        //
+        // It used to be folded into the single "Apply N changes to this machine?"
+        // prompt, listed as one write among several. An operator concentrating on
+        // the plugin config could accept it without registering that their agent
+        // identity changed, and `--yes` — which reasonably means "don't ask me
+        // about the file writes" — skipped it entirely. So it gets asked
+        // separately, and a blanket `--yes` does not answer it: saying yes to
+        // writing files is not the same as saying yes to becoming a different
+        // agent. `--replace-key` is how a script says it deliberately.
+        //
+        // Declining ABORTS rather than continuing, because continuing cannot honour
+        // what was asked. The operator ran `--key <NEW>` meaning "wire this machine
+        // to NEW"; with the key left alone the machine keeps signing as OLD, so
+        // proceeding would configure a runtime that reports one agent while the
+        // dashboard shows another — the exact silent mismatch the rest of this work
+        // exists to remove.
+        const canonicalKeyFile = path.join(home, ...KEY_FILE_REL);
+        const existingRaw = readTextFile(canonicalKeyFile);
+        const existingMaterial = existingRaw === null ? null : parseKeyMaterial(existingRaw);
+        const existingPubkey = existingMaterial ? (0, sdk_1.derivePublicKey)(existingMaterial.privkey) : undefined;
+        if (existingPubkey && existingPubkey.toLowerCase() !== pubkey.toLowerCase()) {
+            const archive = path.join(home, ".config", "atbash", "keys", `${existingPubkey}.key`);
+            console.log(chalk_1.default.yellow("\n  This machine is about to change which agent it signs as.") +
+                chalk_1.default.dim(`\n    now:  ${existingPubkey}`) +
+                chalk_1.default.dim(`\n    new:  ${pubkey}`) +
+                chalk_1.default.dim(`\n  Every integration on this machine reading ${canonicalKeyFile}`) +
+                chalk_1.default.dim("\n  will switch to the new agent. The current key is archived first, to") +
+                chalk_1.default.dim(`\n  ${archive}, so the old agent stays recoverable.\n`));
+            const approved = opts.replaceKey
+                ? true
+                : dryRun
+                    ? true // a preview decides nothing; the real run will still ask
+                    : process.stdin.isTTY
+                        ? await confirm("  Replace the agent this machine signs as? [y/N] ")
+                        : false;
+            if (!approved) {
+                console.log(chalk_1.default.dim("\n  Nothing was changed.") +
+                    chalk_1.default.dim(`\n  This machine still signs as ${existingPubkey}.`) +
+                    (process.stdin.isTTY
+                        ? chalk_1.default.dim("\n  Re-run without --key to configure it for the agent already here.\n")
+                        : chalk_1.default.dim("\n  Re-run with --replace-key to switch agents non-interactively,") +
+                            chalk_1.default.dim("\n  or without --key to configure it for the agent already here.\n")));
+                return;
+            }
+        }
         // ── 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();
@@ -868,7 +2400,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);
@@ -876,7 +2409,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") {
@@ -887,9 +2434,74 @@ 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(", ")}`));
+            }
+        }
+        // ── What OpenClaw is on this machine, and can we ask it to do the work?
+        //
+        // This runs BEFORE the plan, and before anything is written, because both
+        // answers change what we do:
+        //
+        //  - No OpenClaw at all → say so and stop touching OpenClaw. The likeliest
+        //    cause is the operator running this on the wrong computer, and the
+        //    previous behavior (write config for a runtime that is not here) left
+        //    a machine carrying governance for an agent it does not run.
+        //  - An OLD OpenClaw → still supported, still wired. It just cannot
+        //    validate the change for us, so we say that once, offer the upgrade
+        //    command FOR ITS OWN CHANNEL, and continue. Refusing here would break
+        //    2026.2.x boxes that demonstrably work.
+        //
+        // Nothing below compares version numbers to decide anything: capability is
+        // probed from the binary. A version table is exactly what went stale and
+        // produced the config that broke the reporter's machine.
+        const wantsOpenclaw = wantedRuntime("openclaw", opts.runtime ?? []);
+        const openclaw = wantsOpenclaw ? (0, openclaw_runtime_1.detectOpenclaw)() : undefined;
+        if (openclaw) {
+            const status = (0, openclaw_runtime_1.supportStatus)(openclaw);
+            console.log(status.supported ? chalk_1.default.dim(`\n  ${status.message}`) : chalk_1.default.yellow(`\n  ${status.message}`));
+            if (status.upgrade) {
+                console.log(chalk_1.default.dim("  To upgrade it:  ") + chalk_1.default.cyan(status.upgrade));
+            }
+            // ── PREFLIGHT. The step this command never had.
+            //
+            // Setup merged into ~/.openclaw/openclaw.json without ever checking
+            // whether that file currently loads. On a machine whose config was
+            // ALREADY broken it added its entry to an unloadable file and then its
+            // own `openclaw plugins install` step died on the pre-existing breakage —
+            // reported to the operator as an Atbash failure, which it was not.
+            //
+            // A `valid: false` here is NOT a reason to refuse: the operator may well
+            // be running setup precisely because their config is broken, and some of
+            // what we do (pruning a retired `load.paths`) is the repair. So report
+            // the problems in OpenClaw's own words and carry on — the point is that
+            // nobody is left debugging our step for someone else's breakage.
+            if (openclaw.caps.validate) {
+                const configPath = path.join(home, ...OPENCLAW_CONFIG_REL);
+                if (fs.existsSync(configPath)) {
+                    const verdict = (0, openclaw_runtime_1.validateConfig)(openclaw, configPath, "openclaw", home);
+                    if (verdict && !verdict.valid) {
+                        console.log(chalk_1.default.yellow("\n  ⚠ OpenClaw reports your CURRENT config is invalid, before Atbash changes anything:") +
+                            chalk_1.default.dim(`\n${verdict.problems.split("\n").map((l) => `      ${l}`).join("\n")}`) +
+                            chalk_1.default.dim("\n  Atbash will still wire its entry, and will back the file up first. If the") +
+                            chalk_1.default.dim("\n  problem above is not one Atbash introduced, it needs fixing separately —") +
+                            chalk_1.default.dim("\n  OpenClaw will not load ANY config while it stands, so the plugin cannot run.\n"));
+                    }
+                }
+            }
         }
         // ── Plan, show, then (maybe) apply.
         const plan = buildPlan({
@@ -898,7 +2510,24 @@ function registerSetupCommand(program) {
             pubkey,
             noInstall: opts.install === false,
             only: opts.runtime ?? [],
+            orgName: opts.orgName,
+            // Lets the plan hand the config merge to OpenClaw where it can do it, and
+            // tells it whether THIS build accepts `hooks` on a plugin entry — asked of
+            // `openclaw config schema`, since the same key is fatal on 2026.2.x and
+            // legitimate on 2026.6.6+. Unknown resolves to "not supported", which is
+            // the fail-safe direction.
+            ...(openclaw ? { openclaw: { ...openclaw, hooksSupported: (0, openclaw_runtime_1.pluginEntryAcceptsHooks)(openclaw) === true } } : {}),
+            // 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) {
@@ -921,7 +2550,16 @@ function registerSetupCommand(program) {
                 return;
             }
         }
-        const result = applyPlan(plan);
+        // Verification is OpenClaw's own answer, not ours — and only for the file
+        // it is the authority on. Setup used to report success based purely on
+        // having written what it intended to write, which is how a machine with
+        // nothing installed was told it was "fully wired".
+        const openclawConfigPath = path.join(home, ...OPENCLAW_CONFIG_REL);
+        const result = applyPlan(plan, {
+            verify: openclaw?.caps.validate
+                ? (file) => (path.resolve(file) === path.resolve(openclawConfigPath) ? (0, openclaw_runtime_1.validateConfig)(openclaw, file, "openclaw", home) : undefined)
+                : undefined,
+        });
         console.log();
         for (const file of result.written)
             console.log(chalk_1.default.green(`  ✓ wrote ${file}`));
@@ -929,14 +2567,85 @@ function registerSetupCommand(program) {
             console.log(chalk_1.default.dim(`    backup: ${file}`));
         for (const cmd of result.ran)
             console.log(chalk_1.default.green(`  ✓ ran ${cmd}`));
+        for (const file of result.rolledBack)
+            console.log(chalk_1.default.yellow(`  ↩ restored ${file} — the change did not validate`));
+        // A write we deliberately did not make is not a silent non-event: it is the
+        // difference between "no config" and "config for a plugin that isn't there",
+        // and the operator has to know which one they have.
+        for (const skip of result.skipped)
+            console.log(chalk_1.default.yellow(`  ⊘ ${skip}`));
         for (const failure of result.failures)
             console.log(chalk_1.default.red(`  ✗ ${failure}`));
-        if (result.failures.length) {
+        if (result.failures.length || result.skipped.length) {
             console.log(chalk_1.default.yellow("\n  Finished with failures — this machine is NOT fully wired.") +
                 chalk_1.default.dim("\n  Everything that did succeed is listed above; the steps that failed can be re-run.\n"));
             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.
+        }
+        // ── OpenClaw gets the last word about OpenClaw.
+        //
+        // Everything above reports what setup DID. This reports what OpenClaw now
+        // SEES, which is the only thing that answers "is this agent governed?".
+        // The reporter's machine had a config entry, no plugin, and a green
+        // summary — a false green on a control boundary is the most expensive
+        // failure this command can produce.
+        if (openclaw?.present && plan.found.includes("OpenClaw") && wantedRuntime("openclaw", opts.runtime ?? [])) {
+            const verdict = (0, openclaw_runtime_1.verifyOpenclawPlugin)(openclaw, {
+                entryIds: [OPENCLAW_ENTRY, OPENCLAW_LEGACY_ENTRY],
+                configPath: openclawConfigPath,
+                // Pin HOME too: plugin discovery walks $HOME/.openclaw, so without it a
+                // --home run reports the operator's real machine instead of this one.
+                home,
+                expectedSpec: openclawPackageForHost(opts.host || (0, sdk_1.resolve)("judgeEndpoint") || atbash_targets_1.DEFAULT_HOST),
+            });
+            if (verdict.state === "loaded") {
+                console.log(chalk_1.default.green(`\n  OpenClaw loads the plugin — entry \`${verdict.entry}\`${verdict.version ? `, build ${verdict.version}` : ""}.`) +
+                    chalk_1.default.dim("\n  Its hook registers when the gateway starts, so restart the gateway to enforce.\n"));
+            }
+            else if (verdict.state === "unknown") {
+                // Say plainly that this is unverified rather than papering over it.
+                console.log(chalk_1.default.yellow("\n  Could not confirm with OpenClaw whether the plugin loaded.") +
+                    chalk_1.default.dim(`\n  ${verdict.detail ?? ""}\n  Check it yourself with: `) + chalk_1.default.cyan("openclaw plugins list") + "\n");
+            }
+            else {
+                console.log(chalk_1.default.yellow(`\n  This agent is NOT governed yet — OpenClaw does not report the plugin as loaded.`) +
+                    chalk_1.default.dim(`\n  ${verdict.detail ?? ""}`) +
+                    chalk_1.default.dim(`\n  Inspect it with: `) + chalk_1.default.cyan("openclaw plugins list") + chalk_1.default.dim(" and ") + chalk_1.default.cyan("openclaw doctor") +
+                    chalk_1.default.dim("\n  ⚠ `openclaw doctor --fix` will DELETE an Atbash entry it considers stale, so read its plan before accepting.\n"));
+                process.exitCode = 1;
+                return;
+            }
+        }
         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"));
     });