@openclaw-cloud/agent-controller 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/utils/claude-env.d.ts

@@ -1,5 +1,11 @@
 /**
  * Write ~/.claude/settings.json, ~/.claude/cc-notify.sh, and auth-profiles.json
  * from a flat env vars dict (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL).
+ *
+ * This is a WHOLESALE rewrite of the user's Claude settings, so it is gated on
+ * the install being managed ('vm'/'k8s'). The guard lives here rather than in
+ * the callers deliberately: it is defense in depth that holds for every current
+ * and future caller. `agent-controller bootstrap` on a developer laptop once
+ * blew away ~/.claude/settings.json — that must not be re-reachable.
  */
 export declare function writeClaudeEnv(envVars: Record<string, string>): Promise<void>;

package/dist/utils/claude-env.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { classifyAnthropicAuth } from './anthropic-auth.js';
+import { buildClaudeSettings, classifyAnthropicAuth, CLAUDE_PERMISSIONS, } from './anthropic-auth.js';
+import { getResolvedDeployType, isManagedDeploy } from './deploy-type.js';
 const CC_NOTIFY_SH = `#!/bin/bash
 # Claude Code hook: notify OpenClaw on Stop/PermissionRequest
 EVENT_TYPE="\${CC_HOOK_EVENT:-unknown}"
@@ -41,8 +42,18 @@ exit 0
 /**
  * Write ~/.claude/settings.json, ~/.claude/cc-notify.sh, and auth-profiles.json
  * from a flat env vars dict (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL).
+ *
+ * This is a WHOLESALE rewrite of the user's Claude settings, so it is gated on
+ * the install being managed ('vm'/'k8s'). The guard lives here rather than in
+ * the callers deliberately: it is defense in depth that holds for every current
+ * and future caller. `agent-controller bootstrap` on a developer laptop once
+ * blew away ~/.claude/settings.json — that must not be re-reachable.
  */
 export async function writeClaudeEnv(envVars) {
+    if (!isManagedDeploy()) {
+        console.log(`[claude-env] skipped: not a managed install (deployType=${getResolvedDeployType() ?? 'unknown'})`);
+        return;
+    }
     const claudeDir = path.join(os.homedir(), '.claude');
     await fs.mkdir(claudeDir, { recursive: true });
     // Write cc-notify.sh
@@ -50,10 +61,6 @@ export async function writeClaudeEnv(envVars) {
     await fs.writeFile(notifyPath, CC_NOTIFY_SH);
     await fs.chmod(notifyPath, 0o755);
     const auth = classifyAnthropicAuth({ anthropicApiKey: envVars.ANTHROPIC_API_KEY });
-    // This flow only handles the OAuth-vs-API-key split (no explicit
-    // anthropicAuthToken input); an `auth_token` classification here always
-    // means "the API key was in fact an OAuth token".
-    const isOAuthToken = auth.kind === 'auth_token';
     const hooks = {
         PreToolUse: [{ matcher: 'Bash', hooks: [] }],
         PostToolUse: [{ matcher: 'Write|Edit', hooks: [] }],
@@ -69,29 +76,23 @@ export async function writeClaudeEnv(envVars) {
             },
         ],
     };
-    const permissions = {
-        allow: ['Bash(*)', 'Read(*)', 'Write(*)', 'Edit(*)', 'mcp__*'],
-    };
-    let settings;
-    if (isOAuthToken) {
-        // OAuth token flow: set ANTHROPIC_AUTH_TOKEN, no apiKeyHelper, no ANTHROPIC_BASE_URL
-        settings = {
-            permissions,
-            env: { ANTHROPIC_AUTH_TOKEN: auth.value },
-            hooks,
-        };
-    }
-    else {
-        // API key flow (default): apiKeyHelper + optional ANTHROPIC_BASE_URL
-        settings = {
-            permissions,
-            apiKeyHelper: "bash -c 'source /opt/openclaw-cloud/agent-controller/.env && echo $ANTHROPIC_API_KEY'",
-            ...(envVars.ANTHROPIC_BASE_URL
-                ? { env: { ANTHROPIC_BASE_URL: envVars.ANTHROPIC_BASE_URL } }
-                : {}),
-            hooks,
-        };
-    }
+    // This flow only handles the OAuth-vs-API-key split (no explicit
+    // anthropicAuthToken input); an `auth_token` classification here always
+    // means "the API key was in fact an OAuth token".
+    const settings = auth.kind === 'auth_token'
+        ? // OAuth token flow: ANTHROPIC_AUTH_TOKEN, no apiKeyHelper, no ANTHROPIC_BASE_URL
+            { ...buildClaudeSettings(auth), hooks }
+        : // API key flow (default): the key is NOT embedded — apiKeyHelper reads it
+            // out of the VM .env at runtime — so this branch cannot use the shared
+            // `env` variant. Optional ANTHROPIC_BASE_URL rides along.
+            {
+                permissions: CLAUDE_PERMISSIONS,
+                apiKeyHelper: "bash -c 'source /opt/openclaw-cloud/agent-controller/.env && echo $ANTHROPIC_API_KEY'",
+                ...(envVars.ANTHROPIC_BASE_URL
+                    ? { env: { ANTHROPIC_BASE_URL: envVars.ANTHROPIC_BASE_URL } }
+                    : {}),
+                hooks,
+            };
     // Contains ANTHROPIC_AUTH_TOKEN on OAuth flow — chmod 0o600.
     await fs.writeFile(path.join(claudeDir, 'settings.json'), JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
     // auth-profiles.json is now written by applyBootstrapConfig from openclaw.json

package/dist/utils/claude-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-env.js","sourceRoot":"","sources":["../../src/utils/claude-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCpB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA+B;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,qBAAqB;IACrB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACxD,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC7C,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAElC,MAAM,IAAI,GAAG,qBAAqB,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACnF,iEAAiE;IACjE,wEAAwE;IACxE,kDAAkD;IAClD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,KAAK,YAAY,CAAC;IAEhD,MAAM,KAAK,GAAG;QACZ,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC5C,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACnD,IAAI,EAAE;YACJ;gBACE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;aACnF;SACF;QACD,YAAY,EAAE;YACZ;gBACE,OAAO,EAAE,mBAAmB;gBAC5B,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mDAAmD,EAAE,CAAC;aAC3F;SACF;KACF,CAAC;IAEF,MAAM,WAAW,GAAG;QAClB,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC;KAC/D,CAAC;IAEF,IAAI,QAAiC,CAAC;IACtC,IAAI,YAAY,EAAE,CAAC;QACjB,qFAAqF;QACrF,QAAQ,GAAG;YACT,WAAW;YACX,GAAG,EAAE,EAAE,oBAAoB,EAAE,IAAI,CAAC,KAAK,EAAE;YACzC,KAAK;SACN,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,qEAAqE;QACrE,QAAQ,GAAG;YACT,WAAW;YACX,YAAY,EACV,uFAAuF;YACzF,GAAG,CAAC,OAAO,CAAC,kBAAkB;gBAC5B,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,EAAE;gBAC7D,CAAC,CAAC,EAAE,CAAC;YACP,KAAK;SACN,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EACrC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EACxC,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAC;IAEF,+EAA+E;AACjF,CAAC"}
+{"version":3,"file":"claude-env.js","sourceRoot":"","sources":["../../src/utils/claude-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE1E,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCpB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA+B;IAClE,IAAI,CAAC,eAAe,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,GAAG,CACT,2DAA2D,qBAAqB,EAAE,IAAI,SAAS,GAAG,CACnG,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,qBAAqB;IACrB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACxD,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC7C,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAElC,MAAM,IAAI,GAAG,qBAAqB,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEnF,MAAM,KAAK,GAAG;QACZ,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC5C,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QACnD,IAAI,EAAE;YACJ;gBACE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC;aACnF;SACF;QACD,YAAY,EAAE;YACZ;gBACE,OAAO,EAAE,mBAAmB;gBAC5B,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mDAAmD,EAAE,CAAC;aAC3F;SACF;KACF,CAAC;IAEF,iEAAiE;IACjE,wEAAwE;IACxE,kDAAkD;IAClD,MAAM,QAAQ,GACZ,IAAI,CAAC,IAAI,KAAK,YAAY;QACxB,CAAC,CAAC,iFAAiF;YACjF,EAAE,GAAG,mBAAmB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE;QACzC,CAAC,CAAC,0EAA0E;YAC1E,uEAAuE;YACvE,0DAA0D;YAC1D;gBACE,WAAW,EAAE,kBAAkB;gBAC/B,YAAY,EACV,uFAAuF;gBACzF,GAAG,CAAC,OAAO,CAAC,kBAAkB;oBAC5B,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,EAAE,EAAE;oBAC7D,CAAC,CAAC,EAAE,CAAC;gBACP,KAAK;aACN,CAAC;IAER,6DAA6D;IAC7D,MAAM,EAAE,CAAC,SAAS,CAChB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,EACrC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EACxC,EAAE,IAAI,EAAE,KAAK,EAAE,CAChB,CAAC;IAEF,+EAA+E;AACjF,CAAC"}

package/dist/utils/config-merge-paths.d.ts

@@ -19,12 +19,26 @@
  * To extend: add the path here. Keep it tight — every entry is an implicit
  * promise that merging it won't clobber user work.
  */
+/**
+ * The one backend-managed section of openclaw.json. Merged REMOTE-wins per
+ * server name (see `applyMergeableConfig`) and the only section whose change
+ * forces a gateway restart on standalone — openclaw does not hot-reload it.
+ */
+export declare const MCP_SERVERS_PATH = "mcp.servers";
 export declare const MERGEABLE_CONFIG_PATHS: readonly string[];
 /**
  * Paths within ~/.claude/settings.json that are safe to merge from a backend
- * envVars/settings payload. Everything else (apiKeyHelper, permissions, hooks,
+ * bootstrap payload. Everything else (apiKeyHelper, permissions, hooks, `env`,
  * user-owned keys) is left untouched.
  *
+ * `env` is DELIBERATELY EXCLUDED and must never be added back. The backend's
+ * `envVars` carry `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`; merging them into
+ * a standalone user's ~/.claude/settings.json points ALL of that user's own
+ * Claude Code sessions at the platform proxy — which, when it is not running,
+ * breaks Claude Code on the machine outright. That incident happened twice
+ * (latest 2026-08-02) before the path was removed. Managed installs ('vm'/'k8s')
+ * still get their credentials, via `writeClaudeEnv()` — not via this merge.
+ *
  * NOTE: `mcp.servers` is a DOTTED path — Claude Code's modern settings.json
  * schema nests MCP servers under `mcp.servers`, not the legacy flat
  * `mcpServers` key. Agent-controller migrates any pre-existing flat

package/dist/utils/config-merge-paths.js

@@ -19,22 +19,36 @@
  * To extend: add the path here. Keep it tight — every entry is an implicit
  * promise that merging it won't clobber user work.
  */
+/**
+ * The one backend-managed section of openclaw.json. Merged REMOTE-wins per
+ * server name (see `applyMergeableConfig`) and the only section whose change
+ * forces a gateway restart on standalone — openclaw does not hot-reload it.
+ */
+export const MCP_SERVERS_PATH = 'mcp.servers';
 export const MERGEABLE_CONFIG_PATHS = [
-    'mcp.servers',
+    MCP_SERVERS_PATH,
     'tools.media.audio',
     'tools.media.voice',
     'tools.transcription',
 ];
 /**
  * Paths within ~/.claude/settings.json that are safe to merge from a backend
- * envVars/settings payload. Everything else (apiKeyHelper, permissions, hooks,
+ * bootstrap payload. Everything else (apiKeyHelper, permissions, hooks, `env`,
  * user-owned keys) is left untouched.
  *
+ * `env` is DELIBERATELY EXCLUDED and must never be added back. The backend's
+ * `envVars` carry `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`; merging them into
+ * a standalone user's ~/.claude/settings.json points ALL of that user's own
+ * Claude Code sessions at the platform proxy — which, when it is not running,
+ * breaks Claude Code on the machine outright. That incident happened twice
+ * (latest 2026-08-02) before the path was removed. Managed installs ('vm'/'k8s')
+ * still get their credentials, via `writeClaudeEnv()` — not via this merge.
+ *
  * NOTE: `mcp.servers` is a DOTTED path — Claude Code's modern settings.json
  * schema nests MCP servers under `mcp.servers`, not the legacy flat
  * `mcpServers` key. Agent-controller migrates any pre-existing flat
  * `mcpServers` into `mcp.servers` on first merge and deletes the flat key
  * (see `applyMergeableConfig` in apply-config.ts).
  */
-export const MERGEABLE_SETTINGS_PATHS = ['mcp.servers', 'env'];
+export const MERGEABLE_SETTINGS_PATHS = ['mcp.servers'];
 //# sourceMappingURL=config-merge-paths.js.map

package/dist/utils/config-merge-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-merge-paths.js","sourceRoot":"","sources":["../../src/utils/config-merge-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,aAAa;IACb,mBAAmB;IACnB,mBAAmB;IACnB,qBAAqB;CACb,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,CAAC,aAAa,EAAE,KAAK,CAAU,CAAC"}
+{"version":3,"file":"config-merge-paths.js","sourceRoot":"","sources":["../../src/utils/config-merge-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAE9C,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,gBAAgB;IAChB,mBAAmB;IACnB,mBAAmB;IACnB,qBAAqB;CACb,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,CAAC,aAAa,CAAU,CAAC"}

package/dist/utils/deploy-type.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Record the deployment type reported by a bootstrap payload. Ignores empty
+ * values so an older backend that omits the field cannot clear a known type.
+ */
+export declare function setResolvedDeployType(t?: string): void;
+/**
+ * The payload-reported deployment type if one has arrived, otherwise the
+ * `AGENT_DEPLOY_TYPE` env var. `undefined` means "we do not know".
+ */
+export declare function getResolvedDeployType(): string | undefined;
+/**
+ * True only for managed installs ('vm' / 'k8s'). Unknown deployment types
+ * deliberately resolve to false — fail safe, because the expensive mistake is
+ * rewriting a developer's ~/.claude/settings.json, not skipping a full apply.
+ */
+export declare function isManagedDeploy(): boolean;

package/dist/utils/deploy-type.js

@@ -0,0 +1,34 @@
+import { config } from '../config.js';
+/**
+ * Deployment types describing a machine our platform provisioned end to end.
+ * Everything else — 'standalone', 'external', or an unknown/absent type — is a
+ * third-party machine whose config files we are only allowed to merge into.
+ */
+const MANAGED_TYPES = new Set(['vm', 'k8s']);
+/** Set from the bootstrap payload; survives for the life of the process. */
+let resolvedDeployType;
+/**
+ * Record the deployment type reported by a bootstrap payload. Ignores empty
+ * values so an older backend that omits the field cannot clear a known type.
+ */
+export function setResolvedDeployType(t) {
+    if (t)
+        resolvedDeployType = t;
+}
+/**
+ * The payload-reported deployment type if one has arrived, otherwise the
+ * `AGENT_DEPLOY_TYPE` env var. `undefined` means "we do not know".
+ */
+export function getResolvedDeployType() {
+    return resolvedDeployType ?? config.agentDeployType;
+}
+/**
+ * True only for managed installs ('vm' / 'k8s'). Unknown deployment types
+ * deliberately resolve to false — fail safe, because the expensive mistake is
+ * rewriting a developer's ~/.claude/settings.json, not skipping a full apply.
+ */
+export function isManagedDeploy() {
+    const type = getResolvedDeployType();
+    return type !== undefined && MANAGED_TYPES.has(type);
+}
+//# sourceMappingURL=deploy-type.js.map

package/dist/utils/deploy-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-type.js","sourceRoot":"","sources":["../../src/utils/deploy-type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;GAIG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAE7C,4EAA4E;AAC5E,IAAI,kBAAsC,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAU;IAC9C,IAAI,CAAC;QAAE,kBAAkB,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,kBAAkB,IAAI,MAAM,CAAC,eAAe,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,IAAI,GAAG,qBAAqB,EAAE,CAAC;IACrC,OAAO,IAAI,KAAK,SAAS,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/utils/env.d.ts

@@ -1,2 +1 @@
-export declare function requireEnv(name: string): string;
 export declare function getBackendUrl(): string;

package/dist/utils/env.js

@@ -1,12 +1,4 @@
 import { config, requireConfig } from '../config.js';
-export function requireEnv(name) {
-    const value = process.env[name];
-    if (!value) {
-        console.error(`Missing required environment variable: ${name}`);
-        process.exit(1);
-    }
-    return value;
-}
 export function getBackendUrl() {
     return config.backendUrl ?? requireConfig('backendUrl');
 }

package/dist/utils/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,0CAA0C,IAAI,EAAE,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,UAAU,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/utils/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC,UAAU,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC;AAC1D,CAAC"}

package/dist/utils/exec.d.ts

@@ -1 +1,12 @@
+/** PATH handed to child processes: the inherited one plus {@link extraPathDirs}. */
+export declare function execPath(): string;
+/**
+ * Run a command through a shell and resolve its trimmed stdout.
+ *
+ * `timeout` defaults to 0 (no timeout) to preserve the behaviour of existing
+ * no-timeout callers (fast systemctl/launchctl/which calls); long-running
+ * callers already pass an explicit timeout. The raised maxBuffer prevents
+ * verbose output (e.g. `npm install -g`) from rejecting with
+ * ERR_CHILD_PROCESS_STDOUT_MAXBUFFER.
+ */
 export declare function execAsync(cmd: string, timeout?: number): Promise<string>;

package/dist/utils/exec.js

@@ -1,7 +1,53 @@
 import { exec } from 'node:child_process';
+import path from 'node:path';
+import { config } from '../config.js';
+// 16 MB — avoid ERR_CHILD_PROCESS_STDOUT_MAXBUFFER on chatty commands like `npm install -g`.
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+/**
+ * Directories APPENDED to PATH for every child process we spawn.
+ *
+ * Why: the binaries we shell out to (`openclaw`, `npm`) live in a global npm
+ * prefix that is not on the ambient PATH in every context we run from, and a
+ * missing PATH entry has cost us the fleet twice:
+ *   - VM first boot: the user-data step `su - ubuntu -c "openclaw plugins
+ *     install @openclaw-cloud/mcp-warmup@latest"` died with `openclaw: command
+ *     not found` on a whole cohort (~/.profile exports the npm-global bin only
+ *     later in the bootstrap), and the `|| echo` swallowed it.
+ *   - macOS launchd: the service PATH lacks /opt/homebrew/bin, so the
+ *     best-effort `openclaw gateway restart` after a config merge always failed
+ *     with `/bin/sh: openclaw: command not found`.
+ *
+ * APPENDED, never prepended — an operator's own PATH entry still wins, so this
+ * cannot hijack a deliberately pinned binary. Non-existent dirs are harmless.
+ */
+function extraPathDirs() {
+    return [
+        path.join(config.home, '.npm-global', 'bin'), // npm prefix used by the VM provisioner
+        '/usr/local/bin',
+        '/opt/homebrew/bin', // Homebrew on Apple silicon
+    ];
+}
+/** PATH handed to child processes: the inherited one plus {@link extraPathDirs}. */
+export function execPath() {
+    const parts = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+    for (const dir of extraPathDirs()) {
+        if (!parts.includes(dir))
+            parts.push(dir);
+    }
+    return parts.join(path.delimiter);
+}
+/**
+ * Run a command through a shell and resolve its trimmed stdout.
+ *
+ * `timeout` defaults to 0 (no timeout) to preserve the behaviour of existing
+ * no-timeout callers (fast systemctl/launchctl/which calls); long-running
+ * callers already pass an explicit timeout. The raised maxBuffer prevents
+ * verbose output (e.g. `npm install -g`) from rejecting with
+ * ERR_CHILD_PROCESS_STDOUT_MAXBUFFER.
+ */
 export function execAsync(cmd, timeout = 0) {
     return new Promise((resolve, reject) => {
-        exec(cmd, { timeout }, (err, stdout) => {
+        exec(cmd, { timeout, maxBuffer: DEFAULT_MAX_BUFFER, env: { ...process.env, PATH: execPath() } }, (err, stdout) => {
             if (err)
                 reject(err);
             else

package/dist/utils/exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE1C,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,OAAO,GAAG,CAAC;IAChD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,GAAG;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,6FAA6F;AAC7F,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,aAAa;IACpB,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,wCAAwC;QACtF,gBAAgB;QAChB,mBAAmB,EAAE,4BAA4B;KAClD,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,QAAQ;IACtB,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7E,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW,EAAE,OAAO,GAAG,CAAC;IAChD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,CACF,GAAG,EACH,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,EACrF,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE;YACd,IAAI,GAAG;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/gateway-restart-handler.d.ts

@@ -1,6 +1,10 @@
 import type { AgentCommand, AgentResponse } from '../types.js';
 /**
- * Shared handler logic for commands that restart the OpenClaw gateway.
- * Used by handleRestart and handleOnboardingComplete.
+ * The handler behind every command whose whole job is "restart the OpenClaw
+ * gateway": `restart`, `deploy` and `onboarding_complete`. They were three
+ * byte-identical copies of this wrapper.
+ *
+ * Emits only the domain event (`gateway_restart`) — the command lifecycle
+ * events are owned by the dispatch loop in connection.ts.
  */
 export declare function handleGatewayRestartCommand(command: AgentCommand): Promise<AgentResponse>;

package/dist/utils/gateway-restart-handler.js

@@ -1,9 +1,18 @@
 import { restartGateway } from './gateway-restart.js';
+import { logCollector } from '../connection.js';
 /**
- * Shared handler logic for commands that restart the OpenClaw gateway.
- * Used by handleRestart and handleOnboardingComplete.
+ * The handler behind every command whose whole job is "restart the OpenClaw
+ * gateway": `restart`, `deploy` and `onboarding_complete`. They were three
+ * byte-identical copies of this wrapper.
+ *
+ * Emits only the domain event (`gateway_restart`) — the command lifecycle
+ * events are owned by the dispatch loop in connection.ts.
  */
 export async function handleGatewayRestartCommand(command) {
+    logCollector?.push('gateway_restart', 'info', 'Gateway restart requested', {
+        commandId: command.id,
+        type: command.type,
+    });
     try {
         const { stdout, stderr } = await restartGateway();
         return {

package/dist/utils/gateway-restart-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-restart-handler.js","sourceRoot":"","sources":["../../src/utils/gateway-restart-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,OAAqB;IACrE,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;QAClD,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;SACzB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAAmD,CAAC;QAC9D,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE;YACxD,KAAK,EAAE,CAAC,CAAC,OAAO;SACjB,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"gateway-restart-handler.js","sourceRoot":"","sources":["../../src/utils/gateway-restart-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,OAAqB;IACrE,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,EAAE,2BAA2B,EAAE;QACzE,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,IAAI,EAAE,OAAO,CAAC,IAAI;KACnB,CAAC,CAAC;IACH,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,EAAE,CAAC;QAClD,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;SACzB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAAmD,CAAC;QAC9D,OAAO;YACL,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE;YACxD,KAAK,EAAE,CAAC,CAAC,OAAO;SACjB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/utils/gateway-restart.d.ts

@@ -5,6 +5,13 @@ export interface GatewayRestartResult {
 /**
  * Restart the gateway via the configured agent provider.
  * Returns { stdout: '', stderr: '' } for interface compatibility.
+ *
+ * `configureProvider()` only ever runs inside the daemon's `main()`, so in
+ * EVERY CLI invocation `getProvider()` is null. This used to warn and return
+ * success, which made `agent-controller restart` (and the restart tail of
+ * `deploy` / `agent-update` / `self-update`) a silent no-op that still exited
+ * 0. We now build a throwaway provider from config instead, and throw when
+ * even that is impossible so the caller can exit non-zero.
  */
 export declare function restartGateway(): Promise<GatewayRestartResult>;
 /**

package/dist/utils/gateway-restart.js

@@ -1,13 +1,21 @@
-import { getProvider } from '../providers/index.js';
+import { createProviderFromConfig, getProvider } from '../providers/index.js';
+import { config } from '../config.js';
 /**
  * Restart the gateway via the configured agent provider.
  * Returns { stdout: '', stderr: '' } for interface compatibility.
+ *
+ * `configureProvider()` only ever runs inside the daemon's `main()`, so in
+ * EVERY CLI invocation `getProvider()` is null. This used to warn and return
+ * success, which made `agent-controller restart` (and the restart tail of
+ * `deploy` / `agent-update` / `self-update`) a silent no-op that still exited
+ * 0. We now build a throwaway provider from config instead, and throw when
+ * even that is impossible so the caller can exit non-zero.
  */
 export async function restartGateway() {
-    const provider = getProvider();
+    const provider = getProvider() ?? createProviderFromConfig();
     if (!provider) {
-        console.warn('No provider configured, cannot restart gateway');
-        return { stdout: '', stderr: '' };
+        throw new Error(`Cannot restart gateway: unknown agent provider '${config.agentProvider}' ` +
+            '(set AGENT_PROVIDER to openclaw, claude-code or mock)');
     }
     await provider.restart();
     return { stdout: '', stderr: '' };

package/dist/utils/gateway-restart.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-restart.js","sourceRoot":"","sources":["../../src/utils/gateway-restart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOpD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;QAC/D,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC"}
+{"version":3,"file":"gateway-restart.js","sourceRoot":"","sources":["../../src/utils/gateway-restart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAOtC;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,QAAQ,GAAG,WAAW,EAAE,IAAI,wBAAwB,EAAE,CAAC;IAC7D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,CAAC,aAAa,IAAI;YACzE,uDAAuD,CAC1D,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC"}

package/dist/utils/knowledge-graph.d.ts

@@ -48,8 +48,20 @@ export declare class KnowledgeGraphManager extends EventEmitter {
     /** Load graph from disk into memory. Call once at startup. */
     init(): Promise<void>;
     private readGraphFromDisk;
-    /** Serialized persist: enqueues writes so concurrent calls never interleave. */
+    /**
+     * Serialized persist: enqueues writes so concurrent calls never interleave.
+     * The queue tail swallows rejections so persistQueue is always fulfilled — a
+     * failed write never poisons the chain (the next write still runs) — while the
+     * caller of THIS write still observes its real success/failure.
+     */
     private persist;
+    /**
+     * Persist after an in-memory mutation, rolling the graph back to `snapshot`
+     * if the write fails. This keeps memory consistent with disk and with the
+     * backend (which is told the mutation failed and receives no delta) instead
+     * of leaving the failed mutation in memory to land on the next write.
+     */
+    private persistWithRollback;
     /** Atomic persist: write to .tmp, then fs.rename(). */
     private doPersist;
     /** Emit delta event after mutation (for sync to backend). */

package/dist/utils/knowledge-graph.js

@@ -33,24 +33,35 @@ export class KnowledgeGraphManager extends EventEmitter {
         try {
             const data = await fs.readFile(this.memoryFilePath, 'utf-8');
             const lines = data.split('\n').filter((line) => line.trim() !== '');
-            return lines.reduce((graph, line) => {
-                const item = JSON.parse(line);
-                if (item.type === 'entity') {
+            const graph = { entities: [], relations: [] };
+            for (const line of lines) {
+                let item;
+                try {
+                    item = JSON.parse(line);
+                }
+                catch {
+                    // Skip a single corrupt/truncated line instead of discarding the
+                    // entire graph — recover every well-formed record around it.
+                    continue;
+                }
+                if (item.type === 'entity' && typeof item.name === 'string') {
                     graph.entities.push({
                         name: item.name,
-                        entityType: item.entityType,
-                        observations: item.observations,
+                        entityType: item.entityType ?? '',
+                        observations: item.observations ?? [],
                     });
                 }
-                if (item.type === 'relation') {
+                else if (item.type === 'relation' &&
+                    typeof item.from === 'string' &&
+                    typeof item.to === 'string') {
                     graph.relations.push({
                         from: item.from,
                         to: item.to,
-                        relationType: item.relationType,
+                        relationType: item.relationType ?? '',
                     });
                 }
-                return graph;
-            }, { entities: [], relations: [] });
+            }
+            return graph;
         }
         catch (error) {
             if (error?.code === 'ENOENT') {
@@ -59,10 +70,31 @@ export class KnowledgeGraphManager extends EventEmitter {
             throw error;
         }
     }
-    /** Serialized persist: enqueues writes so concurrent calls never interleave. */
+    /**
+     * Serialized persist: enqueues writes so concurrent calls never interleave.
+     * The queue tail swallows rejections so persistQueue is always fulfilled — a
+     * failed write never poisons the chain (the next write still runs) — while the
+     * caller of THIS write still observes its real success/failure.
+     */
     persist() {
-        this.persistQueue = this.persistQueue.then(() => this.doPersist()).catch(() => { });
-        return this.persistQueue;
+        const run = this.persistQueue.then(() => this.doPersist());
+        this.persistQueue = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * Persist after an in-memory mutation, rolling the graph back to `snapshot`
+     * if the write fails. This keeps memory consistent with disk and with the
+     * backend (which is told the mutation failed and receives no delta) instead
+     * of leaving the failed mutation in memory to land on the next write.
+     */
+    async persistWithRollback(snapshot) {
+        try {
+            await this.persist();
+        }
+        catch (err) {
+            this.graph = snapshot;
+            throw err;
+        }
     }
     /** Atomic persist: write to .tmp, then fs.rename(). */
     async doPersist() {
@@ -89,8 +121,9 @@ export class KnowledgeGraphManager extends EventEmitter {
     // -------------------------------------------------------------------------
     async createEntities(entities) {
         const newEntities = entities.filter((e) => !this.graph.entities.some((existing) => existing.name === e.name));
+        const snapshot = structuredClone(this.graph);
         this.graph.entities.push(...newEntities);
-        await this.persist();
+        await this.persistWithRollback(snapshot);
         this.emitDelta('entities_created', newEntities);
         return newEntities;
     }
@@ -98,44 +131,57 @@ export class KnowledgeGraphManager extends EventEmitter {
         const newRelations = relations.filter((r) => !this.graph.relations.some((existing) => existing.from === r.from &&
             existing.to === r.to &&
             existing.relationType === r.relationType));
+        const snapshot = structuredClone(this.graph);
         this.graph.relations.push(...newRelations);
-        await this.persist();
+        await this.persistWithRollback(snapshot);
         this.emitDelta('relations_created', newRelations);
         return newRelations;
     }
     async addObservations(observations) {
-        const results = observations.map((o) => {
-            const entity = this.graph.entities.find((e) => e.name === o.entityName);
-            if (!entity) {
-                throw new Error(`Entity with name ${o.entityName} not found`);
-            }
-            const newObservations = o.contents.filter((content) => !entity.observations.includes(content));
-            entity.observations.push(...newObservations);
-            return { entityName: o.entityName, addedObservations: newObservations };
-        });
-        await this.persist();
-        this.emitDelta('observations_added', results);
-        return results;
+        const snapshot = structuredClone(this.graph);
+        try {
+            const results = observations.map((o) => {
+                const entity = this.graph.entities.find((e) => e.name === o.entityName);
+                if (!entity) {
+                    throw new Error(`Entity with name ${o.entityName} not found`);
+                }
+                const newObservations = o.contents.filter((content) => !entity.observations.includes(content));
+                entity.observations.push(...newObservations);
+                return { entityName: o.entityName, addedObservations: newObservations };
+            });
+            await this.persistWithRollback(snapshot);
+            this.emitDelta('observations_added', results);
+            return results;
+        }
+        catch (err) {
+            // Roll back any partial in-memory mutation (a missing entity throws
+            // mid-map after earlier entities were already mutated).
+            this.graph = snapshot;
+            throw err;
+        }
     }
     async deleteEntities(names) {
+        const snapshot = structuredClone(this.graph);
         this.graph.entities = this.graph.entities.filter((e) => !names.includes(e.name));
         this.graph.relations = this.graph.relations.filter((r) => !names.includes(r.from) && !names.includes(r.to));
-        await this.persist();
+        await this.persistWithRollback(snapshot);
         this.emitDelta('entities_deleted', names);
     }
     async deleteObservations(deletions) {
+        const snapshot = structuredClone(this.graph);
         deletions.forEach((d) => {
             const entity = this.graph.entities.find((e) => e.name === d.entityName);
             if (entity) {
                 entity.observations = entity.observations.filter((o) => !d.observations.includes(o));
             }
         });
-        await this.persist();
+        await this.persistWithRollback(snapshot);
         this.emitDelta('observations_deleted', deletions);
     }
     async deleteRelations(relations) {
+        const snapshot = structuredClone(this.graph);
         this.graph.relations = this.graph.relations.filter((r) => !relations.some((del) => r.from === del.from && r.to === del.to && r.relationType === del.relationType));
-        await this.persist();
+        await this.persistWithRollback(snapshot);
         this.emitDelta('relations_deleted', relations);
     }
     // -------------------------------------------------------------------------