@atbash/cli 0.5.15-dev.12 → 0.5.15-dev.15

package/dist/commands/setup.js

@@ -42,7 +42,9 @@ 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;
@@ -55,6 +57,7 @@ exports.pythonInstallStrategy = pythonInstallStrategy;
 exports.mergeHermesEnv = mergeHermesEnv;
 exports.hadInlineKey = hadInlineKey;
 exports.mergeMcpServer = mergeMcpServer;
+exports.openclawPatchPayload = openclawPatchPayload;
 exports.buildPlan = buildPlan;
 exports.lineDiff = lineDiff;
 exports.renderPlan = renderPlan;
@@ -70,6 +73,7 @@ const jsonc = __importStar(require("jsonc-parser"));
 const yaml_1 = require("yaml");
 const sdk_1 = require("@atbash/sdk");
 const atbash_targets_1 = require("../shared/atbash-targets");
+const openclaw_runtime_1 = require("../shared/openclaw-runtime");
 /**
  * `atbash setup` — the write half of onboarding.
  *
@@ -124,13 +128,15 @@ 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";
 /**
@@ -147,19 +153,38 @@ 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. ⚠️ It is not a key OpenClaw has.
+ * Drop the `hooks` block from a plugin entry.
  *
- * Earlier releases wrote one — the published plugin docs show it — and OpenClaw
- * rejects it. Verified against 2026.2.1 by feeding a generated config through
- * OPENCLAW_CONFIG_PATH:
+ * ⚠️ 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"
  *
- * The first repair scoped removal to the LEGACY entry, on the stated belief that
- * the modern entry documented the key. It does not: OpenClaw rejects it on
- * either, and rejecting means refusing to load ANY config, which also makes
- * `openclaw plugins install` exit 1. So it is stripped wherever it is found, and
- * never written.
+ * 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) {
     if ("hooks" in entry)
@@ -581,6 +606,37 @@ function isJsonc(text) {
  * `<your-username>` placeholder that people paste verbatim, producing a path that
  * does not exist and a plugin that never loads.
  */
+/**
+ * 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;
     const out = { ...config };
@@ -605,12 +661,7 @@ function mergeOpenclawConfig(config, home, orgName, opts = {}) {
     // 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 legacyEntry = OPENCLAW_LEGACY_ENTRY in entries;
-    const installs = isRecord(plugins.installs) ? plugins.installs : {};
-    const legacy = legacyEntry || OPENCLAW_LEGACY_ENTRY in installs;
-    const modern = OPENCLAW_ENTRY in entries;
-    const useLegacy = !installsModern && legacy && !modern;
-    const entryKey = useLegacy ? OPENCLAW_LEGACY_ENTRY : OPENCLAW_ENTRY;
+    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
@@ -681,16 +732,48 @@ function mergeOpenclawConfig(config, home, orgName, opts = {}) {
         out.plugins = plugins;
         return out;
     }
-    // No entry yet — write the shape the published plugin documents, in full.
-    const allow = reconcileAllow(plugins.allow, entryKey, !useLegacy && legacy) ?? [entryKey];
-    plugins.allow = allow;
-    const load = pruneRetiredLoadPath(plugins.load, home) ?? {};
-    const extensionPath = path.join(home, ...OPENCLAW_EXTENSIONS_REL, entryKey);
-    const paths = Array.isArray(load.paths) ? [...load.paths] : [];
-    if (!paths.includes(extensionPath))
-        paths.push(extensionPath);
-    load.paths = paths;
-    plugins.load = load;
+    // 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
@@ -779,6 +862,114 @@ function pruneRetiredLoadPath(current, home) {
     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;
@@ -1212,6 +1403,45 @@ function mergeMcpServer(config, serversKey = "mcpServers") {
     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,
+            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" });
@@ -1227,6 +1457,9 @@ function hasExecutable(command) {
  */
 function buildPlan(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);
     const steps = [];
     const notes = [];
     const found = [];
@@ -1289,14 +1522,48 @@ function buildPlan(args) {
             if (!noInstall) {
                 if (hasExecutable("openclaw")) {
                     const spec = openclawPackageForHost(endpoint);
-                    steps.push({
-                        kind: "exec",
-                        label: spec.endsWith("@dev")
-                            ? `Install ${spec} — the development build, matching the deployment this agent was onboarded on`
-                            : `Install ${spec} — the production build`,
-                        command: "openclaw",
-                        args: ["plugins", "install", spec],
-                    });
+                    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.");
                     }
@@ -1311,14 +1578,60 @@ function buildPlan(args) {
                 }
             }
             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,
+                })
+                : 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, orgName, { installsModern: !noInstall }), 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 }), null, 2),
+                    });
             }
             else {
                 let current = {};
@@ -1338,10 +1651,31 @@ function buildPlan(args) {
                         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 {
@@ -1694,17 +2028,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, child_process_1.spawnSync)(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
@@ -1716,7 +2090,14 @@ 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;
@@ -1736,6 +2117,8 @@ function applyPlan(plan) {
         }
         else if (run.status === 0) {
             result.ran.push(label);
+            if (step.id)
+                succeeded.add(step.id);
         }
         else if (run.signal) {
             result.failures.push(`${label} was killed by ${run.signal}`);
@@ -1744,6 +2127,52 @@ function applyPlan(plan) {
             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;
 }
 // ── Registration check ──────────────────────────────────────────────────────
@@ -1794,6 +2223,7 @@ function registerSetupCommand(program) {
         .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;
@@ -1826,6 +2256,59 @@ 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") || atbash_targets_1.DEFAULT_HOST || sdk_1.DEFAULT_ENDPOINT).replace(/\/$/, "");
@@ -1891,6 +2374,58 @@ function registerSetupCommand(program) {
                 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({
             home,
@@ -1899,6 +2434,8 @@ function registerSetupCommand(program) {
             noInstall: opts.install === false,
             only: opts.runtime ?? [],
             orgName: opts.orgName,
+            // Lets the plan hand the config merge to OpenClaw where it can do it.
+            ...(openclaw ? { openclaw } : {}),
             // 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,
@@ -1932,7 +2469,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}`));
@@ -1940,9 +2486,16 @@ 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;
@@ -1978,6 +2531,40 @@ function registerSetupCommand(program) {
             }
             // "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"));
     });