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

package/dist/commands/setup.js

@@ -42,6 +42,7 @@ exports.keyCandidatesInDir = keyCandidatesInDir;
 exports.resolveKeySource = resolveKeySource;
 exports.keyFileContents = keyFileContents;
 exports.isJsonc = isJsonc;
+exports.openclawEntryDecision = openclawEntryDecision;
 exports.mergeOpenclawConfig = mergeOpenclawConfig;
 exports.openclawInstallState = openclawInstallState;
 exports.detectIndent = detectIndent;
@@ -56,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;
@@ -71,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.
  *
@@ -125,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 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 OpenClaw plugin package.
+ *
+ * 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";
 /**
@@ -148,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.
+ *
+ * ⚠️ 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.
  *
- * 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:
+ * 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)
@@ -582,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 };
@@ -606,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
@@ -682,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
@@ -799,7 +881,74 @@ function pruneRetiredLoadPath(current, home) {
  * 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 };
     }
@@ -1254,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" });
@@ -1269,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 = [];
@@ -1340,6 +1531,7 @@ function buildPlan(args) {
                                 : `Install ${spec} — the production build`,
                             command: "openclaw",
                             args: ["plugins", "install", spec],
+                            id: OPENCLAW_INSTALL_ID,
                         });
                     }
                     else if (installed.sameSpec) {
@@ -1350,6 +1542,10 @@ function buildPlan(args) {
                             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],
                         });
                     }
@@ -1382,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 = {};
@@ -1409,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 {
@@ -1765,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
@@ -1787,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;
@@ -1807,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}`);
@@ -1815,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 ──────────────────────────────────────────────────────
@@ -1865,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;
@@ -1897,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(/\/$/, "");
@@ -1962,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,
@@ -1970,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,
@@ -2003,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}`));
@@ -2011,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;
@@ -2049,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"));
     });