From 75b1ac12df1e6b8cdf2170ccd7b6f51169024d0f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 10:31:58 +0100
Subject: [PATCH 01/76] feat(onboarding): enable lean mode for local models
 (#110596)

---
 docs/.generated/config-baseline.sha256        |   6 +-
 docs/concepts/experimental-features.md        |   6 +-
 src/commands/onboard-guided.custodian.test.ts |  22 ++++
 src/config/local-model-lean-auto.test.ts      |  91 ++++++++++++++++
 src/config/local-model-lean-auto.ts           | 101 ++++++++++++++++++
 src/config/schema.help.core.ts                |   2 +
 src/config/schema.labels.ts                   |   1 +
 src/config/types.openclaw.ts                  |   2 +
 src/config/zod-schema.root-shape.ts           |   1 +
 src/system-agent/setup-inference.test.ts      |  53 ++++++++-
 src/system-agent/setup-inference.ts           |  31 +++++-
 11 files changed, 305 insertions(+), 11 deletions(-)
 create mode 100644 src/config/local-model-lean-auto.test.ts
 create mode 100644 src/config/local-model-lean-auto.ts

diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256
index 753bc17ead0..85012a3c2af 100644
--- a/docs/.generated/config-baseline.sha256
+++ b/docs/.generated/config-baseline.sha256
@@ -1,4 +1,4 @@
-cc6b32ad0a77ec983c3b97fadee565f93e0c9437845335a9dd55ea83e60a366d  config-baseline.json
-17d536dc4bb6a97a18120cb4ed1884a2f4e250a881277cee28dfe26aaeeb005c  config-baseline.core.json
+53e7eea9a0193d94f5afe8e774456ae71cd3eddf99e5224602fcf13bb845051b  config-baseline.json
+97c9ec219366ad2fab4d83d5b05eb3ae3df71db68747e7b31cc697a76676c620  config-baseline.core.json
 f75efa4f3fa4ac7c2e7dc6580a1dd1efaa8e2e13ec7df9c21838c8ebc44a3dca  config-baseline.channel.json
-ddde5320a53d2cb2bb41f4624ae09a4e05b11eba2f3f9d0a53a50ebf65d13ca5  config-baseline.plugin.json
+e4f096d6d3c39fefdd1649cab8336b8dfba1f2194eb804fa6126eb25fe2d2b93  config-baseline.plugin.json
diff --git a/docs/concepts/experimental-features.md b/docs/concepts/experimental-features.md
index 9eb75780502..217978461fb 100644
--- a/docs/concepts/experimental-features.md
+++ b/docs/concepts/experimental-features.md
@@ -7,9 +7,9 @@ read_when:
   - You want one place to find the currently documented experimental flags
 ---
 
-Experimental features are opt-in preview surfaces behind explicit flags. They need more real-world mileage before they get a stable default or a long-lived contract.
+Experimental features are preview surfaces behind explicit flags. They need more real-world mileage before they get a stable default or a long-lived contract.
 
-- Off by default unless a doc tells you to enable one.
+- Off by default unless a doc describes a narrow automatic setup rule.
 - Shape and behavior can change faster than stable config.
 - Prefer a stable path when one already exists.
 - Roll out broadly only after testing in a smaller environment first.
@@ -27,6 +27,8 @@ Experimental features are opt-in preview surfaces behind explicit flags. They ne
 
 `agents.defaults.experimental.localModelLean: true` drops heavyweight optional tools from the agent's direct surface every turn: `browser`, `cron`, `message`, `image_generate`, `music_generate`, `video_generate`, `tts`, and `pdf`. Explicitly allowed or delivery-required tools remain available, though Tool Search may catalog them instead of exposing them directly. Lean mode also defaults plugin/MCP/client catalogs to structured Tool Search (`tool_search`, `tool_describe`, `tool_call`) when `tools.toolSearch` is not already set. Use `agents.list[].experimental.localModelLean` to scope this to one agent.
 
+During onboarding, a verified `ollama` or `lmstudio` inference route automatically sets `agents.defaults.experimental.localModelLean: true` when that value is absent. OpenClaw records that the setting came from onboarding, so a later verified non-local route lifts only the automatic setting. An explicitly configured `true` or `false` is preserved. Other self-hosted and OpenAI-compatible providers are not inferred from model names or URLs.
+
 If you already tune Tool Search globally, OpenClaw leaves that config alone. Set `tools.toolSearch: false` to opt out of the lean-mode Tool Search default.
 
 In structured `tools` mode, lean runs keep `exec` directly visible beside the Tool Search controls so coding-tuned local models can still choose their familiar shell path. This changes schema visibility only: normal tool policy, sandboxing, and exec approvals still apply. Explicit `code` and `directory` modes keep their normal compaction behavior.
diff --git a/src/commands/onboard-guided.custodian.test.ts b/src/commands/onboard-guided.custodian.test.ts
index a03c85f9d12..003bd5b2942 100644
--- a/src/commands/onboard-guided.custodian.test.ts
+++ b/src/commands/onboard-guided.custodian.test.ts
@@ -236,6 +236,28 @@ describe("runGuidedOnboarding custodian flow", () => {
     expect(deps.launchHatchTui).toHaveBeenCalledWith("/tmp/work");
   });
 
+  it("announces the lean surface after local-model activation", async () => {
+    const announcement =
+      "This model is small, so I set up the lean surface — switching to a bigger model later lifts it.";
+    const prompter = createWizardPrompter();
+    const deps = setupDeps({
+      prompter,
+      activate: vi.fn(async () => ({
+        ok: true as const,
+        modelRef: "lmstudio/qwen-local",
+        latencyMs: 1250,
+        lines: ["Inference verified: lmstudio/qwen-local", announcement],
+      })),
+    });
+
+    await runGuidedOnboarding({ acceptRisk: true, workspace: "/tmp/work" }, makeRuntime(), deps);
+
+    expect(prompter.note).toHaveBeenCalledWith(
+      expect.stringContaining(announcement),
+      "Inference ready",
+    );
+  });
+
   it("skips persisting an unchanged access mode", async () => {
     readConfigFileSnapshot.mockResolvedValue({
       exists: true,
diff --git a/src/config/local-model-lean-auto.test.ts b/src/config/local-model-lean-auto.test.ts
new file mode 100644
index 00000000000..73b20c6fdff
--- /dev/null
+++ b/src/config/local-model-lean-auto.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { applyAutoLocalModelLean } from "./local-model-lean-auto.js";
+
+describe("local model lean onboarding defaults", () => {
+  it.each([
+    ["ollama", true],
+    ["OLLAMA", true],
+    ["lmstudio", true],
+    ["ollama-cloud", false],
+    ["sglang", false],
+    ["vllm", false],
+    ["openai", false],
+  ])("classifies %s conservatively", (providerId, expected) => {
+    const modelRef = `${providerId}/test-model`;
+    const result = applyAutoLocalModelLean({ config: {}, providerId, modelRef });
+
+    expect(result.enabled).toBe(expected);
+    expect(result.changed).toBe(expected);
+    expect(result.config.agents?.defaults?.experimental?.localModelLean).toBe(
+      expected ? true : undefined,
+    );
+    expect(result.config.wizard?.localModelLeanAutoModel).toBe(expected ? modelRef : undefined);
+  });
+
+  it.each([false, true])("preserves an explicit localModelLean=%s", (localModelLean) => {
+    const config = { agents: { defaults: { experimental: { localModelLean } } } };
+
+    expect(
+      applyAutoLocalModelLean({ config, providerId: "ollama", modelRef: "ollama/test-model" }),
+    ).toEqual({
+      config,
+      changed: false,
+      enabled: false,
+    });
+  });
+
+  it("lifts only an onboarding-owned lean setting for a later non-local route", () => {
+    const config = {
+      wizard: { localModelLeanAutoModel: "ollama/test-model" },
+      agents: {
+        defaults: {
+          model: "ollama/test-model",
+          experimental: { localModelLean: true },
+        },
+      },
+    };
+    const lifted = applyAutoLocalModelLean({
+      config,
+      providerId: "openai",
+      modelRef: "openai/gpt-test",
+    });
+
+    expect(lifted.changed).toBe(true);
+    expect(lifted.enabled).toBe(false);
+    expect(lifted.config.agents?.defaults?.experimental?.localModelLean).toBeUndefined();
+    expect(lifted.config.wizard?.localModelLeanAutoModel).toBeUndefined();
+  });
+
+  it("preserves an explicit lean setting for a non-local route", () => {
+    const config = { agents: { defaults: { experimental: { localModelLean: true } } } };
+
+    expect(
+      applyAutoLocalModelLean({ config, providerId: "openai", modelRef: "openai/gpt-test" }),
+    ).toEqual({
+      config,
+      changed: false,
+      enabled: false,
+    });
+  });
+
+  it("hands ownership to a model changed outside onboarding", () => {
+    const config = {
+      wizard: { localModelLeanAutoModel: "ollama/old-model" },
+      agents: {
+        defaults: {
+          model: "openai/gpt-test",
+          experimental: { localModelLean: true },
+        },
+      },
+    };
+
+    const result = applyAutoLocalModelLean({
+      config,
+      providerId: "openai",
+      modelRef: "openai/gpt-test",
+    });
+
+    expect(result.config.agents?.defaults?.experimental?.localModelLean).toBe(true);
+    expect(result.config.wizard?.localModelLeanAutoModel).toBeUndefined();
+  });
+});
diff --git a/src/config/local-model-lean-auto.ts b/src/config/local-model-lean-auto.ts
new file mode 100644
index 00000000000..65f3c5fe3d9
--- /dev/null
+++ b/src/config/local-model-lean-auto.ts
@@ -0,0 +1,101 @@
+import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
+import type { OpenClawConfig } from "./types.openclaw.js";
+
+const AUTO_LOCAL_MODEL_LEAN_PROVIDER_IDS = new Set(["lmstudio", "ollama"]);
+
+/** Returns true only for local runtimes that onboarding can identify without model-name guesses. */
+function shouldAutoEnableLocalModelLean(providerId: string): boolean {
+  return AUTO_LOCAL_MODEL_LEAN_PROVIDER_IDS.has(normalizeProviderId(providerId));
+}
+
+function resolveDefaultModelRef(config: OpenClawConfig): string | undefined {
+  const model = config.agents?.defaults?.model;
+  return typeof model === "string" ? model : model?.primary;
+}
+
+function clearAutoModel(config: OpenClawConfig): OpenClawConfig {
+  const wizard = { ...config.wizard };
+  delete wizard.localModelLeanAutoModel;
+  return { ...config, wizard };
+}
+
+/** Maintains the onboarding-owned lean default while preserving explicit user configuration. */
+export function applyAutoLocalModelLean(params: {
+  config: OpenClawConfig;
+  providerId: string;
+  modelRef: string;
+}): {
+  config: OpenClawConfig;
+  changed: boolean;
+  enabled: boolean;
+} {
+  const localModelLean = params.config.agents?.defaults?.experimental?.localModelLean;
+  const autoModel = params.config.wizard?.localModelLeanAutoModel;
+  const onboardingOwnsSetting =
+    autoModel !== undefined && resolveDefaultModelRef(params.config) === autoModel;
+  if (!shouldAutoEnableLocalModelLean(params.providerId)) {
+    if (!autoModel) {
+      return { config: params.config, changed: false, enabled: false };
+    }
+    const config = clearAutoModel(params.config);
+    if (!onboardingOwnsSetting || localModelLean !== true) {
+      return { config, changed: true, enabled: false };
+    }
+    const experimental = { ...params.config.agents?.defaults?.experimental };
+    delete experimental.localModelLean;
+    return {
+      config: {
+        ...config,
+        agents: {
+          ...config.agents,
+          defaults: {
+            ...config.agents?.defaults,
+            experimental,
+          },
+        },
+      },
+      changed: true,
+      enabled: false,
+    };
+  }
+  if (localModelLean !== undefined) {
+    if (!autoModel) {
+      return { config: params.config, changed: false, enabled: false };
+    }
+    if (!onboardingOwnsSetting || !localModelLean) {
+      return { config: clearAutoModel(params.config), changed: true, enabled: false };
+    }
+    if (autoModel === params.modelRef) {
+      return { config: params.config, changed: false, enabled: false };
+    }
+    return {
+      config: {
+        ...params.config,
+        wizard: { ...params.config.wizard, localModelLeanAutoModel: params.modelRef },
+      },
+      changed: true,
+      enabled: false,
+    };
+  }
+  return {
+    config: {
+      ...params.config,
+      wizard: {
+        ...params.config.wizard,
+        localModelLeanAutoModel: params.modelRef,
+      },
+      agents: {
+        ...params.config.agents,
+        defaults: {
+          ...params.config.agents?.defaults,
+          experimental: {
+            ...params.config.agents?.defaults?.experimental,
+            localModelLean: true,
+          },
+        },
+      },
+    },
+    changed: true,
+    enabled: true,
+  };
+}
diff --git a/src/config/schema.help.core.ts b/src/config/schema.help.core.ts
index 62ee40aa7f5..31c39cd4f1f 100644
--- a/src/config/schema.help.core.ts
+++ b/src/config/schema.help.core.ts
@@ -54,6 +54,8 @@ export const CORE_FIELD_HELP: Record<string, string> = {
     "Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce setup steps when verifying setup regressions.",
   "wizard.lastRunMode":
     'Wizard execution mode recorded as "local" or "remote" for the most recent setup flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.',
+  "wizard.localModelLeanAutoModel":
+    "System-managed model reference indicating that inference onboarding enabled the global lean-model surface. A later verified route uses this marker to remove only the onboarding-owned setting; a model changed outside onboarding hands ownership back to the user.",
   "wizard.securityAcknowledgedAt":
     "ISO timestamp for when the setup security acknowledgement was accepted on this config. Setup uses this to avoid repeating the acknowledgement on later wizard runs.",
   audit:
diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts
index 1f2b15646ea..3c54500c0e2 100644
--- a/src/config/schema.labels.ts
+++ b/src/config/schema.labels.ts
@@ -31,6 +31,7 @@ export const FIELD_LABELS: Record<string, string> = {
   "wizard.lastRunCommit": "Wizard Last Run Commit",
   "wizard.lastRunCommand": "Wizard Last Run Command",
   "wizard.lastRunMode": "Wizard Last Run Mode",
+  "wizard.localModelLeanAutoModel": "Wizard Auto-Set Lean Model",
   "wizard.securityAcknowledgedAt": "Wizard Security Acknowledgement Timestamp",
   audit: "Audit Ledger",
   "audit.enabled": "Audit Ledger Enabled",
diff --git a/src/config/types.openclaw.ts b/src/config/types.openclaw.ts
index 8b358c259ad..dda7d445f9c 100644
--- a/src/config/types.openclaw.ts
+++ b/src/config/types.openclaw.ts
@@ -143,6 +143,8 @@ export type OpenClawConfig = {
     lastRunCommand?: string;
     /** Whether the last wizard run configured a local or remote install. */
     lastRunMode?: "local" | "remote";
+    /** Model whose lean-mode default is owned by inference onboarding. */
+    localModelLeanAutoModel?: string;
     /** ISO timestamp when the setup security acknowledgement was accepted on this config. */
     securityAcknowledgedAt?: string;
   };
diff --git a/src/config/zod-schema.root-shape.ts b/src/config/zod-schema.root-shape.ts
index c34b7510b60..08dc934639b 100644
--- a/src/config/zod-schema.root-shape.ts
+++ b/src/config/zod-schema.root-shape.ts
@@ -82,6 +82,7 @@ export const OpenClawSchemaShape = {
       lastRunCommit: z.string().optional(),
       lastRunCommand: z.string().optional(),
       lastRunMode: z.union([z.literal("local"), z.literal("remote")]).optional(),
+      localModelLeanAutoModel: z.string().optional(),
       securityAcknowledgedAt: z.string().optional(),
     })
     .optional(),
diff --git a/src/system-agent/setup-inference.test.ts b/src/system-agent/setup-inference.test.ts
index 7c16f60f74d..aa585c4efeb 100644
--- a/src/system-agent/setup-inference.test.ts
+++ b/src/system-agent/setup-inference.test.ts
@@ -1216,7 +1216,22 @@ describe("activateSetupInference", () => {
     expect(persistedConfig.gateway).toBeUndefined();
   });
 
-  it("rechecks the exact provider model and activates it without storing credentials", async () => {
+  it.each([
+    {
+      name: "auto-enables the lean surface for a verified local model",
+      initialConfig: {} satisfies OpenClawConfig,
+      expectedLean: true,
+      expectedAnnouncement: true,
+    },
+    {
+      name: "preserves an explicit localModelLean=false",
+      initialConfig: {
+        agents: { defaults: { experimental: { localModelLean: false } } },
+      } satisfies OpenClawConfig,
+      expectedLean: false,
+      expectedAnnouncement: false,
+    },
+  ])("$name", async ({ initialConfig, expectedLean, expectedAnnouncement }) => {
     const modelRef = "lmstudio/qwen-local";
     const detect = vi.fn(async () => ({ modelRef, detail: "qwen-local at localhost" }));
     const prepare = vi.fn(async () => ({
@@ -1259,7 +1274,7 @@ describe("activateSetupInference", () => {
         },
       ],
     };
-    const configHarness = createConfigTransformHarness();
+    const configHarness = createConfigTransformHarness(initialConfig);
     const updateAuthStore = vi.fn();
 
     const result = await activateSetupInference({
@@ -1268,6 +1283,15 @@ describe("activateSetupInference", () => {
       surface: "gateway",
       runtime,
       deps: {
+        readConfigFileSnapshot: vi.fn(async () => ({
+          exists: true,
+          valid: true,
+          path: "/tmp/openclaw.json",
+          issues: [],
+          config: initialConfig,
+          sourceConfig: initialConfig,
+          runtimeConfig: initialConfig,
+        })) as never,
         resolveManifestProviderAuthChoice: () => ({
           pluginId: "lmstudio",
           providerId: "lmstudio",
@@ -1285,11 +1309,23 @@ describe("activateSetupInference", () => {
     });
 
     expect(result).toMatchObject({ ok: true, modelRef });
+    if (!result.ok) {
+      throw new Error(result.error);
+    }
+    expect(result.lines).toEqual([
+      `Inference verified: ${modelRef}`,
+      ...(expectedAnnouncement
+        ? [
+            "This model is small, so I set up the lean surface — switching to a bigger model later lifts it.",
+          ]
+        : []),
+    ]);
     expect(detect).not.toHaveBeenCalled();
     expect(prepare).toHaveBeenCalledOnce();
     expect(updateAuthStore).not.toHaveBeenCalled();
     expect(configHarness.current()).toMatchObject({
-      agents: { defaults: { model: modelRef } },
+      ...(expectedAnnouncement ? { wizard: { localModelLeanAutoModel: modelRef } } : {}),
+      agents: { defaults: { model: modelRef, experimental: { localModelLean: expectedLean } } },
       models: {
         providers: {
           lmstudio: {
@@ -1482,8 +1518,15 @@ describe("activateSetupInference", () => {
     expect(configHarness.current()).toEqual(concurrentConfig);
   });
 
-  it("preserves authored provider rows instead of runtime-materialized metadata", async () => {
+  it("preserves authored provider rows and lifts an onboarding-owned lean setting", async () => {
     const sourceConfig = {
+      wizard: { localModelLeanAutoModel: "lmstudio/qwen-local" },
+      agents: {
+        defaults: {
+          model: "lmstudio/qwen-local",
+          experimental: { localModelLean: true },
+        },
+      },
       models: {
         providers: {
           openai: {
@@ -1539,6 +1582,8 @@ describe("activateSetupInference", () => {
     expect(configHarness.current().models?.providers?.openai?.models).toEqual(
       sourceConfig.models.providers.openai.models,
     );
+    expect(configHarness.current().agents?.defaults?.experimental?.localModelLean).toBeUndefined();
+    expect(configHarness.current().wizard?.localModelLeanAutoModel).toBeUndefined();
   });
 
   it("rejects an existing route that changes after its live probe", async () => {
diff --git a/src/system-agent/setup-inference.ts b/src/system-agent/setup-inference.ts
index 8aa873067f6..cb17aedb728 100644
--- a/src/system-agent/setup-inference.ts
+++ b/src/system-agent/setup-inference.ts
@@ -35,6 +35,7 @@ import {
   type InferenceBackendKind,
 } from "../commands/onboard-inference.js";
 import { createMergePatch } from "../config/io.write-prepare.js";
+import { applyAutoLocalModelLean } from "../config/local-model-lean-auto.js";
 import { applyMergePatch } from "../config/merge-patch.js";
 import {
   normalizeAgentModelRefForConfig,
@@ -112,6 +113,8 @@ const log = createSubsystemLogger("system-agent/setup-inference");
 export const SETUP_INFERENCE_TEST_TIMEOUT_MS = 90_000;
 const SETUP_INFERENCE_TEST_PROMPT = "Reply with the single word OK. Do not use tools.";
 const PROVIDER_AUTO_SETUP_KIND_PREFIX = "provider-auto:";
+const AUTO_LOCAL_MODEL_LEAN_ANNOUNCEMENT =
+  "This model is small, so I set up the lean surface — switching to a bigger model later lifts it.";
 
 export type ProviderAutoSetupInferenceKind = `provider-auto:${string}`;
 export type SetupInferenceKind = InferenceBackendKind | ProviderAutoSetupInferenceKind;
@@ -1907,11 +1910,17 @@ async function activateSetupInferenceUnredacted(
       };
     }
 
+    const autoLocalModelLeanUpdate = applyAutoLocalModelLean({
+      config: sourceCfg,
+      providerId: testPlan.provider,
+      modelRef: plan.modelRef,
+    });
     const needsPersistence =
       plan.persistModelRef !== undefined ||
       plan.manualAuth !== undefined ||
       codexPluginPatch !== undefined ||
-      pendingCodexInstall !== undefined;
+      pendingCodexInstall !== undefined ||
+      autoLocalModelLeanUpdate.changed;
     if (
       !test.auth.authFingerprint &&
       (!test.auth.runtimeOwnerFingerprint ||
@@ -1966,6 +1975,7 @@ async function activateSetupInferenceUnredacted(
       }
     }
     let committedConfig: OpenClawConfig | undefined;
+    let autoLocalModelLeanApplied = false;
     if (!needsPersistence) {
       const latestSnapshot = await readSnapshot();
       const latestRuntime =
@@ -2050,6 +2060,11 @@ async function activateSetupInferenceUnredacted(
           }
           next = enabledCodex.config;
         }
+        next = applyAutoLocalModelLean({
+          config: next,
+          providerId: testPlan.provider,
+          modelRef: plan.modelRef,
+        }).config;
         next = selectModel ? selectModel(next) : next;
         if (!pendingCodexInstall) {
           return next;
@@ -2185,6 +2200,11 @@ async function activateSetupInferenceUnredacted(
                 "The authored target model metadata changed during its live inference test, so the verified candidate was not saved. Review the current model settings and retry.",
               );
             }
+            const autoLocalModelLean = applyAutoLocalModelLean({
+              config: current,
+              providerId: testPlan.provider,
+              modelRef: plan.modelRef,
+            });
             const nextConfig = stageCandidate(current, "source");
             const nextRouteProjection = await projectDefaultInferenceRoute(nextConfig);
             const nextResolvedRoute = await resolveSystemAgentConfiguredRouteFromConfig(nextConfig);
@@ -2211,6 +2231,7 @@ async function activateSetupInferenceUnredacted(
             throwIfSetupInferenceCancelled(params);
             params.onCommitStarted?.();
             commitMayHaveStarted = true;
+            autoLocalModelLeanApplied = autoLocalModelLean.enabled;
             return { nextConfig };
           },
         });
@@ -2284,7 +2305,13 @@ async function activateSetupInferenceUnredacted(
         );
       }
     }
-    let lines = [`Inference verified: ${plan.modelRef}`];
+    const announceAutoLocalModelLean =
+      autoLocalModelLeanApplied &&
+      committedConfig?.agents?.defaults?.experimental?.localModelLean === true;
+    let lines = [
+      `Inference verified: ${plan.modelRef}`,
+      ...(announceAutoLocalModelLean ? [AUTO_LOCAL_MODEL_LEAN_ANNOUNCEMENT] : []),
+    ];
     if (params.surface === "gateway" && params.recordSetupAudit !== false) {
       const after = await readSnapshot().catch(() => null);
       try {

From 35754a63ccafc41122085bc9467fd3e1dbc8d4f3 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 17:34:00 +0800
Subject: [PATCH 02/76] fix(plugins): bound marketplace manifest file reads
 (#101774)

* fix(plugins): bound marketplace manifest file reads

* fix(plugins): distinguish oversized marketplace manifest from other read failures

* fix(plugins): follow symlinked marketplace manifests while bounding reads

* test(plugins): cover oversized symlinked marketplace manifest target
---
 src/plugins/marketplace.test.ts | 61 +++++++++++++++++++++++++++++++++
 src/plugins/marketplace.ts      | 25 +++++++++++++-
 2 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/src/plugins/marketplace.test.ts b/src/plugins/marketplace.test.ts
index b7db20bd94a..6f7d6badac6 100644
--- a/src/plugins/marketplace.test.ts
+++ b/src/plugins/marketplace.test.ts
@@ -305,6 +305,67 @@ describe("marketplace plugins", () => {
     });
   });
 
+  it("rejects oversized local marketplace manifests", async () => {
+    await withTempDir("openclaw-marketplace-test-", async (rootDir) => {
+      const manifestPath = path.join(rootDir, ".claude-plugin", "marketplace.json");
+      await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+      await fs.writeFile(manifestPath, Buffer.alloc(16 * 1024 * 1024 + 1, "x"));
+
+      const result = await listMarketplacePlugins({ marketplace: rootDir });
+
+      expect(result).toEqual({
+        ok: false,
+        error: "Marketplace manifest too large",
+      });
+    });
+  });
+
+  it("follows a symlinked marketplace manifest to a regular file", async () => {
+    if (process.platform === "win32") {
+      // Symlink support in unit tests is not guaranteed on Windows CI runners.
+      return;
+    }
+    await withTempDir("openclaw-marketplace-test-", async (rootDir) => {
+      const manifestPath = path.join(rootDir, ".claude-plugin", "marketplace.json");
+      await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+      const targetPath = path.join(rootDir, "real-manifest.json");
+      await fs.writeFile(
+        targetPath,
+        JSON.stringify({ plugins: [{ name: "symlinked-plugin", source: "." }] }),
+        "utf-8",
+      );
+      await fs.symlink(targetPath, manifestPath);
+
+      const result = await listMarketplacePlugins({ marketplace: rootDir });
+
+      expect(result.ok).toBe(true);
+      expect(
+        (result as { ok: true; manifest: { plugins: unknown[] } }).manifest.plugins,
+      ).toHaveLength(1);
+    });
+  });
+
+  it("rejects a symlinked marketplace manifest whose target exceeds the size limit", async () => {
+    if (process.platform === "win32") {
+      // Symlink support in unit tests is not guaranteed on Windows CI runners.
+      return;
+    }
+    await withTempDir("openclaw-marketplace-test-", async (rootDir) => {
+      const manifestPath = path.join(rootDir, ".claude-plugin", "marketplace.json");
+      await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+      const targetPath = path.join(rootDir, "real-manifest.json");
+      await fs.writeFile(targetPath, Buffer.alloc(16 * 1024 * 1024 + 1, "x"));
+      await fs.symlink(targetPath, manifestPath);
+
+      const result = await listMarketplacePlugins({ marketplace: rootDir });
+
+      expect(result).toEqual({
+        ok: false,
+        error: "Marketplace manifest too large",
+      });
+    });
+  });
+
   it("resolves relative plugin paths against the marketplace root", async () => {
     await withTempDir("openclaw-marketplace-test-", async (rootDir) => {
       const pluginDir = path.join(rootDir, "plugins", "frontend-design");
diff --git a/src/plugins/marketplace.ts b/src/plugins/marketplace.ts
index 6a425dd14cf..c670aa2882b 100644
--- a/src/plugins/marketplace.ts
+++ b/src/plugins/marketplace.ts
@@ -13,6 +13,7 @@ import { resolveOsHomeRelativePath } from "../infra/home-dir.js";
 import { tryReadJson } from "../infra/json-files.js";
 import { fetchWithSsrFGuard } from "../infra/net/fetch-guard.js";
 import { isPathInside } from "../infra/path-guards.js";
+import { readRegularFile } from "../infra/regular-file.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 import type { InstallPolicySource } from "../security/install-policy.js";
 import { resolveUserPath } from "../utils.js";
@@ -23,6 +24,7 @@ import { installPluginFromPath, type InstallPluginResult } from "./install.js";
 const DEFAULT_GIT_TIMEOUT_MS = 120_000;
 const DEFAULT_MARKETPLACE_DOWNLOAD_TIMEOUT_MS = 120_000;
 const MAX_MARKETPLACE_ARCHIVE_BYTES = 256 * 1024 * 1024;
+const MAX_MARKETPLACE_MANIFEST_BYTES = 16 * 1024 * 1024;
 const MARKETPLACE_MANIFEST_CANDIDATES = [
   path.join(".claude-plugin", "marketplace.json"),
   "marketplace.json",
@@ -597,7 +599,28 @@ async function loadMarketplace(params: {
     remoteRef?: string;
     cleanup?: () => Promise<void>;
   }): Promise<{ ok: true; marketplace: LoadedMarketplace } | { ok: false; error: string }> => {
-    const raw = await fs.readFile(paramsLocal.manifestPath, "utf-8");
+    let raw: string;
+    try {
+      // Resolve symlinks so a marketplace.json that points to a regular file
+      // keeps working, while the bounded regular-file read still rejects
+      // directories, FIFOs, and oversized targets.
+      const resolvedManifestPath = await fs.realpath(paramsLocal.manifestPath);
+      const { buffer } = await readRegularFile({
+        filePath: resolvedManifestPath,
+        maxBytes: MAX_MARKETPLACE_MANIFEST_BYTES,
+      });
+      raw = buffer.toString("utf-8");
+    } catch (err) {
+      await paramsLocal.cleanup?.();
+      const message = err instanceof Error ? err.message : String(err);
+      // readRegularFile rejects symlinks/non-files and caps file size. Only the
+      // size cap should be reported as an oversize manifest; other read failures
+      // need their own diagnostic so users don't chase the wrong problem.
+      if (message.startsWith("File exceeds")) {
+        return { ok: false, error: "Marketplace manifest too large" };
+      }
+      return { ok: false, error: `Marketplace manifest unreadable: ${message}` };
+    }
     const parsed = parseMarketplaceManifest(raw, paramsLocal.manifestPath);
     if (!parsed.ok) {
       await paramsLocal.cleanup?.();

From 609e5d23184bb849fa2efd9c2d4c945ac8c27c81 Mon Sep 17 00:00:00 2001
From: xingzhou <zhang.guiping@xydigit.com>
Date: Sat, 18 Jul 2026 17:36:35 +0800
Subject: [PATCH 03/76] fix(gateway): session workspace reveal hangs on
 foreground opener (#110277)

* fix(gateway): bound session workspace reveal opener

* refactor(gateway): share bounded path opener lifecycle

---------

Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 src/gateway/server-methods/config.test.ts    |  54 ++------
 src/gateway/server-methods/open-path.test.ts | 138 +++++++++++++++++++
 src/gateway/server-methods/open-path.ts      |  86 +++++++++++-
 3 files changed, 235 insertions(+), 43 deletions(-)
 create mode 100644 src/gateway/server-methods/open-path.test.ts

diff --git a/src/gateway/server-methods/config.test.ts b/src/gateway/server-methods/config.test.ts
index 5cbf9d2bf4c..3a79387678e 100644
--- a/src/gateway/server-methods/config.test.ts
+++ b/src/gateway/server-methods/config.test.ts
@@ -11,10 +11,9 @@ import {
   loadConfigSchemaResponseForTests,
 } from "./config.js";
 import { createConfigHandlerHarness } from "./config.test-helpers.js";
-import { resolveOpenPathCommand } from "./open-path.js";
 
-const { runExecMock, loadGatewayRuntimeConfigSchemaMock } = vi.hoisted(() => ({
-  runExecMock: vi.fn(),
+const { execOpenPathMock, loadGatewayRuntimeConfigSchemaMock } = vi.hoisted(() => ({
+  execOpenPathMock: vi.fn(),
   loadGatewayRuntimeConfigSchemaMock: vi.fn(() => ({
     schema: { type: "object" },
     uiHints: undefined,
@@ -22,14 +21,17 @@ const { runExecMock, loadGatewayRuntimeConfigSchemaMock } = vi.hoisted(() => ({
   })),
 }));
 
-vi.mock("../../process/exec.js", () => ({ runExec: runExecMock }));
+vi.mock("./open-path.js", async () => {
+  const actual = await vi.importActual<typeof import("./open-path.js")>("./open-path.js");
+  return { ...actual, execOpenPath: execOpenPathMock };
+});
 
 vi.mock("../../config/runtime-schema.js", () => ({
   loadGatewayRuntimeConfigSchema: loadGatewayRuntimeConfigSchemaMock,
 }));
 
-function mockRunExecError(error: Error) {
-  runExecMock.mockRejectedValue(error);
+function mockOpenPathError(error: Error) {
+  execOpenPathMock.mockRejectedValue(error);
 }
 
 async function invokeConfigOpenFile() {
@@ -47,40 +49,12 @@ afterEach(() => {
   vi.clearAllMocks();
 });
 
-describe("resolveOpenPathCommand", () => {
-  it("uses open on macOS", () => {
-    expect(resolveOpenPathCommand("/tmp/openclaw.json", "darwin")).toEqual({
-      command: "open",
-      args: ["/tmp/openclaw.json"],
-    });
-  });
-
-  it("uses xdg-open on Linux", () => {
-    expect(resolveOpenPathCommand("/tmp/openclaw.json", "linux")).toEqual({
-      command: "xdg-open",
-      args: ["/tmp/openclaw.json"],
-    });
-  });
-
-  it("uses a quoted PowerShell FilePath on Windows", () => {
-    expect(resolveOpenPathCommand(String.raw`C:\tmp\o'hai & calc.json`, "win32")).toEqual({
-      command: "powershell.exe",
-      args: [
-        "-NoProfile",
-        "-NonInteractive",
-        "-Command",
-        String.raw`Start-Process -FilePath 'C:\tmp\o''hai & calc.json'`,
-      ],
-    });
-  });
-});
-
 describe("config.openFile", () => {
   it("opens the configured file without shell interpolation", async () => {
     await withEnvAsync({ OPENCLAW_CONFIG_PATH: "/tmp/config $(touch pwned).json" }, async () => {
-      runExecMock.mockImplementation(async (command: string, args: string[]) => {
-        expect(["open", "xdg-open", "powershell.exe"]).toContain(command);
-        expect(args).toEqual(["/tmp/config $(touch pwned).json"]);
+      execOpenPathMock.mockImplementation(async (command: { command: string; args: string[] }) => {
+        expect(["open", "xdg-open", "powershell.exe"]).toContain(command.command);
+        expect(command.args).toEqual(["/tmp/config $(touch pwned).json"]);
         return { stdout: "", stderr: "" };
       });
 
@@ -99,7 +73,7 @@ describe("config.openFile", () => {
 
   it("returns a detailed error and logs details when the opener fails", async () => {
     await withEnvAsync({ OPENCLAW_CONFIG_PATH: "/tmp/config.json" }, async () => {
-      mockRunExecError(Object.assign(new Error("spawn xdg-open ENOENT"), { code: "ENOENT" }));
+      mockOpenPathError(Object.assign(new Error("spawn xdg-open ENOENT"), { code: "ENOENT" }));
 
       const { respond, logGateway } = await invokeConfigOpenFile();
 
@@ -121,7 +95,7 @@ describe("config.openFile", () => {
   it("does not split surrogate pairs when truncating the failed config path", async () => {
     const pathPrefix = `/tmp/${"a".repeat(111)}`;
     await withEnvAsync({ OPENCLAW_CONFIG_PATH: `${pathPrefix}😀tail.json` }, async () => {
-      mockRunExecError(new Error("open failed"));
+      mockOpenPathError(new Error("open failed"));
 
       const { logGateway } = await invokeConfigOpenFile();
 
@@ -133,7 +107,7 @@ describe("config.openFile", () => {
 
   it("returns actionable headless environment error when xdg-open reports no method available", async () => {
     await withEnvAsync({ OPENCLAW_CONFIG_PATH: "/tmp/config.json" }, async () => {
-      mockRunExecError(new Error("xdg-open: no method available for opening '/tmp/config.json'"));
+      mockOpenPathError(new Error("xdg-open: no method available for opening '/tmp/config.json'"));
 
       const { respond, logGateway } = await invokeConfigOpenFile();
 
diff --git a/src/gateway/server-methods/open-path.test.ts b/src/gateway/server-methods/open-path.test.ts
new file mode 100644
index 00000000000..5a58ad6849f
--- /dev/null
+++ b/src/gateway/server-methods/open-path.test.ts
@@ -0,0 +1,138 @@
+import { PassThrough } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { runExecMock, spawnCommandMock } = vi.hoisted(() => ({
+  runExecMock: vi.fn(),
+  spawnCommandMock: vi.fn(),
+}));
+
+vi.mock("../../process/exec.js", () => ({
+  runExec: runExecMock,
+  spawnCommand: spawnCommandMock,
+}));
+
+import { execOpenPath, resolveOpenPathCommand } from "./open-path.js";
+
+function fakeChild(result: Promise<unknown>) {
+  const unref = vi.fn();
+  const kill = vi.fn();
+  const stderr = new PassThrough();
+  return {
+    child: Object.assign(result, { kill, stderr, unref }),
+    kill,
+    stderr,
+    unref,
+  };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.clearAllMocks();
+});
+
+describe("resolveOpenPathCommand", () => {
+  it("uses open on macOS", () => {
+    expect(resolveOpenPathCommand("/tmp/openclaw.json", "darwin")).toEqual({
+      command: "open",
+      args: ["/tmp/openclaw.json"],
+    });
+  });
+
+  it("uses xdg-open on Linux", () => {
+    expect(resolveOpenPathCommand("/tmp/openclaw.json", "linux")).toEqual({
+      command: "xdg-open",
+      args: ["/tmp/openclaw.json"],
+    });
+  });
+
+  it("uses a quoted PowerShell FilePath on Windows", () => {
+    expect(resolveOpenPathCommand(String.raw`C:\tmp\o'hai & calc.json`, "win32")).toEqual({
+      command: "powershell.exe",
+      args: [
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        String.raw`Start-Process -FilePath 'C:\tmp\o''hai & calc.json'`,
+      ],
+    });
+  });
+});
+
+describe("execOpenPath", () => {
+  it.each(["darwin", "win32"] as const)("bounds the %s launcher wait", async (platform) => {
+    runExecMock.mockResolvedValue({ stdout: "", stderr: "" });
+    const command = {
+      command: platform === "darwin" ? "open" : "powershell.exe",
+      args: ["/tmp/workspace"],
+    };
+
+    await execOpenPath(command, platform);
+
+    expect(runExecMock).toHaveBeenCalledWith(command.command, command.args, {
+      logOutput: false,
+      timeoutMs: 5_000,
+    });
+  });
+
+  it("detaches xdg-open and preserves an immediate successful exit", async () => {
+    const spawned = fakeChild(Promise.resolve({ failed: false }));
+    spawnCommandMock.mockReturnValue(spawned.child);
+
+    await execOpenPath({ command: "xdg-open", args: ["/tmp/workspace"] }, "linux");
+
+    expect(spawnCommandMock).toHaveBeenCalledWith(["xdg-open", "/tmp/workspace"], {
+      buffer: false,
+      cleanup: false,
+      detached: true,
+      reject: true,
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    expect(spawned.unref).toHaveBeenCalledOnce();
+  });
+
+  it("returns after startup observation without killing a foreground Linux handler", async () => {
+    vi.useFakeTimers();
+    let settleChild: (value: unknown) => void = () => {};
+    const childResult = new Promise<unknown>((resolve) => {
+      settleChild = resolve;
+    });
+    const spawned = fakeChild(childResult);
+    spawnCommandMock.mockReturnValue(spawned.child);
+    let settled = false;
+
+    const execution = execOpenPath({ command: "xdg-open", args: ["/tmp/workspace"] }, "linux").then(
+      () => {
+        settled = true;
+      },
+    );
+
+    await vi.advanceTimersByTimeAsync(4_999);
+    expect(settled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    await execution;
+
+    expect(settled).toBe(true);
+    expect(spawned.kill).not.toHaveBeenCalled();
+    expect(spawned.stderr.destroyed).toBe(false);
+    expect(spawned.stderr.write("foreground handler: delayed diagnostic")).toBe(true);
+    settleChild({ failed: false });
+    await Promise.resolve();
+    expect(spawned.stderr.destroyed).toBe(true);
+  });
+
+  it("propagates an immediate Linux launcher failure with bounded stderr", async () => {
+    let rejectChild: (error: Error) => void = () => {};
+    const spawned = fakeChild(
+      new Promise((_, reject) => {
+        rejectChild = reject;
+      }),
+    );
+    spawnCommandMock.mockReturnValue(spawned.child);
+
+    const execution = execOpenPath({ command: "xdg-open", args: ["/tmp/workspace"] }, "linux");
+    spawned.stderr.write("xdg-open: no method available for opening '/tmp/workspace'");
+    rejectChild(new Error("Command failed with exit code 3: xdg-open"));
+
+    await expect(execution).rejects.toThrow("xdg-open: no method available");
+  });
+});
diff --git a/src/gateway/server-methods/open-path.ts b/src/gateway/server-methods/open-path.ts
index a2d0926cc43..480240dc626 100644
--- a/src/gateway/server-methods/open-path.ts
+++ b/src/gateway/server-methods/open-path.ts
@@ -1,5 +1,9 @@
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
-import { runExec } from "../../process/exec.js";
+import { runExec, spawnCommand } from "../../process/exec.js";
+
+const OPEN_PATH_TIMEOUT_MS = 5_000;
+const XDG_OPEN_STARTUP_OBSERVATION_MS = 5_000;
+const XDG_OPEN_STDERR_MAX_CHARS = 4_096;
 
 type OpenPathCommand = {
   command: string;
@@ -32,8 +36,84 @@ export function resolveOpenPathCommand(
   };
 }
 
-export async function execOpenPath(command: OpenPathCommand): Promise<void> {
-  await runExec(command.command, command.args, { logOutput: false });
+async function observeXdgOpenStartup(command: OpenPathCommand): Promise<void> {
+  // xdg-open can synchronously own a foreground application. Observe startup
+  // failures without making the Gateway own the launched application's lifetime.
+  const child = spawnCommand([command.command, ...command.args], {
+    buffer: false,
+    cleanup: false,
+    detached: true,
+    reject: true,
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  child.unref();
+  let stderrText = "";
+  const stderr = child.stderr;
+  stderr?.setEncoding("utf8");
+  const onStderr = (chunk: string | Buffer) => {
+    if (stderrText.length >= XDG_OPEN_STDERR_MAX_CHARS) {
+      return;
+    }
+    stderrText += String(chunk).slice(0, XDG_OPEN_STDERR_MAX_CHARS - stderrText.length);
+  };
+  stderr?.on("data", onStderr);
+
+  await new Promise<void>((resolve, reject) => {
+    let observationComplete = false;
+    const releaseStderr = (childSettled: boolean) => {
+      stderr?.off("data", onStderr);
+      if (childSettled) {
+        stderr?.destroy();
+        return;
+      }
+      // Keep draining after the observation window. Closing the pipe can send
+      // SIGPIPE to a foreground application that writes diagnostics later.
+      stderr?.resume();
+      (stderr as (typeof stderr & { unref?: () => void }) | null)?.unref?.();
+    };
+    const timer = setTimeout(() => {
+      observationComplete = true;
+      releaseStderr(false);
+      resolve();
+    }, XDG_OPEN_STARTUP_OBSERVATION_MS);
+    void child.then(
+      () => {
+        clearTimeout(timer);
+        releaseStderr(true);
+        if (!observationComplete) {
+          resolve();
+        }
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        releaseStderr(true);
+        if (observationComplete) {
+          return;
+        }
+        const commandError = error instanceof Error ? error : new Error(String(error));
+        const diagnostic = stderrText.trim();
+        reject(
+          diagnostic
+            ? new Error(`${commandError.message}: ${diagnostic}`, { cause: commandError })
+            : commandError,
+        );
+      },
+    );
+  });
+}
+
+export async function execOpenPath(
+  command: OpenPathCommand,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  if (platform === "linux") {
+    await observeXdgOpenStartup(command);
+    return;
+  }
+  await runExec(command.command, command.args, {
+    logOutput: false,
+    timeoutMs: OPEN_PATH_TIMEOUT_MS,
+  });
 }
 
 export function formatOpenPathError(error: unknown): string {

From f14947d256d8238ed2fce3ca3ec81e4dae3fe8c2 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 10:37:25 +0100
Subject: [PATCH 04/76] fix(codex): persist automatic compaction history
 (#110587)

* fix(codex): persist automatic compaction counts

* test(codex): stress compaction and restart recovery

* test(codex): bind compaction waves to fresh counts

* chore: keep Codex release note in PR
---
 docs/help/testing-live.md                     |  22 +
 .../src/app-server/event-projector.test.ts    |   5 +-
 .../codex/src/app-server/event-projector.ts   |   6 +-
 .../codex/src/app-server/run-attempt-start.ts |   7 +-
 scripts/test-live-codex-harness-docker.sh     |  12 +
 ...gateway-codex-harness.live-helpers.test.ts |  25 +
 .../gateway-codex-harness.live-helpers.ts     |  24 +
 .../gateway-codex-harness.live.test.ts        | 477 +++++++++++++++---
 .../test-live-codex-harness-docker.test.ts    |  18 +
 9 files changed, 510 insertions(+), 86 deletions(-)

diff --git a/docs/help/testing-live.md b/docs/help/testing-live.md
index c4ab7b43791..af947358fdb 100644
--- a/docs/help/testing-live.md
+++ b/docs/help/testing-live.md
@@ -334,6 +334,17 @@ Docker notes:
   history. Override the bounded counts with
   `OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_HISTORY_TURNS` (1-20) and
   `OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS` (1-10).
+- Optional fan-out stress: set `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1`
+  and `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT` (1-12). The harness starts
+  every child concurrently, waits for every terminal run, and verifies each
+  unique child reply and native thread identity.
+- Optional compaction stress: `OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS=1`
+  generates bounded native tool output, requires automatic compaction events,
+  verifies the persisted compaction count and hidden-marker recall, restarts
+  the Gateway and physical Codex app-server, then repeats the output and
+  compaction wave. Tune the bounded work with
+  `OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS` (1-8) and
+  `OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES` (100000-1000000).
 - Optional loop-relay opt-out probe:
   `OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY=1`
 - The requested thinking preference may map to the nearest effort advertised
@@ -367,6 +378,17 @@ Restart and history stress:
 
 ```bash
 OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS=1 \
+pnpm test:docker:live-codex-harness
+```
+
+Fan-out, large-output, compaction, and restart stress:
+
+```bash
+OPENCLAW_LIVE_CODEX_HARNESS_AUTH=api-key \
+  OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT=8 \
+  OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS=1 \
+  OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS=1 \
   pnpm test:docker:live-codex-harness
 ```
 
diff --git a/extensions/codex/src/app-server/event-projector.test.ts b/extensions/codex/src/app-server/event-projector.test.ts
index 3e8ae5f6166..03856fcbcc2 100644
--- a/extensions/codex/src/app-server/event-projector.test.ts
+++ b/extensions/codex/src/app-server/event-projector.test.ts
@@ -2998,7 +2998,10 @@ describe("CodexAppServerEventProjector", () => {
     expect(JSON.stringify(result.messagesSnapshot[2])).toContain("Codex plan");
     expect(JSON.stringify(result.messagesSnapshot[2])).toContain("next");
     expect(JSON.stringify(result.messagesSnapshot[2])).toContain("[in_progress] patch");
-    expect(requireRecord(result.itemLifecycle, "item lifecycle").compactionCount).toBe(1);
+    expect(result.compactionCount).toBe(1);
+    expect(requireRecord(result.itemLifecycle, "item lifecycle")).not.toHaveProperty(
+      "compactionCount",
+    );
     expect(onContextCompacted).toHaveBeenCalledOnce();
   });
 
diff --git a/extensions/codex/src/app-server/event-projector.ts b/extensions/codex/src/app-server/event-projector.ts
index d894f3d89d7..8feada7e4b4 100644
--- a/extensions/codex/src/app-server/event-projector.ts
+++ b/extensions/codex/src/app-server/event-projector.ts
@@ -434,6 +434,9 @@ export class CodexAppServerEventProjector {
       successfulCronAdds: toolTelemetry.successfulCronAdds,
       cloudCodeAssistFormatError: false,
       attemptUsage: projectedUsage,
+      ...(this.completedCompactionCount > 0
+        ? { compactionCount: this.completedCompactionCount }
+        : {}),
       replayMetadata: {
         hadPotentialSideEffects,
         replaySafe: !hadPotentialSideEffects,
@@ -442,9 +445,6 @@ export class CodexAppServerEventProjector {
         startedCount: this.activeItemIds.size + this.completedItemIds.size,
         completedCount: this.completedItemIds.size,
         activeCount: this.activeItemIds.size,
-        ...(this.completedCompactionCount > 0
-          ? { compactionCount: this.completedCompactionCount }
-          : {}),
       },
       yieldDetected: options?.yieldDetected || false,
       didSendDeterministicApprovalPrompt:
diff --git a/extensions/codex/src/app-server/run-attempt-start.ts b/extensions/codex/src/app-server/run-attempt-start.ts
index 872c310ab3b..be79f0d33b4 100644
--- a/extensions/codex/src/app-server/run-attempt-start.ts
+++ b/extensions/codex/src/app-server/run-attempt-start.ts
@@ -159,7 +159,12 @@ export async function startCodexAttemptRuntime(resources: CodexAttemptResources)
     state.codexSandboxPolicy = startupResult.sandboxPolicy;
     void emitCodexAppServerEvent(params, {
       stream: "codex_app_server.lifecycle",
-      data: { phase: "thread_ready", threadId: state.thread.threadId },
+      data: {
+        phase: "thread_ready",
+        threadId: state.thread.threadId,
+        action: state.thread.lifecycle.action,
+        clientId: state.client.getInstanceId(),
+      },
     });
   } catch (error) {
     activateNativePreToolUseFailureFallback();
diff --git a/scripts/test-live-codex-harness-docker.sh b/scripts/test-live-codex-harness-docker.sh
index 0f06a4ea7ca..b8f5cfe4a8c 100644
--- a/scripts/test-live-codex-harness-docker.sh
+++ b/scripts/test-live-codex-harness-docker.sh
@@ -367,11 +367,17 @@ echo "==> Chat image probe: ${OPENCLAW_LIVE_CODEX_HARNESS_CHAT_IMAGE_PROBE:-0}"
 echo "==> Image probe: ${OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE:-1}"
 echo "==> MCP probe: ${OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE:-1}"
 echo "==> Subagent probe: ${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE:-1}"
+echo "==> Subagent count: ${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT:-1}"
 echo "==> Subagent-only fast path: ${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY:-auto}"
 echo "==> Guardian probe: ${OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE:-1}"
+echo "==> Code-mode-only probe: ${OPENCLAW_LIVE_CODEX_HARNESS_CODE_MODE_ONLY:-0}"
+echo "==> Loop relay disabled: ${OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY:-0}"
 echo "==> Resume stress: ${OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS:-0}"
 echo "==> Resume stress history turns: ${OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_HISTORY_TURNS:-4}"
 echo "==> Resume stress restarts: ${OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS:-3}"
+echo "==> Compaction stress: ${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS:-0}"
+echo "==> Compaction stress turns: ${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS:-4}"
+echo "==> Large output bytes: ${OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES:-300000}"
 echo "==> Auth mode: $CODEX_HARNESS_AUTH_MODE"
 echo "==> Profile file: $PROFILE_STATUS"
 echo "==> CI-safe Codex config: ${OPENCLAW_LIVE_CODEX_HARNESS_USE_CI_SAFE_CODEX_CONFIG:-1}"
@@ -401,9 +407,14 @@ DOCKER_RUN_ARGS+=(--rm -t \
   -e OPENCLAW_LIVE_CODEX_HARNESS_AUTH="$CODEX_HARNESS_AUTH_MODE" \
   -e OPENCLAW_LIVE_CODEX_HARNESS=1 \
   -e OPENCLAW_LIVE_CODEX_HARNESS_CHAT_IMAGE_PROBE="${OPENCLAW_LIVE_CODEX_HARNESS_CHAT_IMAGE_PROBE:-0}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_CODE_MODE_ONLY="${OPENCLAW_LIVE_CODEX_HARNESS_CODE_MODE_ONLY:-0}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS="${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS:-0}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS="${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS:-4}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_DEBUG="${OPENCLAW_LIVE_CODEX_HARNESS_DEBUG:-}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY="${OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY:-0}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE="${OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE:-1}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE="${OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE:-1}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES="${OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES:-300000}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE="${OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE:-1}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_MODEL="${OPENCLAW_LIVE_CODEX_HARNESS_MODEL:-openai/gpt-5.6-luna}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_TARGETS="${OPENCLAW_LIVE_CODEX_HARNESS_TARGETS:-}" \
@@ -416,6 +427,7 @@ DOCKER_RUN_ARGS+=(--rm -t \
   -e OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS="${OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS:-3}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_SETUP_TIMEOUT_SECONDS="$CODEX_HARNESS_SETUP_TIMEOUT_SECONDS" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY="${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY:-}" \
+  -e OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT="${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT:-1}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE="${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE:-1}" \
   -e OPENCLAW_LIVE_CODEX_HARNESS_USE_CI_SAFE_CODEX_CONFIG="${OPENCLAW_LIVE_CODEX_HARNESS_USE_CI_SAFE_CODEX_CONFIG:-1}" \
   -e OPENCLAW_LIVE_CODEX_CLI_PACKAGE_SPEC="$CODEX_CLI_PACKAGE_SPEC" \
diff --git a/src/gateway/gateway-codex-harness.live-helpers.test.ts b/src/gateway/gateway-codex-harness.live-helpers.test.ts
index b2aa0136758..f173074350e 100644
--- a/src/gateway/gateway-codex-harness.live-helpers.test.ts
+++ b/src/gateway/gateway-codex-harness.live-helpers.test.ts
@@ -10,6 +10,7 @@ import {
   isExpectedYieldedAgentTimeout,
   isRetryableCodexHarnessLiveError,
   isStrictExpectedCodexModelsCommandText,
+  shouldUseCodexHarnessSubagentOnlyFastPath,
 } from "./gateway-codex-harness.live-helpers.js";
 
 const includesExpectedCodexModelsCommandText = (text: string) =>
@@ -30,6 +31,30 @@ function expectStrictCodexModelsCommandText(text: string): void {
 }
 
 describe("gateway codex harness live helpers", () => {
+  it("keeps combined stress probes out of the subagent-only fast path", () => {
+    const base = {
+      chatImageProbe: false,
+      codeModeOnly: false,
+      compactionStress: false,
+      explicitOptOut: false,
+      guardianProbe: false,
+      imageProbe: false,
+      mcpProbe: false,
+      resumeStress: false,
+      subagentProbe: true,
+    };
+
+    expect(shouldUseCodexHarnessSubagentOnlyFastPath(base)).toBe(true);
+    expect(shouldUseCodexHarnessSubagentOnlyFastPath({ ...base, resumeStress: true })).toBe(false);
+    expect(shouldUseCodexHarnessSubagentOnlyFastPath({ ...base, compactionStress: true })).toBe(
+      false,
+    );
+    expect(shouldUseCodexHarnessSubagentOnlyFastPath({ ...base, codeModeOnly: true })).toBe(false);
+    expect(shouldUseCodexHarnessSubagentOnlyFastPath({ ...base, explicitOptOut: true })).toBe(
+      false,
+    );
+  });
+
   it("classifies sessions.list timeouts as retryable live Codex errors", () => {
     const error = new Error("gateway request timeout for sessions.list");
 
diff --git a/src/gateway/gateway-codex-harness.live-helpers.ts b/src/gateway/gateway-codex-harness.live-helpers.ts
index 9b8c83b4014..2fec444a104 100644
--- a/src/gateway/gateway-codex-harness.live-helpers.ts
+++ b/src/gateway/gateway-codex-harness.live-helpers.ts
@@ -81,6 +81,30 @@ export const EXPECTED_CODEX_MODELS_COMMAND_TEXT = [
   "Current OpenClaw session status reports the active model as:",
 ] as const;
 
+export function shouldUseCodexHarnessSubagentOnlyFastPath(params: {
+  chatImageProbe: boolean;
+  codeModeOnly: boolean;
+  compactionStress: boolean;
+  explicitOptOut: boolean;
+  guardianProbe: boolean;
+  imageProbe: boolean;
+  mcpProbe: boolean;
+  resumeStress: boolean;
+  subagentProbe: boolean;
+}): boolean {
+  return (
+    params.subagentProbe &&
+    !params.chatImageProbe &&
+    !params.codeModeOnly &&
+    !params.compactionStress &&
+    !params.guardianProbe &&
+    !params.imageProbe &&
+    !params.mcpProbe &&
+    !params.resumeStress &&
+    !params.explicitOptOut
+  );
+}
+
 const HEALTHY_CODEX_MODELS_COMMAND_TEXT = [
   "Codex models:",
   "Available Codex models",
diff --git a/src/gateway/gateway-codex-harness.live.test.ts b/src/gateway/gateway-codex-harness.live.test.ts
index a781904dbe1..cf948c623cc 100644
--- a/src/gateway/gateway-codex-harness.live.test.ts
+++ b/src/gateway/gateway-codex-harness.live.test.ts
@@ -30,6 +30,7 @@ import {
   isExpectedYieldedAgentTimeout,
   isRetryableCodexHarnessLiveError,
   isStrictExpectedCodexModelsCommandText,
+  shouldUseCodexHarnessSubagentOnlyFastPath,
 } from "./gateway-codex-harness.live-helpers.js";
 import {
   assertCronJobMatches,
@@ -63,13 +64,6 @@ const CODEX_HARNESS_CODE_MODE_ONLY = isTruthyEnvValue(
 const CODEX_HARNESS_DISABLE_LOOP_RELAY = isTruthyEnvValue(
   process.env.OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY,
 );
-const CODEX_HARNESS_SUBAGENT_ONLY =
-  CODEX_HARNESS_SUBAGENT_PROBE &&
-  !CODEX_HARNESS_CHAT_IMAGE_PROBE &&
-  !CODEX_HARNESS_IMAGE_PROBE &&
-  !CODEX_HARNESS_MCP_PROBE &&
-  !CODEX_HARNESS_GUARDIAN_PROBE &&
-  process.env.OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY !== "0";
 const CODEX_HARNESS_REQUIRE_GUARDIAN_EVENTS = isTruthyEnvValue(
   process.env.OPENCLAW_LIVE_CODEX_HARNESS_REQUIRE_GUARDIAN_EVENTS,
 );
@@ -88,6 +82,40 @@ const CODEX_HARNESS_RESUME_STRESS_RESTARTS = resolveBoundedPositiveIntEnv(
   3,
   10,
 );
+const CODEX_HARNESS_COMPACTION_STRESS = isTruthyEnvValue(
+  process.env.OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS,
+);
+const CODEX_HARNESS_COMPACTION_STRESS_TURNS = resolveBoundedPositiveIntEnv(
+  "OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS",
+  process.env.OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS,
+  4,
+  8,
+);
+const CODEX_HARNESS_LARGE_OUTPUT_BYTES = resolveBoundedPositiveIntEnv(
+  "OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES",
+  process.env.OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES,
+  300_000,
+  1_000_000,
+  100_000,
+);
+const CODEX_HARNESS_SUBAGENT_COUNT = resolveBoundedPositiveIntEnv(
+  "OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT",
+  process.env.OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT,
+  1,
+  12,
+);
+const CODEX_HARNESS_SUBAGENT_ONLY = shouldUseCodexHarnessSubagentOnlyFastPath({
+  chatImageProbe: CODEX_HARNESS_CHAT_IMAGE_PROBE,
+  codeModeOnly: CODEX_HARNESS_CODE_MODE_ONLY,
+  compactionStress: CODEX_HARNESS_COMPACTION_STRESS,
+  explicitOptOut: process.env.OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY === "0",
+  guardianProbe: CODEX_HARNESS_GUARDIAN_PROBE,
+  imageProbe: CODEX_HARNESS_IMAGE_PROBE,
+  mcpProbe: CODEX_HARNESS_MCP_PROBE,
+  resumeStress: CODEX_HARNESS_RESUME_STRESS,
+  subagentProbe: CODEX_HARNESS_SUBAGENT_PROBE,
+});
+const CODEX_HARNESS_RESTART_STRESS = CODEX_HARNESS_RESUME_STRESS || CODEX_HARNESS_COMPACTION_STRESS;
 const CODEX_HARNESS_REQUEST_TIMEOUT_MS = resolveLiveTimeoutMs(
   process.env.OPENCLAW_LIVE_CODEX_HARNESS_REQUEST_TIMEOUT_MS,
   300_000,
@@ -103,7 +131,7 @@ const CODEX_HARNESS_THINKING = resolveCodexHarnessThinkingLevel(
 );
 const describeLive = LIVE && CODEX_HARNESS_LIVE ? describe : describe.skip;
 const describeDisabled = LIVE && !CODEX_HARNESS_LIVE ? describe : describe.skip;
-const CODEX_HARNESS_TIMEOUT_MS = CODEX_HARNESS_RESUME_STRESS ? 1_800_000 : 900_000;
+const CODEX_HARNESS_TIMEOUT_MS = CODEX_HARNESS_RESTART_STRESS ? 3_600_000 : 900_000;
 const DEFAULT_CODEX_MODEL = "openai/gpt-5.6-luna";
 const GATEWAY_CONNECT_TIMEOUT_MS = 60_000;
 const CODEX_HARNESS_REASONING_EFFORTS = [
@@ -132,6 +160,8 @@ type CapturedAgentEvent = {
 };
 
 const observedCodexThreadIds = new Map<string, string>();
+const observedCodexClientIds = new Map<string, string>();
+const observedCodexThreadActions = new Map<string, string>();
 
 type GuardianPluginApprovalDecision = "allow-once" | "deny";
 type CodexHarnessThinkingLevel =
@@ -154,6 +184,7 @@ function resolveBoundedPositiveIntEnv(
   raw: string | undefined,
   fallback: number,
   max: number,
+  min = 1,
 ): number {
   if (raw === undefined || raw.trim() === "") {
     return fallback;
@@ -162,8 +193,8 @@ function resolveBoundedPositiveIntEnv(
     throw new Error(`invalid ${name}: ${raw}`);
   }
   const parsed = Number(raw);
-  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > max) {
-    throw new Error(`${name} must be between 1 and ${max}`);
+  if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+    throw new Error(`${name} must be between ${min} and ${max}`);
   }
   return parsed;
 }
@@ -392,6 +423,7 @@ async function assertCodexHarnessTranscriptModelIdentity(params: {
 async function writeLiveGatewayConfig(params: {
   codexAppServerMode?: "guardian" | "yolo";
   codeModeOnly?: boolean;
+  compactionStress?: boolean;
   loopDetectionPreToolUseRelay?: boolean;
   configPath: string;
   modelKey: string;
@@ -414,6 +446,23 @@ async function writeLiveGatewayConfig(params: {
           config: {
             appServer: {
               mode: params.codexAppServerMode ?? "yolo",
+              ...(params.compactionStress
+                ? {
+                    args: [
+                      "-c",
+                      "model_auto_compact_token_limit_scope=body_after_prefix",
+                      "-c",
+                      // One truncated 300 KB tool result is only a few thousand
+                      // tokens after Codex applies its transcript output cap.
+                      "model_auto_compact_token_limit=4000",
+                      "-c",
+                      "tool_output_token_limit=10000",
+                      "app-server",
+                      "--listen",
+                      "stdio://",
+                    ],
+                  }
+                : {}),
               ...(params.codeModeOnly === true ? { codeModeOnly: true } : {}),
               ...(params.loopDetectionPreToolUseRelay === false
                 ? { loopDetectionPreToolUseRelay: false }
@@ -430,6 +479,11 @@ async function writeLiveGatewayConfig(params: {
         workspace: params.workspace,
         skipBootstrap: true,
         timeoutSeconds: CODEX_HARNESS_AGENT_TIMEOUT_SECONDS,
+        maxConcurrent: Math.max(4, CODEX_HARNESS_SUBAGENT_COUNT + 1),
+        subagents: {
+          maxConcurrent: CODEX_HARNESS_SUBAGENT_COUNT,
+          maxChildrenPerAgent: CODEX_HARNESS_SUBAGENT_COUNT,
+        },
         thinkingDefault: CODEX_HARNESS_THINKING,
         model: { primary: params.modelKey },
         models: { [params.modelKey]: { agentRuntime: { id: "codex" } } },
@@ -454,17 +508,18 @@ async function requestAgentTextWithEvents(params: {
   acceptYieldedTimeout?: boolean;
   client: GatewayClient;
   eventPrefix?: string;
+  eventPrefixes?: readonly string[];
   includeAllSessions?: boolean;
   message: string;
   sessionKey: string;
-}): Promise<{ text: string; events: CapturedAgentEvent[] }> {
+}): Promise<{ text: string; events: CapturedAgentEvent[]; compactionCount: number }> {
   const { extractPayloadText } = await import("./test-helpers.agent-results.js");
   const { onAgentEvent } = await import("../infra/agent-events.js");
   const events: CapturedAgentEvent[] = [];
-  const eventPrefix = params.eventPrefix ?? "codex_app_server.guardian";
+  const eventPrefixes = params.eventPrefixes ?? [params.eventPrefix ?? "codex_app_server.guardian"];
   const unsubscribe = onAgentEvent((event) => {
     if (
-      !event.stream.startsWith(eventPrefix) ||
+      !eventPrefixes.some((prefix) => event.stream.startsWith(prefix)) ||
       (!params.includeAllSessions && event.sessionKey && event.sessionKey !== params.sessionKey)
     ) {
       return;
@@ -493,7 +548,14 @@ async function requestAgentTextWithEvents(params: {
     if (payload?.status !== "ok" && !acceptedYieldedTimeout) {
       throw new Error(`agent status=${String(payload?.status)} payload=${JSON.stringify(payload)}`);
     }
-    return { text: extractPayloadText(payload.result), events };
+    const result = payload.result as
+      | { meta?: { agentMeta?: { compactionCount?: number } } }
+      | undefined;
+    return {
+      text: extractPayloadText(payload.result),
+      events,
+      compactionCount: Math.max(0, result?.meta?.agentMeta?.compactionCount ?? 0),
+    };
   } finally {
     unsubscribe();
   }
@@ -501,7 +563,7 @@ async function requestAgentTextWithEvents(params: {
 
 async function requestAgentText(params: {
   client: GatewayClient;
-  expectedToken: string;
+  expectedReply: string;
   message: string;
   sessionKey: string;
 }): Promise<string> {
@@ -511,7 +573,16 @@ async function requestAgentText(params: {
     message: params.message,
     sessionKey: params.sessionKey,
   });
-  expect(text).toContain(params.expectedToken);
+  expect(text).toContain(params.expectedReply);
+  recordCodexAttemptIdentity({ events, sessionKey: params.sessionKey });
+  return text;
+}
+
+function recordCodexAttemptIdentity(params: {
+  events: CapturedAgentEvent[];
+  sessionKey: string;
+}): void {
+  const { events } = params;
   const turnStarting = events.find(
     (event) =>
       event.stream === "codex_app_server.lifecycle" && event.data?.phase === "turn_starting",
@@ -539,7 +610,15 @@ async function requestAgentText(params: {
     `expected Codex thread_ready identity for ${params.sessionKey}; events=${JSON.stringify(events)}`,
   ).toBe(true);
   observedCodexThreadIds.set(params.sessionKey, threadId as string);
-  return text;
+  const clientId = threadReady?.data?.clientId;
+  expect(
+    typeof clientId === "string" && clientId.trim().length > 0,
+    `expected Codex client identity for ${params.sessionKey}; events=${JSON.stringify(events)}`,
+  ).toBe(true);
+  observedCodexClientIds.set(params.sessionKey, clientId as string);
+  const action = threadReady?.data?.action;
+  expect(["started", "resumed", "forked"]).toContain(action);
+  observedCodexThreadActions.set(params.sessionKey, action as string);
 }
 
 async function verifyCodexCodeModeOnlyDynamicToolProbe(params: {
@@ -726,6 +805,127 @@ function formatAssistantTextPreview(texts: string[], maxChars = 800): string {
   return combined.length > maxChars ? `${combined.slice(0, maxChars)}...` : combined;
 }
 
+async function readCodexHarnessCompactionCount(params: {
+  client: GatewayClient;
+  events: EventFrame[];
+  minimum: number;
+  sessionKey: string;
+}): Promise<number> {
+  const statusText = await requestCodexCommandText({
+    client: params.client,
+    command: "/status",
+    events: params.events,
+    expectedText: "Compactions:",
+    sessionKey: params.sessionKey,
+  });
+  const count = Number(/Compactions:\s*(\d+)/u.exec(statusText)?.[1]);
+  expect(
+    count,
+    `session ${params.sessionKey} did not report ${params.minimum} persisted compactions`,
+  ).toBeGreaterThanOrEqual(params.minimum);
+  return count;
+}
+
+async function verifyCodexCompactionStress(params: {
+  client: GatewayClient;
+  events: EventFrame[];
+  sessionKey: string;
+}): Promise<{ hiddenMarker: string; persistedCount: number }> {
+  const hiddenMarker = `CODEX-DURABLE-${randomBytes(6).toString("hex").toUpperCase()}`;
+  await requestAgentText({
+    client: params.client,
+    sessionKey: params.sessionKey,
+    expectedReply: hiddenMarker,
+    message: [
+      `Remember this as durable slot A: ${hiddenMarker}`,
+      `Reply exactly ${hiddenMarker} and nothing else.`,
+    ].join("\n"),
+  });
+  const baselineCount = await readCodexHarnessCompactionCount({
+    client: params.client,
+    events: params.events,
+    minimum: 0,
+    sessionKey: params.sessionKey,
+  });
+
+  const outputLines = Math.ceil(CODEX_HARNESS_LARGE_OUTPUT_BYTES / 90);
+  let completedCompactions = 0;
+  let reportedCompactions = 0;
+  for (let turn = 1; turn <= CODEX_HARNESS_COMPACTION_STRESS_TURNS; turn += 1) {
+    const acknowledgement = `CODEX-LARGE-OUTPUT-${turn}-${randomBytes(3)
+      .toString("hex")
+      .toUpperCase()}`;
+    const { text, events, compactionCount } = await requestAgentTextWithEvents({
+      client: params.client,
+      eventPrefixes: ["codex_app_server.", "compaction"],
+      sessionKey: params.sessionKey,
+      message: [
+        "Large-output compaction probe.",
+        "Use the native exec_command tool exactly once.",
+        `Run this exact command: node -e 'for(let i=0;i<${outputLines};i++){console.log(i.toString(36).padStart(8,"0")+"-"+((i*2654435761)>>>0).toString(16).padStart(8,"0")+"-ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")}'`,
+        "Set max_output_tokens to 10000.",
+        `After the tool completes, reply exactly ${acknowledgement} and nothing else.`,
+      ].join("\n"),
+    });
+    expect(text).toContain(acknowledgement);
+    recordCodexAttemptIdentity({ events, sessionKey: params.sessionKey });
+    completedCompactions += events.filter(
+      (event) =>
+        event.stream === "compaction" &&
+        event.data?.phase === "end" &&
+        event.data?.completed === true,
+    ).length;
+    reportedCompactions += compactionCount;
+
+    const history: { messages?: unknown[] } = await params.client.request("chat.history", {
+      sessionKey: params.sessionKey,
+      limit: 100,
+    });
+    const serialized = JSON.stringify(history.messages ?? []);
+    const originalLengths = Array.from(serialized.matchAll(/original (\d+) chars/gu), (match) =>
+      Number(match[1]),
+    );
+    expect(
+      originalLengths.some((length) => length > 10_000),
+      `expected a truncated large native tool result; lengths=${JSON.stringify(originalLengths)}`,
+    ).toBe(true);
+  }
+
+  expect(completedCompactions, "expected at least one native automatic compaction").toBeGreaterThan(
+    0,
+  );
+  expect(reportedCompactions, "agent result dropped native automatic compactions").toBe(
+    completedCompactions,
+  );
+  // `/status` stops in the local command handler (`shouldContinue: false`), so
+  // these snapshots cannot introduce an unobserved native Codex compaction.
+  const persistedCount = await readCodexHarnessCompactionCount({
+    client: params.client,
+    events: params.events,
+    minimum: baselineCount + completedCompactions,
+    sessionKey: params.sessionKey,
+  });
+  expect(
+    persistedCount - baselineCount,
+    "persisted session count did not match this wave's native compactions",
+  ).toBe(completedCompactions);
+  const recalled = await requestAgentText({
+    client: params.client,
+    sessionKey: params.sessionKey,
+    expectedReply: hiddenMarker,
+    message: "Reply with exactly the value stored in durable slot A and nothing else.",
+  });
+  expect(recalled.trim()).toBe(hiddenMarker);
+  logCodexLiveStep("compaction-stress:complete", {
+    baselineCount,
+    completedCompactions,
+    outputBytes: CODEX_HARNESS_LARGE_OUTPUT_BYTES,
+    outputTurns: CODEX_HARNESS_COMPACTION_STRESS_TURNS,
+    persistedCount,
+  });
+  return { hiddenMarker, persistedCount };
+}
+
 async function waitForAssistantText(params: {
   client: GatewayClient;
   sessionKey: string;
@@ -930,7 +1130,6 @@ async function verifyCodexGuardianProbe(params: {
   const allowReview = assertGuardianReviewCompleted({
     events: allowResult.events,
     label: "allow probe",
-    requireEvents: false,
   });
   const allowStatus = findGuardianReviewStatus(allowResult.events);
   if (allowStatus === "denied") {
@@ -977,7 +1176,6 @@ async function verifyCodexGuardianProbe(params: {
   const review = assertGuardianReviewCompleted({
     events: deniedResult.events,
     label: "ask-back probe",
-    requireEvents: false,
   });
   // The approve/deny call is Codex policy-owned and may change independently.
   // OpenClaw's strict projection contract is covered by the allow probe above.
@@ -1067,24 +1265,21 @@ async function verifyCodexCronMcpProbe(params: {
   }
 }
 
-function hasCodexAppServerLifecycleEvent(params: {
-  childSessionKey: string;
-  events: CapturedAgentEvent[];
-}): boolean {
-  return params.events.some(
-    (event) =>
-      event.sessionKey === params.childSessionKey && event.stream === "codex_app_server.lifecycle",
-  );
-}
-
 async function waitForCodexSubagentStarted(params: {
   childSessionKey: string;
   events: CapturedAgentEvent[];
-}): Promise<void> {
+}): Promise<string> {
   const deadline = Date.now() + CODEX_HARNESS_REQUEST_TIMEOUT_MS;
   while (Date.now() < deadline) {
-    if (hasCodexAppServerLifecycleEvent(params)) {
-      return;
+    const threadReady = params.events.find(
+      (event) =>
+        event.sessionKey === params.childSessionKey &&
+        event.stream === "codex_app_server.lifecycle" &&
+        event.data?.phase === "thread_ready" &&
+        typeof event.data.threadId === "string",
+    );
+    if (threadReady && typeof threadReady.data?.threadId === "string") {
+      return threadReady.data.threadId;
     }
     await delay(2_000);
   }
@@ -1158,36 +1353,84 @@ async function verifyCodexSubagentProbe(params: {
         }
       },
     });
-    const spawnResult = await spawnSubagentDirect(
-      {
-        task: `Reply exactly ${expectedToken} and nothing else.`,
-        agentId: "dev",
-        thinking: CODEX_HARNESS_THINKING,
-        mode: "run",
-        cleanup: "keep",
-        context: "isolated",
-        lightContext: true,
-        expectsCompletionMessage: false,
-        runTimeoutSeconds: CODEX_HARNESS_AGENT_TIMEOUT_SECONDS,
-      },
-      {
-        agentSessionKey: params.sessionKey,
-      },
+    const probeReplies = [
+      expectedToken,
+      ...Array.from(
+        { length: CODEX_HARNESS_SUBAGENT_COUNT - 1 },
+        (_, index) => `CODEX-SUBAGENT-${index + 2}-${randomUUID().slice(0, 6).toUpperCase()}`,
+      ),
+    ];
+    const probes = probeReplies.map((expectedReply, index) => ({ expectedReply, index }));
+    const spawnResults = await Promise.all(
+      probes.map(async (probe) => ({
+        expectedReply: probe.expectedReply,
+        index: probe.index,
+        result: await spawnSubagentDirect(
+          {
+            task: `Reply exactly ${probe.expectedReply} and nothing else.`,
+            agentId: "dev",
+            thinking: CODEX_HARNESS_THINKING,
+            mode: "run",
+            cleanup: "keep",
+            context: "isolated",
+            lightContext: true,
+            expectsCompletionMessage: false,
+            runTimeoutSeconds: CODEX_HARNESS_AGENT_TIMEOUT_SECONDS,
+          },
+          {
+            agentSessionKey: params.sessionKey,
+          },
+        ),
+      })),
     );
-    if (spawnResult.status !== "accepted") {
-      throw new Error(
-        `Codex subagent spawn failed: ${JSON.stringify(spawnResult)} trace=${JSON.stringify(gatewayTrace)}`,
-      );
-    }
-    const childSessionKey = spawnResult.childSessionKey;
-    if (!childSessionKey?.includes(":subagent:")) {
-      throw new Error(
-        `subagent spawn did not return a child session key: ${JSON.stringify(spawnResult)}`,
-      );
+    for (const probe of spawnResults) {
+      if (probe.result.status !== "accepted") {
+        throw new Error(
+          `Codex subagent ${probe.index + 1} spawn failed: ${JSON.stringify(probe.result)} trace=${JSON.stringify(gatewayTrace)}`,
+        );
+      }
+      if (!probe.result.childSessionKey?.includes(":subagent:") || !probe.result.runId) {
+        throw new Error(
+          `subagent spawn did not return child/run identities: ${JSON.stringify(probe.result)}`,
+        );
+      }
     }
-    await waitForCodexSubagentStarted({
-      childSessionKey,
-      events,
+    expect(new Set(spawnResults.map((probe) => probe.result.childSessionKey)).size).toBe(
+      spawnResults.length,
+    );
+    expect(new Set(spawnResults.map((probe) => probe.result.runId)).size).toBe(spawnResults.length);
+
+    const threadIds = await Promise.all(
+      spawnResults.map((probe) =>
+        waitForCodexSubagentStarted({
+          childSessionKey: probe.result.childSessionKey as string,
+          events,
+        }),
+      ),
+    );
+    expect(new Set(threadIds).size).toBe(threadIds.length);
+
+    await Promise.all(
+      spawnResults.map((probe) =>
+        waitForChatAgentRunOk(params.client, probe.result.runId as string),
+      ),
+    );
+    await Promise.all(
+      spawnResults.map(async (probe) => {
+        const history: { messages?: unknown[] } = await params.client.request("chat.history", {
+          sessionKey: probe.result.childSessionKey,
+          limit: 20,
+        });
+        const replies = extractAssistantTexts(history.messages ?? []);
+        expect(
+          replies.some((text) => text.trim() === probe.expectedReply),
+          `subagent ${probe.index + 1} missing exact reply ${probe.expectedReply}; replies=${formatAssistantTextPreview(replies)}`,
+        ).toBe(true);
+      }),
+    );
+    logCodexLiveStep("subagent-fanout:complete", {
+      count: spawnResults.length,
+      uniqueThreads: new Set(threadIds).size,
     });
   } finally {
     const { testing: subagentSpawnTesting } =
@@ -1306,6 +1549,7 @@ describeLive("gateway live (Codex harness)", () => {
         workspace,
         codexAppServerMode: CODEX_HARNESS_GUARDIAN_PROBE ? "guardian" : "yolo",
         codeModeOnly: CODEX_HARNESS_CODE_MODE_ONLY,
+        compactionStress: CODEX_HARNESS_COMPACTION_STRESS,
         ...(CODEX_HARNESS_DISABLE_LOOP_RELAY ? { loopDetectionPreToolUseRelay: false } : {}),
       });
       const deviceIdentity = await ensurePairedTestGatewayClientIdentity({
@@ -1318,7 +1562,14 @@ describeLive("gateway live (Codex harness)", () => {
       let guardianPluginApprovalDecision: GuardianPluginApprovalDecision | undefined;
       let activeApprovalClient: GatewayClient | undefined;
       let resumeStressState:
-        | { lastMarker: string; sessionKey: string; threadId: string }
+        | {
+            clientId: string;
+            hiddenMarker?: string;
+            lastMarker: string;
+            persistedCompactionCount: number;
+            sessionKey: string;
+            threadId: string;
+          }
         | undefined;
       const maybeResolveGuardianPluginApproval = (event: EventFrame): void => {
         const decision = guardianPluginApprovalDecision;
@@ -1345,6 +1596,8 @@ describeLive("gateway live (Codex harness)", () => {
       };
       logCodexLiveStep("config-written", { configPath, modelKey, port });
       observedCodexThreadIds.clear();
+      observedCodexClientIds.clear();
+      observedCodexThreadActions.clear();
 
       try {
         server = await startGatewayServer(port, {
@@ -1411,7 +1664,7 @@ describeLive("gateway live (Codex harness)", () => {
               const firstText = await requestAgentText({
                 client: activeClient,
                 sessionKey,
-                expectedToken: firstToken,
+                expectedReply: firstToken,
                 message: `Reply with exactly ${firstToken} and nothing else.`,
               });
               expect(firstText).toContain(firstToken);
@@ -1422,7 +1675,7 @@ describeLive("gateway live (Codex harness)", () => {
               const secondText = await requestAgentText({
                 client: activeClient,
                 sessionKey,
-                expectedToken: secondToken,
+                expectedReply: secondToken,
                 message: `Reply with exactly ${secondToken} and nothing else. Do not repeat ${firstToken}.`,
               });
               expect(secondText).toContain(secondToken);
@@ -1529,31 +1782,51 @@ describeLive("gateway live (Codex harness)", () => {
               });
               logCodexLiveStep("guardian-probe:done");
             }
-            if (CODEX_HARNESS_RESUME_STRESS) {
+            const compactionStressState = CODEX_HARNESS_COMPACTION_STRESS
+              ? await verifyCodexCompactionStress({
+                  client: activeClient,
+                  events: gatewayEvents,
+                  sessionKey,
+                })
+              : undefined;
+            if (CODEX_HARNESS_RESTART_STRESS) {
               const threadId = observedCodexThreadIds.get(sessionKey);
               if (!threadId) {
                 throw new Error("Codex resume stress did not observe a thread identity");
               }
+              const clientId = observedCodexClientIds.get(sessionKey);
+              if (!clientId) {
+                throw new Error("Codex resume stress did not observe a client identity");
+              }
               let lastMarker = "";
-              for (
-                let historyTurn = 1;
-                historyTurn <= CODEX_HARNESS_RESUME_STRESS_HISTORY_TURNS;
-                historyTurn += 1
-              ) {
+              const historyTurns = CODEX_HARNESS_RESUME_STRESS
+                ? CODEX_HARNESS_RESUME_STRESS_HISTORY_TURNS
+                : 1;
+              for (let historyTurn = 1; historyTurn <= historyTurns; historyTurn += 1) {
                 lastMarker = `CODEX-HISTORY-${historyTurn}-${randomBytes(3)
                   .toString("hex")
                   .toUpperCase()}`;
                 await requestAgentText({
                   client: activeClient,
                   sessionKey,
-                  expectedToken: lastMarker,
-                  message: `Reply with exactly ${lastMarker} and nothing else.`,
+                  expectedReply: lastMarker,
+                  message: [
+                    `Replace durable resume slot B with ${lastMarker}.`,
+                    `Reply with exactly ${lastMarker} and nothing else.`,
+                  ].join(" "),
                 });
                 expect(observedCodexThreadIds.get(sessionKey)).toBe(threadId);
               }
-              resumeStressState = { lastMarker, sessionKey, threadId };
+              resumeStressState = {
+                clientId,
+                hiddenMarker: compactionStressState?.hiddenMarker,
+                lastMarker,
+                persistedCompactionCount: compactionStressState?.persistedCount ?? 0,
+                sessionKey,
+                threadId,
+              };
               logCodexLiveStep("resume-stress:history-ready", {
-                historyTurns: CODEX_HARNESS_RESUME_STRESS_HISTORY_TURNS + 2,
+                historyTurns: historyTurns + 2,
                 threadId,
               });
             }
@@ -1583,7 +1856,7 @@ describeLive("gateway live (Codex harness)", () => {
             }
           }
         }
-        if (CODEX_HARNESS_RESUME_STRESS) {
+        if (CODEX_HARNESS_RESTART_STRESS) {
           if (!resumeStressState) {
             throw new Error("Codex resume stress did not seed a thread");
           }
@@ -1622,25 +1895,67 @@ describeLive("gateway live (Codex harness)", () => {
             const nextMarker = `CODEX-RESTART-${restart}-${randomBytes(3)
               .toString("hex")
               .toUpperCase()}`;
+            const priorClientId = resumeStressState.clientId;
+            const replyInstructions = [
+              "Read durable resume slot B before replacing it.",
+              "Reply with exactly the requested lines and nothing else.",
+              "First line: the current value of durable resume slot B.",
+              `Second line: ${nextMarker}`,
+              `Then replace durable resume slot B with ${nextMarker}.`,
+              ...(resumeStressState.hiddenMarker
+                ? ["Third line: the value stored in durable slot A."]
+                : []),
+            ];
             const resumedText = await requestAgentText({
               client,
               sessionKey: resumeStressState.sessionKey,
-              expectedToken: nextMarker,
-              message: [
-                "Reply with exactly two lines and nothing else.",
-                "First line: the final marker from the immediately preceding assistant message.",
-                `Second line: ${nextMarker}`,
-              ].join(" "),
+              expectedReply: nextMarker,
+              message: replyInstructions.join(" "),
             });
-            expect(resumedText.trim()).toBe(`${resumeStressState.lastMarker}\n${nextMarker}`);
+            const expectedResumeText = [
+              resumeStressState.lastMarker,
+              nextMarker,
+              ...(resumeStressState.hiddenMarker ? [resumeStressState.hiddenMarker] : []),
+            ].join("\n");
+            expect(resumedText.trim()).toBe(expectedResumeText);
             const resumedThreadId = observedCodexThreadIds.get(resumeStressState.sessionKey);
             expect(resumedThreadId).toBe(resumeStressState.threadId);
+            expect(observedCodexThreadActions.get(resumeStressState.sessionKey)).toBe("resumed");
+            const resumedClientId = observedCodexClientIds.get(resumeStressState.sessionKey);
+            expect(resumedClientId).toBeTruthy();
+            expect(resumedClientId).not.toBe(priorClientId);
+            resumeStressState.clientId = resumedClientId as string;
             resumeStressState.lastMarker = nextMarker;
+            if (resumeStressState.persistedCompactionCount > 0) {
+              await readCodexHarnessCompactionCount({
+                client,
+                events: gatewayEvents,
+                minimum: resumeStressState.persistedCompactionCount,
+                sessionKey: resumeStressState.sessionKey,
+              });
+            }
             logCodexLiveStep("resume-stress:restart-complete", {
               restart,
+              action: observedCodexThreadActions.get(resumeStressState.sessionKey),
               threadId: resumedThreadId,
             });
           }
+          if (CODEX_HARNESS_SUBAGENT_PROBE && !CODEX_HARNESS_SUBAGENT_ONLY) {
+            await verifyCodexSubagentProbe({
+              client,
+              sessionKey: resumeStressState.sessionKey,
+            });
+          }
+          if (CODEX_HARNESS_COMPACTION_STRESS) {
+            const continued = await verifyCodexCompactionStress({
+              client,
+              events: gatewayEvents,
+              sessionKey: resumeStressState.sessionKey,
+            });
+            expect(continued.persistedCount).toBeGreaterThan(
+              resumeStressState.persistedCompactionCount,
+            );
+          }
         }
       } finally {
         try {
diff --git a/test/scripts/test-live-codex-harness-docker.test.ts b/test/scripts/test-live-codex-harness-docker.test.ts
index 9e3a45758ed..f56f6101abd 100644
--- a/test/scripts/test-live-codex-harness-docker.test.ts
+++ b/test/scripts/test-live-codex-harness-docker.test.ts
@@ -110,6 +110,24 @@ describe("scripts/test-live-codex-harness-docker.sh", () => {
     expect(script).toContain(
       '-e OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS="${OPENCLAW_LIVE_CODEX_HARNESS_RESUME_STRESS_RESTARTS:-3}"',
     );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT="${OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_COUNT:-1}"',
+    );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS="${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS:-0}"',
+    );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS="${OPENCLAW_LIVE_CODEX_HARNESS_COMPACTION_STRESS_TURNS:-4}"',
+    );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES="${OPENCLAW_LIVE_CODEX_HARNESS_LARGE_OUTPUT_BYTES:-300000}"',
+    );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_CODE_MODE_ONLY="${OPENCLAW_LIVE_CODEX_HARNESS_CODE_MODE_ONLY:-0}"',
+    );
+    expect(script).toContain(
+      '-e OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY="${OPENCLAW_LIVE_CODEX_HARNESS_DISABLE_LOOP_RELAY:-0}"',
+    );
   });
 
   it("installs the plugin-pinned Codex CLI package for app-server proof", () => {

From e721508ed38edeb3e48f7297f1060c4eee6f3dc8 Mon Sep 17 00:00:00 2001
From: "thomas.szbay" <zheng.tao@xydigit.com>
Date: Sat, 18 Jul 2026 17:38:12 +0800
Subject: [PATCH 05/76] fix(ui): bound chat avatar fetches (#110010)

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 ui/src/pages/chat/chat-avatar.test.ts | 96 ++++++++++++++++++++++++++-
 ui/src/pages/chat/chat-avatar.ts      | 37 ++++++++++-
 2 files changed, 129 insertions(+), 4 deletions(-)

diff --git a/ui/src/pages/chat/chat-avatar.test.ts b/ui/src/pages/chat/chat-avatar.test.ts
index a19dd1d0c9c..7e4dffd0cc3 100644
--- a/ui/src/pages/chat/chat-avatar.test.ts
+++ b/ui/src/pages/chat/chat-avatar.test.ts
@@ -1,8 +1,8 @@
 /* @vitest-environment jsdom */
 
 import { render } from "lit";
-import { describe, expect, it } from "vitest";
-import { renderChatAvatar } from "./chat-avatar.ts";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { refreshChatAvatar, renderChatAvatar } from "./chat-avatar.ts";
 
 function renderAvatar(params: Parameters<typeof renderChatAvatar>) {
   const container = document.createElement("div");
@@ -10,6 +10,37 @@ function renderAvatar(params: Parameters<typeof renderChatAvatar>) {
   return container.querySelector<HTMLElement>(".chat-avatar");
 }
 
+function createHost(): Parameters<typeof refreshChatAvatar>[0] {
+  return {
+    basePath: "",
+    chatAvatarUrl: null,
+    connected: true,
+    hello: null,
+    sessionKey: "agent:main",
+  };
+}
+
+function pendingUntilAbort<T>(signal: AbortSignal | null | undefined): Promise<T> {
+  if (!signal) {
+    throw new Error("expected avatar fetch signal");
+  }
+  return new Promise<T>((_resolve, reject) => {
+    signal.addEventListener(
+      "abort",
+      () => {
+        const reason = signal.reason;
+        reject(reason instanceof Error ? reason : new Error("avatar fetch aborted"));
+      },
+      { once: true },
+    );
+  });
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
 describe("renderChatAvatar", () => {
   it("renders assistant fallback, blob image, and text avatars", () => {
     const defaultAvatar = renderAvatar(["assistant"]);
@@ -53,3 +84,64 @@ describe("renderChatAvatar", () => {
     expect(textAvatar?.textContent?.trim()).toBe("AB");
   });
 });
+
+describe("refreshChatAvatar", () => {
+  it("aborts a stalled metadata fetch at the deadline", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn((_input: RequestInfo | URL, init?: RequestInit) =>
+      pendingUntilAbort<Response>(init?.signal),
+    );
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const host = createHost();
+    const refresh = refreshChatAvatar(host);
+    const signal = fetchMock.mock.calls[0]?.[1]?.signal;
+    expect(signal?.aborted).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(29_999);
+    expect(signal?.aborted).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(signal?.aborted).toBe(true);
+
+    await expect(refresh).resolves.toBeUndefined();
+    expect(host.chatAvatarUrl).toBeNull();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("keeps the image body read bounded by its own deadline", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ avatarUrl: "/avatar/main" }),
+      })
+      .mockImplementationOnce((_input: RequestInfo | URL, init?: RequestInit) =>
+        Promise.resolve({
+          ok: true,
+          blob: () => pendingUntilAbort<Blob>(init?.signal),
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const host = createHost();
+    const refresh = refreshChatAvatar(host);
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const metadataSignal = fetchMock.mock.calls[0]?.[1]?.signal as AbortSignal | undefined;
+    const imageSignal = fetchMock.mock.calls[1]?.[1]?.signal as AbortSignal | undefined;
+    expect(metadataSignal).not.toBe(imageSignal);
+    expect(metadataSignal?.aborted).toBe(false);
+    expect(imageSignal?.aborted).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(29_999);
+    expect(imageSignal?.aborted).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(imageSignal?.aborted).toBe(true);
+
+    await expect(refresh).resolves.toBeUndefined();
+    expect(host.chatAvatarUrl).toBeNull();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
diff --git a/ui/src/pages/chat/chat-avatar.ts b/ui/src/pages/chat/chat-avatar.ts
index 41063cd4a99..592736d2399 100644
--- a/ui/src/pages/chat/chat-avatar.ts
+++ b/ui/src/pages/chat/chat-avatar.ts
@@ -262,6 +262,16 @@ function isLocalControlUiAvatarUrl(avatarUrl: string): boolean {
   return avatarUrl.startsWith("/");
 }
 
+/** Give each sequential fetch a full budget; sharing one can starve the image request. */
+const CHAT_AVATAR_FETCH_TIMEOUT_MS = 30_000;
+
+function scheduleChatAvatarFetchTimeout(controller: AbortController, label: string) {
+  return setTimeout(
+    () => controller.abort(new DOMException(`${label} timed out`, "TimeoutError")),
+    CHAT_AVATAR_FETCH_TIMEOUT_MS,
+  );
+}
+
 export async function refreshChatAvatar(host: ChatAvatarHost) {
   if (!host.connected) {
     clearChatAvatarState(host);
@@ -280,8 +290,16 @@ export async function refreshChatAvatar(host: ChatAvatarHost) {
   const authHeader = resolveControlUiAuthHeader(host);
   const headers = buildControlUiAuthHeaders(authHeader);
   const url = buildAvatarMetaUrl(host.basePath, agentId);
+
+  const metaController = new AbortController();
+  const metaTimeout = scheduleChatAvatarFetchTimeout(metaController, "chat avatar metadata fetch");
+  let avatarUrl: string;
   try {
-    const res = await fetch(url, { method: "GET", ...(headers ? { headers } : {}) });
+    const res = await fetch(url, {
+      method: "GET",
+      ...(headers ? { headers } : {}),
+      signal: metaController.signal,
+    });
     if (!shouldApplyChatAvatarResult(host, requestVersion, sessionKey, agentId)) {
       return;
     }
@@ -299,7 +317,7 @@ export async function refreshChatAvatar(host: ChatAvatarHost) {
       return;
     }
     setChatAvatarMeta(host, data);
-    const avatarUrl = typeof data.avatarUrl === "string" ? data.avatarUrl.trim() : "";
+    avatarUrl = typeof data.avatarUrl === "string" ? data.avatarUrl.trim() : "";
     if (!avatarUrl || !isRenderableControlUiAvatarUrl(avatarUrl)) {
       clearChatAvatarUrl(host);
       return;
@@ -308,9 +326,22 @@ export async function refreshChatAvatar(host: ChatAvatarHost) {
       setChatAvatarUrl(host, avatarUrl);
       return;
     }
+  } catch {
+    if (shouldApplyChatAvatarResult(host, requestVersion, sessionKey, agentId)) {
+      clearChatAvatarState(host);
+    }
+    return;
+  } finally {
+    clearTimeout(metaTimeout);
+  }
+
+  const avatarController = new AbortController();
+  const avatarTimeout = scheduleChatAvatarFetchTimeout(avatarController, "chat avatar image fetch");
+  try {
     const avatarRes = await fetch(avatarUrl, {
       method: "GET",
       ...(headers ? { headers } : {}),
+      signal: avatarController.signal,
     });
     if (!avatarRes.ok) {
       if (shouldApplyChatAvatarResult(host, requestVersion, sessionKey, agentId)) {
@@ -328,5 +359,7 @@ export async function refreshChatAvatar(host: ChatAvatarHost) {
     if (shouldApplyChatAvatarResult(host, requestVersion, sessionKey, agentId)) {
       clearChatAvatarState(host);
     }
+  } finally {
+    clearTimeout(avatarTimeout);
   }
 }

From 39528edd745a484457e2add67155f611b2f7da5b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 18 Jul 2026 02:38:13 -0700
Subject: [PATCH 06/76] fix(security): restore fs import lost in bounded
 manifest-read merge

#101773 removed the node:fs/promises import while switching plugin manifest
reads to fs-safe helpers, but getSkillCodeSafetySummary (added later by
#109363) still reads SKILL.md via fs.readFile. Main has been red since the
merge (check-prod-types, check-lint, check-test-types, package-boundary
compile, compact-large-5). Restore the import; skill-file reads keep their
pre-existing unbounded contract.
---
 .../gateway-protocol/src/schema/nodes.test.ts |  34 -----
 packages/gateway-protocol/src/schema/nodes.ts |  17 ++-
 .../src/schema/session-placement.test.ts      |  24 ----
 .../src/schema/session-placement.ts           | 128 +++++++++++-------
 4 files changed, 87 insertions(+), 116 deletions(-)
 delete mode 100644 packages/gateway-protocol/src/schema/nodes.test.ts

diff --git a/packages/gateway-protocol/src/schema/nodes.test.ts b/packages/gateway-protocol/src/schema/nodes.test.ts
deleted file mode 100644
index 5735413cc91..00000000000
--- a/packages/gateway-protocol/src/schema/nodes.test.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { validateNodeInvokeProgressParams } from "../index.js";
-
-describe("node protocol schemas", () => {
-  it("accepts bounded progress chunks and rejects extra fields", () => {
-    expect(
-      validateNodeInvokeProgressParams({
-        invokeId: "invoke-1",
-        nodeId: "node-1",
-        seq: 0,
-        chunk: "stdout line",
-      }),
-    ).toBe(true);
-
-    expect(
-      validateNodeInvokeProgressParams({
-        invokeId: "invoke-1",
-        nodeId: "node-1",
-        seq: 0,
-        chunk: "x".repeat(16 * 1024 + 1),
-      }),
-    ).toBe(false);
-
-    expect(
-      validateNodeInvokeProgressParams({
-        invokeId: "invoke-1",
-        nodeId: "node-1",
-        seq: 0,
-        chunk: "stdout line",
-        extra: "not allowed",
-      }),
-    ).toBe(false);
-  });
-});
diff --git a/packages/gateway-protocol/src/schema/nodes.ts b/packages/gateway-protocol/src/schema/nodes.ts
index 47fd1a300ec..40e8ce9fea5 100644
--- a/packages/gateway-protocol/src/schema/nodes.ts
+++ b/packages/gateway-protocol/src/schema/nodes.ts
@@ -164,13 +164,16 @@ export const NodeInvokeResultParamsSchema = closedObject({
 });
 
 /** Ordered UTF-8 output emitted while a node command invocation is running. */
-export const NodeInvokeProgressParamsSchema = closedObject({
-  invokeId: NonEmptyString,
-  nodeId: NonEmptyString,
-  seq: Type.Integer({ minimum: 0 }),
-  // Empty chunks are liveness heartbeats for captured stderr or capped stdout.
-  chunk: Type.String({ maxLength: 16 * 1024 }),
-});
+export const NodeInvokeProgressParamsSchema = Type.Object(
+  {
+    invokeId: NonEmptyString,
+    nodeId: NonEmptyString,
+    seq: Type.Integer({ minimum: 0 }),
+    // Empty chunks are liveness heartbeats for captured stderr or capped stdout.
+    chunk: Type.String({ maxLength: 16 * 1024 }),
+  },
+  { additionalProperties: false },
+);
 
 /** Generic node event envelope accepted by the gateway. */
 export const NodeEventParamsSchema = closedObject({
diff --git a/packages/gateway-protocol/src/schema/session-placement.test.ts b/packages/gateway-protocol/src/schema/session-placement.test.ts
index 789b72bb629..8943d06e094 100644
--- a/packages/gateway-protocol/src/schema/session-placement.test.ts
+++ b/packages/gateway-protocol/src/schema/session-placement.test.ts
@@ -282,28 +282,4 @@ describe("session dispatch protocol schemas", () => {
       }),
     ).toBe(false);
   });
-
-  it("rejects extra fields in dispatch params and results", () => {
-    const active = {
-      state: "active" as const,
-      ...basePlacement,
-      ...workerOwnedFields,
-    };
-    expect(
-      validateSessionsDispatchResult({
-        ok: true,
-        key: "agent:main:dispatch",
-        sessionId: "session-1",
-        placement: active,
-        extra: true,
-      }),
-    ).toBe(false);
-    expect(
-      validateSessionsDispatchParams({
-        key: "agent:main:dispatch",
-        profileId: "development",
-        extra: true,
-      }),
-    ).toBe(false);
-  });
 });
diff --git a/packages/gateway-protocol/src/schema/session-placement.ts b/packages/gateway-protocol/src/schema/session-placement.ts
index 34acbab4ff7..65ff59e7989 100644
--- a/packages/gateway-protocol/src/schema/session-placement.ts
+++ b/packages/gateway-protocol/src/schema/session-placement.ts
@@ -1,6 +1,5 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
-import { closedObject } from "./closed-object.js";
 import { NonEmptyString } from "./primitives.js";
 import { SESSION_PLACEMENT_STATES } from "./session-placement-state.js";
 
@@ -78,64 +77,85 @@ const TerminalSessionPlacementProperties = {
 function createUnownedSessionPlacementSchema<const State extends "local" | "requested">(
   state: State,
 ) {
-  return closedObject({ state: Type.Literal(state), ...SessionPlacementTimingProperties });
+  return Type.Object(
+    { state: Type.Literal(state), ...SessionPlacementTimingProperties },
+    { additionalProperties: false },
+  );
 }
 
 function createWorkerOwnedSessionPlacementSchema<
   const State extends "active" | "draining" | "reconciling",
 >(state: State) {
-  return closedObject({
-    state: Type.Literal(state),
-    ...SessionPlacementTimingProperties,
-    environmentId: NonEmptyString,
-    activeOwnerEpoch: SessionPlacementOwnerEpochSchema,
-    workerBundleHash: WorkerBundleHashSchema,
-    ...SessionPlacementWorkspaceProperties,
-    ...SessionPlacementAckProperties,
-  });
+  return Type.Object(
+    {
+      state: Type.Literal(state),
+      ...SessionPlacementTimingProperties,
+      environmentId: NonEmptyString,
+      activeOwnerEpoch: SessionPlacementOwnerEpochSchema,
+      workerBundleHash: WorkerBundleHashSchema,
+      ...SessionPlacementWorkspaceProperties,
+      ...SessionPlacementAckProperties,
+    },
+    { additionalProperties: false },
+  );
 }
 
 export const LocalSessionPlacementSchema = createUnownedSessionPlacementSchema("local");
 export const RequestedSessionPlacementSchema = createUnownedSessionPlacementSchema("requested");
 
-export const ProvisioningSessionPlacementSchema = closedObject({
-  state: Type.Literal("provisioning"),
-  ...SessionPlacementTimingProperties,
-  environmentId: Type.Optional(NonEmptyString),
-});
+export const ProvisioningSessionPlacementSchema = Type.Object(
+  {
+    state: Type.Literal("provisioning"),
+    ...SessionPlacementTimingProperties,
+    environmentId: Type.Optional(NonEmptyString),
+  },
+  { additionalProperties: false },
+);
 
-export const SyncingSessionPlacementSchema = closedObject({
-  state: Type.Literal("syncing"),
-  ...SessionPlacementTimingProperties,
-  environmentId: NonEmptyString,
-  workerBundleHash: WorkerBundleHashSchema,
-});
+export const SyncingSessionPlacementSchema = Type.Object(
+  {
+    state: Type.Literal("syncing"),
+    ...SessionPlacementTimingProperties,
+    environmentId: NonEmptyString,
+    workerBundleHash: WorkerBundleHashSchema,
+  },
+  { additionalProperties: false },
+);
 
-export const StartingSessionPlacementSchema = closedObject({
-  state: Type.Literal("starting"),
-  ...SessionPlacementTimingProperties,
-  environmentId: NonEmptyString,
-  workerBundleHash: WorkerBundleHashSchema,
-  ...SessionPlacementWorkspaceProperties,
-});
+export const StartingSessionPlacementSchema = Type.Object(
+  {
+    state: Type.Literal("starting"),
+    ...SessionPlacementTimingProperties,
+    environmentId: NonEmptyString,
+    workerBundleHash: WorkerBundleHashSchema,
+    ...SessionPlacementWorkspaceProperties,
+  },
+  { additionalProperties: false },
+);
 
 export const ActiveWorkerSessionPlacementSchema = createWorkerOwnedSessionPlacementSchema("active");
 export const DrainingSessionPlacementSchema = createWorkerOwnedSessionPlacementSchema("draining");
 export const ReconcilingSessionPlacementSchema =
   createWorkerOwnedSessionPlacementSchema("reconciling");
 
-export const ReclaimedSessionPlacementSchema = closedObject({
-  state: Type.Literal("reclaimed"),
-  ...SessionPlacementTimingProperties,
-  ...TerminalSessionPlacementProperties,
-});
+export const ReclaimedSessionPlacementSchema = Type.Object(
+  {
+    state: Type.Literal("reclaimed"),
+    ...SessionPlacementTimingProperties,
+    ...TerminalSessionPlacementProperties,
+  },
+  { additionalProperties: false },
+);
 
-export const FailedSessionPlacementSchema = closedObject({
-  state: Type.Literal("failed"),
-  ...SessionPlacementTimingProperties,
-  ...TerminalSessionPlacementProperties,
-  recoveryError: NonEmptyString,
-});
+export const FailedSessionPlacementSchema = Type.Object(
+  {
+    state: Type.Literal("failed"),
+    ...SessionPlacementTimingProperties,
+    ...TerminalSessionPlacementProperties,
+    recoveryError: NonEmptyString,
+  },
+  { additionalProperties: false },
+);
 
 /** Gateway-visible placement projection; `state` remains the closed discriminator. */
 export const SessionPlacementSchema = Type.Union([
@@ -152,19 +172,25 @@ export const SessionPlacementSchema = Type.Union([
 ]);
 
 /** Requests one-way dispatch of an existing local session to a configured worker profile. */
-export const SessionsDispatchParamsSchema = closedObject({
-  key: NonEmptyString,
-  agentId: Type.Optional(NonEmptyString),
-  profileId: NonEmptyString,
-});
+export const SessionsDispatchParamsSchema = Type.Object(
+  {
+    key: NonEmptyString,
+    agentId: Type.Optional(NonEmptyString),
+    profileId: NonEmptyString,
+  },
+  { additionalProperties: false },
+);
 
 /** Result returned once session dispatch reaches durable worker ownership. */
-export const SessionsDispatchResultSchema = closedObject({
-  ok: Type.Literal(true),
-  key: NonEmptyString,
-  sessionId: NonEmptyString,
-  placement: ActiveWorkerSessionPlacementSchema,
-});
+export const SessionsDispatchResultSchema = Type.Object(
+  {
+    ok: Type.Literal(true),
+    key: NonEmptyString,
+    sessionId: NonEmptyString,
+    placement: ActiveWorkerSessionPlacementSchema,
+  },
+  { additionalProperties: false },
+);
 
 /** Requests safe workspace reconciliation and teardown of an active cloud worker. */
 export const SessionsReclaimParamsSchema = Type.Object(

From b34d0a8bb6aaac68669e791362083b8772b5f30d Mon Sep 17 00:00:00 2001
From: tzy-17 <tang.ziyi@xydigit.com>
Date: Sat, 18 Jul 2026 17:40:05 +0800
Subject: [PATCH 07/76] fix(gateway): bound usage.list days parameter to 100
 years (#110552)

* fix(gateway): bound usage.list days parameter to 100 years

parseDays accepted any finite number including 1e300, which downstream
resolveTrailingDays would feed into Date arithmetic as a day offset,
overflowing the ECMAScript Date range and surfacing as a misleading
"calendar day does not exist in requested time zone" error. Reject
day counts above 100 years (36600); callers wanting truly unbounded
history should use `range: "all"`.

Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>

* fix(gateway): clamp oversized usage day ranges

---------

Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/gateway/server-methods/usage.test.ts | 13 ++++++++++++-
 src/gateway/server-methods/usage.ts      | 19 +++++++++++++------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/gateway/server-methods/usage.test.ts b/src/gateway/server-methods/usage.test.ts
index 1cab7dc5da1..f4ab4ff8086 100644
--- a/src/gateway/server-methods/usage.test.ts
+++ b/src/gateway/server-methods/usage.test.ts
@@ -266,6 +266,13 @@ describe("gateway usage helpers", () => {
     expect(testApi.parseDays("nope")).toBeUndefined();
   });
 
+  it("parseDays caps day counts before Date arithmetic can overflow", () => {
+    expect(testApi.parseDays(1e300)).toBe(36600);
+    expect(testApi.parseDays("1e300")).toBe(36600);
+    expect(testApi.parseDays(Number.MAX_SAFE_INTEGER)).toBe(36600);
+    expect(testApi.parseDays(366 * 100)).toBe(36600);
+  });
+
   it("resolveDateRange uses explicit start/end as UTC when mode is missing (backward compatible)", () => {
     const result = testApi.resolveDateRange({
       startDate: "2026-02-01",
@@ -413,13 +420,17 @@ describe("gateway usage helpers", () => {
     });
   });
 
-  it("resolveDateRange clamps days to at least 1 and defaults to 30 days", () => {
+  it("resolveDateRange clamps days to its supported bounds and defaults to 30 days", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-02-05T12:34:56.000Z"));
     const oneDay = expectDateRange(testApi.resolveDateRange({ days: 0 }));
     expect(oneDay.endMs).toBe(Date.UTC(2026, 1, 5) + dayMs - 1);
     expect(oneDay.startMs).toBe(Date.UTC(2026, 1, 5));
 
+    const maxDays = expectDateRange(testApi.resolveDateRange({ days: Number.MAX_SAFE_INTEGER }));
+    expect(maxDays.endMs).toBe(Date.UTC(2026, 1, 5) + dayMs - 1);
+    expect(maxDays.startMs).toBe(Date.UTC(2026, 1, 5) - (36600 - 1) * dayMs);
+
     const def = expectDateRange(testApi.resolveDateRange({}));
     expect(def.endMs).toBe(Date.UTC(2026, 1, 5) + dayMs - 1);
     expect(def.startMs).toBe(Date.UTC(2026, 1, 5) - 29 * dayMs);
diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts
index b9cfca2aaee..655348ba825 100644
--- a/src/gateway/server-methods/usage.ts
+++ b/src/gateway/server-methods/usage.ts
@@ -88,6 +88,10 @@ type DateRange = { startMs: number; endMs: number; includeUntimestamped?: boolea
 // Keep validation and parsed timestamps in one result so handlers cannot forward
 // an invalid or backwards window to the usage loaders.
 type DateRangeResolution = { ok: true; value: DateRange } | { ok: false; error: string };
+// 100 years: callers requesting unbounded history should use `range: "all"`.
+// Larger explicit day counts would overflow ECMAScript Date arithmetic and
+// surface as a misleading "calendar day does not exist" error from the resolver.
+const MAX_USAGE_DAYS = 366 * 100;
 type DateInterpretation =
   | { mode: "utc" | "gateway" }
   | { mode: "utc-offset"; utcOffsetMinutes: number }
@@ -388,14 +392,17 @@ const formatDateParts = (year: number, monthIndex: number, day: number): string
   `${year}-${String(monthIndex + 1).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
 
 const parseDays = (raw: unknown): number | undefined => {
-  if (typeof raw === "number" && Number.isFinite(raw)) {
-    return Math.floor(raw);
+  const fromFinite = (n: number): number | undefined => {
+    if (!Number.isFinite(n)) {
+      return undefined;
+    }
+    return Math.min(Math.floor(n), MAX_USAGE_DAYS);
+  };
+  if (typeof raw === "number") {
+    return fromFinite(raw);
   }
   if (typeof raw === "string" && raw.trim() !== "") {
-    const parsed = Number(raw);
-    if (Number.isFinite(parsed)) {
-      return Math.floor(parsed);
-    }
+    return fromFinite(Number(raw));
   }
   return undefined;
 };

From 1af6d99658098ceb2f75f36acf68b92c8eefe635 Mon Sep 17 00:00:00 2001
From: xingzhou <zhang.guiping@xydigit.com>
Date: Sat, 18 Jul 2026 17:41:31 +0800
Subject: [PATCH 08/76] fix: surface cron errors for empty isolated agent
 replies (#100229)

* fix(cron): fail empty isolated agent completions

* fix: surface cron errors for empty isolated agent replies

* fix(cron): preserve intentional terminal progress

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 .../run.meta-error-status.test.ts             | 274 ++++++++++++++++++
 src/cron/isolated-agent/run.ts                |  36 +++
 2 files changed, 310 insertions(+)

diff --git a/src/cron/isolated-agent/run.meta-error-status.test.ts b/src/cron/isolated-agent/run.meta-error-status.test.ts
index c85f5668dc4..57ae4c0d92a 100644
--- a/src/cron/isolated-agent/run.meta-error-status.test.ts
+++ b/src/cron/isolated-agent/run.meta-error-status.test.ts
@@ -4,7 +4,10 @@ import { makeIsolatedAgentJobFixture, makeIsolatedAgentParamsFixture } from "./j
 import { setupRunCronIsolatedAgentTurnSuite } from "./run.suite-helpers.js";
 import {
   cleanupDirectCronSessionMock,
+  dispatchCronDeliveryMock,
   loadRunCronIsolatedAgentTurn,
+  resolveCronDeliveryPlanMock,
+  resolveCronPayloadOutcomeMock,
   runWithModelFallbackMock,
 } from "./run.test-harness.js";
 
@@ -94,6 +97,277 @@ describe("runCronIsolatedAgentTurn - meta.error status propagation", () => {
     });
   });
 
+  it("marks a completed embedded run with no final payload as a cron error", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).not.toHaveBeenCalled();
+    expect(result.status).toBe("error");
+    expect(result.error).toBe("cron isolated run completed without a final assistant payload");
+    expect(result.delivered).toBe(false);
+  });
+
+  it("marks empty message-tool attempts without source delivery as cron errors", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        didSendViaMessagingTool: true,
+        messagingToolSentTargets: [],
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).not.toHaveBeenCalled();
+    expect(result.status).toBe("error");
+    expect(result.error).toBe("cron isolated run completed without a final assistant payload");
+    expect(result.delivered).toBe(false);
+  });
+
+  it("keeps explicit silent replies as successful cron completions", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        meta: {
+          finalAssistantRawText: "NO_REPLY",
+          finalAssistantVisibleText: "NO_REPLY",
+          agentMeta: { usage: { input: 10, output: 1 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).toHaveBeenCalled();
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("keeps committed message-tool deliveries as successful cron completions", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        didSendViaMessagingTool: true,
+        messagingToolSentTexts: ["Delivered to an intentional recipient"],
+        messagingToolSentTargets: [],
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).toHaveBeenCalled();
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("does not mark empty deterministic approval prompts as cron errors", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        didSendDeterministicApprovalPrompt: true,
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).toHaveBeenCalled();
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("does not mark empty accepted child-session handoffs as cron errors", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        acceptedSessionSpawns: [{ runId: "run-child", childSessionKey: "agent:default:child" }],
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).toHaveBeenCalled();
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("does not mark empty successful cron-add completions as cron errors", async () => {
+    runWithModelFallbackMock.mockResolvedValueOnce({
+      result: {
+        payloads: [],
+        successfulCronAdds: 1,
+        meta: {
+          agentMeta: { usage: { input: 10, output: 0 } },
+        },
+      },
+      provider: "anthropic",
+      model: "claude-opus-4-8",
+      attempts: [],
+    });
+    resolveCronDeliveryPlanMock.mockReturnValue({
+      requested: true,
+      mode: "announce",
+      channel: "messagechat",
+      to: "test-target",
+    });
+    resolveCronPayloadOutcomeMock.mockReturnValue({
+      summary: undefined,
+      outputText: undefined,
+      synthesizedText: undefined,
+      deliveryPayload: undefined,
+      deliveryPayloads: [],
+      deliveryPayloadHasStructuredContent: false,
+      hasFatalErrorPayload: false,
+      hasFatalStructuredErrorPayload: false,
+      embeddedRunError: undefined,
+    });
+
+    const result = await runCronIsolatedAgentTurn(makeIsolatedAgentParamsFixture());
+
+    expect(dispatchCronDeliveryMock).toHaveBeenCalled();
+    expect(result.status).toBe("ok");
+    expect(result.error).toBeUndefined();
+  });
+
   it("surfaces cron timeout result when the cron-nested lane watchdog fires", async () => {
     runWithModelFallbackMock.mockRejectedValueOnce(
       makeCommandLaneTaskTimeoutError("cron-nested", 330_000),
diff --git a/src/cron/isolated-agent/run.ts b/src/cron/isolated-agent/run.ts
index 7d556884a38..e35d087f56e 100644
--- a/src/cron/isolated-agent/run.ts
+++ b/src/cron/isolated-agent/run.ts
@@ -1,7 +1,9 @@
 import { isDeepStrictEqual } from "node:util";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { hasAcceptedSessionSpawn } from "../../agents/accepted-session-spawn.js";
 import { retireSessionMcpRuntime } from "../../agents/agent-bundle-mcp-tools.js";
 import { hasAnyAuthProfileStoreSource } from "../../agents/auth-profiles/source-check.js";
+import { hasCommittedMessagingToolDeliveryEvidence } from "../../agents/embedded-agent-runner/delivery-evidence.js";
 import { findModelInCatalog } from "../../agents/model-catalog-lookup.js";
 import type { ModelCatalogEntry } from "../../agents/model-catalog.types.js";
 import { listOpenAIAuthProfileProvidersForAgentRuntime } from "../../agents/openai-routing.js";
@@ -9,6 +11,7 @@ import { createAgentRunRestartAbortError } from "../../agents/run-termination.js
 import { expandToolGroups, normalizeToolName } from "../../agents/tool-policy.js";
 import { deriveContextPromptTokens } from "../../agents/usage.js";
 import type { ThinkLevel } from "../../auto-reply/thinking.js";
+import { isSilentReplyPayloadText } from "../../auto-reply/tokens.js";
 import type { CliDeps } from "../../cli/outbound-send-deps.js";
 import { resolveAgentModelPrimaryValue } from "../../config/model-input.js";
 import type { SessionEntry } from "../../config/sessions.js";
@@ -1442,6 +1445,39 @@ async function finalizeCronRun(params: {
       sourceDeliveryOutcome,
     });
   }
+  const hasCommittedTerminalProgress =
+    hasCommittedMessagingToolDeliveryEvidence(finalRunResult) ||
+    finalRunResult.didSendDeterministicApprovalPrompt === true ||
+    hasAcceptedSessionSpawn(finalRunResult.acceptedSessionSpawns) ||
+    (finalRunResult.successfulCronAdds ?? 0) > 0;
+  const hasIntentionalSilentReply =
+    finalRunResult.meta?.terminalReplyKind === "silent-empty" ||
+    isSilentReplyPayloadText(finalRunResult.meta?.finalAssistantRawText) ||
+    isSilentReplyPayloadText(finalRunResult.meta?.finalAssistantVisibleText);
+  if (
+    prepared.deliveryRequested &&
+    !hasFatalErrorPayload &&
+    !sourceDeliveryOutcome.satisfiesSourceDelivery &&
+    !hasCommittedTerminalProgress &&
+    !hasIntentionalSilentReply &&
+    deliveryPayloads.length === 0 &&
+    normalizeOptionalString(synthesizedText) === undefined
+  ) {
+    const error = "cron isolated run completed without a final assistant payload";
+    return prepared.withRunSession({
+      status: "error",
+      error,
+      summary: error,
+      outputText: error,
+      delivered: false,
+      deliveryAttempted: false,
+      diagnostics: mergeCronRunDiagnostics(
+        runDiagnostics,
+        createCronRunDiagnosticsFromError("agent-run", error),
+      ),
+      ...telemetry,
+    });
+  }
   if (hasFatalStructuredErrorPayload && prepared.deliveryRequested) {
     // Structured run error payloads belong in cron state and failure alerts,
     // not the normal completion announce path where provider JSON can leak.

From 2b04c350a322a038fe6677c848cf654c80d9f74c Mon Sep 17 00:00:00 2001
From: Peter Lee <li.xialong@xydigit.com>
Date: Sat, 18 Jul 2026 04:41:44 -0500
Subject: [PATCH 09/76] fix(config): restore process.env after invalid config
 rejection (#103786)

* fix(config): restore process.env after invalid config rejection

When config validation fails, env vars from the rejected config
(env.vars in openclaw.json) leaked into process.env and were never
cleaned up. In long-running gateways this meant rejected config
values could persist until process restart.

Add restoreEnvChangesIfUnchanged calls in both sync (loadConfigLocal)
and async (readConfigFileSnapshotInternal) validation-failure paths,
matching the pattern already used by suspicious-config recovery paths.

* fix(config): restore env before observer and on duplicate-agent-dir rejection

- Add restoreEnvChangesIfUnchanged before DuplicateAgentDirError throw
  in the sync loadConfigLocal path so env vars from rejected config
  do not leak when duplicate agent directories are detected.
- Move restoreEnvChangesIfUnchanged before observeLoadConfigSnapshot
  in the sync validation-failure path so config health/audit
  observation does not see rejected env values.
- Add entry-point regression tests exercising sync loadConfig,
  async readConfigFileSnapshot, and duplicate-agent-dir rejection
  paths through createConfigIO with real config files.

* fix(config): restore env after invalid snapshot

Co-authored-by: xialonglee <li.xialong@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/config/io.load-env-restore.test.ts | 47 ++++++++++++++++++++++++++
 src/config/io.snapshot.ts              |  6 ++++
 2 files changed, 53 insertions(+)

diff --git a/src/config/io.load-env-restore.test.ts b/src/config/io.load-env-restore.test.ts
index 6f5be4b868f..f252371d991 100644
--- a/src/config/io.load-env-restore.test.ts
+++ b/src/config/io.load-env-restore.test.ts
@@ -123,3 +123,50 @@ describe("loadConfig env restoration", () => {
     });
   });
 });
+
+describe("readConfigFileSnapshot env restoration", () => {
+  it("removes a newly injected env var after invalid snapshot validation", async () => {
+    await withTempHome(async (home) => {
+      await writeOpenClawConfig(home, {
+        env: { vars: { TEST_VAR: "injected-value" } },
+        gateway: { port: "invalid" },
+      });
+
+      const env = { HOME: home } as NodeJS.ProcessEnv;
+      const io = createConfigIO({
+        env,
+        homedir: () => home,
+        logger: { warn: () => {}, error: () => {} },
+      });
+
+      const snapshot = await io.readConfigFileSnapshot();
+
+      expect(snapshot.valid).toBe(false);
+      expect(env.TEST_VAR).toBeUndefined();
+    });
+  });
+
+  it("restores an overwritten env var after invalid snapshot validation", async () => {
+    await withTempHome(async (home) => {
+      await writeOpenClawConfig(home, {
+        env: { vars: { PRE_EXISTING: "new-value" } },
+        gateway: { port: "invalid" },
+      });
+
+      const env = {
+        HOME: home,
+        PRE_EXISTING: "original-value",
+      } as NodeJS.ProcessEnv;
+      const io = createConfigIO({
+        env,
+        homedir: () => home,
+        logger: { warn: () => {}, error: () => {} },
+      });
+
+      const snapshot = await io.readConfigFileSnapshot();
+
+      expect(snapshot.valid).toBe(false);
+      expect(env.PRE_EXISTING).toBe("original-value");
+    });
+  });
+});
diff --git a/src/config/io.snapshot.ts b/src/config/io.snapshot.ts
index 707070d7ad4..dd8eb1630eb 100644
--- a/src/config/io.snapshot.ts
+++ b/src/config/io.snapshot.ts
@@ -182,6 +182,12 @@ export async function readConfigFileSnapshotInternal(
       const legacyIssues = await deps.measure("config.snapshot.read.legacy-issues", () =>
         collectInvalidConfigLegacyIssues(effectiveConfigRaw, effectiveParsed),
       );
+      // Invalid snapshots stay inspectable, but rejected env.vars must not become runtime state.
+      restoreEnvChangesIfUnchanged({
+        env: deps.env,
+        before: envBeforeRead,
+        after: snapshotEnv(deps.env),
+      });
       return await finalizeReadConfigSnapshotInternalResult(deps, {
         snapshot: createConfigFileSnapshot({
           path: configPath,

From fceae4d8aa04d98963d1b928da7863c2c7b3e2f1 Mon Sep 17 00:00:00 2001
From: chengzhichao-xydt <cheng.zhichao@xydigit.com>
Date: Sat, 18 Jul 2026 17:42:19 +0800
Subject: [PATCH 10/76] fix(ui): bound managed outgoing image fetches (#108116)

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: chengzhichao-xydt <chengzhichao-xydt@users.noreply.github.com>
---
 .../chat/components/chat-message.test.ts      | 130 ++++++++++++++++++
 ui/src/pages/chat/components/chat-message.ts  |  45 ++++--
 2 files changed, 161 insertions(+), 14 deletions(-)

diff --git a/ui/src/pages/chat/components/chat-message.test.ts b/ui/src/pages/chat/components/chat-message.test.ts
index 451f2a39c0d..b8137990f2d 100644
--- a/ui/src/pages/chat/components/chat-message.test.ts
+++ b/ui/src/pages/chat/components/chat-message.test.ts
@@ -105,6 +105,12 @@ function expectSameOriginGet(init: RequestInit | undefined) {
   expect(init?.method).toBe("GET");
 }
 
+function rejectWhenAborted<T>(signal: AbortSignal, rejection: () => Error): Promise<T> {
+  return new Promise<T>((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(rejection()), { once: true });
+  });
+}
+
 function renderAssistantMessage(
   container: HTMLElement,
   message: unknown,
@@ -2678,6 +2684,130 @@ describe("grouped chat rendering", () => {
     expectSameOriginGet(fetchInit);
   });
 
+  it("aborts a stalled managed outgoing image fetch after the deadline", async () => {
+    vi.useFakeTimers();
+    const managedChatImageUrl = `/api/chat/media/outgoing/agent%3Amain%3Amain/${crypto.randomUUID()}/full`;
+    const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+      const signal = init?.signal;
+      if (!signal) {
+        throw new Error("missing managed image signal");
+      }
+      return await rejectWhenAborted<Response>(signal, () => {
+        const reason = signal.reason;
+        return reason instanceof Error ? reason : new Error("managed image fetch aborted");
+      });
+    });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const container = document.createElement("div");
+    renderAssistantMessage(
+      container,
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "image",
+            url: managedChatImageUrl,
+            alt: "Generated image timeout",
+            width: 1,
+            height: 1,
+          },
+        ],
+        timestamp: Date.now(),
+      },
+      {
+        showToolCalls: false,
+        assistantAttachmentAuthToken: "test-auth-token",
+      },
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, fetchInit] = requireFetchCallForUrl(fetchMock, managedChatImageUrl);
+    expect(fetchInit?.signal?.aborted).toBe(false);
+    expectSameOriginGet(fetchInit);
+
+    await vi.advanceTimersByTimeAsync(29_999);
+    expect(fetchInit?.signal?.aborted).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(fetchInit?.signal?.aborted).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(container.querySelector(".chat-message-image")).toBeNull();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("falls back when a managed outgoing image body stalls after headers", async () => {
+    vi.useFakeTimers();
+    const managedChatImageUrl = `/api/chat/media/outgoing/agent%3Amain%3Amain/${crypto.randomUUID()}/full`;
+    const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => {
+      const signal = init?.signal;
+      if (!signal) {
+        throw new Error("missing managed image signal");
+      }
+      return {
+        ok: true,
+        blob: async () =>
+          await rejectWhenAborted<Blob>(
+            signal,
+            () => new DOMException("The operation was aborted.", "AbortError"),
+          ),
+      };
+    });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const container = document.createElement("div");
+    renderAssistantMessage(container, {
+      role: "assistant",
+      content: [
+        {
+          type: "image",
+          url: managedChatImageUrl,
+          alt: "Generated image body stall",
+          width: 1,
+          height: 1,
+        },
+      ],
+      timestamp: Date.now(),
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, fetchInit] = requireFetchCallForUrl(fetchMock, managedChatImageUrl);
+    expect(fetchInit?.signal?.aborted).toBe(false);
+    expectSameOriginGet(fetchInit);
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(fetchInit?.signal?.aborted).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(0);
+    expect(container.querySelector(".chat-message-image")).toBeNull();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("treats a failed managed outgoing image fetch as a missing preview", async () => {
+    const managedChatImageUrl = `/api/chat/media/outgoing/agent%3Amain%3Amain/${crypto.randomUUID()}/full`;
+    const fetchMock = vi.fn(async () => {
+      throw new Error("gateway unavailable");
+    });
+    vi.stubGlobal("fetch", fetchMock as unknown as typeof fetch);
+
+    const container = document.createElement("div");
+    renderAssistantMessage(container, {
+      role: "assistant",
+      content: [
+        {
+          type: "image",
+          url: managedChatImageUrl,
+          alt: "Unavailable generated image",
+        },
+      ],
+      timestamp: Date.now(),
+    });
+
+    await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    await flushAssistantAttachmentAvailabilityChecks();
+    expect(container.querySelector(".chat-message-image")).toBeNull();
+  });
+
   it("bounds managed outgoing image blob URLs with least-recently-used eviction", async () => {
     const imageUrls = Array.from(
       { length: 65 },
diff --git a/ui/src/pages/chat/components/chat-message.ts b/ui/src/pages/chat/components/chat-message.ts
index 9446cf4eb46..27ce735b6d5 100644
--- a/ui/src/pages/chat/components/chat-message.ts
+++ b/ui/src/pages/chat/components/chat-message.ts
@@ -267,6 +267,7 @@ const managedImageBlobUrlResolvedCache = new Map<string, string>();
 const managedImageBlobUrlMissCache = new Map<string, number>();
 const MANAGED_IMAGE_BLOB_URL_CACHE_MAX_ENTRIES = 64;
 const MANAGED_IMAGE_BLOB_URL_MISS_RETRY_MS = 5_000;
+const MANAGED_OUTGOING_IMAGE_FETCH_TIMEOUT_MS = 30_000;
 
 function readManagedImageBlobUrl(cacheKey: string): string | undefined {
   const cached = managedImageBlobUrlResolvedCache.get(cacheKey);
@@ -1669,23 +1670,39 @@ async function resolveManagedOutgoingImageBlobUrl(
       if (requesterSessionKey) {
         headers.set("x-openclaw-requester-session-key", requesterSessionKey);
       }
-      const res = await fetch(fetchUrl, {
-        method: "GET",
-        headers,
-        credentials: "same-origin",
-      });
-      if (!res.ok) {
-        cacheManagedImageBlobUrlMiss(cacheKey);
-        return null;
-      }
-      const blob = await res.blob();
-      if (!blob.type.startsWith("image/")) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => {
+        controller.abort(
+          new DOMException("managed outgoing image fetch timed out", "TimeoutError"),
+        );
+      }, MANAGED_OUTGOING_IMAGE_FETCH_TIMEOUT_MS);
+      try {
+        const res = await fetch(fetchUrl, {
+          method: "GET",
+          headers,
+          credentials: "same-origin",
+          signal: controller.signal,
+        });
+        if (!res.ok) {
+          cacheManagedImageBlobUrlMiss(cacheKey);
+          return null;
+        }
+        const blob = await res.blob();
+        if (!blob.type.startsWith("image/")) {
+          cacheManagedImageBlobUrlMiss(cacheKey);
+          return null;
+        }
+        const blobUrl = URL.createObjectURL(blob);
+        cacheManagedImageBlobUrl(cacheKey, blobUrl);
+        return blobUrl;
+      } catch {
+        // The render path treats a missing preview as `nothing`; never reject
+        // its `until` promise for an optional image fetch or body failure.
         cacheManagedImageBlobUrlMiss(cacheKey);
         return null;
+      } finally {
+        clearTimeout(timeout);
       }
-      const blobUrl = URL.createObjectURL(blob);
-      cacheManagedImageBlobUrl(cacheKey, blobUrl);
-      return blobUrl;
     })().finally(() => {
       managedImageBlobUrlCache.delete(cacheKey);
     });

From 95d632e644b3c826ca74b76494857f9e9a0fd4e8 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 10:44:01 +0100
Subject: [PATCH 11/76] fix(security): bound skill-file audit read via safe
 reader (restore removed fs dependency) (#110589)

---
 src/security/audit-extra.async.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/security/audit-extra.async.ts b/src/security/audit-extra.async.ts
index dfb66112a2f..6a7c7f4819c 100644
--- a/src/security/audit-extra.async.ts
+++ b/src/security/audit-extra.async.ts
@@ -3,7 +3,6 @@
  *
  * These functions perform I/O (filesystem, config reads) to detect security issues.
  */
-import fs from "node:fs/promises";
 import path from "node:path";
 import { clearTimeout as clearNodeTimeout, setTimeout as setNodeTimeout } from "node:timers";
 import {
@@ -99,6 +98,10 @@ function expandTilde(p: string, env: NodeJS.ProcessEnv): string | null {
 }
 
 const MAX_PLUGIN_MANIFEST_BYTES = 1024 * 1024;
+// Skill file audit reads are bounded like other audit reads; matches the
+// workspace loader's DEFAULT_MAX_SKILL_FILE_BYTES so oversized SKILL.md files
+// cannot force an unbounded read during the code-safety scan.
+const MAX_SKILL_AUDIT_FILE_BYTES = 256_000;
 
 async function readPluginManifestExtensions(pluginPath: string): Promise<string[]> {
   const manifestPath = path.join(pluginPath, "package.json");
@@ -194,7 +197,10 @@ async function getSkillCodeSafetySummary(params: {
       dirPath: params.dirPath,
       summaryCache: params.summaryCache,
     }),
-    fs.readFile(params.skillFilePath, "utf-8"),
+    readRegularFile({
+      filePath: params.skillFilePath,
+      maxBytes: MAX_SKILL_AUDIT_FILE_BYTES,
+    }).then(({ buffer }) => buffer.toString("utf-8")),
     loadSkillScannerModule(),
   ]);
   const skillFindings = [

From a941d3ab727e3f0d789f51dd6abfb8c433bcdee6 Mon Sep 17 00:00:00 2001
From: tzy-17 <tang.ziyi@xydigit.com>
Date: Sat, 18 Jul 2026 17:44:31 +0800
Subject: [PATCH 12/76] fix(shared): reject HTTP status codes outside the
 100-599 range (#110554)

* fix(shared): reject HTTP status codes outside the 100-599 range

extractHttpStatusMatch only checked Number.isFinite, so 3-digit
sequences such as "000", "099", "600", and "999" were accepted as
valid HTTP statuses. Downstream code then surfaced them as "HTTP 0"
in user-visible messages and fed them into retry/classification
branches (e.g. isCloudflareOrHtmlErrorPage checks `code < 500` and
`code < 600`). Restrict the extracted code to the IANA HTTP status
code range (100-599).

Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>

* fix(shared): validate all parsed HTTP status prefixes

---------

Co-authored-by: Patrick Erichsen <patrick.a.erichsen@gmail.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/shared/assistant-error-format.test.ts | 87 +++++++++++++++++++++++
 src/shared/assistant-error-format.ts      | 18 +++--
 2 files changed, 95 insertions(+), 10 deletions(-)
 create mode 100644 src/shared/assistant-error-format.test.ts

diff --git a/src/shared/assistant-error-format.test.ts b/src/shared/assistant-error-format.test.ts
new file mode 100644
index 00000000000..85d8f76a2e1
--- /dev/null
+++ b/src/shared/assistant-error-format.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import {
+  extractLeadingHttpStatus,
+  extractProviderWrappedHttpStatus,
+  formatRawAssistantErrorForUi,
+  parseApiErrorInfo,
+} from "./assistant-error-format.js";
+
+describe("extractLeadingHttpStatus", () => {
+  it("accepts status codes in the valid HTTP range 100-599", () => {
+    expect(extractLeadingHttpStatus("100 everything is fine")).toEqual({
+      code: 100,
+      rest: "everything is fine",
+    });
+    expect(extractLeadingHttpStatus("500 internal error")).toEqual({
+      code: 500,
+      rest: "internal error",
+    });
+    expect(extractLeadingHttpStatus("599 something rest")).toEqual({
+      code: 599,
+      rest: "something rest",
+    });
+  });
+
+  it("rejects 3-digit sequences outside the HTTP status code range", () => {
+    // 000 / 099 / 999 / 600 — the regex would capture these as 3-digit
+    // numbers, but they are not valid HTTP statuses and should not be
+    // surfaced as "HTTP <code>" in user-visible messages or in retry
+    // classification.
+    expect(extractLeadingHttpStatus("000 something")).toBeNull();
+    expect(extractLeadingHttpStatus("099 something")).toBeNull();
+    expect(extractLeadingHttpStatus("600 something")).toBeNull();
+    expect(extractLeadingHttpStatus("999 something")).toBeNull();
+  });
+
+  it("rejects strings that do not start with a 3-digit HTTP status", () => {
+    expect(extractLeadingHttpStatus("no status here")).toBeNull();
+    expect(extractLeadingHttpStatus("")).toBeNull();
+  });
+});
+
+describe("extractProviderWrappedHttpStatus", () => {
+  it("accepts provider-wrapped statuses inside the valid HTTP range", () => {
+    expect(extractProviderWrappedHttpStatus("OpenAI API error (503): service down")).toEqual({
+      code: 503,
+      rest: "service down",
+    });
+    expect(extractProviderWrappedHttpStatus("API error (429): rate limited")).toEqual({
+      code: 429,
+      rest: "rate limited",
+    });
+  });
+
+  it("rejects provider-wrapped statuses outside the valid HTTP range", () => {
+    expect(extractProviderWrappedHttpStatus("API error (000): something")).toBeNull();
+    expect(extractProviderWrappedHttpStatus("API error (999): something")).toBeNull();
+    expect(extractProviderWrappedHttpStatus("API error (600): something")).toBeNull();
+  });
+});
+
+describe("HTTP status consumers", () => {
+  it("formats only status lines inside the HTTP range", () => {
+    expect(formatRawAssistantErrorForUi("100 Continue")).toBe("HTTP 100: Continue");
+    expect(formatRawAssistantErrorForUi("599 Provider Error")).toBe("HTTP 599: Provider Error");
+    expect(formatRawAssistantErrorForUi("000 Invalid")).toBe("000 Invalid");
+    expect(formatRawAssistantErrorForUi("600 Invalid")).toBe("600 Invalid");
+    expect(formatRawAssistantErrorForUi("999 Invalid")).toBe("999 Invalid");
+  });
+
+  it("does not attach invalid status prefixes to API payloads", () => {
+    const payload = '{"type":"error","error":{"type":"server_error","message":"Provider failed."}}';
+
+    expect(parseApiErrorInfo(`599 ${payload}`)).toMatchObject({
+      httpCode: "599",
+      type: "server_error",
+      message: "Provider failed.",
+    });
+    expect(formatRawAssistantErrorForUi(`599 ${payload}`)).toBe(
+      "HTTP 599 server_error: Provider failed.",
+    );
+
+    for (const code of ["000", "600", "999"]) {
+      expect(parseApiErrorInfo(`${code} ${payload}`)).toBeNull();
+      expect(formatRawAssistantErrorForUi(`${code} ${payload}`)).toBe(`${code} ${payload}`);
+    }
+  });
+});
diff --git a/src/shared/assistant-error-format.ts b/src/shared/assistant-error-format.ts
index 46a30479a41..5ed7532a862 100644
--- a/src/shared/assistant-error-format.ts
+++ b/src/shared/assistant-error-format.ts
@@ -1,4 +1,3 @@
-import { expectDefined } from "@openclaw/normalization-core";
 // Assistant error formatting helpers normalize assistant-visible error payloads.
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 const ERROR_PAYLOAD_PREFIX_RE =
@@ -107,7 +106,7 @@ function extractHttpStatusMatch(
     return null;
   }
   const code = Number(match[1]);
-  if (!Number.isFinite(code)) {
+  if (!Number.isInteger(code) || code < 100 || code > 599) {
     return null;
   }
   return { code, rest: (match[2] ?? "").trim() };
@@ -174,10 +173,10 @@ export function parseApiErrorInfo(raw?: string): ApiErrorInfo | null {
   let httpCode: string | undefined;
   let candidate = trimmed;
 
-  const httpPrefixMatch = candidate.match(/^(\d{3})\s+(.+)$/s);
-  if (httpPrefixMatch) {
-    httpCode = httpPrefixMatch[1];
-    candidate = expectDefined(httpPrefixMatch[2], "http prefix match capture group 2").trim();
+  const httpPrefix = extractHttpStatusMatch(candidate.match(/^(\d{3})\s+(.+)$/s));
+  if (httpPrefix) {
+    httpCode = String(httpPrefix.code);
+    candidate = httpPrefix.rest;
   }
 
   const payload = parseApiErrorPayload(candidate);
@@ -249,11 +248,10 @@ export function formatRawAssistantErrorForUi(raw?: string): string {
     );
   }
 
-  const httpMatch = trimmed.match(HTTP_STATUS_PREFIX_RE);
+  const httpMatch = extractHttpStatusMatch(trimmed.match(HTTP_STATUS_PREFIX_RE));
   if (httpMatch) {
-    const rest = expectDefined(httpMatch[2], "http match capture group 2").trim();
-    if (!rest.startsWith("{")) {
-      return `HTTP ${httpMatch[1]}: ${rest}`;
+    if (!httpMatch.rest.startsWith("{")) {
+      return `HTTP ${httpMatch.code}: ${httpMatch.rest}`;
     }
   }
 

From 7752e33f799e7d207aca195a2f1ad835541c5958 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 18 Jul 2026 02:40:37 -0700
Subject: [PATCH 13/76] Revert "fix(security): restore fs import lost in
 bounded manifest-read merge"

This reverts commit 39528edd745a484457e2add67155f611b2f7da5b.

That push was an accident: the fs-import fix it described had already landed
on main, and a rebase reduced the commit to unrelated in-progress
gateway-protocol schema edits (nodes/session-placement) that were staged in
the pushing worktree and belong to another work stream. Restore the reviewed
main state; the protocol work can land through its own PR.
---
 .../gateway-protocol/src/schema/nodes.test.ts |  34 +++++
 packages/gateway-protocol/src/schema/nodes.ts |  17 +--
 .../src/schema/session-placement.test.ts      |  24 ++++
 .../src/schema/session-placement.ts           | 128 +++++++-----------
 4 files changed, 116 insertions(+), 87 deletions(-)
 create mode 100644 packages/gateway-protocol/src/schema/nodes.test.ts

diff --git a/packages/gateway-protocol/src/schema/nodes.test.ts b/packages/gateway-protocol/src/schema/nodes.test.ts
new file mode 100644
index 00000000000..5735413cc91
--- /dev/null
+++ b/packages/gateway-protocol/src/schema/nodes.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { validateNodeInvokeProgressParams } from "../index.js";
+
+describe("node protocol schemas", () => {
+  it("accepts bounded progress chunks and rejects extra fields", () => {
+    expect(
+      validateNodeInvokeProgressParams({
+        invokeId: "invoke-1",
+        nodeId: "node-1",
+        seq: 0,
+        chunk: "stdout line",
+      }),
+    ).toBe(true);
+
+    expect(
+      validateNodeInvokeProgressParams({
+        invokeId: "invoke-1",
+        nodeId: "node-1",
+        seq: 0,
+        chunk: "x".repeat(16 * 1024 + 1),
+      }),
+    ).toBe(false);
+
+    expect(
+      validateNodeInvokeProgressParams({
+        invokeId: "invoke-1",
+        nodeId: "node-1",
+        seq: 0,
+        chunk: "stdout line",
+        extra: "not allowed",
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/packages/gateway-protocol/src/schema/nodes.ts b/packages/gateway-protocol/src/schema/nodes.ts
index 40e8ce9fea5..47fd1a300ec 100644
--- a/packages/gateway-protocol/src/schema/nodes.ts
+++ b/packages/gateway-protocol/src/schema/nodes.ts
@@ -164,16 +164,13 @@ export const NodeInvokeResultParamsSchema = closedObject({
 });
 
 /** Ordered UTF-8 output emitted while a node command invocation is running. */
-export const NodeInvokeProgressParamsSchema = Type.Object(
-  {
-    invokeId: NonEmptyString,
-    nodeId: NonEmptyString,
-    seq: Type.Integer({ minimum: 0 }),
-    // Empty chunks are liveness heartbeats for captured stderr or capped stdout.
-    chunk: Type.String({ maxLength: 16 * 1024 }),
-  },
-  { additionalProperties: false },
-);
+export const NodeInvokeProgressParamsSchema = closedObject({
+  invokeId: NonEmptyString,
+  nodeId: NonEmptyString,
+  seq: Type.Integer({ minimum: 0 }),
+  // Empty chunks are liveness heartbeats for captured stderr or capped stdout.
+  chunk: Type.String({ maxLength: 16 * 1024 }),
+});
 
 /** Generic node event envelope accepted by the gateway. */
 export const NodeEventParamsSchema = closedObject({
diff --git a/packages/gateway-protocol/src/schema/session-placement.test.ts b/packages/gateway-protocol/src/schema/session-placement.test.ts
index 8943d06e094..789b72bb629 100644
--- a/packages/gateway-protocol/src/schema/session-placement.test.ts
+++ b/packages/gateway-protocol/src/schema/session-placement.test.ts
@@ -282,4 +282,28 @@ describe("session dispatch protocol schemas", () => {
       }),
     ).toBe(false);
   });
+
+  it("rejects extra fields in dispatch params and results", () => {
+    const active = {
+      state: "active" as const,
+      ...basePlacement,
+      ...workerOwnedFields,
+    };
+    expect(
+      validateSessionsDispatchResult({
+        ok: true,
+        key: "agent:main:dispatch",
+        sessionId: "session-1",
+        placement: active,
+        extra: true,
+      }),
+    ).toBe(false);
+    expect(
+      validateSessionsDispatchParams({
+        key: "agent:main:dispatch",
+        profileId: "development",
+        extra: true,
+      }),
+    ).toBe(false);
+  });
 });
diff --git a/packages/gateway-protocol/src/schema/session-placement.ts b/packages/gateway-protocol/src/schema/session-placement.ts
index 65ff59e7989..34acbab4ff7 100644
--- a/packages/gateway-protocol/src/schema/session-placement.ts
+++ b/packages/gateway-protocol/src/schema/session-placement.ts
@@ -1,5 +1,6 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
+import { closedObject } from "./closed-object.js";
 import { NonEmptyString } from "./primitives.js";
 import { SESSION_PLACEMENT_STATES } from "./session-placement-state.js";
 
@@ -77,85 +78,64 @@ const TerminalSessionPlacementProperties = {
 function createUnownedSessionPlacementSchema<const State extends "local" | "requested">(
   state: State,
 ) {
-  return Type.Object(
-    { state: Type.Literal(state), ...SessionPlacementTimingProperties },
-    { additionalProperties: false },
-  );
+  return closedObject({ state: Type.Literal(state), ...SessionPlacementTimingProperties });
 }
 
 function createWorkerOwnedSessionPlacementSchema<
   const State extends "active" | "draining" | "reconciling",
 >(state: State) {
-  return Type.Object(
-    {
-      state: Type.Literal(state),
-      ...SessionPlacementTimingProperties,
-      environmentId: NonEmptyString,
-      activeOwnerEpoch: SessionPlacementOwnerEpochSchema,
-      workerBundleHash: WorkerBundleHashSchema,
-      ...SessionPlacementWorkspaceProperties,
-      ...SessionPlacementAckProperties,
-    },
-    { additionalProperties: false },
-  );
+  return closedObject({
+    state: Type.Literal(state),
+    ...SessionPlacementTimingProperties,
+    environmentId: NonEmptyString,
+    activeOwnerEpoch: SessionPlacementOwnerEpochSchema,
+    workerBundleHash: WorkerBundleHashSchema,
+    ...SessionPlacementWorkspaceProperties,
+    ...SessionPlacementAckProperties,
+  });
 }
 
 export const LocalSessionPlacementSchema = createUnownedSessionPlacementSchema("local");
 export const RequestedSessionPlacementSchema = createUnownedSessionPlacementSchema("requested");
 
-export const ProvisioningSessionPlacementSchema = Type.Object(
-  {
-    state: Type.Literal("provisioning"),
-    ...SessionPlacementTimingProperties,
-    environmentId: Type.Optional(NonEmptyString),
-  },
-  { additionalProperties: false },
-);
+export const ProvisioningSessionPlacementSchema = closedObject({
+  state: Type.Literal("provisioning"),
+  ...SessionPlacementTimingProperties,
+  environmentId: Type.Optional(NonEmptyString),
+});
 
-export const SyncingSessionPlacementSchema = Type.Object(
-  {
-    state: Type.Literal("syncing"),
-    ...SessionPlacementTimingProperties,
-    environmentId: NonEmptyString,
-    workerBundleHash: WorkerBundleHashSchema,
-  },
-  { additionalProperties: false },
-);
+export const SyncingSessionPlacementSchema = closedObject({
+  state: Type.Literal("syncing"),
+  ...SessionPlacementTimingProperties,
+  environmentId: NonEmptyString,
+  workerBundleHash: WorkerBundleHashSchema,
+});
 
-export const StartingSessionPlacementSchema = Type.Object(
-  {
-    state: Type.Literal("starting"),
-    ...SessionPlacementTimingProperties,
-    environmentId: NonEmptyString,
-    workerBundleHash: WorkerBundleHashSchema,
-    ...SessionPlacementWorkspaceProperties,
-  },
-  { additionalProperties: false },
-);
+export const StartingSessionPlacementSchema = closedObject({
+  state: Type.Literal("starting"),
+  ...SessionPlacementTimingProperties,
+  environmentId: NonEmptyString,
+  workerBundleHash: WorkerBundleHashSchema,
+  ...SessionPlacementWorkspaceProperties,
+});
 
 export const ActiveWorkerSessionPlacementSchema = createWorkerOwnedSessionPlacementSchema("active");
 export const DrainingSessionPlacementSchema = createWorkerOwnedSessionPlacementSchema("draining");
 export const ReconcilingSessionPlacementSchema =
   createWorkerOwnedSessionPlacementSchema("reconciling");
 
-export const ReclaimedSessionPlacementSchema = Type.Object(
-  {
-    state: Type.Literal("reclaimed"),
-    ...SessionPlacementTimingProperties,
-    ...TerminalSessionPlacementProperties,
-  },
-  { additionalProperties: false },
-);
+export const ReclaimedSessionPlacementSchema = closedObject({
+  state: Type.Literal("reclaimed"),
+  ...SessionPlacementTimingProperties,
+  ...TerminalSessionPlacementProperties,
+});
 
-export const FailedSessionPlacementSchema = Type.Object(
-  {
-    state: Type.Literal("failed"),
-    ...SessionPlacementTimingProperties,
-    ...TerminalSessionPlacementProperties,
-    recoveryError: NonEmptyString,
-  },
-  { additionalProperties: false },
-);
+export const FailedSessionPlacementSchema = closedObject({
+  state: Type.Literal("failed"),
+  ...SessionPlacementTimingProperties,
+  ...TerminalSessionPlacementProperties,
+  recoveryError: NonEmptyString,
+});
 
 /** Gateway-visible placement projection; `state` remains the closed discriminator. */
 export const SessionPlacementSchema = Type.Union([
@@ -172,25 +152,19 @@ export const SessionPlacementSchema = Type.Union([
 ]);
 
 /** Requests one-way dispatch of an existing local session to a configured worker profile. */
-export const SessionsDispatchParamsSchema = Type.Object(
-  {
-    key: NonEmptyString,
-    agentId: Type.Optional(NonEmptyString),
-    profileId: NonEmptyString,
-  },
-  { additionalProperties: false },
-);
+export const SessionsDispatchParamsSchema = closedObject({
+  key: NonEmptyString,
+  agentId: Type.Optional(NonEmptyString),
+  profileId: NonEmptyString,
+});
 
 /** Result returned once session dispatch reaches durable worker ownership. */
-export const SessionsDispatchResultSchema = Type.Object(
-  {
-    ok: Type.Literal(true),
-    key: NonEmptyString,
-    sessionId: NonEmptyString,
-    placement: ActiveWorkerSessionPlacementSchema,
-  },
-  { additionalProperties: false },
-);
+export const SessionsDispatchResultSchema = closedObject({
+  ok: Type.Literal(true),
+  key: NonEmptyString,
+  sessionId: NonEmptyString,
+  placement: ActiveWorkerSessionPlacementSchema,
+});
 
 /** Requests safe workspace reconciliation and teardown of an active cloud worker. */
 export const SessionsReclaimParamsSchema = Type.Object(

From fcdf06ed29449355fa636566a30b27416327eaab Mon Sep 17 00:00:00 2001
From: zengLingbiao <zeng.lingbiao@xydigit.com>
Date: Sat, 18 Jul 2026 17:49:53 +0800
Subject: [PATCH 14/76] fix(config): ignore inherited keys when restoring env
 refs (#109463)

* fix(config): use Object.hasOwn in restoreEnvVarRefs to avoid prototype pollution

When key comes from Object.entries(incoming) on user config data,
'key in parsed' traverses the prototype chain. If a config key
collides with an Object.prototype property (e.g. 'toString'),
the check incorrectly returns true and calls restoreEnvVarRefs
with a prototype function instead of a config value.

Replace with Object.hasOwn(parsed, key) to check only own properties.

* test(config): prove inherited env refs are ignored

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 src/config/env-preserve.test.ts | 12 ++++++++++++
 src/config/env-preserve.ts      |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/config/env-preserve.test.ts b/src/config/env-preserve.test.ts
index 3053cb2de6c..a41f1273f5d 100644
--- a/src/config/env-preserve.test.ts
+++ b/src/config/env-preserve.test.ts
@@ -833,4 +833,16 @@ describe("restoreEnvVarRefs", () => {
       resolved: "${MY_TOKEN}", // should restore ref
     });
   });
+
+  it("does not restore env refs from inherited parsed properties", () => {
+    // isPlainObject accepts custom prototypes, but only own properties represent authored config.
+    const parsed = Object.create({
+      toString: "${TEST_VALUE}",
+    }) as Record<string, unknown>;
+    const testEnv = { TEST_VALUE: "resolved-value" } as unknown as NodeJS.ProcessEnv;
+
+    expect(restoreEnvVarRefs({ toString: "resolved-value" }, parsed, testEnv)).toEqual({
+      toString: "resolved-value",
+    });
+  });
 });
diff --git a/src/config/env-preserve.ts b/src/config/env-preserve.ts
index b56a514db9f..fae54c623f3 100644
--- a/src/config/env-preserve.ts
+++ b/src/config/env-preserve.ts
@@ -820,7 +820,7 @@ export function restoreEnvVarRefs(
   if (isPlainObject(incoming) && isPlainObject(parsed)) {
     const result: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(incoming)) {
-      if (key in parsed) {
+      if (Object.hasOwn(parsed, key)) {
         result[key] = restoreEnvVarRefs(value, parsed[key], env);
       } else {
         // New key added by caller — keep as-is

From a068d38b663e28a8c5f0731699c935ba9c0ad14c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 10:56:37 +0100
Subject: [PATCH 15/76] refactor(plugins)!: remove experimental workspaces
 plugin (#110416)

* refactor(plugins)!: remove experimental workspaces plugin

* fix(doctor): remove retired workspaces plugin state

* refactor(doctor): settle retired-workspaces cleanup before legacy-state detect

* chore(i18n): leave workflow-owned locale artifacts to the locale refresh

* ci: retrigger after GitHub scheduling outage
---
 .github/labeler.yml                           |    5 -
 config/max-lines-baseline.txt                 |    3 -
 docs/docs.json                                |    1 -
 docs/docs_map.md                              |   20 -
 docs/plugins/plugin-inventory.md              |    4 +-
 docs/plugins/reference.md                     |    2 +-
 docs/plugins/reference/workspaces.md          |   19 -
 docs/web/workspaces.md                        |  132 --
 extensions/workspaces/index.ts                |   81 --
 extensions/workspaces/openclaw.plugin.json    |   35 -
 extensions/workspaces/package.json            |   27 -
 .../workspaces/src/asset-tokens.test.ts       |   23 -
 extensions/workspaces/src/asset-tokens.ts     |   61 -
 extensions/workspaces/src/binding-contract.ts |   71 --
 extensions/workspaces/src/broadcast.ts        |   27 -
 .../workspaces/src/cli-registration.test.ts   |   35 -
 extensions/workspaces/src/cli.test.ts         |  427 -------
 extensions/workspaces/src/cli.ts              |  509 --------
 extensions/workspaces/src/data-read.test.ts   |  162 ---
 extensions/workspaces/src/data-read.ts        |  167 ---
 .../workspaces/src/default-workspace.test.ts  |   61 -
 .../workspaces/src/default-workspace.ts       |  108 --
 extensions/workspaces/src/gateway.test.ts     |  297 -----
 extensions/workspaces/src/gateway.ts          |  838 -------------
 extensions/workspaces/src/http-route.ts       |   32 -
 extensions/workspaces/src/manifest.test.ts    |  215 ----
 extensions/workspaces/src/manifest.ts         |  369 ------
 extensions/workspaces/src/scaffold.test.ts    |   32 -
 extensions/workspaces/src/scaffold.ts         |  177 ---
 extensions/workspaces/src/schema.test.ts      |  164 ---
 extensions/workspaces/src/schema.ts           |  476 --------
 extensions/workspaces/src/serve.test.ts       |  435 -------
 extensions/workspaces/src/serve.ts            |  296 -----
 extensions/workspaces/src/store.test.ts       |  339 ------
 extensions/workspaces/src/store.ts            |  313 -----
 extensions/workspaces/src/tools.test.ts       |  422 -------
 extensions/workspaces/src/tools.ts            |  919 --------------
 .../src/ui-gateway-integration.test.ts        |  251 ----
 pnpm-lock.yaml                                |   13 -
 src/flows/doctor-core-checks.ts               |    4 +-
 src/flows/doctor-health-contributions.test.ts |    8 +-
 src/flows/doctor-health-contributions.ts      |    5 +-
 ...tor-removed-workspaces-state-check.test.ts |   85 ++
 .../doctor-removed-workspaces-state-check.ts  |   72 ++
 src/plugins/bundled-plugin-metadata.test.ts   |    1 -
 .../workspace-custom-widget.test.ts           |  339 ------
 ui/src/components/workspace-custom-widget.ts  |  360 ------
 .../components/workspace-widget-cell.test.ts  |  173 ---
 ui/src/components/workspace-widget-cell.ts    |  393 ------
 ui/src/e2e/workspace-chart.e2e.test.ts        |  131 --
 .../e2e/workspace-custom-widget.e2e.test.ts   |  495 --------
 ui/src/e2e/workspace-full-bleed.e2e.test.ts   |  135 ---
 ui/src/e2e/workspace-operations.e2e.test.ts   |  193 ---
 ui/src/e2e/workspace-preview.e2e.test.ts      |  147 ---
 ui/src/i18n/locales/en.ts                     |  127 --
 ui/src/lib/workspace/approval-state.ts        |   13 -
 ui/src/lib/workspace/bridge.test.ts           |  363 ------
 ui/src/lib/workspace/bridge.ts                |  326 -----
 ui/src/lib/workspace/grid.test.ts             |   91 --
 ui/src/lib/workspace/grid.ts                  |  230 ----
 ui/src/lib/workspace/index.test.ts            |  872 -------------
 ui/src/lib/workspace/index.ts                 |  838 -------------
 ui/src/lib/workspace/tab-selection.ts         |   73 --
 ui/src/lib/workspace/types.ts                 |  118 --
 ui/src/lib/workspace/widgets/activity.ts      |   93 --
 ui/src/lib/workspace/widgets/agent-status.ts  |  122 --
 ui/src/lib/workspace/widgets/chart.ts         |  275 -----
 ui/src/lib/workspace/widgets/cron.ts          |   93 --
 .../widgets/custom-widget-approvals.ts        |  120 --
 ui/src/lib/workspace/widgets/iframe-embed.ts  |  120 --
 ui/src/lib/workspace/widgets/index.ts         |   43 -
 ui/src/lib/workspace/widgets/instances.ts     |  101 --
 ui/src/lib/workspace/widgets/markdown.ts      |   36 -
 ui/src/lib/workspace/widgets/preview.ts       |  105 --
 ui/src/lib/workspace/widgets/sessions.ts      |   94 --
 ui/src/lib/workspace/widgets/stat-card.ts     |   80 --
 ui/src/lib/workspace/widgets/table.ts         |  103 --
 ui/src/lib/workspace/widgets/types.ts         |   73 --
 ui/src/lib/workspace/widgets/usage.ts         |   38 -
 ui/src/lib/workspace/widgets/widgets.test.ts  |  585 ---------
 ui/src/pages/plugin/plugin-page.test.ts       |   35 +-
 ui/src/pages/plugin/plugin-page.ts            |    9 -
 .../pages/plugin/workspace-controller.test.ts |   23 -
 ui/src/pages/plugin/workspace-controller.ts   |   15 -
 ui/src/pages/plugin/workspace-view.test.ts    |  519 --------
 ui/src/pages/plugin/workspace-view.ts         | 1080 -----------------
 ui/src/styles/workspace.css                   | 1043 ----------------
 87 files changed, 188 insertions(+), 17777 deletions(-)
 delete mode 100644 docs/plugins/reference/workspaces.md
 delete mode 100644 docs/web/workspaces.md
 delete mode 100644 extensions/workspaces/index.ts
 delete mode 100644 extensions/workspaces/openclaw.plugin.json
 delete mode 100644 extensions/workspaces/package.json
 delete mode 100644 extensions/workspaces/src/asset-tokens.test.ts
 delete mode 100644 extensions/workspaces/src/asset-tokens.ts
 delete mode 100644 extensions/workspaces/src/binding-contract.ts
 delete mode 100644 extensions/workspaces/src/broadcast.ts
 delete mode 100644 extensions/workspaces/src/cli-registration.test.ts
 delete mode 100644 extensions/workspaces/src/cli.test.ts
 delete mode 100644 extensions/workspaces/src/cli.ts
 delete mode 100644 extensions/workspaces/src/data-read.test.ts
 delete mode 100644 extensions/workspaces/src/data-read.ts
 delete mode 100644 extensions/workspaces/src/default-workspace.test.ts
 delete mode 100644 extensions/workspaces/src/default-workspace.ts
 delete mode 100644 extensions/workspaces/src/gateway.test.ts
 delete mode 100644 extensions/workspaces/src/gateway.ts
 delete mode 100644 extensions/workspaces/src/http-route.ts
 delete mode 100644 extensions/workspaces/src/manifest.test.ts
 delete mode 100644 extensions/workspaces/src/manifest.ts
 delete mode 100644 extensions/workspaces/src/scaffold.test.ts
 delete mode 100644 extensions/workspaces/src/scaffold.ts
 delete mode 100644 extensions/workspaces/src/schema.test.ts
 delete mode 100644 extensions/workspaces/src/schema.ts
 delete mode 100644 extensions/workspaces/src/serve.test.ts
 delete mode 100644 extensions/workspaces/src/serve.ts
 delete mode 100644 extensions/workspaces/src/store.test.ts
 delete mode 100644 extensions/workspaces/src/store.ts
 delete mode 100644 extensions/workspaces/src/tools.test.ts
 delete mode 100644 extensions/workspaces/src/tools.ts
 delete mode 100644 extensions/workspaces/src/ui-gateway-integration.test.ts
 create mode 100644 src/flows/doctor-removed-workspaces-state-check.test.ts
 create mode 100644 src/flows/doctor-removed-workspaces-state-check.ts
 delete mode 100644 ui/src/components/workspace-custom-widget.test.ts
 delete mode 100644 ui/src/components/workspace-custom-widget.ts
 delete mode 100644 ui/src/components/workspace-widget-cell.test.ts
 delete mode 100644 ui/src/components/workspace-widget-cell.ts
 delete mode 100644 ui/src/e2e/workspace-chart.e2e.test.ts
 delete mode 100644 ui/src/e2e/workspace-custom-widget.e2e.test.ts
 delete mode 100644 ui/src/e2e/workspace-full-bleed.e2e.test.ts
 delete mode 100644 ui/src/e2e/workspace-operations.e2e.test.ts
 delete mode 100644 ui/src/e2e/workspace-preview.e2e.test.ts
 delete mode 100644 ui/src/lib/workspace/approval-state.ts
 delete mode 100644 ui/src/lib/workspace/bridge.test.ts
 delete mode 100644 ui/src/lib/workspace/bridge.ts
 delete mode 100644 ui/src/lib/workspace/grid.test.ts
 delete mode 100644 ui/src/lib/workspace/grid.ts
 delete mode 100644 ui/src/lib/workspace/index.test.ts
 delete mode 100644 ui/src/lib/workspace/index.ts
 delete mode 100644 ui/src/lib/workspace/tab-selection.ts
 delete mode 100644 ui/src/lib/workspace/types.ts
 delete mode 100644 ui/src/lib/workspace/widgets/activity.ts
 delete mode 100644 ui/src/lib/workspace/widgets/agent-status.ts
 delete mode 100644 ui/src/lib/workspace/widgets/chart.ts
 delete mode 100644 ui/src/lib/workspace/widgets/cron.ts
 delete mode 100644 ui/src/lib/workspace/widgets/custom-widget-approvals.ts
 delete mode 100644 ui/src/lib/workspace/widgets/iframe-embed.ts
 delete mode 100644 ui/src/lib/workspace/widgets/index.ts
 delete mode 100644 ui/src/lib/workspace/widgets/instances.ts
 delete mode 100644 ui/src/lib/workspace/widgets/markdown.ts
 delete mode 100644 ui/src/lib/workspace/widgets/preview.ts
 delete mode 100644 ui/src/lib/workspace/widgets/sessions.ts
 delete mode 100644 ui/src/lib/workspace/widgets/stat-card.ts
 delete mode 100644 ui/src/lib/workspace/widgets/table.ts
 delete mode 100644 ui/src/lib/workspace/widgets/types.ts
 delete mode 100644 ui/src/lib/workspace/widgets/usage.ts
 delete mode 100644 ui/src/lib/workspace/widgets/widgets.test.ts
 delete mode 100644 ui/src/pages/plugin/workspace-controller.test.ts
 delete mode 100644 ui/src/pages/plugin/workspace-controller.ts
 delete mode 100644 ui/src/pages/plugin/workspace-view.test.ts
 delete mode 100644 ui/src/pages/plugin/workspace-view.ts
 delete mode 100644 ui/src/styles/workspace.css

diff --git a/.github/labeler.yml b/.github/labeler.yml
index a448dc25c9b..b926f4827f9 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -70,11 +70,6 @@
           - "extensions/workboard/**"
           - "docs/plugins/workboard.md"
           - "docs/plugins/reference/workboard.md"
-"plugin: workspaces":
-  - changed-files:
-      - any-glob-to-any-file:
-          - "extensions/workspaces/**"
-          - "docs/web/workspaces.md"
 "plugin: migrate-hermes":
   - changed-files:
       - any-glob-to-any-file:
diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 3364cfb8bf7..433a2aa64af 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -339,8 +339,6 @@ extensions/workboard/src/store-core.ts
 extensions/workboard/src/store-normalizers.ts
 extensions/workboard/src/store.test.ts
 extensions/workboard/src/tools.ts
-extensions/workspaces/src/gateway.ts
-extensions/workspaces/src/tools.ts
 extensions/xai/realtime-voice-provider.test.ts
 extensions/xai/web-search.test.ts
 extensions/zalo/src/monitor.ts
@@ -1155,7 +1153,6 @@ ui/src/pages/config/view.browser.test.ts
 ui/src/pages/config/view.ts
 ui/src/pages/cron/view.ts
 ui/src/pages/new-session/new-session-page.ts
-ui/src/pages/plugin/workspace-view.ts
 ui/src/pages/plugins/plugins-page.ts
 ui/src/pages/plugins/view.ts
 ui/src/pages/sessions/sessions-page.ts
diff --git a/docs/docs.json b/docs/docs.json
index c27d8c5de8e..4497d692185 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1750,7 +1750,6 @@
                 "pages": [
                   "web/index",
                   "web/control-ui",
-                  "web/workspaces",
                   "web/dashboard",
                   "web/webchat",
                   "web/tui",
diff --git a/docs/docs_map.md b/docs/docs_map.md
index d2aa5612e7b..4fd98d4a6a2 100644
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -7263,14 +7263,6 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H2: Surface
   - H2: Related docs
 
-## plugins/reference/workspaces.md
-
-- Route: /plugins/reference/workspaces
-- Headings:
-  - H1: Workspaces plugin
-  - H2: Distribution
-  - H2: Surface
-
 ## plugins/reference/xai.md
 
 - Route: /plugins/reference/xai
@@ -10612,15 +10604,3 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H2: Remote use
   - H2: Configuration reference (WebChat)
   - H2: Related
-
-## web/workspaces.md
-
-- Route: /web/workspaces
-- Headings:
-  - H2: Enable Workspaces
-  - H2: The default workspace
-  - H2: Built-in widgets
-  - H2: Provenance
-  - H2: Custom widgets
-  - H2: CLI
-  - H2: Storage
diff --git a/docs/plugins/plugin-inventory.md b/docs/plugins/plugin-inventory.md
index ebdc06d7e49..0f889677d34 100644
--- a/docs/plugins/plugin-inventory.md
+++ b/docs/plugins/plugin-inventory.md
@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Core npm package
 
-69 plugins
+68 plugins
 
 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.
 
@@ -185,8 +185,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[workboard](/plugins/reference/workboard)** (`@openclaw/workboard`) - included in OpenClaw. Dashboard workboard for agent-owned issues and sessions.
 
-- **[workspaces](/plugins/reference/workspaces)** (`@openclaw/workspaces-plugin`) - included in OpenClaw. Agent-composable Workspaces document and control-plane backend.
-
 - **[xai](/plugins/reference/xai)** (`@openclaw/xai-plugin`) - included in OpenClaw. Adds xAI model provider support to OpenClaw.
 
 - **[xiaomi](/plugins/reference/xiaomi)** (`@openclaw/xiaomi-provider`) - included in OpenClaw. Adds Xiaomi, Xiaomi Token Plan model provider support to OpenClaw.
diff --git a/docs/plugins/reference.md b/docs/plugins/reference.md
index 11258cad202..4d4ccfadaf3 100644
--- a/docs/plugins/reference.md
+++ b/docs/plugins/reference.md
@@ -15,5 +15,5 @@ This page is generated from `extensions/*/package.json` and
 pnpm plugins:inventory:gen
 ```
 
-Use [Plugin inventory](/plugins/plugin-inventory) to browse all 142
+Use [Plugin inventory](/plugins/plugin-inventory) to browse all 141
 generated plugin reference pages by distribution, package, and description.
diff --git a/docs/plugins/reference/workspaces.md b/docs/plugins/reference/workspaces.md
deleted file mode 100644
index 0014e2083f0..00000000000
--- a/docs/plugins/reference/workspaces.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-summary: "Agent-composable Workspaces document and control-plane backend."
-read_when:
-  - You are installing, configuring, or auditing the workspaces plugin
-title: "Workspaces plugin"
----
-
-# Workspaces plugin
-
-Agent-composable Workspaces document and control-plane backend.
-
-## Distribution
-
-- Package: `@openclaw/workspaces-plugin`
-- Install route: included in OpenClaw
-
-## Surface
-
-contracts: `tools`
diff --git a/docs/web/workspaces.md b/docs/web/workspaces.md
deleted file mode 100644
index 1cfcaa37295..00000000000
--- a/docs/web/workspaces.md
+++ /dev/null
@@ -1,132 +0,0 @@
----
-summary: "Agent-composable Workspaces in the Control UI"
-read_when:
-  - Building or rearranging workspace tabs and widgets
-  - Letting an agent compose a workspace
-  - Reviewing the custom-widget approval and sandbox model
-title: "Workspaces"
----
-
-The **Workspaces** tab in the [Control UI](/web/control-ui) is a surface you and your
-agents arrange together. Tabs, widgets, their positions on a 12-column grid, and their
-data bindings all live in one document. Anything that can edit that document can compose
-the workspace: you, the `openclaw workspaces` CLI, or an agent calling `workspace_*` tools.
-
-Every write goes through the same validated path, so a human's layout and an agent's
-layout cannot diverge. Each accepted write bumps a version and broadcasts
-`plugin.workspaces.changed`, so an agent's edit appears in an already-open browser without
-a reload.
-
-## Enable Workspaces
-
-The bundled Workspaces plugin is disabled by default. In the Control UI, open **Plugins**,
-find **Workspaces**, and select **Enable**. You can also enable it from the CLI:
-
-```sh
-openclaw plugins enable workspaces
-```
-
-Enabling the plugin adds the **Workspaces** tab and makes the `openclaw workspaces` CLI
-and `workspace_*` agent tools available. Disabling it removes those surfaces without
-deleting the workspace database or widget assets.
-
-## The default workspace
-
-On first load you get an **Overview** workspace: cost and token cards, instance health,
-sessions, cron status, and an activity feed. It is ordinary workspace content — drag it,
-collapse it, hide it, or delete it.
-
-## Built-in widgets
-
-Thirteen trusted widgets ship with the plugin and render as first-party UI:
-
-`stat-card`, `markdown`, `table`, `iframe-embed`, `sessions`, `usage`, `cron`,
-`instances`, `activity`, `chart`, `preview`, `agent-status`,
-`custom-widget-approvals`.
-
-The `chart` widget renders dependency-free inline SVG as `line`, `bar`, `area`,
-`sparkline`, or `gauge`. Bind `value` to a numeric array or to an object shaped like
-`{ "points": [1, { "y": 2 }, { "value": 3 }] }`. Set `props.type` to select the
-visual and optionally set finite numeric `props.min` and `props.max` bounds. Invalid
-types, bounds, points, and series longer than 500 entries render a safe error state;
-empty series render an empty state.
-
-The `preview` widget embeds a live page with reload plus desktop, tablet, and mobile
-viewport controls. Set `props.url`, or bind `value` to a URL when the preview target is
-data-driven; a binding takes precedence over the prop. Relative and same-origin HTTP(S)
-URLs are allowed. External HTTP(S) URLs follow the gateway's external-embed policy, and
-other schemes are blocked. Preview frames share the `iframe-embed` sandbox ceiling and
-never receive same-origin access.
-
-The `agent-status` widget presents the current Busy or Idle state from a
-`sessions.list` RPC binding. Session-list events refresh it immediately, while the normal
-visibility-gated binding poll remains a fallback. The `custom-widget-approvals` widget
-lists only pending entries from the Workspaces custom-widget registry. Its Approve and
-Reject controls are disabled unless the current connection holds `operator.approvals`;
-it does not expose exec, plugin, or system-agent approvals.
-
-Tabs use the 12-column widget grid by default. A tab containing zero or one widget can
-instead use the `full` layout, which removes the widget card chrome and lets the widget
-fill the tab. Switch layouts with `openclaw workspaces tabs full <slug>` and
-`openclaw workspaces tabs grid <slug>`.
-
-Widgets declare data through **bindings**, they never fetch on their own:
-
-| Binding  | Resolves to                                                                                               |
-| -------- | --------------------------------------------------------------------------------------------------------- |
-| `static` | A literal value stored in the document (8 KB max).                                                        |
-| `file`   | A JSON, Markdown, or CSV file under `<stateDir>/workspaces/data/`, optionally narrowed by a JSON pointer. |
-| `rpc`    | One of a fixed allowlist of read-only gateway methods, resolved by the trusted Control UI.                |
-
-The `file` binding is the simplest way to put your own numbers in a workspace: write a
-JSON file into the data directory and point a `stat-card` at it.
-
-## Provenance
-
-Tabs and widgets carry a `createdBy` stamp — `user`, `system`, or `agent:<id>` — set from
-whoever made the write. It cannot be supplied by the caller, so an agent cannot label its
-work as yours, and the "AI" chip on an agent-authored widget always means what it says.
-
-## Custom widgets
-
-An agent can author a real HTML widget with `workspace_widget_scaffold` (or you can, with
-`openclaw workspaces widget-scaffold <name>`). Agent-authored code is treated as hostile:
-
-- A scaffolded widget enters the registry as **pending**. No iframe is created, and the
-  asset route returns 404 for its files, until an operator approves it.
-- Approval is a separate decision from editing a layout: `workspaces.widget.approve`
-  requires the `operator.approvals` scope, the same scope that guards exec approvals.
-- An approved widget renders in an `<iframe sandbox="allow-scripts">` — never
-  `allow-same-origin` — so its origin is opaque and it cannot reach the parent's DOM,
-  storage, or cookies.
-- Its assets are served with `connect-src 'none'`, blocking script networking such as
-  `fetch`, XHR, and WebSockets. It holds no credential and never talks to the gateway.
-- Data reaches it only through a versioned `postMessage` bridge. Custom code can receive
-  declared `static` bindings, which are already agent- or operator-authored workspace
-  values. RPC and file bindings stay in trusted built-in widgets: browsers allow a
-  sandboxed child to navigate its own frame, so privileged data is never posted into
-  agent-authored HTML.
-
-Sending a prompt into chat from a widget additionally requires a manifest capability, a
-per-invocation confirmation quoting the exact text, and passes a rate limit.
-
-## CLI
-
-```sh
-openclaw workspaces tabs list
-openclaw workspaces tabs create --title Financials
-openclaw workspaces tabs full financials
-openclaw workspaces widget-scaffold revenue-chart --title "Revenue Chart"
-openclaw workspaces widget-approve revenue-chart
-```
-
-`widget-approve` and the Control UI decision controls both need a device paired with the
-`operator.approvals` scope.
-
-## Storage
-
-The workspace document, the custom-widget registry, and a 20-entry undo ring live in
-`<stateDir>/workspaces/workspaces.sqlite`. Agent-authored widget assets stay on disk under
-`<stateDir>/workspaces/widgets/<name>/`, and file-binding data under
-`<stateDir>/workspaces/data/`, because an agent authors those with ordinary file tools and
-the widget route serves their bytes.
diff --git a/extensions/workspaces/index.ts b/extensions/workspaces/index.ts
deleted file mode 100644
index c304c8e2699..00000000000
--- a/extensions/workspaces/index.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
-import { registerWorkspaceGatewayMethods } from "./src/gateway.js";
-import { createWidgetHttpRouteHandler, WIDGETS_ROUTE_PREFIX } from "./src/http-route.js";
-import { WorkspaceStore } from "./src/store.js";
-import { createWorkspaceTools } from "./src/tools.js";
-
-export default definePluginEntry({
-  id: "workspaces",
-  name: "Workspaces",
-  description: "Agent-composable Workspaces document and control-plane backend.",
-  register(api) {
-    const store = new WorkspaceStore();
-    registerWorkspaceGatewayMethods({ api, store });
-    api.registerCli(
-      async ({ program }) => {
-        const { registerWorkspaceCli } = await import("./src/cli.js");
-        registerWorkspaceCli({ program });
-      },
-      {
-        descriptors: [
-          {
-            // Core already owns `dashboard` for opening the Control UI. A plugin
-            // CLI group that overlaps a core command is silently skipped.
-            name: "workspaces",
-            description: "Manage Workspaces tabs and widgets",
-            hasSubcommands: true,
-          },
-        ],
-      },
-    );
-    api.registerTool((context) => createWorkspaceTools({ api, context, store }), {
-      names: [
-        "workspace_get",
-        "workspace_tab_create",
-        "workspace_tab_update",
-        "workspace_tab_delete",
-        "workspace_tabs_reorder",
-        "workspace_widget_add",
-        "workspace_widget_update",
-        "workspace_widget_move",
-        "workspace_widget_remove",
-        "workspace_layout_set",
-        "workspace_replace",
-        "workspace_widget_scaffold",
-        "workspace_undo",
-        "workspace_data_read",
-      ],
-      optional: true,
-    });
-
-    // Declares the Workspaces tab; the Control UI renders its bundled view
-    // (BUNDLED_TAB_VIEWS "workspaces/workspaces") only while this plugin is
-    // active, so no core code references the plugin id.
-    api.session.controls.registerControlUiDescriptor({
-      surface: "tab",
-      id: "workspaces",
-      label: "Workspaces",
-      description: "Composable workspaces you and your agents build together.",
-      icon: "puzzle",
-      group: "control",
-      order: -10,
-      requiredScopes: ["operator.read"],
-    });
-
-    // Sandboxed iframes cannot attach the gateway device token. The authenticated
-    // frame RPC mints a scoped capability for one approved content snapshot; the
-    // static route rejects every request without that capability.
-    const widgetRoute = createWidgetHttpRouteHandler({ store });
-    api.registerHttpRoute({
-      path: WIDGETS_ROUTE_PREFIX,
-      auth: "plugin",
-      match: "prefix",
-      handler: async (req: IncomingMessage, res: ServerResponse) =>
-        await widgetRoute.handleHttpRequest(req, res),
-    });
-
-    // L2/L5 wire tools, CLI, and HTTP routes through this same store
-    // instance so every caller shares one validated writer.
-  },
-});
diff --git a/extensions/workspaces/openclaw.plugin.json b/extensions/workspaces/openclaw.plugin.json
deleted file mode 100644
index 58210a1de8b..00000000000
--- a/extensions/workspaces/openclaw.plugin.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
-  "id": "workspaces",
-  "name": "Workspaces",
-  "description": "Agent-composable Workspaces document and control-plane backend.",
-  "enabledByDefault": false,
-  "activation": {
-    "onStartup": true,
-    "onCommands": [
-      "workspaces"
-    ]
-  },
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {}
-  },
-  "contracts": {
-    "tools": [
-      "workspace_get",
-      "workspace_tab_create",
-      "workspace_tab_update",
-      "workspace_tab_delete",
-      "workspace_tabs_reorder",
-      "workspace_widget_add",
-      "workspace_widget_update",
-      "workspace_widget_move",
-      "workspace_widget_remove",
-      "workspace_layout_set",
-      "workspace_replace",
-      "workspace_widget_scaffold",
-      "workspace_undo",
-      "workspace_data_read"
-    ]
-  }
-}
diff --git a/extensions/workspaces/package.json b/extensions/workspaces/package.json
deleted file mode 100644
index a48ee6cc46f..00000000000
--- a/extensions/workspaces/package.json
+++ /dev/null
@@ -1,27 +0,0 @@
-{
-  "name": "@openclaw/workspaces-plugin",
-  "version": "2026.7.2",
-  "private": true,
-  "description": "OpenClaw agent-composable Workspaces plugin",
-  "type": "module",
-  "dependencies": {
-    "typebox": "1.3.3"
-  },
-  "devDependencies": {
-    "@openclaw/plugin-sdk": "workspace:*",
-    "openclaw": "workspace:*"
-  },
-  "peerDependencies": {
-    "openclaw": ">=2026.7.2"
-  },
-  "peerDependenciesMeta": {
-    "openclaw": {
-      "optional": true
-    }
-  },
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ]
-  }
-}
diff --git a/extensions/workspaces/src/asset-tokens.test.ts b/extensions/workspaces/src/asset-tokens.test.ts
deleted file mode 100644
index 7dda37fbae4..00000000000
--- a/extensions/workspaces/src/asset-tokens.test.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { WidgetAssetTokens } from "./asset-tokens.js";
-
-describe("WidgetAssetTokens", () => {
-  it("scopes an unguessable token to one widget approval snapshot", () => {
-    const tokens = new WidgetAssetTokens();
-    const approved = { "index.html": "a".repeat(64) };
-    const token = tokens.issue("chart", approved);
-
-    expect(token).toMatch(/^[A-Za-z0-9_-]{40,}$/);
-    expect(tokens.allows(token, "chart", approved)).toBe(true);
-    expect(tokens.allows(token, "other", approved)).toBe(false);
-    expect(tokens.allows(token, "chart", { "index.html": "b".repeat(64) })).toBe(false);
-    expect(tokens.isIssued("not-a-token", "chart")).toBe(false);
-  });
-
-  it("issues distinct capabilities for repeated frame requests", () => {
-    const tokens = new WidgetAssetTokens();
-    const approved = { "index.html": "a".repeat(64) };
-
-    expect(tokens.issue("chart", approved)).not.toBe(tokens.issue("chart", approved));
-  });
-});
diff --git a/extensions/workspaces/src/asset-tokens.ts b/extensions/workspaces/src/asset-tokens.ts
deleted file mode 100644
index 0f465938d6e..00000000000
--- a/extensions/workspaces/src/asset-tokens.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-
-const TOKEN_TTL_MS = 12 * 60 * 60 * 1000;
-const MAX_TOKENS = 512;
-
-type TokenEntry = { name: string; approval: string; expiresAt: number };
-
-function approvalFingerprint(files: Record<string, string>): string {
-  const canonical = Object.entries(files).toSorted(([left], [right]) => left.localeCompare(right));
-  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
-}
-
-/** In-memory capabilities for one approved widget snapshot. Restart revokes all tokens. */
-export class WidgetAssetTokens {
-  private readonly tokens = new Map<string, TokenEntry>();
-
-  issue(name: string, approvedFiles: Record<string, string>): string {
-    const now = Date.now();
-    this.prune(now);
-    while (this.tokens.size >= MAX_TOKENS) {
-      const oldest = this.tokens.keys().next().value;
-      if (typeof oldest !== "string") {
-        break;
-      }
-      this.tokens.delete(oldest);
-    }
-    const token = randomBytes(32).toString("base64url");
-    this.tokens.set(token, {
-      name,
-      approval: approvalFingerprint(approvedFiles),
-      expiresAt: now + TOKEN_TTL_MS,
-    });
-    return token;
-  }
-
-  expiresAt(token: string, name: string): number | null {
-    return this.isIssued(token, name) ? (this.tokens.get(token)?.expiresAt ?? null) : null;
-  }
-
-  isIssued(token: string, name: string): boolean {
-    const entry = this.tokens.get(token);
-    if (!entry || entry.name !== name || entry.expiresAt <= Date.now()) {
-      this.tokens.delete(token);
-      return false;
-    }
-    return true;
-  }
-
-  allows(token: string, name: string, approvedFiles: Record<string, string>): boolean {
-    const entry = this.tokens.get(token);
-    return this.isIssued(token, name) && entry?.approval === approvalFingerprint(approvedFiles);
-  }
-
-  private prune(now: number): void {
-    for (const [token, entry] of this.tokens) {
-      if (entry.expiresAt <= now) {
-        this.tokens.delete(token);
-      }
-    }
-  }
-}
diff --git a/extensions/workspaces/src/binding-contract.ts b/extensions/workspaces/src/binding-contract.ts
deleted file mode 100644
index ef96e489fbe..00000000000
--- a/extensions/workspaces/src/binding-contract.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-// Leaf contract shared by write-time schema validation and resolve-time data reads.
-// Kept dependency-free so schema.ts and data-read.ts never import each other.
-import path from "node:path";
-
-export const DATA_READ_RPC_ALLOWLIST = [
-  "health",
-  "system-presence",
-  "usage.status",
-  "usage.cost",
-  "agents.list",
-  "sessions.list",
-  "sessions.resolve",
-  "sessions.get",
-  "sessions.usage",
-  "sessions.usage.timeseries",
-  "sessions.usage.logs",
-  "node.list",
-  "node.describe",
-  "cron.get",
-  "cron.list",
-  "cron.status",
-  "cron.runs",
-] as const;
-
-type WorkspaceBindingErrorCode =
-  | "binding_denied"
-  | "binding_not_found"
-  | "binding_too_large"
-  | "binding_invalid"
-  | "binding_client_resolved";
-
-export class WorkspaceBindingResolutionError extends Error {
-  constructor(
-    readonly code: WorkspaceBindingErrorCode,
-    message: string,
-  ) {
-    super(message);
-    this.name = "WorkspaceBindingResolutionError";
-  }
-}
-
-function hasControlCharacter(value: string): boolean {
-  for (const char of value) {
-    const code = char.charCodeAt(0);
-    if (code < 0x20 || code === 0x7f) {
-      return true;
-    }
-  }
-  return false;
-}
-
-export function normalizeWorkspaceDataLogicalPath(value: string): string {
-  if (
-    value.startsWith("/") ||
-    path.isAbsolute(value) ||
-    path.win32.isAbsolute(value) ||
-    hasControlCharacter(value)
-  ) {
-    throw new WorkspaceBindingResolutionError("binding_invalid", "file binding path is invalid");
-  }
-  const normalized = value.replaceAll("\\", "/");
-  const parts = normalized.split("/").filter(Boolean);
-  if (
-    parts.length === 0 ||
-    parts[0] === "~" ||
-    parts.some((part) => part === "." || part === ".." || part.includes(":"))
-  ) {
-    throw new WorkspaceBindingResolutionError("binding_invalid", "file binding path is invalid");
-  }
-  return parts.join("/");
-}
diff --git a/extensions/workspaces/src/broadcast.ts b/extensions/workspaces/src/broadcast.ts
deleted file mode 100644
index 10c2a0527a5..00000000000
--- a/extensions/workspaces/src/broadcast.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-// Single-slot handle for the gateway's broadcast function.
-//
-// Agent tools must be able to announce `plugin.workspaces.changed` so an open
-// Control UI live-updates. They cannot always reach one: the plugin runtime's
-// gateway-request scope is an AsyncLocalStorage set around gateway RPC handlers
-// and plugin HTTP routes only, so a tool call inside an agent turn that started
-// from a channel, cron, or heartbeat sees no scope and would silently skip the
-// broadcast — the edit lands on disk but no browser hears about it.
-//
-// `GatewayBroadcastFn` is server-lifetime (it fans out to every connection), not
-// request- or connection-scoped, so remembering the current one a gateway method
-// receives is sound. The Control UI calls `workspaces.get` on load, so the slot is
-// populated long before an agent edits anything.
-
-export type WorkspaceBroadcast = (event: string, payload: unknown) => void;
-
-let handle: WorkspaceBroadcast | undefined;
-
-/** Called by every workspace gateway method to retain the current server broadcast. */
-export function rememberWorkspaceBroadcast(broadcast: WorkspaceBroadcast): void {
-  handle = broadcast;
-}
-
-/** The remembered broadcast, or undefined before any gateway method has run. */
-export function workspaceBroadcast(): WorkspaceBroadcast | undefined {
-  return handle;
-}
diff --git a/extensions/workspaces/src/cli-registration.test.ts b/extensions/workspaces/src/cli-registration.test.ts
deleted file mode 100644
index e48ea583e8d..00000000000
--- a/extensions/workspaces/src/cli-registration.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, expect, it } from "vitest";
-import plugin from "../index.js";
-
-/**
- * `openclaw dashboard` is a core command (it opens the Control UI). A plugin CLI
- * group whose name overlaps a core command is skipped at registration, and the
- * skip is only a `logger.debug` line — so the whole CLI face of this plugin
- * silently disappears at runtime while its unit tests, which build their own
- * Commander program, keep passing.
- *
- * This test pins the name that made the CLI reachable.
- */
-describe("Workspaces plugin CLI registration", () => {
-  it("does not claim a command name core already owns", () => {
-    const descriptorNames: string[] = [];
-    const api = {
-      registerCli: (_register: unknown, options?: { descriptors?: Array<{ name: string }> }) => {
-        for (const descriptor of options?.descriptors ?? []) {
-          descriptorNames.push(descriptor.name);
-        }
-      },
-      registerGatewayMethod: () => {},
-      registerTool: () => {},
-      registerHttpRoute: () => {},
-      session: { controls: { registerControlUiDescriptor: () => {} } },
-    };
-
-    plugin.register(api as never);
-
-    expect(descriptorNames).toEqual(["workspaces"]);
-    // Names reserved by `src/cli/program/command-registry-core.ts`.
-    expect(descriptorNames).not.toContain("dashboard");
-    expect(descriptorNames).not.toContain("doctor");
-  });
-});
diff --git a/extensions/workspaces/src/cli.test.ts b/extensions/workspaces/src/cli.test.ts
deleted file mode 100644
index 7f51c00c0d0..00000000000
--- a/extensions/workspaces/src/cli.test.ts
+++ /dev/null
@@ -1,427 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { Command } from "commander";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { registerWorkspaceCli } from "./cli.js";
-import { registerWorkspaceGatewayMethods } from "./gateway.js";
-import { WorkspaceStore } from "./store.js";
-
-const gatewayRuntime = vi.hoisted(() => ({
-  callGatewayFromCli: vi.fn(),
-}));
-
-vi.mock("openclaw/plugin-sdk/gateway-runtime", async () => {
-  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/gateway-runtime")>(
-    "openclaw/plugin-sdk/gateway-runtime",
-  );
-  return {
-    ...actual,
-    callGatewayFromCli: gatewayRuntime.callGatewayFromCli,
-  };
-});
-
-type RegisteredMethod = {
-  handler: Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1];
-};
-
-async function withTempStateDir<T>(run: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-cli-"));
-  try {
-    return await run(stateDir);
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-function createProgram(stateDir?: string): Command {
-  const program = new Command();
-  program.exitOverride();
-  program.configureOutput({
-    writeErr: () => {},
-    writeOut: () => {},
-  });
-  registerWorkspaceCli({ program, stateDir });
-  return program;
-}
-
-function captureStdout(run: () => Promise<void>): Promise<string> {
-  const chunks: string[] = [];
-  const write = vi.spyOn(process.stdout, "write").mockImplementation((chunk): boolean => {
-    chunks.push(String(chunk));
-    return true;
-  });
-  return run()
-    .then(() => chunks.join(""))
-    .finally(() => {
-      write.mockRestore();
-    });
-}
-
-function installGatewayMock(store: WorkspaceStore) {
-  const methods = new Map<string, RegisteredMethod>();
-  const api = {
-    registerGatewayMethod: vi.fn((method: string, handler: RegisteredMethod["handler"]) => {
-      methods.set(method, { handler });
-    }),
-  } as unknown as OpenClawPluginApi;
-  registerWorkspaceGatewayMethods({ api, store });
-  const broadcast = vi.fn();
-  gatewayRuntime.callGatewayFromCli.mockImplementation(
-    async (method: string, _opts: unknown, params: unknown) => {
-      const entry = methods.get(method);
-      if (!entry) {
-        throw new Error(`unknown method: ${method}`);
-      }
-      const respond = vi.fn();
-      await entry.handler({
-        params: params ?? {},
-        respond,
-        context: { broadcast },
-      } as never);
-      const [ok, result, error] = respond.mock.calls[0] ?? [];
-      if (ok) {
-        return result;
-      }
-      throw new Error(error?.message ?? "gateway error");
-    },
-  );
-  return { broadcast };
-}
-
-describe("workspace CLI", () => {
-  beforeEach(() => {
-    gatewayRuntime.callGatewayFromCli.mockReset();
-  });
-
-  it("round-trips tabs and widgets through the L1 gateway methods", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const { broadcast } = installGatewayMock(store);
-      const program = createProgram(stateDir);
-
-      await captureStdout(async () => {
-        await program.parseAsync(
-          ["workspaces", "tabs", "create", "--title", "Finance Ops", "--slug", "finance"],
-          { from: "user" },
-        );
-      });
-      await captureStdout(async () => {
-        await program.parseAsync(
-          [
-            "workspaces",
-            "widgets",
-            "add",
-            "--tab",
-            "finance",
-            "--kind",
-            "builtin:stat-card",
-            "--title",
-            "Q3 Revenue",
-            "--binding",
-            "value=file:q3.json#/revenue",
-            "--binding",
-            "rows=rpc:sessions.list",
-            "--binding",
-            'summary=static:{"ok":true}',
-            "--props",
-            '{"format":"usd"}',
-          ],
-          { from: "user" },
-        );
-      });
-
-      const output = await captureStdout(async () => {
-        await program.parseAsync(["workspaces", "widgets", "list", "--tab", "finance", "--json"], {
-          from: "user",
-        });
-      });
-      expect(JSON.parse(output)).toMatchObject({
-        widgets: [
-          {
-            title: "Q3 Revenue",
-            grid: { x: 0, y: 0, w: 4, h: 2 },
-            bindings: {
-              value: { source: "file", path: "q3.json", pointer: "/revenue" },
-              rows: { source: "rpc", method: "sessions.list" },
-              summary: { source: "static", value: { ok: true } },
-            },
-            props: { format: "usd" },
-          },
-        ],
-      });
-      expect(gatewayRuntime.callGatewayFromCli).toHaveBeenCalledWith(
-        "workspaces.widget.add",
-        expect.any(Object),
-        expect.objectContaining({ tab: "finance" }),
-        expect.objectContaining({ mode: "cli", scopes: ["operator.write", "operator.read"] }),
-      );
-      expect(broadcast).toHaveBeenCalledWith("plugin.workspaces.changed", {
-        workspaceVersion: 3,
-        changedTabSlug: "finance",
-        actor: "user",
-      });
-
-      for (const binding of ["file:q3.json", "value=static:{bad", "value=command:date"]) {
-        await expect(
-          program.parseAsync(
-            [
-              "workspaces",
-              "widgets",
-              "add",
-              "--tab",
-              "finance",
-              "--kind",
-              "builtin:stat-card",
-              "--binding",
-              binding,
-            ],
-            { from: "user" },
-          ),
-        ).rejects.toThrow();
-      }
-    });
-  });
-
-  it("uses workspace get/replace for layout set and rejects invalid local docs", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      installGatewayMock(store);
-      const program = createProgram(stateDir);
-      const before = store.read();
-      const replacement = structuredClone(before);
-      replacement.tabs[0]!.title = "Renamed";
-      const filePath = path.join(stateDir, "workspace.json");
-      await fs.writeFile(filePath, JSON.stringify(replacement), "utf8");
-
-      await captureStdout(async () => {
-        await program.parseAsync(["workspaces", "layout", "set", "--file", filePath], {
-          from: "user",
-        });
-      });
-      expect(store.read().tabs[0]?.title).toBe("Renamed");
-
-      await fs.writeFile(filePath, JSON.stringify({ schemaVersion: 1 }), "utf8");
-      await expect(
-        program.parseAsync(["workspaces", "layout", "set", "--file", filePath], {
-          from: "user",
-        }),
-      ).rejects.toThrow("workspaceVersion");
-    });
-  });
-
-  it("round-trips every remaining subcommand through the gateway", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      installGatewayMock(store);
-      const program = createProgram(stateDir);
-
-      const run = async (args: string[]) => {
-        await captureStdout(async () => {
-          await program.parseAsync(args, { from: "user" });
-        });
-      };
-
-      await run(["workspaces", "tabs", "create", "--title", "Ops", "--slug", "ops"]);
-      await run(["workspaces", "tabs", "hide", "ops"]);
-      await run(["workspaces", "tabs", "show", "ops"]);
-      await run(["workspaces", "tabs", "reorder", "ops", "main"]);
-      await run([
-        "workspaces",
-        "widgets",
-        "add",
-        "--tab",
-        "ops",
-        "--id",
-        "notes",
-        "--kind",
-        "builtin:markdown",
-        "--title",
-        "Notes",
-        "--grid",
-        "0,0,4,2",
-      ]);
-      await run([
-        "workspaces",
-        "widgets",
-        "update",
-        "--tab",
-        "ops",
-        "--id",
-        "notes",
-        "--title",
-        "Updated Notes",
-        "--collapsed",
-        "true",
-        "--hidden",
-        "false",
-      ]);
-      await run([
-        "workspaces",
-        "widgets",
-        "move",
-        "--tab",
-        "ops",
-        "--id",
-        "notes",
-        "--grid",
-        "4,0,4,2",
-      ]);
-      await run(["workspaces", "tabs", "create", "--title", "Other", "--slug", "other"]);
-      await run(["workspaces", "widgets", "move", "--id", "notes", "--to-tab", "other"]);
-      await run(["workspaces", "widgets", "remove", "--tab", "other", "--id", "notes"]);
-      const layout = await captureStdout(async () => {
-        await program.parseAsync(["workspaces", "layout", "get", "--json"], { from: "user" });
-      });
-      expect(JSON.parse(layout)).toMatchObject({ doc: { tabs: expect.any(Array) } });
-      await run(["workspaces", "layout", "undo"]);
-      await run(["workspaces", "tabs", "delete", "other"]);
-
-      const doc = store.read();
-      expect(doc.prefs.tabOrder).toContain("ops");
-      expect(doc.tabs.some((tab) => tab.slug === "other")).toBe(false);
-    });
-  });
-
-  it("rejects invalid CLI inputs before or through gateway validation", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      installGatewayMock(store);
-      const program = createProgram(stateDir);
-
-      await captureStdout(async () => {
-        await program.parseAsync(
-          ["workspaces", "tabs", "create", "--title", "Ops", "--slug", "ops"],
-          {
-            from: "user",
-          },
-        );
-      });
-
-      await expect(
-        program.parseAsync(["workspaces", "tabs", "reorder", "Bad"], { from: "user" }),
-      ).rejects.toThrow("order[0] is invalid");
-      await expect(
-        program.parseAsync(
-          [
-            "workspaces",
-            "widgets",
-            "add",
-            "--tab",
-            "ops",
-            "--kind",
-            "builtin:markdown",
-            "--grid",
-            "bad",
-          ],
-          { from: "user" },
-        ),
-      ).rejects.toThrow("grid must be x,y,w,h");
-      await expect(
-        program.parseAsync(["workspaces", "widgets", "update", "--tab", "ops", "--id", "missing"], {
-          from: "user",
-        }),
-      ).rejects.toThrow("at least one patch option is required");
-      await expect(
-        program.parseAsync(
-          [
-            "workspaces",
-            "widgets",
-            "move",
-            "--tab",
-            "ops",
-            "--id",
-            "missing",
-            "--grid",
-            "0,0,4,2",
-            "--to-tab",
-            "ops",
-          ],
-          { from: "user" },
-        ),
-      ).rejects.toThrow("not both");
-      await expect(
-        program.parseAsync(["workspaces", "widget-scaffold", "bad/name"], { from: "user" }),
-      ).rejects.toThrow("widget name is invalid");
-      await expect(
-        program.parseAsync(["workspaces", "widget-scaffold", "."], { from: "user" }),
-      ).rejects.toThrow("widget name is invalid");
-    });
-  });
-
-  it.each([
-    ["0x1,0,4,2", "hex"],
-    ["1e0,0,4,2", "exponent"],
-    ["0o1,0,4,2", "octal literal"],
-    ["0b1,0,4,2", "binary literal"],
-    [",0,4,2", "empty segment"],
-  ])("rejects %s (%s) --grid input", async (grid, _label) => {
-    const program = createProgram();
-
-    await expect(
-      program.parseAsync(
-        [
-          "workspaces",
-          "widgets",
-          "add",
-          "--tab",
-          "ops",
-          "--kind",
-          "builtin:markdown",
-          "--grid",
-          grid,
-        ],
-        { from: "user" },
-      ),
-    ).rejects.toThrow("grid must be x,y,w,h");
-    expect(gatewayRuntime.callGatewayFromCli).not.toHaveBeenCalled();
-  });
-
-  it("scaffolds operator widgets as pending and approves them through the approvals method", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      installGatewayMock(store);
-      const program = createProgram(stateDir);
-
-      await captureStdout(async () => {
-        await program.parseAsync(
-          ["workspaces", "widget-scaffold", "revenue-chart", "--title", "Revenue Chart"],
-          { from: "user" },
-        );
-      });
-
-      const widgetDir = path.join(stateDir, "workspaces", "widgets", "revenue-chart");
-      const manifest = JSON.parse(await fs.readFile(path.join(widgetDir, "widget.json"), "utf8"));
-      const html = await fs.readFile(path.join(widgetDir, "index.html"), "utf8");
-      expect(manifest).toMatchObject({
-        schemaVersion: 1,
-        name: "revenue-chart",
-        title: "Revenue Chart",
-        entrypoint: "index.html",
-      });
-      expect(html).toContain("workspace:ready");
-      expect(html).toContain("workspace:getData");
-      expect(html).toContain("function onData");
-      expect(html).not.toMatch(/https?:\/\//);
-      // An operator-scaffolded widget is pending too: the CLI cannot be a way to
-      // mount agent-authored code without the approvals-scoped decision.
-      expect(store.read().widgetsRegistry["revenue-chart"]).toEqual({
-        status: "pending",
-        createdBy: "user",
-      });
-
-      await captureStdout(async () => {
-        await program.parseAsync(["workspaces", "widget-approve", "revenue-chart"], {
-          from: "user",
-        });
-      });
-
-      expect(store.read().widgetsRegistry["revenue-chart"]).toMatchObject({
-        status: "approved",
-        createdBy: "user",
-        approvedBy: "user",
-      });
-    });
-  });
-});
diff --git a/extensions/workspaces/src/cli.ts b/extensions/workspaces/src/cli.ts
deleted file mode 100644
index c9b6cce5abd..00000000000
--- a/extensions/workspaces/src/cli.ts
+++ /dev/null
@@ -1,509 +0,0 @@
-import fs from "node:fs/promises";
-import type { Command } from "commander";
-import { addGatewayClientOptions, callGatewayFromCli } from "openclaw/plugin-sdk/gateway-runtime";
-import { parseStrictNonNegativeInteger } from "openclaw/plugin-sdk/number-runtime";
-import {
-  validateWorkspaceDoc,
-  type WorkspaceBinding,
-  type WorkspaceGrid,
-  type WorkspaceTab,
-  type WorkspaceWidget,
-  type JsonValue,
-  type WorkspaceDoc,
-} from "./schema.js";
-
-type JsonOptions = {
-  json?: boolean;
-};
-
-type GatewayOptions = JsonOptions & {
-  url?: string;
-  token?: string;
-  timeout?: string;
-  expectFinal?: boolean;
-};
-
-type RegisterWorkspaceCliOptions = {
-  program: Command;
-  stateDir?: string;
-};
-
-function writeJson(value: unknown): void {
-  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
-}
-
-function writeLine(value: string): void {
-  process.stdout.write(`${value}\n`);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function parseJson(value: string, label: string): JsonValue {
-  try {
-    return JSON.parse(value) as JsonValue;
-  } catch (error) {
-    throw new Error(`invalid ${label} JSON: ${(error as Error).message}`, { cause: error });
-  }
-}
-
-function parseOptionalBoolean(value: string): boolean {
-  const normalized = value.trim().toLowerCase();
-  if (["true", "1", "yes", "on"].includes(normalized)) {
-    return true;
-  }
-  if (["false", "0", "no", "off"].includes(normalized)) {
-    return false;
-  }
-  throw new Error(`invalid boolean: ${value}`);
-}
-
-function parseWorkspaceGrid(value: string): WorkspaceGrid {
-  // Reject alternate JS numeric spellings that the CLI contract does not expose.
-  const parts = value.split(",").map((entry) => parseStrictNonNegativeInteger(entry.trim()));
-  if (parts.length !== 4 || parts.includes(undefined)) {
-    throw new Error("grid must be x,y,w,h");
-  }
-  return { x: parts[0]!, y: parts[1]!, w: parts[2]!, h: parts[3]! };
-}
-
-function parseWorkspaceBindingShorthand(value: string): [string, WorkspaceBinding] {
-  const eqIndex = value.indexOf("=");
-  if (eqIndex <= 0) {
-    throw new Error("binding must be id=file:<path>, id=rpc:<method>, or id=static:<json>");
-  }
-  const id = value.slice(0, eqIndex).trim();
-  const body = value.slice(eqIndex + 1).trim();
-  if (!/^[A-Za-z0-9._-]{1,64}$/.test(id)) {
-    throw new Error("binding id is invalid");
-  }
-  if (body.startsWith("file:")) {
-    const fileSpec = body.slice("file:".length);
-    const hashIndex = fileSpec.indexOf("#");
-    const bindingPath = hashIndex >= 0 ? fileSpec.slice(0, hashIndex) : fileSpec;
-    const pointer = hashIndex >= 0 ? fileSpec.slice(hashIndex + 1) : undefined;
-    if (!bindingPath) {
-      throw new Error("file binding path is required");
-    }
-    return [
-      id,
-      {
-        source: "file",
-        path: bindingPath,
-        ...(pointer !== undefined ? { pointer } : {}),
-      },
-    ];
-  }
-  if (body.startsWith("rpc:")) {
-    const method = body.slice("rpc:".length).trim();
-    if (!method) {
-      throw new Error("rpc binding method is required");
-    }
-    return [id, { source: "rpc", method }];
-  }
-  if (body.startsWith("static:")) {
-    return [id, { source: "static", value: parseJson(body.slice("static:".length), "static") }];
-  }
-  throw new Error("binding source must be file, rpc, or static");
-}
-
-function collectBinding(value: string, previous: string[] = []): string[] {
-  return [...previous, value];
-}
-
-function parseBindings(values: string[] | undefined): Record<string, WorkspaceBinding> | undefined {
-  if (!values?.length) {
-    return undefined;
-  }
-  return Object.fromEntries(values.map(parseWorkspaceBindingShorthand));
-}
-
-async function callWorkspaceGateway(
-  method: string,
-  options: GatewayOptions,
-  params?: unknown,
-): Promise<unknown> {
-  // `workspaces.widget.approve` is the only approvals-scoped method here: approving
-  // agent-authored widget code is a separate decision from editing a layout, so the
-  // connection asks for that scope only when it is about to make it.
-  // Match `src/gateway/operator-approvals-client.ts`: ask for the approvals scope
-  // alone. A paired device approves scope sets, so requesting a superset here is
-  // rejected as "asking for more scopes than currently approved".
-  const scopes =
-    method === "workspaces.widget.approve"
-      ? (["operator.approvals"] as const)
-      : (["operator.write", "operator.read"] as const);
-  return await callGatewayFromCli(method, options, params, { mode: "cli", scopes: [...scopes] });
-}
-
-function readWorkspaceResult(value: unknown): { doc: WorkspaceDoc; workspaceVersion: number } {
-  if (!isRecord(value)) {
-    throw new Error("workspace gateway response must be an object");
-  }
-  const doc = validateWorkspaceDoc(value.doc);
-  return {
-    doc,
-    workspaceVersion:
-      typeof value.workspaceVersion === "number" ? value.workspaceVersion : doc.workspaceVersion,
-  };
-}
-
-async function readWorkspace(options: GatewayOptions): Promise<WorkspaceDoc> {
-  return readWorkspaceResult(await callWorkspaceGateway("workspaces.get", options)).doc;
-}
-
-function orderedTabs(doc: WorkspaceDoc): WorkspaceTab[] {
-  const bySlug = new Map(doc.tabs.map((tab) => [tab.slug, tab]));
-  const ordered = doc.prefs.tabOrder.flatMap((slug) => {
-    const tab = bySlug.get(slug);
-    return tab ? [tab] : [];
-  });
-  const seen = new Set(ordered.map((tab) => tab.slug));
-  return [...ordered, ...doc.tabs.filter((tab) => !seen.has(tab.slug))];
-}
-
-function formatTabLine(tab: WorkspaceTab): string {
-  const hidden = tab.hidden ? "hidden" : "visible";
-  return `${tab.slug.padEnd(18)} ${hidden.padEnd(8)} ${tab.title}`;
-}
-
-function formatWidgetLine(tab: string, widget: WorkspaceWidget): string {
-  const grid = `${widget.grid.x},${widget.grid.y},${widget.grid.w},${widget.grid.h}`;
-  const state = [widget.hidden ? "hidden" : "visible", widget.collapsed ? "collapsed" : ""]
-    .filter(Boolean)
-    .join(",");
-  return `${tab.padEnd(14)} ${widget.id.padEnd(18)} ${widget.kind.padEnd(20)} ${grid.padEnd(9)} ${state.padEnd(10)} ${widget.title ?? ""}`;
-}
-
-function writeTabs(doc: WorkspaceDoc, options: JsonOptions): void {
-  const tabs = orderedTabs(doc);
-  if (options.json) {
-    writeJson({ tabs });
-    return;
-  }
-  for (const tab of tabs) {
-    writeLine(formatTabLine(tab));
-  }
-}
-
-function widgetRows(
-  doc: WorkspaceDoc,
-  tabSlug?: string,
-): Array<{ tab: string; widget: WorkspaceWidget }> {
-  const tabs = tabSlug ? doc.tabs.filter((tab) => tab.slug === tabSlug) : orderedTabs(doc);
-  if (tabSlug && tabs.length === 0) {
-    throw new Error(`workspace tab not found: ${tabSlug}`);
-  }
-  return tabs.flatMap((tab) => tab.widgets.map((widget) => ({ tab: tab.slug, widget })));
-}
-
-function writeWidgets(doc: WorkspaceDoc, options: JsonOptions & { tab?: string }): void {
-  const widgets = widgetRows(doc, options.tab);
-  if (options.json) {
-    writeJson({ widgets: widgets.map(({ tab, widget }) => ({ tab, ...widget })) });
-    return;
-  }
-  for (const { tab, widget } of widgets) {
-    writeLine(formatWidgetLine(tab, widget));
-  }
-}
-
-function requirePatch(patch: Record<string, unknown>): void {
-  if (Object.keys(patch).length === 0) {
-    throw new Error("at least one patch option is required");
-  }
-}
-
-function addGatewayOptions(command: Command): Command {
-  return addGatewayClientOptions(command);
-}
-
-export function registerWorkspaceCli(options: RegisterWorkspaceCliOptions): void {
-  const workspace = options.program
-    .command("workspaces")
-    .description("Manage Workspaces tabs and widgets");
-  const tabs = workspace.command("tabs").description("Manage workspace tabs");
-  const widgets = workspace.command("widgets").description("Manage workspace widgets");
-  const layout = workspace.command("layout").description("Manage workspace layout documents");
-
-  addGatewayOptions(
-    tabs.command("list").description("List workspace tabs").option("--json", "Print JSON", false),
-  ).action(async (commandOptions: GatewayOptions) => {
-    writeTabs(await readWorkspace(commandOptions), commandOptions);
-  });
-
-  addGatewayOptions(
-    tabs
-      .command("create")
-      .description("Create a workspace tab")
-      .requiredOption("--title <title>", "Tab title")
-      .option("--slug <slug>", "Tab slug")
-      .option("--icon <icon>", "Icon name"),
-  ).action(
-    async (commandOptions: GatewayOptions & { title: string; slug?: string; icon?: string }) => {
-      const result = await callWorkspaceGateway("workspaces.tab.create", commandOptions, {
-        title: commandOptions.title,
-        ...(commandOptions.slug ? { slug: commandOptions.slug } : {}),
-        ...(commandOptions.icon ? { icon: commandOptions.icon } : {}),
-      });
-      writeTabs(readWorkspaceResult(result).doc, commandOptions);
-    },
-  );
-
-  addGatewayOptions(
-    tabs.command("delete").argument("<slug>", "Tab slug").description("Delete a workspace tab"),
-  ).action(async (slug: string, commandOptions: GatewayOptions) => {
-    const result = await callWorkspaceGateway("workspaces.tab.delete", commandOptions, {
-      slug,
-    });
-    writeTabs(readWorkspaceResult(result).doc, commandOptions);
-  });
-
-  addGatewayOptions(
-    tabs
-      .command("reorder")
-      .argument("<slug...>", "Tab slugs")
-      .description("Set workspace tab order"),
-  ).action(async (order: string[], commandOptions: GatewayOptions) => {
-    const result = await callWorkspaceGateway("workspaces.tab.reorder", commandOptions, {
-      order,
-    });
-    writeTabs(readWorkspaceResult(result).doc, commandOptions);
-  });
-
-  for (const [verb, hidden] of [
-    ["hide", true],
-    ["show", false],
-  ] as const) {
-    addGatewayOptions(
-      tabs.command(verb).argument("<slug>", "Tab slug").description(`${verb} a workspace tab`),
-    ).action(async (slug: string, commandOptions: GatewayOptions) => {
-      const result = await callWorkspaceGateway("workspaces.tab.update", commandOptions, {
-        slug,
-        patch: { hidden },
-      });
-      writeTabs(readWorkspaceResult(result).doc, commandOptions);
-    });
-  }
-
-  for (const [verb, tabLayout] of [
-    ["grid", "grid"],
-    ["full", "full"],
-  ] as const) {
-    addGatewayOptions(
-      tabs.command(verb).argument("<slug>", "Tab slug").description(`Use ${tabLayout} layout`),
-    ).action(async (slug: string, commandOptions: GatewayOptions) => {
-      const result = await callWorkspaceGateway("workspaces.tab.update", commandOptions, {
-        slug,
-        patch: { layout: tabLayout },
-      });
-      writeTabs(readWorkspaceResult(result).doc, commandOptions);
-    });
-  }
-
-  addGatewayOptions(
-    widgets
-      .command("list")
-      .description("List workspace widgets")
-      .option("--tab <slug>", "Tab slug")
-      .option("--json", "Print JSON", false),
-  ).action(async (commandOptions: GatewayOptions & { tab?: string }) => {
-    writeWidgets(await readWorkspace(commandOptions), commandOptions);
-  });
-
-  addGatewayOptions(
-    widgets
-      .command("add")
-      .description("Add a workspace widget")
-      .requiredOption("--tab <slug>", "Tab slug")
-      .requiredOption("--kind <kind>", "Widget kind")
-      .option("--id <id>", "Widget id")
-      .option("--title <title>", "Widget title")
-      .option("--grid <x,y,w,h>", "Widget grid", "0,0,4,2")
-      .option("--binding <id=source>", "Binding shorthand", collectBinding, [])
-      .option("--props <json>", "Widget props JSON"),
-  ).action(
-    async (
-      commandOptions: GatewayOptions & {
-        tab: string;
-        id?: string;
-        kind: string;
-        title?: string;
-        grid?: string;
-        binding?: string[];
-        props?: string;
-      },
-    ) => {
-      const bindings = parseBindings(commandOptions.binding);
-      const result = await callWorkspaceGateway("workspaces.widget.add", commandOptions, {
-        tab: commandOptions.tab,
-        widget: {
-          ...(commandOptions.id ? { id: commandOptions.id } : {}),
-          kind: commandOptions.kind,
-          ...(commandOptions.title ? { title: commandOptions.title } : {}),
-          grid: parseWorkspaceGrid(commandOptions.grid ?? "0,0,4,2"),
-          ...(bindings ? { bindings } : {}),
-          ...(commandOptions.props ? { props: parseJson(commandOptions.props, "props") } : {}),
-        },
-      });
-      writeWidgets(readWorkspaceResult(result).doc, { ...commandOptions, tab: commandOptions.tab });
-    },
-  );
-
-  addGatewayOptions(
-    widgets
-      .command("update")
-      .description("Update a workspace widget")
-      .requiredOption("--tab <slug>", "Tab slug")
-      .requiredOption("--id <id>", "Widget id")
-      .option("--title <title>", "Widget title")
-      .option("--collapsed <bool>", "Collapsed state", parseOptionalBoolean)
-      .option("--hidden <bool>", "Hidden state", parseOptionalBoolean),
-  ).action(
-    async (
-      commandOptions: GatewayOptions & {
-        tab: string;
-        id: string;
-        title?: string;
-        collapsed?: boolean;
-        hidden?: boolean;
-      },
-    ) => {
-      const patch = {
-        ...(commandOptions.title !== undefined ? { title: commandOptions.title } : {}),
-        ...(commandOptions.collapsed !== undefined ? { collapsed: commandOptions.collapsed } : {}),
-        ...(commandOptions.hidden !== undefined ? { hidden: commandOptions.hidden } : {}),
-      };
-      requirePatch(patch);
-      const result = await callWorkspaceGateway("workspaces.widget.update", commandOptions, {
-        tab: commandOptions.tab,
-        id: commandOptions.id,
-        patch,
-      });
-      writeWidgets(readWorkspaceResult(result).doc, { ...commandOptions, tab: commandOptions.tab });
-    },
-  );
-
-  addGatewayOptions(
-    widgets
-      .command("move")
-      .description("Move a workspace widget")
-      .option("--tab <slug>", "Current tab slug")
-      .requiredOption("--id <id>", "Widget id")
-      .option("--grid <x,y,w,h>", "New grid")
-      .option("--to-tab <slug>", "Destination tab slug"),
-  ).action(
-    async (
-      commandOptions: GatewayOptions & { tab?: string; id: string; grid?: string; toTab?: string },
-    ) => {
-      const result = await callWorkspaceGateway("workspaces.widget.move", commandOptions, {
-        ...(commandOptions.tab ? { tab: commandOptions.tab } : {}),
-        id: commandOptions.id,
-        ...(commandOptions.grid ? { grid: parseWorkspaceGrid(commandOptions.grid) } : {}),
-        ...(commandOptions.toTab ? { toTab: commandOptions.toTab } : {}),
-      });
-      writeWidgets(readWorkspaceResult(result).doc, { ...commandOptions, tab: commandOptions.tab });
-    },
-  );
-
-  addGatewayOptions(
-    widgets
-      .command("remove")
-      .description("Remove a workspace widget")
-      .requiredOption("--tab <slug>", "Tab slug")
-      .requiredOption("--id <id>", "Widget id"),
-  ).action(async (commandOptions: GatewayOptions & { tab: string; id: string }) => {
-    const result = await callWorkspaceGateway("workspaces.widget.remove", commandOptions, {
-      tab: commandOptions.tab,
-      id: commandOptions.id,
-    });
-    writeWidgets(readWorkspaceResult(result).doc, { ...commandOptions, tab: commandOptions.tab });
-  });
-
-  addGatewayOptions(
-    layout
-      .command("get")
-      .description("Read the Workspaces layout")
-      .option("--json", "Print JSON", false),
-  ).action(async (commandOptions: GatewayOptions) => {
-    const doc = await readWorkspace(commandOptions);
-    if (commandOptions.json) {
-      writeJson({ doc, workspaceVersion: doc.workspaceVersion });
-    } else {
-      writeLine(`workspaceVersion ${doc.workspaceVersion}`);
-      writeTabs(doc, commandOptions);
-    }
-  });
-
-  addGatewayOptions(
-    layout
-      .command("set")
-      .description("Replace the Workspaces layout")
-      .requiredOption("--file <path>", "Workspace JSON file"),
-  ).action(async (commandOptions: GatewayOptions & { file: string }) => {
-    const doc = validateWorkspaceDoc(JSON.parse(await fs.readFile(commandOptions.file, "utf8")));
-    const result = await callWorkspaceGateway("workspaces.replace", commandOptions, {
-      doc,
-    });
-    const next = readWorkspaceResult(result);
-    if (commandOptions.json) {
-      writeJson(next);
-    } else {
-      writeLine(`workspaceVersion ${next.workspaceVersion}`);
-    }
-  });
-
-  addGatewayOptions(
-    layout.command("undo").description("Restore the newest workspace undo snapshot"),
-  ).action(async (commandOptions: GatewayOptions) => {
-    const result = await callWorkspaceGateway("workspaces.undo", commandOptions, {});
-    const next = readWorkspaceResult(result);
-    if (commandOptions.json) {
-      writeJson(next);
-    } else {
-      writeLine(`workspaceVersion ${next.workspaceVersion}`);
-    }
-  });
-
-  addGatewayOptions(
-    workspace
-      .command("widget-scaffold")
-      .argument("<name>", "Custom widget name")
-      .description("Create a custom widget scaffold (starts pending approval)")
-      .option("--title <title>", "Widget title"),
-  ).action(async (name: string, commandOptions: GatewayOptions & { title?: string }) => {
-    const result = await callWorkspaceGateway("workspaces.widget.scaffold", commandOptions, {
-      name,
-      ...(commandOptions.title !== undefined ? { title: commandOptions.title } : {}),
-    });
-    if (commandOptions.json) {
-      writeJson(result);
-      return;
-    }
-    const dir = isRecord(result) && typeof result.dir === "string" ? result.dir : name;
-    writeLine(`created ${dir}`);
-    writeLine(`pending approval; run: openclaw workspaces widget-approve ${name}`);
-  });
-
-  addGatewayOptions(
-    workspace
-      .command("widget-approve")
-      .argument("<name>", "Custom widget name")
-      .description("Approve or reject a pending custom widget")
-      .option("--reject", "Reject instead of approving"),
-  ).action(async (name: string, commandOptions: GatewayOptions & { reject?: boolean }) => {
-    const decision = commandOptions.reject ? "rejected" : "approved";
-    // Approve responds with the registry entry only: the approvals scope is not a
-    // door onto the workspace document.
-    const result = await callWorkspaceGateway("workspaces.widget.approve", commandOptions, {
-      name,
-      decision,
-    });
-    if (commandOptions.json) {
-      writeJson(result);
-    } else {
-      writeLine(`${name} ${decision}`);
-    }
-  });
-}
diff --git a/extensions/workspaces/src/data-read.test.ts b/extensions/workspaces/src/data-read.test.ts
deleted file mode 100644
index 5fedf15d38f..00000000000
--- a/extensions/workspaces/src/data-read.test.ts
+++ /dev/null
@@ -1,162 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { DATA_READ_RPC_ALLOWLIST, resolveBinding } from "./data-read.js";
-
-async function withTempStateDir<T>(run: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-data-"));
-  try {
-    return await run(stateDir);
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-describe("workspace data binding resolver", () => {
-  it("returns static values", async () => {
-    await expect(resolveBinding({ source: "static", value: { ok: true } })).resolves.toEqual({
-      ok: true,
-    });
-  });
-
-  it("returns the client-resolution signal for rpc bindings", async () => {
-    expect(DATA_READ_RPC_ALLOWLIST).toContain("sessions.list");
-
-    await expect(resolveBinding({ source: "rpc", method: "sessions.list" })).rejects.toMatchObject({
-      code: "binding_client_resolved",
-    });
-  });
-
-  it("allowlists the read methods the L4 builtin data widgets bind", () => {
-    // Frozen so a builtin can never reference a method the write-time schema
-    // would reject. system-presence backs builtin:instances; cron.runs backs
-    // builtin:activity; usage.cost backs the stat-cards + usage widget.
-    for (const method of [
-      "usage.cost",
-      "sessions.list",
-      "cron.list",
-      "cron.runs",
-      "system-presence",
-    ]) {
-      expect(DATA_READ_RPC_ALLOWLIST).toContain(method);
-    }
-  });
-
-  it("reads JSON pointers and raw markdown from the workspace data jail", async () => {
-    await withTempStateDir(async (stateDir) => {
-      await fs.mkdir(path.join(stateDir, "workspaces", "data", "metrics"), { recursive: true });
-      await fs.writeFile(
-        path.join(stateDir, "workspaces", "data", "metrics", "q3.json"),
-        JSON.stringify({ revenue: 42, nested: { "a/b": "escaped" } }),
-      );
-      await fs.writeFile(path.join(stateDir, "workspaces", "data", "notes.md"), "# Notes\n");
-
-      await expect(
-        resolveBinding(
-          { source: "file", path: "metrics/q3.json", pointer: "/nested/a~1b" },
-          { stateDir },
-        ),
-      ).resolves.toBe("escaped");
-      await expect(
-        resolveBinding({ source: "file", path: "notes.md" }, { stateDir }),
-      ).resolves.toBe("# Notes\n");
-    });
-  });
-
-  it("rejects noncanonical array indices in JSON pointers", async () => {
-    await withTempStateDir(async (stateDir) => {
-      await fs.mkdir(path.join(stateDir, "workspaces", "data"), { recursive: true });
-      await fs.writeFile(
-        path.join(stateDir, "workspaces", "data", "items.json"),
-        JSON.stringify({ items: ["zero", "one"], lookup: { "01": "object-key" } }),
-      );
-
-      await expect(
-        resolveBinding({ source: "file", path: "items.json", pointer: "/items/0" }, { stateDir }),
-      ).resolves.toBe("zero");
-      await expect(
-        resolveBinding({ source: "file", path: "items.json", pointer: "/items/1" }, { stateDir }),
-      ).resolves.toBe("one");
-      await expect(
-        resolveBinding({ source: "file", path: "items.json", pointer: "/lookup/01" }, { stateDir }),
-      ).resolves.toBe("object-key");
-
-      for (const segment of [
-        "",
-        " ",
-        "00",
-        "01",
-        "+1",
-        "-0",
-        "1.0",
-        "1e0",
-        "0x1",
-        "9007199254740993",
-      ]) {
-        await expect(
-          resolveBinding(
-            { source: "file", path: "items.json", pointer: `/items/${segment}` },
-            { stateDir },
-          ),
-        ).rejects.toMatchObject({ code: "binding_not_found" });
-      }
-    });
-  });
-
-  it("rejects file traversal and oversized files with typed errors", async () => {
-    await withTempStateDir(async (stateDir) => {
-      await expect(
-        resolveBinding({ source: "file", path: "../secrets.json" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_invalid" });
-      await expect(
-        resolveBinding({ source: "file", path: "~/metrics.json" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_invalid" });
-
-      await fs.mkdir(path.join(stateDir, "workspaces", "data"), { recursive: true });
-      await fs.writeFile(
-        path.join(stateDir, "workspaces", "data", "big.csv"),
-        "x".repeat(1_100_000),
-      );
-
-      await expect(
-        resolveBinding({ source: "file", path: "big.csv" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_too_large" });
-    });
-  });
-
-  it("rejects leaf and ancestor symlinks that escape the workspace data jail", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const dataDir = path.join(stateDir, "workspaces", "data");
-      const outsideDir = path.join(stateDir, "outside");
-      const outsideFile = path.join(outsideDir, "secret.json");
-      await fs.mkdir(dataDir, { recursive: true });
-      await fs.mkdir(outsideDir);
-      await fs.writeFile(outsideFile, JSON.stringify({ secret: true }));
-      await fs.symlink(outsideFile, path.join(dataDir, "leak.json"));
-      await fs.symlink(outsideDir, path.join(dataDir, "leak-dir"));
-
-      await expect(
-        resolveBinding({ source: "file", path: "leak.json" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_invalid" });
-      await expect(
-        resolveBinding({ source: "file", path: "leak-dir/secret.json" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_invalid" });
-    });
-  });
-
-  it("rejects a workspace data root replaced with a symlink", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const workspaceDir = path.join(stateDir, "workspaces");
-      const outsideDir = path.join(stateDir, "outside");
-      await fs.mkdir(workspaceDir);
-      await fs.mkdir(outsideDir);
-      await fs.writeFile(path.join(outsideDir, "secret.json"), JSON.stringify({ secret: true }));
-      await fs.symlink(outsideDir, path.join(workspaceDir, "data"));
-
-      await expect(
-        resolveBinding({ source: "file", path: "secret.json" }, { stateDir }),
-      ).rejects.toMatchObject({ code: "binding_invalid" });
-    });
-  });
-});
diff --git a/extensions/workspaces/src/data-read.ts b/extensions/workspaces/src/data-read.ts
deleted file mode 100644
index 2436c08c216..00000000000
--- a/extensions/workspaces/src/data-read.ts
+++ /dev/null
@@ -1,167 +0,0 @@
-import path from "node:path";
-import { FsSafeError, root as fsRoot } from "openclaw/plugin-sdk/security-runtime";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import {
-  WorkspaceBindingResolutionError,
-  normalizeWorkspaceDataLogicalPath,
-} from "./binding-contract.js";
-import type { WorkspaceBinding, JsonValue } from "./schema.js";
-
-export { DATA_READ_RPC_ALLOWLIST, WorkspaceBindingResolutionError } from "./binding-contract.js";
-
-export type ResolveBindingOptions = {
-  stateDir?: string;
-};
-
-const MAX_FILE_BYTES = 1024 * 1024;
-const JSON_POINTER_ARRAY_INDEX_SEGMENT = /^(?:0|[1-9]\d*)$/u;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function readBinding(value: unknown): WorkspaceBinding {
-  if (!isRecord(value) || typeof value.source !== "string") {
-    throw new WorkspaceBindingResolutionError("binding_invalid", "binding source is required");
-  }
-  if (value.source === "static") {
-    return { source: "static", value: value.value as JsonValue };
-  }
-  if (value.source === "rpc") {
-    if (typeof value.method !== "string" || !value.method.trim()) {
-      throw new WorkspaceBindingResolutionError(
-        "binding_invalid",
-        "rpc binding method is required",
-      );
-    }
-    const params = isRecord(value.params) ? (value.params as Record<string, JsonValue>) : undefined;
-    return { source: "rpc", method: value.method, ...(params ? { params } : {}) };
-  }
-  if (value.source === "file") {
-    if (typeof value.path !== "string") {
-      throw new WorkspaceBindingResolutionError("binding_invalid", "file binding path is required");
-    }
-    if (value.pointer !== undefined && typeof value.pointer !== "string") {
-      throw new WorkspaceBindingResolutionError(
-        "binding_invalid",
-        "file binding pointer is invalid",
-      );
-    }
-    return {
-      source: "file",
-      path: value.path,
-      ...(value.pointer !== undefined ? { pointer: value.pointer } : {}),
-    };
-  }
-  throw new WorkspaceBindingResolutionError("binding_invalid", "binding source is invalid");
-}
-
-function decodePointerSegment(value: string): string {
-  return value.replaceAll("~1", "/").replaceAll("~0", "~");
-}
-
-function parseJsonPointerArrayIndex(segment: string): number | undefined {
-  // RFC 6901 array tokens are canonical decimal indices; object tokens remain opaque keys.
-  if (!JSON_POINTER_ARRAY_INDEX_SEGMENT.test(segment)) {
-    return undefined;
-  }
-  const index = Number(segment);
-  return Number.isSafeInteger(index) ? index : undefined;
-}
-
-function applyJsonPointer(value: unknown, pointer: string | undefined): unknown {
-  if (pointer === undefined || pointer === "") {
-    return value;
-  }
-  if (!pointer.startsWith("/")) {
-    throw new WorkspaceBindingResolutionError("binding_invalid", "JSON pointer is invalid");
-  }
-  let current = value;
-  for (const rawSegment of pointer.slice(1).split("/")) {
-    const segment = decodePointerSegment(rawSegment);
-    if (Array.isArray(current)) {
-      const index = parseJsonPointerArrayIndex(segment);
-      if (index === undefined || index >= current.length) {
-        throw new WorkspaceBindingResolutionError("binding_not_found", "JSON pointer not found");
-      }
-      current = current[index];
-      continue;
-    }
-    if (!isRecord(current) || !Object.hasOwn(current, segment)) {
-      throw new WorkspaceBindingResolutionError("binding_not_found", "JSON pointer not found");
-    }
-    current = current[segment];
-  }
-  return current;
-}
-
-async function resolveFileBinding(
-  binding: Extract<WorkspaceBinding, { source: "file" }>,
-  options: ResolveBindingOptions,
-): Promise<unknown> {
-  const logicalPath = normalizeWorkspaceDataLogicalPath(binding.path);
-  const stateDir = path.resolve(options.stateDir ?? resolveStateDir());
-  const dataRoot = path.join(stateDir, "workspaces", "data");
-  let content: string;
-  try {
-    const state = await fsRoot(stateDir);
-    const data = await fsRoot(dataRoot);
-    const expectedDataRoot = path.join(state.rootReal, "workspaces", "data");
-    // The data directory itself is part of the jail, not a trusted alias. Once
-    // this matches, fs-safe pins its canonical root and rejects later swaps.
-    if (data.rootReal !== expectedDataRoot) {
-      throw new WorkspaceBindingResolutionError("binding_invalid", "file binding path is invalid");
-    }
-    // The schema rejects leading `~/`, so this absolute path never invokes the
-    // shared root helper's home-expansion convenience.
-    const read = await data.readAbsolute(path.join(data.rootDir, logicalPath), {
-      hardlinks: "reject",
-      maxBytes: MAX_FILE_BYTES,
-      symlinks: "reject",
-    });
-    content = read.buffer.toString("utf8");
-  } catch (error) {
-    if (error instanceof FsSafeError) {
-      if (error.code === "too-large") {
-        throw new WorkspaceBindingResolutionError("binding_too_large", "file binding is too large");
-      }
-      if (error.code === "not-found" || error.code === "not-file") {
-        throw new WorkspaceBindingResolutionError("binding_not_found", "file binding not found");
-      }
-      throw new WorkspaceBindingResolutionError("binding_invalid", "file binding path is invalid");
-    }
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new WorkspaceBindingResolutionError("binding_not_found", "file binding not found");
-    }
-    throw error;
-  }
-  const extension = path.extname(logicalPath).toLowerCase();
-  if (extension === ".md" || extension === ".csv") {
-    return content;
-  }
-  try {
-    return applyJsonPointer(JSON.parse(content), binding.pointer);
-  } catch (error) {
-    if (error instanceof WorkspaceBindingResolutionError) {
-      throw error;
-    }
-    throw new WorkspaceBindingResolutionError("binding_invalid", "file binding JSON is invalid");
-  }
-}
-
-export async function resolveBinding(
-  bindingInput: unknown,
-  options: ResolveBindingOptions = {},
-): Promise<unknown> {
-  const binding = readBinding(bindingInput);
-  if (binding.source === "static") {
-    return binding.value;
-  }
-  if (binding.source === "rpc") {
-    throw new WorkspaceBindingResolutionError(
-      "binding_client_resolved",
-      "rpc workspace bindings are resolved by the Control UI gateway client",
-    );
-  }
-  return await resolveFileBinding(binding, options);
-}
diff --git a/extensions/workspaces/src/default-workspace.test.ts b/extensions/workspaces/src/default-workspace.test.ts
deleted file mode 100644
index 2f4135f5b1e..00000000000
--- a/extensions/workspaces/src/default-workspace.test.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-import { expectDefined } from "@openclaw/normalization-core";
-import { describe, expect, it } from "vitest";
-import { DATA_READ_RPC_ALLOWLIST } from "./binding-contract.js";
-import { DEFAULT_WORKSPACE } from "./default-workspace.js";
-import { validateWorkspaceDoc } from "./schema.js";
-
-function mainTab() {
-  return expectDefined(DEFAULT_WORKSPACE.tabs[0], "default main workspace tab");
-}
-
-describe("default Workspaces document", () => {
-  it("passes write-time schema validation (seeds cleanly on fresh state)", () => {
-    expect(() => validateWorkspaceDoc(DEFAULT_WORKSPACE)).not.toThrow();
-  });
-
-  it("ships a single curated system Overview tab", () => {
-    expect(DEFAULT_WORKSPACE.tabs).toHaveLength(1);
-    const main = mainTab();
-    expect(main.slug).toBe("main");
-    expect(main.createdBy).toBe("system");
-    expect(DEFAULT_WORKSPACE.prefs.tabOrder).toEqual(["main"]);
-  });
-
-  it("matches the spec layout (usage cards + instances, sessions + cron, activity)", () => {
-    const kinds = mainTab().widgets.map((w) => w.kind);
-    expect(kinds).toEqual([
-      "builtin:stat-card",
-      "builtin:stat-card",
-      "builtin:instances",
-      "builtin:sessions",
-      "builtin:cron",
-      "builtin:activity",
-    ]);
-    // Activity spans the full width, taller (row 3).
-    const activity = mainTab().widgets.find((w) => w.id === "activity");
-    expect(activity?.grid).toMatchObject({ x: 0, w: 12 });
-  });
-
-  it("scopes the Today cards to one calendar day", () => {
-    const widgets = mainTab().widgets;
-    for (const id of ["cost-today", "tokens-today"]) {
-      expect(widgets.find((widget) => widget.id === id)?.bindings?.value).toEqual({
-        source: "rpc",
-        method: "usage.cost",
-        params: { days: 1, agentScope: "all" },
-      });
-    }
-  });
-
-  it("binds only allowlisted rpc methods", () => {
-    for (const tab of DEFAULT_WORKSPACE.tabs) {
-      for (const widget of tab.widgets) {
-        for (const binding of Object.values(widget.bindings ?? {})) {
-          if (binding.source === "rpc") {
-            expect(DATA_READ_RPC_ALLOWLIST).toContain(binding.method);
-          }
-        }
-      }
-    }
-  });
-});
diff --git a/extensions/workspaces/src/default-workspace.ts b/extensions/workspaces/src/default-workspace.ts
deleted file mode 100644
index bdcd8b756f0..00000000000
--- a/extensions/workspaces/src/default-workspace.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-import type { WorkspaceDoc } from "./schema.js";
-
-export const DEFAULT_WORKSPACE: WorkspaceDoc = {
-  schemaVersion: 1,
-  workspaceVersion: 1,
-  tabs: [
-    {
-      slug: "main",
-      title: "Overview",
-      icon: "layoutWorkspace",
-      hidden: false,
-      createdBy: "system",
-      widgets: [
-        {
-          id: "cost-today",
-          kind: "builtin:stat-card",
-          title: "Cost Today",
-          grid: { x: 0, y: 0, w: 4, h: 2 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            value: {
-              source: "rpc",
-              method: "usage.cost",
-              params: { days: 1, agentScope: "all" },
-            },
-          },
-          props: { metric: "todayCost", format: "usd" },
-        },
-        {
-          id: "tokens-today",
-          kind: "builtin:stat-card",
-          title: "Tokens Today",
-          grid: { x: 4, y: 0, w: 4, h: 2 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            // usage.cost carries the day-scoped totals; the stat-card selects the
-            // token total via props.metric. (usage.status is provider rate-limit
-            // windows — not token counts.)
-            value: {
-              source: "rpc",
-              method: "usage.cost",
-              params: { days: 1, agentScope: "all" },
-            },
-          },
-          props: { metric: "todayTokens", format: "int" },
-        },
-        {
-          id: "instances-health",
-          kind: "builtin:instances",
-          title: "Instances",
-          grid: { x: 8, y: 0, w: 4, h: 2 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            // system-presence is the live connected-instances + health feed the
-            // instances page consumes (PresenceEntry[]).
-            presence: { source: "rpc", method: "system-presence" },
-          },
-        },
-        {
-          id: "sessions",
-          kind: "builtin:sessions",
-          title: "Sessions",
-          grid: { x: 0, y: 2, w: 6, h: 5 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            sessions: { source: "rpc", method: "sessions.list" },
-          },
-        },
-        {
-          id: "cron",
-          kind: "builtin:cron",
-          title: "Cron",
-          grid: { x: 6, y: 2, w: 6, h: 5 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            jobs: { source: "rpc", method: "cron.list" },
-          },
-        },
-        {
-          id: "activity",
-          kind: "builtin:activity",
-          title: "Activity",
-          grid: { x: 0, y: 7, w: 12, h: 8 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "system",
-          bindings: {
-            // cron.runs (scope defaults to "all" without a jobId) is the global
-            // recent-run feed. sessions.usage.logs is per-session (needs a key).
-            runs: { source: "rpc", method: "cron.runs" },
-          },
-        },
-      ],
-    },
-  ],
-  widgetsRegistry: {},
-  prefs: { tabOrder: ["main"] },
-};
diff --git a/extensions/workspaces/src/gateway.test.ts b/extensions/workspaces/src/gateway.test.ts
deleted file mode 100644
index bdbdd98f4ee..00000000000
--- a/extensions/workspaces/src/gateway.test.ts
+++ /dev/null
@@ -1,297 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { describe, expect, it, vi } from "vitest";
-import { workspaceBroadcast } from "./broadcast.js";
-import { registerWorkspaceGatewayMethods } from "./gateway.js";
-import { WorkspaceStore } from "./store.js";
-
-type RegisteredMethod = {
-  handler: Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1];
-  opts: Parameters<OpenClawPluginApi["registerGatewayMethod"]>[2];
-};
-
-async function withTempStateDir<T>(run: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-gateway-"));
-  try {
-    return await run(stateDir);
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-function createApi() {
-  const methods = new Map<string, RegisteredMethod>();
-  const api = {
-    registerGatewayMethod: vi.fn(
-      (method: string, handler: RegisteredMethod["handler"], opts: RegisteredMethod["opts"]) => {
-        methods.set(method, { handler, opts });
-      },
-    ),
-  } as unknown as OpenClawPluginApi;
-  return { api, methods };
-}
-
-async function callMethod(
-  method: RegisteredMethod,
-  params: Record<string, unknown>,
-  broadcast = vi.fn(),
-) {
-  const respond = vi.fn();
-  await method.handler({
-    params,
-    respond,
-    context: { broadcast },
-  } as never);
-  return { broadcast, respond, response: respond.mock.calls[0] };
-}
-
-describe("workspace gateway methods", () => {
-  it("registers all L1 methods with read/write scopes", () => {
-    const { api, methods } = createApi();
-    registerWorkspaceGatewayMethods({
-      api,
-      store: new WorkspaceStore({ stateDir: "/tmp/unused" }),
-    });
-
-    expect([...methods.keys()]).toEqual([
-      "workspaces.get",
-      "workspaces.widget.frame",
-      "workspaces.tab.create",
-      "workspaces.tab.update",
-      "workspaces.tab.delete",
-      "workspaces.tab.reorder",
-      "workspaces.widget.add",
-      "workspaces.widget.update",
-      "workspaces.widget.move",
-      "workspaces.widget.remove",
-      "workspaces.widget.setLayout",
-      "workspaces.widget.scaffold",
-      "workspaces.widget.approve",
-      "workspaces.replace",
-      "workspaces.undo",
-      "workspaces.data.read",
-    ]);
-    expect(methods.get("workspaces.get")?.opts).toEqual({ scope: "operator.read" });
-    expect(methods.get("workspaces.widget.frame")?.opts).toEqual({ scope: "operator.read" });
-    expect(methods.get("workspaces.data.read")?.opts).toEqual({ scope: "operator.read" });
-    // Approving agent-authored code is an approvals decision: operator.write alone
-    // must not be enough to mount an untrusted widget.
-    expect(methods.get("workspaces.widget.approve")?.opts).toEqual({
-      scope: "operator.approvals",
-    });
-    const readOnly = new Set(["workspaces.get", "workspaces.widget.frame", "workspaces.data.read"]);
-    for (const [name, method] of methods) {
-      if (readOnly.has(name) || name === "workspaces.widget.approve") {
-        continue;
-      }
-      expect(method.opts).toEqual({ scope: "operator.write" });
-    }
-  });
-
-  it("returns the workspace without broadcasting and broadcasts successful writes", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const { api, methods } = createApi();
-      registerWorkspaceGatewayMethods({ api, store: new WorkspaceStore({ stateDir }) });
-      const broadcast = vi.fn();
-
-      const read = await callMethod(methods.get("workspaces.get")!, {}, broadcast);
-      expect(read.response?.[0]).toBe(true);
-      expect(read.response?.[1]).toMatchObject({ workspaceVersion: 1 });
-      expect(broadcast).not.toHaveBeenCalled();
-
-      // Provenance is derived from the caller. An RPC client must not be able to
-      // stamp `agent:<id>` on work a human did (or the reverse).
-      const forged = await callMethod(
-        methods.get("workspaces.tab.create")!,
-        { title: "Finance Ops", actor: "agent:main" },
-        broadcast,
-      );
-      expect(forged.response?.[0]).toBe(false);
-      expect(forged.response?.[2]?.message).toContain("unexpected param: actor");
-      expect(broadcast).not.toHaveBeenCalled();
-
-      const created = await callMethod(
-        methods.get("workspaces.tab.create")!,
-        { title: "Finance Ops" },
-        broadcast,
-      );
-
-      expect(created.response?.[0]).toBe(true);
-      expect(created.response?.[1]).toMatchObject({
-        doc: {
-          workspaceVersion: 2,
-          tabs: expect.arrayContaining([expect.objectContaining({ slug: "finance-ops" })]),
-        },
-        workspaceVersion: 2,
-      });
-      expect(broadcast).toHaveBeenCalledWith("plugin.workspaces.changed", {
-        workspaceVersion: 2,
-        changedTabSlug: "finance-ops",
-        actor: "user",
-      });
-    });
-  });
-
-  it("rejects unknown params and bad shapes without broadcasting", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const { api, methods } = createApi();
-      registerWorkspaceGatewayMethods({ api, store: new WorkspaceStore({ stateDir }) });
-      const broadcast = vi.fn();
-
-      const response = await callMethod(
-        methods.get("workspaces.tab.create")!,
-        { title: "Bad", unexpected: true },
-        broadcast,
-      );
-
-      expect(response.response?.[0]).toBe(false);
-      expect(response.response?.[2]?.message).toContain("unexpected param");
-      expect(broadcast).not.toHaveBeenCalled();
-    });
-  });
-
-  it("applies widget, workspace replace, undo, and data read methods", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const { api, methods } = createApi();
-      registerWorkspaceGatewayMethods({
-        api,
-        store: new WorkspaceStore({ stateDir }),
-      });
-      const broadcast = vi.fn();
-
-      await callMethod(
-        methods.get("workspaces.tab.create")!,
-        { slug: "ops", title: "Ops" },
-        broadcast,
-      );
-      await callMethod(
-        methods.get("workspaces.widget.add")!,
-        {
-          tab: "ops",
-          widget: {
-            kind: "builtin:markdown",
-            title: "Notes",
-            grid: { x: 0, y: 0, w: 4, h: 2 },
-          },
-        },
-        broadcast,
-      );
-      const updated = await callMethod(
-        methods.get("workspaces.widget.update")!,
-        { tab: "ops", id: "notes", patch: { collapsed: true } },
-        broadcast,
-      );
-      expect(
-        updated.response?.[1]?.doc.tabs.find((tab: { slug: string }) => tab.slug === "ops"),
-      ).toMatchObject({
-        widgets: [expect.objectContaining({ id: "notes", collapsed: true })],
-      });
-
-      await callMethod(
-        methods.get("workspaces.widget.move")!,
-        { tab: "ops", id: "notes", grid: { x: 4, y: 0, w: 4, h: 2 } },
-        broadcast,
-      );
-      const ambiguousMove = await callMethod(
-        methods.get("workspaces.widget.move")!,
-        { tab: "ops", id: "notes", grid: { x: 0, y: 0, w: 4, h: 2 }, toTab: "main" },
-        broadcast,
-      );
-      expect(ambiguousMove.response?.[0]).toBe(false);
-      expect(ambiguousMove.response?.[2]?.message).toContain("not both");
-      await callMethod(
-        methods.get("workspaces.widget.setLayout")!,
-        { tab: "ops", layout: [{ id: "notes", grid: { x: 0, y: 3, w: 6, h: 3 } }] },
-        broadcast,
-      );
-      // Approval decides on a scaffolded widget; it cannot mint a registry entry.
-      const orphanApprove = await callMethod(
-        methods.get("workspaces.widget.approve")!,
-        { name: "custom-chart", decision: "approved" },
-        broadcast,
-      );
-      expect(orphanApprove.response?.[0]).toBe(false);
-      expect(orphanApprove.response?.[2]?.message).toContain("not found");
-
-      const scaffolded = await callMethod(
-        methods.get("workspaces.widget.scaffold")!,
-        { name: "custom-chart" },
-        broadcast,
-      );
-      expect(scaffolded.response?.[1]?.registry).toEqual({
-        status: "pending",
-        createdBy: "user",
-      });
-      const approved = await callMethod(
-        methods.get("workspaces.widget.approve")!,
-        { name: "custom-chart", decision: "approved" },
-        broadcast,
-      );
-      // Approvals-only callers get the registry entry, never the whole document.
-      expect(approved.response?.[1]).toMatchObject({
-        name: "custom-chart",
-        registry: { status: "approved", approvedBy: "user" },
-      });
-      expect(approved.response?.[1]?.doc).toBeUndefined();
-      const frame = await callMethod(
-        methods.get("workspaces.widget.frame")!,
-        { name: "custom-chart" },
-        broadcast,
-      );
-      expect(frame.response?.[0]).toBe(true);
-      expect(frame.response?.[1]).toMatchObject({
-        manifest: { name: "custom-chart", entrypoint: "index.html" },
-        frameToken: expect.stringMatching(/^[A-Za-z0-9_-]{40,}$/),
-        frameExpiresAt: expect.any(Number),
-      });
-      const data = await callMethod(
-        methods.get("workspaces.data.read")!,
-        { binding: { source: "static", value: { ok: true } } },
-        broadcast,
-      );
-      expect(data.response?.[1]).toEqual({ data: { ok: true } });
-      const rpcData = await callMethod(
-        methods.get("workspaces.data.read")!,
-        { binding: { source: "rpc", method: "sessions.list" } },
-        broadcast,
-      );
-      expect(rpcData.response?.[0]).toBe(false);
-      expect(rpcData.response?.[2]).toMatchObject({ code: "binding_client_resolved" });
-
-      const beforeReplace = await callMethod(methods.get("workspaces.get")!, {}, broadcast);
-      const replacement = structuredClone(beforeReplace.response?.[1]?.doc);
-      replacement.tabs = [replacement.tabs.find((tab: { slug: string }) => tab.slug === "ops")];
-      replacement.prefs.tabOrder = ["ops"];
-      await callMethod(methods.get("workspaces.replace")!, { doc: replacement }, broadcast);
-
-      const undo = await callMethod(methods.get("workspaces.undo")!, {}, broadcast);
-      expect(undo.response?.[0]).toBe(true);
-      expect(
-        undo.response?.[1]?.doc.tabs.some((tab: { slug: string }) => tab.slug === "main"),
-      ).toBe(true);
-      // create + add + update + move + setLayout + scaffold + approve + replace + undo
-      expect(broadcast).toHaveBeenCalledTimes(9);
-    });
-  });
-});
-
-describe("workspace broadcast handle", () => {
-  it("keeps the current server broadcast so agent tools can announce changes off-request", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const { api, methods } = createApi();
-      registerWorkspaceGatewayMethods({ api, store: new WorkspaceStore({ stateDir }) });
-      const initialBroadcast = vi.fn();
-      const currentBroadcast = vi.fn();
-
-      // A read populates the slot; agent turns started from a channel or cron have
-      // no gateway request scope and rely on it.
-      await callMethod(methods.get("workspaces.get")!, {}, initialBroadcast);
-      expect(workspaceBroadcast()).toBe(initialBroadcast);
-
-      await callMethod(methods.get("workspaces.get")!, {}, currentBroadcast);
-      expect(workspaceBroadcast()).toBe(currentBroadcast);
-    });
-  });
-});
diff --git a/extensions/workspaces/src/gateway.ts b/extensions/workspaces/src/gateway.ts
deleted file mode 100644
index 0affa054f25..00000000000
--- a/extensions/workspaces/src/gateway.ts
+++ /dev/null
@@ -1,838 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { rememberWorkspaceBroadcast } from "./broadcast.js";
-import { resolveBinding, type ResolveBindingOptions } from "./data-read.js";
-import { snapshotApprovedWidget } from "./manifest.js";
-import { scaffoldWorkspaceWidget } from "./scaffold.js";
-import {
-  validateWorkspaceDoc,
-  type WorkspaceActor,
-  type WorkspaceBinding,
-  type WorkspaceGrid,
-  type WorkspaceTab,
-  type WorkspaceWidget,
-  type JsonValue,
-  type WorkspaceDoc,
-} from "./schema.js";
-import { WorkspaceStore } from "./store.js";
-
-const READ_SCOPE = "operator.read" as const;
-const WRITE_SCOPE = "operator.write" as const;
-// Approving agent-authored widget code is an approval decision, not an ordinary
-// layout write: it is the gate that lets untrusted HTML mount and be served.
-// Holding operator.write must not be enough to self-approve.
-const APPROVE_SCOPE = "operator.approvals" as const;
-const TAB_SLUG_PATTERN = /^[a-z0-9-]{1,40}$/;
-const WIDGET_ID_PATTERN = /^[A-Za-z0-9_-]{1,48}$/;
-const CUSTOM_WIDGET_NAME_PATTERN = /^(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-
-type GatewayMethodContext = Parameters<
-  Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1]
->[0];
-type GatewayRespond = GatewayMethodContext["respond"];
-type GatewayBroadcast = GatewayMethodContext["context"]["broadcast"];
-
-type WorkspaceGatewayMethodOptions = {
-  api: OpenClawPluginApi;
-  store?: WorkspaceStore;
-  dataRead?: ResolveBindingOptions;
-};
-
-function respondError(respond: GatewayRespond, error: unknown) {
-  const code =
-    typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
-      ? error.code
-      : "workspace_error";
-  respond(false, undefined, { code, message: formatErrorMessage(error) });
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function approvedFilesMatch(left: Record<string, string>, right: Record<string, string>): boolean {
-  const leftKeys = Object.keys(left);
-  return (
-    leftKeys.length === Object.keys(right).length &&
-    leftKeys.every((key) => left[key] === right[key])
-  );
-}
-
-function readParams(params: unknown, allowedKeys: readonly string[]): Record<string, unknown> {
-  if (!isRecord(params)) {
-    throw new Error("params must be an object");
-  }
-  for (const key of Object.keys(params)) {
-    if (!allowedKeys.includes(key)) {
-      throw new Error(`unexpected param: ${key}`);
-    }
-  }
-  return params;
-}
-
-function readRequiredString(
-  record: Record<string, unknown>,
-  key: string,
-  description: string,
-): string {
-  const value = record[key];
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`${description} is required`);
-  }
-  return value.trim();
-}
-
-function readOptionalString(record: Record<string, unknown>, key: string): string | undefined {
-  const value = record[key];
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${key} must be a string`);
-  }
-  return value.trim();
-}
-
-// Gateway RPC is the operator's surface (Control UI and CLI). Provenance is
-// derived from the caller, never read from params: a caller-supplied `RPC_ACTOR`
-// would let an operator forge `agent:<id>` chips, and let any agent that can
-// reach an operator.write RPC forge `user`.
-const RPC_ACTOR: WorkspaceActor = "user";
-
-function readSlug(record: Record<string, unknown>, key = "slug"): string {
-  const slug = readRequiredString(record, key, key);
-  if (!TAB_SLUG_PATTERN.test(slug)) {
-    throw new Error(`${key} is invalid`);
-  }
-  return slug;
-}
-
-function readWidgetId(record: Record<string, unknown>, key = "id"): string {
-  const id = readRequiredString(record, key, key);
-  if (!WIDGET_ID_PATTERN.test(id)) {
-    throw new Error(`${key} is invalid`);
-  }
-  return id;
-}
-
-function readBooleanPatch(record: Record<string, unknown>, key: string): boolean | undefined {
-  if (!Object.hasOwn(record, key)) {
-    return undefined;
-  }
-  const value = record[key];
-  if (typeof value !== "boolean") {
-    throw new Error(`${key} must be a boolean`);
-  }
-  return value;
-}
-
-function readGrid(value: unknown, path = "grid"): WorkspaceGrid {
-  if (!isRecord(value)) {
-    throw new Error(`${path} must be an object`);
-  }
-  for (const key of Object.keys(value)) {
-    if (!["x", "y", "w", "h"].includes(key)) {
-      throw new Error(`${path}.${key} is not allowed`);
-    }
-  }
-  return {
-    x: readGridInt(value.x, `${path}.x`, 0, 11),
-    y: readGridInt(value.y, `${path}.y`, 0, 499),
-    w: readGridInt(value.w, `${path}.w`, 1, 12),
-    h: readGridInt(value.h, `${path}.h`, 1, 20),
-  };
-}
-
-function readGridInt(value: unknown, path: string, min: number, max: number): number {
-  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
-    throw new Error(`${path} must be an integer from ${min} to ${max}`);
-  }
-  return value as number;
-}
-
-function slugBase(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40)
-    .replace(/-+$/g, "");
-}
-
-function makeUniqueSlug(title: string, tabs: WorkspaceTab[]): string {
-  const used = new Set(tabs.map((tab) => tab.slug));
-  const base = slugBase(title) || "tab";
-  if (!used.has(base)) {
-    return base;
-  }
-  for (let index = 2; index < 1000; index += 1) {
-    const suffix = `-${index}`;
-    const candidate = `${base.slice(0, 40 - suffix.length)}${suffix}`;
-    if (!used.has(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error("could not generate a unique tab slug");
-}
-
-function makeWidgetIdBase(value: string): string {
-  return (
-    value
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "")
-      .slice(0, 48)
-      .replace(/-+$/g, "") || `w_${randomUUID().replaceAll("-", "").slice(0, 12)}`
-  );
-}
-
-function makeUniqueWidgetId(widget: Record<string, unknown>, doc: WorkspaceDoc): string {
-  const existing = new Set(doc.tabs.flatMap((tab) => tab.widgets.map((entry) => entry.id)));
-  const explicit = widget.id;
-  if (explicit !== undefined) {
-    if (typeof explicit !== "string" || !WIDGET_ID_PATTERN.test(explicit)) {
-      throw new Error("widget.id is invalid");
-    }
-    if (existing.has(explicit)) {
-      throw new Error(`duplicate widget id: ${explicit}`);
-    }
-    return explicit;
-  }
-  const title =
-    typeof widget.title === "string"
-      ? widget.title
-      : typeof widget.kind === "string"
-        ? widget.kind
-        : "widget";
-  const base = makeWidgetIdBase(title);
-  if (!existing.has(base)) {
-    return base;
-  }
-  for (let index = 2; index < 1000; index += 1) {
-    const suffix = `-${index}`;
-    const candidate = `${base.slice(0, 48 - suffix.length)}${suffix}`;
-    if (!existing.has(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error("could not generate a unique widget id");
-}
-
-function findTab(doc: WorkspaceDoc, slug: string): WorkspaceTab {
-  const tab = doc.tabs.find((entry) => entry.slug === slug);
-  if (!tab) {
-    throw new Error(`workspace tab not found: ${slug}`);
-  }
-  return tab;
-}
-
-function findWidget(tab: WorkspaceTab, id: string): WorkspaceWidget {
-  const widget = tab.widgets.find((entry) => entry.id === id);
-  if (!widget) {
-    throw new Error(`workspace widget not found: ${id}`);
-  }
-  return widget;
-}
-
-function readWidgetInput(
-  value: unknown,
-  doc: WorkspaceDoc,
-  actor: WorkspaceActor,
-): WorkspaceWidget {
-  if (!isRecord(value)) {
-    throw new Error("widget must be an object");
-  }
-  for (const key of Object.keys(value)) {
-    if (
-      !["id", "kind", "title", "grid", "collapsed", "hidden", "bindings", "props"].includes(key)
-    ) {
-      throw new Error(`widget.${key} is not allowed`);
-    }
-  }
-  const title = readOptionalString(value, "title");
-  return {
-    id: makeUniqueWidgetId(value, doc),
-    kind: readRequiredString(value, "kind", "widget.kind"),
-    ...(title !== undefined ? { title } : {}),
-    grid: readGrid(value.grid, "widget.grid"),
-    collapsed: value.collapsed === undefined ? false : readRequiredBoolean(value, "collapsed"),
-    hidden: value.hidden === undefined ? false : readRequiredBoolean(value, "hidden"),
-    createdBy: actor,
-    ...(value.bindings !== undefined
-      ? { bindings: value.bindings as Record<string, WorkspaceBinding> }
-      : {}),
-    ...(value.props !== undefined ? { props: value.props as JsonValue } : {}),
-  };
-}
-
-function readRequiredBoolean(record: Record<string, unknown>, key: string): boolean {
-  const value = record[key];
-  if (typeof value !== "boolean") {
-    throw new Error(`${key} must be a boolean`);
-  }
-  return value;
-}
-
-function readTabPatch(
-  value: unknown,
-): Partial<Pick<WorkspaceTab, "title" | "icon" | "hidden" | "layout">> {
-  const patch = readParams(value, ["title", "icon", "hidden", "layout"]);
-  const title = readOptionalString(patch, "title");
-  if (title !== undefined && (title.length < 1 || title.length > 80)) {
-    throw new Error("patch.title must be 1-80 characters");
-  }
-  const icon = readOptionalString(patch, "icon");
-  if (icon !== undefined && icon.length > 40) {
-    throw new Error("patch.icon must be 40 characters or fewer");
-  }
-  const hidden = readBooleanPatch(patch, "hidden");
-  const layout = patch.layout;
-  if (layout !== undefined && layout !== "grid" && layout !== "full") {
-    throw new Error('patch.layout must be "grid" or "full"');
-  }
-  return {
-    ...(title !== undefined ? { title } : {}),
-    ...(icon !== undefined ? { icon } : {}),
-    ...(hidden !== undefined ? { hidden } : {}),
-    ...(layout !== undefined ? { layout } : {}),
-  };
-}
-
-function readWidgetPatch(value: unknown): Partial<WorkspaceWidget> {
-  const patch = readParams(value, ["title", "grid", "collapsed", "hidden", "bindings", "props"]);
-  const title = readOptionalString(patch, "title");
-  if (title !== undefined && title.length > 80) {
-    throw new Error("patch.title must be 80 characters or fewer");
-  }
-  return {
-    ...(title !== undefined ? { title } : {}),
-    ...(patch.grid !== undefined ? { grid: readGrid(patch.grid, "patch.grid") } : {}),
-    ...(readBooleanPatch(patch, "collapsed") !== undefined
-      ? { collapsed: readBooleanPatch(patch, "collapsed")! }
-      : {}),
-    ...(readBooleanPatch(patch, "hidden") !== undefined
-      ? { hidden: readBooleanPatch(patch, "hidden")! }
-      : {}),
-    ...(patch.bindings !== undefined
-      ? { bindings: patch.bindings as Record<string, WorkspaceBinding> }
-      : {}),
-    ...(patch.props !== undefined ? { props: patch.props as JsonValue } : {}),
-  };
-}
-
-function readLayout(value: unknown): Array<{ id: string; grid: WorkspaceGrid }> {
-  if (!Array.isArray(value)) {
-    throw new Error("layout must be an array");
-  }
-  return value.map((entry, index) => {
-    const record = readParams(entry, ["id", "grid"]);
-    return {
-      id: readWidgetId(record),
-      grid: readGrid(record.grid, `layout[${index}].grid`),
-    };
-  });
-}
-
-function appendMissingTabsToOrder(doc: WorkspaceDoc): void {
-  const seen = new Set(doc.prefs.tabOrder);
-  for (const tab of doc.tabs) {
-    if (!seen.has(tab.slug)) {
-      doc.prefs.tabOrder.push(tab.slug);
-    }
-  }
-}
-
-function broadcastChange(
-  broadcast: GatewayBroadcast,
-  params: { doc: WorkspaceDoc; actor: WorkspaceActor; changedTabSlug?: string },
-) {
-  // Agent tool calls outside a gateway request reuse this handle; see broadcast.ts.
-  rememberWorkspaceBroadcast(broadcast);
-  broadcast("plugin.workspaces.changed", {
-    workspaceVersion: params.doc.workspaceVersion,
-    ...(params.changedTabSlug ? { changedTabSlug: params.changedTabSlug } : {}),
-    actor: params.actor,
-  });
-}
-
-async function respondWrite(
-  opts: GatewayMethodContext,
-  actor: WorkspaceActor,
-  changedTabSlug: string | undefined,
-  run: () => Promise<{ doc: WorkspaceDoc }>,
-) {
-  const result = await run();
-  broadcastChange(opts.context.broadcast, { doc: result.doc, actor, changedTabSlug });
-  opts.respond(true, { doc: result.doc, workspaceVersion: result.doc.workspaceVersion });
-}
-
-export function registerWorkspaceGatewayMethods(options: WorkspaceGatewayMethodOptions) {
-  const { api } = options;
-  const store = options.store ?? new WorkspaceStore();
-
-  api.registerGatewayMethod(
-    "workspaces.get",
-    async ({ respond, context }) => {
-      try {
-        rememberWorkspaceBroadcast(context.broadcast);
-        const doc = store.read();
-        respond(true, { doc, workspaceVersion: doc.workspaceVersion });
-      } catch (error) {
-        respondError(respond, error);
-      }
-    },
-    { scope: READ_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.frame",
-    async ({ params: rawParams, respond }) => {
-      try {
-        const params = readParams(rawParams, ["name"]);
-        const name = readRequiredString(params, "name", "name");
-        if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-          throw new Error("name is invalid");
-        }
-        const entry = store.widgetEntry(name);
-        if (entry?.status !== "approved" || !entry.approvedFiles) {
-          throw new Error(`workspace widget is not approved: ${name}`);
-        }
-        const snapshot = await snapshotApprovedWidget(name, { stateDir: store.stateDir });
-        if (!approvedFilesMatch(snapshot.files, entry.approvedFiles)) {
-          throw new Error(`workspace widget approval no longer matches: ${name}`);
-        }
-        const frameToken = store.assetTokens.issue(name, entry.approvedFiles);
-        const frameExpiresAt = store.assetTokens.expiresAt(frameToken, name);
-        if (frameExpiresAt === null) {
-          throw new Error(`workspace widget frame capability failed: ${name}`);
-        }
-        respond(true, {
-          manifest: snapshot.manifest,
-          frameToken,
-          frameExpiresAt,
-        });
-      } catch (error) {
-        respondError(respond, error);
-      }
-    },
-    { scope: READ_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.tab.create",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["slug", "title", "icon"]);
-        const title = readRequiredString(params, "title", "title");
-        const icon = readOptionalString(params, "icon");
-        const result = store.mutate(
-          (draft) => {
-            const slug =
-              params.slug === undefined ? makeUniqueSlug(title, draft.tabs) : readSlug(params);
-            if (draft.tabs.some((tab) => tab.slug === slug)) {
-              throw new Error(`workspace tab already exists: ${slug}`);
-            }
-            draft.tabs.push({
-              slug,
-              title,
-              ...(icon !== undefined ? { icon } : {}),
-              hidden: false,
-              createdBy: RPC_ACTOR,
-              widgets: [],
-            });
-            draft.prefs.tabOrder.push(slug);
-          },
-          { actor: RPC_ACTOR },
-        );
-        const changedTabSlug = result.doc.tabs.at(-1)?.slug;
-        broadcastChange(opts.context.broadcast, {
-          doc: result.doc,
-          actor: RPC_ACTOR,
-          changedTabSlug,
-        });
-        opts.respond(true, { doc: result.doc, workspaceVersion: result.doc.workspaceVersion });
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.tab.update",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["slug", "patch"]);
-        const slug = readSlug(params);
-        const patch = readTabPatch(params.patch);
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              Object.assign(findTab(draft, slug), patch);
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.tab.delete",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["slug"]);
-        const slug = readSlug(params);
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              const nextTabs = draft.tabs.filter((tab) => tab.slug !== slug);
-              if (nextTabs.length === draft.tabs.length) {
-                throw new Error(`workspace tab not found: ${slug}`);
-              }
-              draft.tabs = nextTabs;
-              draft.prefs.tabOrder = draft.prefs.tabOrder.filter((entry) => entry !== slug);
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.tab.reorder",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["order"]);
-        const order = readSlugOrder(params.order);
-        await respondWrite(opts, RPC_ACTOR, undefined, async () =>
-          store.mutate(
-            (draft) => {
-              const slugs = new Set(draft.tabs.map((tab) => tab.slug));
-              for (const slug of order) {
-                if (!slugs.has(slug)) {
-                  throw new Error(`workspace tab not found: ${slug}`);
-                }
-              }
-              draft.prefs.tabOrder = order;
-              appendMissingTabsToOrder(draft);
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.add",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["tab", "widget"]);
-        const slug = readRequiredString(params, "tab", "tab");
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              findTab(draft, slug).widgets.push(readWidgetInput(params.widget, draft, RPC_ACTOR));
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.update",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["tab", "id", "patch"]);
-        const slug = readRequiredString(params, "tab", "tab");
-        const id = readWidgetId(params);
-        const patch = readWidgetPatch(params.patch);
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              Object.assign(findWidget(findTab(draft, slug), id), patch);
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.move",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["tab", "id", "grid", "toTab"]);
-        if (params.grid !== undefined && params.toTab !== undefined) {
-          throw new Error("workspaces.widget.move accepts either grid or toTab, not both");
-        }
-        const id = readWidgetId(params);
-        const changedTabSlug =
-          typeof params.toTab === "string"
-            ? params.toTab
-            : typeof params.tab === "string"
-              ? params.tab
-              : undefined;
-        await respondWrite(opts, RPC_ACTOR, changedTabSlug, async () =>
-          store.mutate(
-            (draft) => {
-              if (params.grid !== undefined) {
-                const slug = readRequiredString(params, "tab", "tab");
-                findWidget(findTab(draft, slug), id).grid = readGrid(params.grid);
-                return;
-              }
-              const toTab = readRequiredString(params, "toTab", "toTab");
-              const destination = findTab(draft, toTab);
-              for (const tab of draft.tabs) {
-                const index = tab.widgets.findIndex((widget) => widget.id === id);
-                if (index >= 0) {
-                  destination.widgets.push(tab.widgets.splice(index, 1)[0]!);
-                  return;
-                }
-              }
-              throw new Error(`workspace widget not found: ${id}`);
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.remove",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["tab", "id"]);
-        const slug = readRequiredString(params, "tab", "tab");
-        const id = readWidgetId(params);
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              const tab = findTab(draft, slug);
-              const next = tab.widgets.filter((widget) => widget.id !== id);
-              if (next.length === tab.widgets.length) {
-                throw new Error(`workspace widget not found: ${id}`);
-              }
-              tab.widgets = next;
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.setLayout",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["tab", "layout"]);
-        const slug = readRequiredString(params, "tab", "tab");
-        const layout = readLayout(params.layout);
-        await respondWrite(opts, RPC_ACTOR, slug, async () =>
-          store.mutate(
-            (draft) => {
-              const tab = findTab(draft, slug);
-              for (const entry of layout) {
-                findWidget(tab, entry.id).grid = entry.grid;
-              }
-            },
-            { actor: RPC_ACTOR },
-          ),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  // Scaffolding over RPC exists so the CLI creates a widget through the same
-  // store path the agent tool uses. Without it the CLI had to read-modify-write
-  // the whole document through `workspace.replace`, which is both racy and the
-  // only way it could mark its own widget approved.
-  api.registerGatewayMethod(
-    "workspaces.widget.scaffold",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["name", "title"]);
-        const name = readRequiredString(params, "name", "name");
-        const title = readOptionalString(params, "title");
-        const scaffold = await scaffoldWorkspaceWidget({
-          name,
-          ...(title !== undefined ? { title } : {}),
-          stateDir: store.stateDir,
-          createdBy: RPC_ACTOR,
-        });
-        const result = store.mutate(
-          (draft) => {
-            // Operator-scaffolded or agent-scaffolded, a widget always starts
-            // pending: approval is a separate, separately-scoped decision.
-            draft.widgetsRegistry[scaffold.name] = { status: "pending", createdBy: RPC_ACTOR };
-          },
-          { actor: RPC_ACTOR },
-        );
-        broadcastChange(opts.context.broadcast, { doc: result.doc, actor: RPC_ACTOR });
-        opts.respond(true, {
-          ...scaffold,
-          registry: result.doc.widgetsRegistry[scaffold.name],
-          workspaceVersion: result.doc.workspaceVersion,
-        });
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.widget.approve",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["name", "decision"]);
-        const name = readRequiredString(params, "name", "name");
-        if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-          throw new Error("name is invalid");
-        }
-        const decision = readRequiredString(params, "decision", "decision");
-        if (decision !== "approved" && decision !== "rejected") {
-          throw new Error("decision must be approved or rejected");
-        }
-        // What the operator approves is the code on disk, not the name. Freeze a
-        // digest of every servable file: the route re-hashes what it reads, so an
-        // agent cannot win approval on one tree and then write another.
-        // One read of the widget directory: the manifest is parsed from the same
-        // bytes that are hashed, so no swap can slip between validation and freeze.
-        const approvedFiles =
-          decision === "approved"
-            ? (await snapshotApprovedWidget(name, { stateDir: store.stateDir })).files
-            : undefined;
-        const result = store.mutate(
-          (draft) => {
-            const existing = draft.widgetsRegistry[name];
-            if (!existing) {
-              throw new Error(`workspace widget not found: ${name}`);
-            }
-            draft.widgetsRegistry[name] = {
-              status: decision,
-              createdBy: existing.createdBy,
-              ...(approvedFiles
-                ? {
-                    approvedBy: RPC_ACTOR,
-                    approvedAt: new Date().toISOString(),
-                    approvedFiles,
-                  }
-                : {}),
-            };
-          },
-          { actor: RPC_ACTOR },
-        );
-        broadcastChange(opts.context.broadcast, { doc: result.doc, actor: RPC_ACTOR });
-        // A connection holding only operator.approvals must not read the workspace
-        // through this method; `workspaces.get` is the operator.read door.
-        opts.respond(true, {
-          name,
-          registry: result.doc.widgetsRegistry[name],
-          workspaceVersion: result.doc.workspaceVersion,
-        });
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: APPROVE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.replace",
-    async (opts) => {
-      try {
-        const params = readParams(opts.params, ["doc"]);
-        const doc = validateWorkspaceDoc(params.doc);
-        await respondWrite(opts, RPC_ACTOR, undefined, async () =>
-          store.replace(doc, { actor: RPC_ACTOR }),
-        );
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.undo",
-    async (opts) => {
-      try {
-        readParams(opts.params, []);
-        const doc = store.undo();
-        broadcastChange(opts.context.broadcast, { doc, actor: RPC_ACTOR });
-        opts.respond(true, { doc, workspaceVersion: doc.workspaceVersion });
-      } catch (error) {
-        respondError(opts.respond, error);
-      }
-    },
-    { scope: WRITE_SCOPE },
-  );
-
-  api.registerGatewayMethod(
-    "workspaces.data.read",
-    async ({ params: requestParams, respond }) => {
-      try {
-        const params = readParams(requestParams, ["binding"]);
-        respond(true, {
-          data: await resolveBinding(params.binding, options.dataRead),
-        });
-      } catch (error) {
-        respondError(respond, error);
-      }
-    },
-    { scope: READ_SCOPE },
-  );
-}
-
-function readSlugOrder(value: unknown): string[] {
-  if (!Array.isArray(value)) {
-    throw new Error("order must be an array");
-  }
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (typeof entry !== "string" || !TAB_SLUG_PATTERN.test(entry)) {
-      throw new Error(`order[${index}] is invalid`);
-    }
-    if (seen.has(entry)) {
-      throw new Error(`order contains duplicate slug: ${entry}`);
-    }
-    seen.add(entry);
-    return entry;
-  });
-}
-/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/extensions/workspaces/src/http-route.ts b/extensions/workspaces/src/http-route.ts
deleted file mode 100644
index 0c2a8537ec6..00000000000
--- a/extensions/workspaces/src/http-route.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-// Plugin HTTP route adapter for serving approved custom-widget assets.
-//
-// Registered with `auth:"plugin"` because sandboxed iframes carry no device
-// token. The authenticated gateway mints a scoped asset capability first; the
-// route validates it on every request. This adapter only translates the request;
-// all capability, jail, approval, and header logic lives in `serve.ts`.
-
-import type { IncomingMessage, ServerResponse } from "node:http";
-import { serveWidgetAsset, WIDGETS_ROUTE_PREFIX } from "./serve.js";
-import type { WorkspaceStore } from "./store.js";
-
-export { WIDGETS_ROUTE_PREFIX };
-
-type WidgetHttpRouteHandler = {
-  handleHttpRequest: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
-};
-
-/** Creates the HTTP route handler bound to the shared workspace store. */
-export function createWidgetHttpRouteHandler(params: {
-  store: WorkspaceStore;
-  stateDir?: string;
-}): WidgetHttpRouteHandler {
-  return {
-    async handleHttpRequest(req, res) {
-      const url = new URL(req.url ?? "/", "http://localhost");
-      return await serveWidgetAsset({ method: req.method, pathname: url.pathname }, res, {
-        store: params.store,
-        ...(params.stateDir ? { stateDir: params.stateDir } : {}),
-      });
-    },
-  };
-}
diff --git a/extensions/workspaces/src/manifest.test.ts b/extensions/workspaces/src/manifest.test.ts
deleted file mode 100644
index 08271b724f6..00000000000
--- a/extensions/workspaces/src/manifest.test.ts
+++ /dev/null
@@ -1,215 +0,0 @@
-import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { resolveWidgetDir, snapshotApprovedWidget, validateWidgetManifest } from "./manifest.js";
-
-const VALID_MANIFEST = {
-  schemaVersion: 1,
-  name: "revenue-chart",
-  title: "Revenue Chart",
-  entrypoint: "index.html",
-  bindings: [{ id: "rev", source: "static", value: { revenue: 42 } }],
-  capabilities: ["data:read"],
-  preferredSize: { w: 6, h: 4 },
-};
-
-describe("validateWidgetManifest", () => {
-  it("accepts a well-formed manifest", () => {
-    expect(validateWidgetManifest(VALID_MANIFEST)).toEqual(VALID_MANIFEST);
-  });
-
-  it("rejects a future schemaVersion", () => {
-    expect(() => validateWidgetManifest({ ...VALID_MANIFEST, schemaVersion: 2 })).toThrow(
-      /schemaVersion must be 1/,
-    );
-  });
-
-  it("rejects an invalid widget name charset", () => {
-    expect(() => validateWidgetManifest({ ...VALID_MANIFEST, name: "../evil" })).toThrow(
-      /name is invalid/,
-    );
-  });
-
-  it("rejects prototype-setter widget and binding names", () => {
-    expect(() => validateWidgetManifest({ ...VALID_MANIFEST, name: "__proto__" })).toThrow(
-      /name is invalid/,
-    );
-    expect(() =>
-      validateWidgetManifest({
-        ...VALID_MANIFEST,
-        bindings: [{ id: "__proto__", source: "static", value: 1 }],
-      }),
-    ).toThrow(/id is invalid/);
-  });
-
-  it("rejects rpc bindings for custom code", () => {
-    expect(() =>
-      validateWidgetManifest({
-        ...VALID_MANIFEST,
-        bindings: [{ id: "x", source: "rpc", method: "sessions.delete" }],
-      }),
-    ).toThrow(/source must be static/);
-  });
-
-  it("rejects file bindings for custom code", () => {
-    expect(() =>
-      validateWidgetManifest({
-        ...VALID_MANIFEST,
-        bindings: [{ id: "x", source: "file", path: "../../etc/passwd" }],
-      }),
-    ).toThrow(/source must be static/);
-  });
-
-  it("rejects an entrypoint that escapes the widget dir", () => {
-    expect(() =>
-      validateWidgetManifest({ ...VALID_MANIFEST, entrypoint: "../index.html" }),
-    ).toThrow();
-  });
-
-  it("rejects an unknown capability", () => {
-    expect(() =>
-      validateWidgetManifest({ ...VALID_MANIFEST, capabilities: ["data:write"] }),
-    ).toThrow(/capability is invalid/);
-  });
-
-  it("accepts the prompt:send capability", () => {
-    const manifest = validateWidgetManifest({
-      ...VALID_MANIFEST,
-      capabilities: ["data:read", "prompt:send"],
-    });
-    expect(manifest.capabilities).toEqual(["data:read", "prompt:send"]);
-  });
-
-  it("rejects duplicate binding ids", () => {
-    expect(() =>
-      validateWidgetManifest({
-        ...VALID_MANIFEST,
-        bindings: [
-          { id: "dup", source: "static", value: 1 },
-          { id: "dup", source: "static", value: 2 },
-        ],
-      }),
-    ).toThrow(/duplicate binding id/);
-  });
-
-  it("rejects unexpected top-level keys", () => {
-    expect(() => validateWidgetManifest({ ...VALID_MANIFEST, extra: true })).toThrow(
-      /is not allowed/,
-    );
-  });
-
-  it("rejects a name that does not match the directory when expected", () => {
-    expect(() => validateWidgetManifest(VALID_MANIFEST, "other-name")).toThrow(
-      /does not match its directory/,
-    );
-  });
-});
-
-describe("resolveWidgetDir", () => {
-  it("rejects a name with a path separator", () => {
-    expect(() => resolveWidgetDir("a/b")).toThrow(/name is invalid/);
-  });
-
-  it("rejects a traversal name", () => {
-    expect(() => resolveWidgetDir("..")).toThrow(/name is invalid/);
-  });
-
-  it("resolves a valid name under the widgets root", () => {
-    const dir = resolveWidgetDir("revenue-chart", "/tmp/state");
-    expect(dir).toBe(path.resolve("/tmp/state", "workspaces", "widgets", "revenue-chart"));
-  });
-});
-
-describe("snapshotApprovedWidget", () => {
-  it("parses the manifest from the same bytes it hashes", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      const snapshot = await snapshotApprovedWidget("demo", { stateDir });
-      const digestOfHashedManifest = snapshot.files["widget.json"];
-
-      // The manifest the caller receives must be the one whose digest was frozen:
-      // reading widget.json twice would let it change in between, so an operator
-      // could validate one entrypoint while a different one got served.
-      const bytes = await fs.readFile(path.join(widgetDir, "widget.json"));
-      expect(createHash("sha256").update(bytes).digest("hex")).toBe(digestOfHashedManifest);
-      expect(snapshot.manifest.entrypoint).toBe("index.html");
-      expect(snapshot.files[snapshot.manifest.entrypoint]).toBeDefined();
-    });
-  });
-
-  it("refuses a widget whose declared entrypoint does not exist", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      await fs.rm(path.join(widgetDir, "index.html"));
-
-      await expect(snapshotApprovedWidget("demo", { stateDir })).rejects.toThrow(
-        "entrypoint is missing",
-      );
-    });
-  });
-
-  it("refuses to hash an oversized widget asset", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      // Pending widget files are agent-authored; approval must not read an
-      // arbitrarily large file into memory.
-      await fs.writeFile(path.join(widgetDir, "huge.png"), Buffer.alloc(2 * 1024 * 1024 + 1));
-
-      await expect(snapshotApprovedWidget("demo", { stateDir })).rejects.toThrow("too large");
-    });
-  });
-
-  it("refuses to approve a hardlink to a file outside the widget directory", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      const outsideFile = path.join(stateDir, "outside-secret.txt");
-      await fs.writeFile(outsideFile, "top secret");
-      await fs.link(outsideFile, path.join(widgetDir, "leak.txt"));
-
-      await expect(snapshotApprovedWidget("demo", { stateDir })).rejects.toThrow(
-        "widget file is unsafe: leak.txt",
-      );
-    });
-  });
-
-  it("refuses to approve a symlink substituted for the widget directory", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      const outsideDir = path.join(stateDir, "outside-widget");
-      await fs.rename(widgetDir, outsideDir);
-      await fs.symlink(outsideDir, widgetDir, "dir");
-
-      await expect(snapshotApprovedWidget("demo", { stateDir })).rejects.toThrow();
-    });
-  });
-
-  it("refuses a widget with no manifest at all", async () => {
-    await withWidget(async ({ stateDir, widgetDir }) => {
-      await fs.rm(path.join(widgetDir, "widget.json"));
-
-      await expect(snapshotApprovedWidget("demo", { stateDir })).rejects.toThrow("not found");
-    });
-  });
-});
-
-async function withWidget(
-  run: (ctx: { stateDir: string; widgetDir: string }) => Promise<void>,
-): Promise<void> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-manifest-"));
-  try {
-    const widgetDir = path.join(stateDir, "workspaces", "widgets", "demo");
-    await fs.mkdir(widgetDir, { recursive: true });
-    await fs.writeFile(
-      path.join(widgetDir, "widget.json"),
-      JSON.stringify({
-        schemaVersion: 1,
-        name: "demo",
-        title: "Demo",
-        entrypoint: "index.html",
-        bindings: [],
-        capabilities: [],
-      }),
-    );
-    await fs.writeFile(path.join(widgetDir, "index.html"), "<h1>demo</h1>");
-    await run({ stateDir, widgetDir });
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
diff --git a/extensions/workspaces/src/manifest.ts b/extensions/workspaces/src/manifest.ts
deleted file mode 100644
index 8c79f4292f0..00000000000
--- a/extensions/workspaces/src/manifest.ts
+++ /dev/null
@@ -1,369 +0,0 @@
-// Custom-widget `widget.json` manifest load + validation (schema per 00 §2).
-//
-// The manifest is the sole source of truth for what a sandboxed widget is allowed
-// to do: which static binding ids it may request, which capabilities it holds, and
-// its entrypoint. The parent bridge (UI side) re-checks every child request against
-// the manifest the operator approved and never resolves RPC/file bindings for custom
-// code. Hand-written guards mirror `schema.ts` (no zod).
-
-import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { FsSafeError, root as fsRoot } from "openclaw/plugin-sdk/security-runtime";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import { normalizeWorkspaceDataLogicalPath } from "./binding-contract.js";
-
-export const CUSTOM_WIDGET_NAME_PATTERN = /^(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-
-/**
- * Content types the widget route will serve, keyed by lowercase extension. Owned
- * here because approval hashes exactly the set of files the route can hand to a
- * browser — the two must never drift.
- */
-export const WIDGET_CONTENT_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".webp": "image/webp",
-  ".woff2": "font/woff2",
-  ".txt": "text/plain; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".csv": "text/csv; charset=utf-8",
-};
-
-/** Max servable files one widget may have; keeps the approval digest bounded. */
-const MAX_WIDGET_FILES = 64;
-const MAX_WIDGET_TREE_ENTRIES = 256;
-/**
- * Byte caps on the assets approval hashes. Pending widget files are agent-authored
- * and untrusted: without a cap, dropping one huge file into the scaffold directory
- * would make approval read it into memory and stall or OOM the gateway.
- */
-export const MAX_WIDGET_FILE_BYTES = 2 * 1024 * 1024;
-const MAX_WIDGET_TOTAL_BYTES = 8 * 1024 * 1024;
-
-/** sha256 of one file's bytes, lowercase hex. */
-function hashBytes(bytes: Buffer): string {
-  return createHash("sha256").update(bytes).digest("hex");
-}
-
-type ApprovedWidgetSnapshot = {
-  /** sha256 of every servable file, keyed by the logical path the route serves. */
-  files: Record<string, string>;
-  /** Parsed from the exact `widget.json` bytes that were hashed. */
-  manifest: WidgetManifest;
-};
-
-type WidgetRoot = Awaited<ReturnType<typeof fsRoot>>;
-
-async function listServableWidgetFiles(
-  stateRoot: WidgetRoot,
-  widgetRelativeDir: string,
-): Promise<string[]> {
-  const files: string[] = [];
-  let entriesSeen = 0;
-  async function visit(relativeDir: string, logicalDir: string): Promise<void> {
-    const entries = await stateRoot.list(relativeDir, { withFileTypes: true });
-    for (const entry of entries) {
-      entriesSeen += 1;
-      if (entriesSeen > MAX_WIDGET_TREE_ENTRIES) {
-        throw new Error(`widget has more than ${MAX_WIDGET_TREE_ENTRIES} filesystem entries`);
-      }
-      const relative = path.posix.join(relativeDir, entry.name);
-      const logical = path.posix.join(logicalDir, entry.name);
-      if (entry.isDirectory) {
-        await visit(relative, logical);
-      } else if (entry.isFile && path.extname(logical).toLowerCase() in WIDGET_CONTENT_TYPES) {
-        files.push(logical);
-      }
-    }
-  }
-  await visit(widgetRelativeDir, "");
-  return files;
-}
-
-/**
- * Reads a widget's directory once and returns both the digests of every servable
- * file and the manifest parsed from the very bytes that were hashed.
- *
- * This is what an operator approves. Hashing matters because "approved" must name
- * the code, not the directory: otherwise an agent could win approval on an
- * innocuous tree and write the real payload afterwards. Parsing the manifest from
- * the hashed bytes matters for the same reason one level up — reading `widget.json`
- * twice would let it change between the read that validates the entrypoint and the
- * read that freezes the digest, so the operator would approve one manifest while a
- * different one got served.
- */
-export async function snapshotApprovedWidget(
-  name: string,
-  options: { stateDir?: string } = {},
-): Promise<ApprovedWidgetSnapshot> {
-  const stateDir = path.resolve(options.stateDir ?? resolveStateDir());
-  const widgetDir = resolveWidgetDir(name, stateDir);
-  const widgetRelativeDir = path.posix.join("workspaces", "widgets", name);
-  let widgetRoot: WidgetRoot;
-  let widgetReal: string;
-  let logicalFiles: string[];
-  try {
-    widgetRoot = await fsRoot(stateDir, {
-      hardlinks: "reject",
-      maxBytes: MAX_WIDGET_FILE_BYTES,
-      nonBlockingRead: true,
-      symlinks: "reject",
-    });
-    const widgetStat = await fs.lstat(widgetDir);
-    widgetReal = await fs.realpath(widgetDir);
-    const expectedWidgetReal = path.join(widgetRoot.rootReal, "workspaces", "widgets", name);
-    if (
-      widgetStat.isSymbolicLink() ||
-      !widgetStat.isDirectory() ||
-      widgetReal !== expectedWidgetReal
-    ) {
-      throw new Error("widget directory is unsafe");
-    }
-    logicalFiles = await listServableWidgetFiles(widgetRoot, widgetRelativeDir);
-  } catch (error) {
-    if (
-      (error as NodeJS.ErrnoException).code === "ENOENT" ||
-      (error instanceof FsSafeError && error.code === "not-found")
-    ) {
-      throw new Error(`workspace widget not found: ${name}`, { cause: error });
-    }
-    throw error;
-  }
-  const files: Record<string, string> = {};
-  let manifestBytes: Buffer | undefined;
-  let totalBytes = 0;
-  for (const logical of logicalFiles) {
-    if (Object.keys(files).length >= MAX_WIDGET_FILES) {
-      throw new Error(`widget has more than ${MAX_WIDGET_FILES} servable files`);
-    }
-    let bytes: Buffer;
-    try {
-      // Pin and validate the opened file before reading. A same-user agent can
-      // create hardlinks, so path containment alone cannot define approval.
-      const read = await widgetRoot.read(path.posix.join(widgetRelativeDir, logical), {
-        hardlinks: "reject",
-        maxBytes: MAX_WIDGET_FILE_BYTES,
-        nonBlockingRead: true,
-        symlinks: "reject",
-      });
-      // The state-root reader blocks escapes, while this identity check also
-      // blocks a widget-directory swap to another location inside stateDir.
-      if (read.realPath !== widgetReal && !read.realPath.startsWith(`${widgetReal}${path.sep}`)) {
-        throw new Error("widget directory changed during approval");
-      }
-      bytes = read.buffer;
-    } catch (error) {
-      if (error instanceof FsSafeError && error.code === "too-large") {
-        throw new Error(`widget file is too large: ${logical}`, { cause: error });
-      }
-      throw new Error(`widget file is unsafe: ${logical}`, { cause: error });
-    }
-    totalBytes += bytes.byteLength;
-    if (totalBytes > MAX_WIDGET_TOTAL_BYTES) {
-      throw new Error("widget assets exceed the approval size limit");
-    }
-    files[logical] = hashBytes(bytes);
-    if (logical === "widget.json") {
-      manifestBytes = bytes;
-    }
-  }
-  if (!manifestBytes || manifestBytes.byteLength > MANIFEST_MAX_BYTES) {
-    throw new Error(`workspace widget not found: ${name}`);
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(manifestBytes.toString("utf8"));
-  } catch (error) {
-    throw new Error("widget.json is not valid JSON", { cause: error });
-  }
-  const manifest = validateWidgetManifest(parsed, name);
-  if (!files[manifest.entrypoint]) {
-    throw new Error(`workspace widget entrypoint is missing: ${manifest.entrypoint}`);
-  }
-  return { files, manifest };
-}
-
-/** True when `bytes` are exactly what was approved for `logicalPath`. */
-export function matchesApprovedFile(
-  approvedFiles: Record<string, string> | undefined,
-  logicalPath: string,
-  bytes: Buffer,
-): boolean {
-  const expected = approvedFiles?.[logicalPath];
-  return expected !== undefined && expected === hashBytes(bytes);
-}
-const BINDING_ID_PATTERN = /^(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-const WIDGET_CAPABILITIES = ["data:read", "prompt:send"] as const;
-
-type WidgetCapability = (typeof WIDGET_CAPABILITIES)[number];
-
-type WidgetManifestBinding = { id: string; source: "static"; value: unknown };
-
-type WidgetManifest = {
-  schemaVersion: 1;
-  name: string;
-  title: string;
-  entrypoint: string;
-  bindings: WidgetManifestBinding[];
-  capabilities: WidgetCapability[];
-  preferredSize?: { w: number; h: number };
-};
-
-const MANIFEST_MAX_BYTES = 32 * 1024;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function assertRecord(value: unknown, at: string): Record<string, unknown> {
-  if (!isRecord(value)) {
-    throw new Error(`${at} must be an object`);
-  }
-  return value;
-}
-
-function assertKnownKeys(
-  record: Record<string, unknown>,
-  allowed: readonly string[],
-  at: string,
-): void {
-  for (const key of Object.keys(record)) {
-    if (!allowed.includes(key)) {
-      throw new Error(`${at}.${key} is not allowed`);
-    }
-  }
-}
-
-function requireString(record: Record<string, unknown>, key: string, at: string): string {
-  const value = record[key];
-  if (typeof value !== "string") {
-    throw new Error(`${at}.${key} must be a string`);
-  }
-  return value;
-}
-
-function assertIntegerRange(value: unknown, at: string, min: number, max: number): number {
-  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
-    throw new Error(`${at} must be an integer from ${min} to ${max}`);
-  }
-  return value as number;
-}
-
-function validateBinding(value: unknown, at: string): WidgetManifestBinding {
-  const record = assertRecord(value, at);
-  const id = requireString(record, "id", at);
-  if (!BINDING_ID_PATTERN.test(id)) {
-    throw new Error(`${at}.id is invalid`);
-  }
-  const source = requireString(record, "source", at);
-  if (source === "static") {
-    assertKnownKeys(record, ["id", "source", "value"], at);
-    return { id, source, value: record.value };
-  }
-  throw new Error(`${at}.source must be static`);
-}
-
-function validateCapabilities(value: unknown): WidgetCapability[] {
-  if (value === undefined) {
-    return [];
-  }
-  if (!Array.isArray(value)) {
-    throw new Error("capabilities must be an array");
-  }
-  const seen = new Set<WidgetCapability>();
-  for (const entry of value) {
-    if (typeof entry !== "string" || !WIDGET_CAPABILITIES.includes(entry as WidgetCapability)) {
-      throw new Error(`capability is invalid: ${String(entry)}`);
-    }
-    seen.add(entry as WidgetCapability);
-  }
-  return [...seen];
-}
-
-/** Validates a parsed `widget.json` object against the schema (00 §2). */
-export function validateWidgetManifest(value: unknown, expectedName?: string): WidgetManifest {
-  const record = assertRecord(value, "widget.json");
-  assertKnownKeys(
-    record,
-    ["schemaVersion", "name", "title", "entrypoint", "bindings", "capabilities", "preferredSize"],
-    "widget.json",
-  );
-  if (record.schemaVersion !== 1) {
-    throw new Error("widget.json schemaVersion must be 1");
-  }
-  const name = requireString(record, "name", "widget.json");
-  if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-    throw new Error("widget.json name is invalid");
-  }
-  if (expectedName !== undefined && name !== expectedName) {
-    throw new Error("widget.json name does not match its directory");
-  }
-  const title = requireString(record, "title", "widget.json");
-  if (title.length < 1 || title.length > 80) {
-    throw new Error("widget.json title must be 1-80 characters");
-  }
-  const entrypoint = requireString(record, "entrypoint", "widget.json");
-  // The entrypoint is a logical path served through the jail; normalize it the
-  // same way the serving route does so a manifest cannot name an out-of-dir file.
-  normalizeWorkspaceDataLogicalPath(entrypoint);
-  const rawBindings = record.bindings;
-  if (!Array.isArray(rawBindings)) {
-    throw new Error("widget.json bindings must be an array");
-  }
-  if (rawBindings.length > 32) {
-    throw new Error("widget.json bindings must contain at most 32 entries");
-  }
-  const bindings = rawBindings.map((binding, index) =>
-    validateBinding(binding, `widget.json.bindings[${index}]`),
-  );
-  const ids = new Set<string>();
-  for (const binding of bindings) {
-    if (ids.has(binding.id)) {
-      throw new Error(`widget.json duplicate binding id: ${binding.id}`);
-    }
-    ids.add(binding.id);
-  }
-  const capabilities = validateCapabilities(record.capabilities);
-  const preferredSize =
-    record.preferredSize === undefined
-      ? undefined
-      : (() => {
-          const size = assertRecord(record.preferredSize, "widget.json.preferredSize");
-          assertKnownKeys(size, ["w", "h"], "widget.json.preferredSize");
-          return {
-            w: assertIntegerRange(size.w, "widget.json.preferredSize.w", 1, 12),
-            h: assertIntegerRange(size.h, "widget.json.preferredSize.h", 1, 20),
-          };
-        })();
-  return {
-    schemaVersion: 1,
-    name,
-    title,
-    entrypoint,
-    bindings,
-    capabilities,
-    ...(preferredSize !== undefined ? { preferredSize } : {}),
-  };
-}
-
-/** Resolves the on-disk directory for one custom widget by name. */
-export function resolveWidgetDir(name: string, stateDir = resolveStateDir()): string {
-  if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-    throw new Error("widget name is invalid");
-  }
-  const widgetsRoot = path.resolve(stateDir, "workspaces", "widgets");
-  const widgetDir = path.resolve(widgetsRoot, name);
-  // Belt-and-braces: the charset check already forbids separators, but confirm
-  // containment so the resolved directory can never escape the widgets root.
-  if (widgetDir !== widgetsRoot && !widgetDir.startsWith(`${widgetsRoot}${path.sep}`)) {
-    throw new Error("widget name is invalid");
-  }
-  return widgetDir;
-}
diff --git a/extensions/workspaces/src/scaffold.test.ts b/extensions/workspaces/src/scaffold.test.ts
deleted file mode 100644
index 3a427d2bfb0..00000000000
--- a/extensions/workspaces/src/scaffold.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { scaffoldWorkspaceWidget } from "./scaffold.js";
-
-const stateDirs: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(
-    stateDirs.splice(0).map((stateDir) => fs.rm(stateDir, { recursive: true, force: true })),
-  );
-});
-
-describe("scaffoldWorkspaceWidget", () => {
-  it("escapes apostrophes in generated HTML text nodes", async () => {
-    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-scaffold-"));
-    stateDirs.push(stateDir);
-
-    const result = await scaffoldWorkspaceWidget({
-      name: "team-status",
-      title: "Team's <status>",
-      createdBy: "agent's helper",
-      stateDir,
-    });
-    const html = await fs.readFile(path.join(result.dir, "index.html"), "utf8");
-
-    expect(html).toContain("<title>Team&#39;s &lt;status&gt;</title>");
-    expect(html).toContain("<h1>Team&#39;s &lt;status&gt;</h1>");
-    expect(html).toContain("<footer>Built by agent&#39;s helper</footer>");
-  });
-});
diff --git a/extensions/workspaces/src/scaffold.ts b/extensions/workspaces/src/scaffold.ts
deleted file mode 100644
index 986dcdc38f0..00000000000
--- a/extensions/workspaces/src/scaffold.ts
+++ /dev/null
@@ -1,177 +0,0 @@
-// Custom-widget scaffolding: creates the on-disk widget directory an agent (or an
-// operator) authors against. Kept as a leaf module so both the agent tools and the
-// gateway method can create a widget through the identical code path — the CLI must
-// not be able to author a widget any way the agent cannot, and vice versa.
-
-import fs from "node:fs/promises";
-import path from "node:path";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import { escapeHtml } from "openclaw/plugin-sdk/text-utility-runtime";
-import { validateWidgetManifest } from "./manifest.js";
-
-type WorkspaceScaffoldOptions = {
-  name: string;
-  title?: string;
-  stateDir?: string;
-  /** Provenance stamped into the scaffold's "built by" footer. */
-  createdBy?: string;
-};
-
-type WorkspaceScaffoldResult = {
-  name: string;
-  title: string;
-  dir: string;
-  manifestPath: string;
-  htmlPath: string;
-  readmePath: string;
-};
-
-const CUSTOM_WIDGET_NAME_PATTERN = /^(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-
-function scaffoldTitle(name: string, title: string | undefined): string {
-  if (title?.trim()) {
-    return title.trim();
-  }
-  return name
-    .replace(/[-_.]+/g, " ")
-    .replace(/\b\w/g, (char) => char.toUpperCase())
-    .trim();
-}
-
-function widgetManifest(name: string, title: string) {
-  return {
-    schemaVersion: 1,
-    name,
-    title,
-    entrypoint: "index.html",
-    bindings: [{ id: "value", source: "static", value: "Hello from your workspace widget." }],
-    capabilities: ["data:read"],
-    preferredSize: { w: 6, h: 4 },
-  };
-}
-
-function widgetHtml(title: string, createdBy: string): string {
-  return `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>${escapeHtml(title)}</title>
-  <style>
-    :root { color-scheme: light dark; --wg-bg: Canvas; --wg-text: CanvasText; --wg-accent: #ff5c5c; }
-    body { margin: 0; padding: 16px; font-family: var(--font-sans, system-ui, sans-serif);
-      background: var(--wg-bg); color: var(--wg-text); }
-    h1 { margin: 0 0 12px; font-size: 1.1rem; }
-    #value { white-space: pre-wrap; overflow-wrap: anywhere; }
-    footer { margin-top: 16px; font-size: 0.75rem; color: var(--wg-accent); }
-  </style>
-</head>
-<body>
-  <h1>${escapeHtml(title)}</h1>
-  <pre id="value">Waiting for workspace data...</pre>
-  <footer>Built by ${escapeHtml(createdBy)}</footer>
-  <script>
-    const valueNode = document.getElementById("value");
-    const bridge = window.openclawWorkspaceBridge;
-    function post(type, payload = {}) {
-      bridge.postMessage({ v: 1, type, ...payload });
-    }
-    function render(data) {
-      valueNode.textContent = typeof data === "string" ? data : JSON.stringify(data, null, 2);
-    }
-    function onData(message) {
-      render(message.data);
-    }
-    function applyTheme(tokens) {
-      const root = document.documentElement.style;
-      if (tokens["--bg"]) root.setProperty("--wg-bg", tokens["--bg"]);
-      if (tokens["--text"]) root.setProperty("--wg-text", tokens["--text"]);
-      if (tokens["--accent"]) root.setProperty("--wg-accent", tokens["--accent"]);
-    }
-    bridge.addEventListener("message", (event) => {
-      const message = event.data;
-      if (!message || message.v !== 1) return;
-      if (message.type === "workspace:data" || message.type === "workspace:push") onData(message);
-      else if (message.type === "workspace:theme") applyTheme(message.tokens || {});
-      else if (message.type === "workspace:error") render({ error: message.message });
-    });
-    post("workspace:ready");
-    post("workspace:getData", { requestId: "initial", bindingId: "value" });
-    post("workspace:getTheme", { requestId: "theme" });
-  </script>
-</body>
-</html>
-`;
-}
-
-function widgetReadme(name: string): string {
-  return `# ${name}
-
-This workspace widget runs inside a sandboxed iframe and talks to the parent
-Control UI through the document-bound workspace message bridge exposed as
-\`window.openclawWorkspaceBridge\`.
-
-- Send messages with \`window.openclawWorkspaceBridge.postMessage(...)\`.
-- Listen with \`window.openclawWorkspaceBridge.addEventListener("message", ...)\`.
-- Send \`{ "v": 1, "type": "workspace:ready" }\` when loaded.
-- Send \`workspace:getData\` with a \`requestId\` and \`bindingId\` to read a declared binding.
-- Re-render on \`workspace:data\` and \`workspace:push\`.
-- Do not fetch gateway data directly; the authenticated parent resolves bindings.
-`;
-}
-
-function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
-  return error instanceof Error && "code" in error;
-}
-
-export async function scaffoldWorkspaceWidget(
-  options: WorkspaceScaffoldOptions,
-): Promise<WorkspaceScaffoldResult> {
-  const name = options.name.trim();
-  if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-    throw new Error("widget name is invalid");
-  }
-  const widgetsRoot = path.resolve(options.stateDir ?? resolveStateDir(), "workspaces", "widgets");
-  const widgetDir = path.resolve(widgetsRoot, name);
-  // The charset pattern permits dots, so `.` and `..` pass it — containment is what
-  // actually keeps the directory inside the widgets root. Check it before anything
-  // else can report a different reason for rejecting the name.
-  if (widgetDir === widgetsRoot || !widgetDir.startsWith(`${widgetsRoot}${path.sep}`)) {
-    throw new Error("widget name is invalid");
-  }
-  const title = scaffoldTitle(name, options.title);
-  // Validate what we are about to write: the approval snapshot enforces the same
-  // schema, and a scaffold that cannot be approved is worse than a clear error.
-  validateWidgetManifest(widgetManifest(name, title), name);
-  await fs.mkdir(widgetsRoot, { recursive: true, mode: 0o700 });
-  try {
-    await fs.mkdir(widgetDir, { mode: 0o700 });
-  } catch (error) {
-    if (isErrnoException(error) && error.code === "EEXIST") {
-      throw new Error("widget already exists", { cause: error });
-    }
-    throw error;
-  }
-  const manifestPath = path.join(widgetDir, "widget.json");
-  const htmlPath = path.join(widgetDir, "index.html");
-  const readmePath = path.join(widgetDir, "README.md");
-  await Promise.all([
-    fs.writeFile(
-      `${manifestPath}.tmp`,
-      `${JSON.stringify(widgetManifest(name, title), null, 2)}\n`,
-      {
-        mode: 0o600,
-      },
-    ),
-    fs.writeFile(`${htmlPath}.tmp`, widgetHtml(title, options.createdBy ?? "an agent"), {
-      mode: 0o600,
-    }),
-    fs.writeFile(`${readmePath}.tmp`, widgetReadme(name), { mode: 0o600 }),
-  ]);
-  await Promise.all([
-    fs.rename(`${manifestPath}.tmp`, manifestPath),
-    fs.rename(`${htmlPath}.tmp`, htmlPath),
-    fs.rename(`${readmePath}.tmp`, readmePath),
-  ]);
-  return { name, title, dir: widgetDir, manifestPath, htmlPath, readmePath };
-}
diff --git a/extensions/workspaces/src/schema.test.ts b/extensions/workspaces/src/schema.test.ts
deleted file mode 100644
index 0b103b06321..00000000000
--- a/extensions/workspaces/src/schema.test.ts
+++ /dev/null
@@ -1,164 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DEFAULT_WORKSPACE } from "./default-workspace.js";
-import { validateWorkspaceDoc, type WorkspaceDoc } from "./schema.js";
-
-function validDoc(): WorkspaceDoc {
-  return structuredClone(DEFAULT_WORKSPACE);
-}
-
-function expectInvalid(mutator: (doc: WorkspaceDoc) => void, message: string) {
-  const doc = validDoc();
-  mutator(doc);
-
-  expect(() => validateWorkspaceDoc(doc)).toThrow(message);
-}
-
-describe("Workspaces document schema", () => {
-  it("accepts the default workspace seed", () => {
-    expect(validateWorkspaceDoc(validDoc())).toEqual(validDoc());
-  });
-
-  it.each(["builtin:agent-status", "builtin:custom-widget-approvals"])("accepts %s", (kind) => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets[0]!.kind = kind;
-    expect(validateWorkspaceDoc(doc).tabs[0]!.widgets[0]!.kind).toBe(kind);
-  });
-
-  it("accepts full-bleed tabs and rejects unknown layouts", () => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets = doc.tabs[0]!.widgets.slice(0, 1);
-    doc.tabs[0]!.layout = "full";
-    expect(validateWorkspaceDoc(doc).tabs[0]?.layout).toBe("full");
-    expectInvalid((invalid) => {
-      invalid.tabs[0]!.layout = "columns" as never;
-    }, 'layout must be "grid" or "full"');
-
-    expectInvalid((invalid) => {
-      invalid.tabs[0]!.layout = "full";
-      invalid.tabs[0]!.widgets.push({
-        ...structuredClone(invalid.tabs[0]!.widgets[0]!),
-        id: "second",
-      });
-    }, "at most one entry for full layout");
-  });
-
-  it("rejects invalid tab slugs", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.slug = "Bad Slug";
-    }, "tabs[0].slug");
-  });
-
-  it("rejects duplicate tab slugs", () => {
-    expectInvalid((doc) => {
-      doc.tabs.push({ ...structuredClone(doc.tabs[0]!), title: "Duplicate" });
-    }, "duplicate tab slug");
-  });
-
-  it("rejects widget grid overflow", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.grid = { x: 10, y: 0, w: 3, h: 2 };
-    }, "x + w");
-  });
-
-  it("rejects invalid widget kinds", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.kind = "builtin:unknown";
-    }, "widgets[0].kind");
-  });
-
-  it("accepts the trusted builtin chart kind", () => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets[0]!.kind = "builtin:chart";
-    expect(validateWorkspaceDoc(doc).tabs[0]!.widgets[0]!.kind).toBe("builtin:chart");
-  });
-
-  it("accepts the trusted builtin preview kind", () => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets[0]!.kind = "builtin:preview";
-    expect(validateWorkspaceDoc(doc).tabs[0]!.widgets[0]!.kind).toBe("builtin:preview");
-  });
-
-  it("rejects a prototype-setter custom widget kind", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.kind = "custom:__proto__";
-    }, "widgets[0].kind");
-  });
-
-  it("rejects invalid binding unions", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.bindings = {
-        bad: { source: "command", value: "date" } as never,
-      };
-    }, "bindings.bad.source");
-  });
-
-  it("rejects non-allowlisted rpc binding methods at write time", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.bindings = {
-        sessions: { source: "rpc", method: "config.get" },
-      };
-    }, "bindings.sessions.method is not allowlisted");
-  });
-
-  it("accepts bounded parameters for parameterized rpc methods", () => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets[0]!.bindings = {
-      session: { source: "rpc", method: "sessions.get", params: { key: "agent:main:main" } },
-    };
-
-    expect(validateWorkspaceDoc(doc).tabs[0]?.widgets[0]?.bindings?.session).toEqual({
-      source: "rpc",
-      method: "sessions.get",
-      params: { key: "agent:main:main" },
-    });
-  });
-
-  it("rejects prototype-setter binding and widget names", () => {
-    const doc = validDoc();
-    doc.tabs[0]!.widgets[0]!.bindings = JSON.parse(
-      '{"__proto__":{"source":"static","value":1}}',
-    ) as WorkspaceDoc["tabs"][number]["widgets"][number]["bindings"];
-    expect(() => validateWorkspaceDoc(doc)).toThrow("binding id is invalid");
-
-    doc.tabs[0]!.widgets[0]!.bindings = {};
-    doc.widgetsRegistry = JSON.parse(
-      '{"__proto__":{"status":"pending","createdBy":"agent:main"}}',
-    ) as WorkspaceDoc["widgetsRegistry"];
-    expect(() => validateWorkspaceDoc(doc)).toThrow("name is invalid");
-  });
-
-  it("rejects non-object and oversized rpc parameters", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.bindings = {
-        session: { source: "rpc", method: "sessions.get", params: [] } as never,
-      };
-    }, "bindings.session.params must be an object");
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets[0]!.bindings = {
-        session: { source: "rpc", method: "sessions.get", params: { key: "x".repeat(9_000) } },
-      };
-    }, "bindings.session.params must serialize to 8 KB or less");
-  });
-
-  it("rejects tabs and widgets over the caps", () => {
-    expectInvalid((doc) => {
-      doc.tabs = Array.from({ length: 33 }, (_, index) => ({
-        ...structuredClone(doc.tabs[0]!),
-        slug: `tab-${index}`,
-      }));
-    }, "tabs must contain at most 32 entries");
-
-    expectInvalid((doc) => {
-      doc.tabs[0]!.widgets = Array.from({ length: 25 }, (_, index) => ({
-        ...structuredClone(doc.tabs[0]!.widgets[0]!),
-        id: `w_${index}`,
-      }));
-    }, "widgets must contain at most 24 entries");
-  });
-
-  it("rejects invalid createdBy provenance", () => {
-    expectInvalid((doc) => {
-      doc.tabs[0]!.createdBy = "robot" as never;
-    }, "createdBy");
-  });
-});
diff --git a/extensions/workspaces/src/schema.ts b/extensions/workspaces/src/schema.ts
deleted file mode 100644
index 89934943130..00000000000
--- a/extensions/workspaces/src/schema.ts
+++ /dev/null
@@ -1,476 +0,0 @@
-import { DATA_READ_RPC_ALLOWLIST, normalizeWorkspaceDataLogicalPath } from "./binding-contract.js";
-
-export type JsonValue =
-  | null
-  | boolean
-  | number
-  | string
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-export type WorkspaceActor = "user" | "system" | `agent:${string}`;
-export type WorkspaceGrid = { x: number; y: number; w: number; h: number };
-type WorkspaceRpcBinding = {
-  source: "rpc";
-  method: string;
-  params?: Record<string, JsonValue>;
-};
-type WorkspaceFileBinding = { source: "file"; path: string; pointer?: string };
-type WorkspaceStaticBinding = { source: "static"; value: JsonValue };
-export type WorkspaceBinding = WorkspaceRpcBinding | WorkspaceFileBinding | WorkspaceStaticBinding;
-export type WorkspaceWidget = {
-  id: string;
-  kind: string;
-  title?: string;
-  grid: WorkspaceGrid;
-  collapsed: boolean;
-  hidden: boolean;
-  /** Provenance stamp; the Control UI renders an "AI" chip for `agent:<id>`. */
-  createdBy: WorkspaceActor;
-  bindings?: Record<string, WorkspaceBinding>;
-  props?: JsonValue;
-};
-export type WorkspaceTab = {
-  slug: string;
-  title: string;
-  icon?: string;
-  hidden: boolean;
-  /** Default grid, or a single app-like widget without grid chrome. */
-  layout?: "grid" | "full";
-  createdBy: WorkspaceActor;
-  widgets: WorkspaceWidget[];
-};
-export type WorkspaceWidgetRegistryEntry = {
-  status: "pending" | "approved" | "rejected";
-  createdBy: WorkspaceActor;
-  approvedBy?: WorkspaceActor;
-  approvedAt?: string;
-  /** sha256 of every servable file, keyed by logical path, frozen at approval. */
-  approvedFiles?: Record<string, string>;
-};
-export type WorkspaceDoc = {
-  schemaVersion: 1;
-  workspaceVersion: number;
-  tabs: WorkspaceTab[];
-  widgetsRegistry: Record<string, WorkspaceWidgetRegistryEntry>;
-  prefs: { tabOrder: string[] };
-};
-
-const CURRENT_WORKSPACE_SCHEMA_VERSION = 1;
-
-const TAB_SLUG_PATTERN = /^[a-z0-9-]{1,40}$/;
-const ACTOR_PATTERN = /^(user|system|agent:[A-Za-z0-9._-]{1,64})$/;
-const WIDGET_ID_PATTERN = /^[A-Za-z0-9_-]{1,48}$/;
-/** The trusted widget set. Exported so tool schemas can name them for the model. */
-export const BUILTIN_WIDGET_KINDS = [
-  "builtin:stat-card",
-  "builtin:markdown",
-  "builtin:table",
-  "builtin:iframe-embed",
-  "builtin:preview",
-  "builtin:sessions",
-  "builtin:usage",
-  "builtin:cron",
-  "builtin:instances",
-  "builtin:activity",
-  "builtin:chart",
-  "builtin:agent-status",
-  "builtin:custom-widget-approvals",
-] as const;
-
-const BUILTIN_KINDS = new Set<string>(BUILTIN_WIDGET_KINDS);
-const CUSTOM_KIND_PATTERN = /^custom:(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-const CUSTOM_WIDGET_NAME_PATTERN = /^(?!__proto__$)[A-Za-z0-9._-]{1,64}$/;
-const MAX_STATIC_BINDING_BYTES = 8 * 1024;
-const MAX_RPC_BINDING_PARAMS_BYTES = 8 * 1024;
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function assertRecord(value: unknown, path: string): Record<string, unknown> {
-  if (!isRecord(value)) {
-    throw new Error(`${path} must be an object`);
-  }
-  return value;
-}
-
-function assertKnownKeys(
-  record: Record<string, unknown>,
-  allowed: readonly string[],
-  path: string,
-): void {
-  for (const key of Object.keys(record)) {
-    if (!allowed.includes(key)) {
-      throw new Error(`${path}.${key} is not allowed`);
-    }
-  }
-}
-
-function requireString(record: Record<string, unknown>, key: string, path: string): string {
-  const value = record[key];
-  if (typeof value !== "string") {
-    throw new Error(`${path}.${key} must be a string`);
-  }
-  return value;
-}
-
-function optionalString(
-  record: Record<string, unknown>,
-  key: string,
-  path: string,
-): string | undefined {
-  const value = record[key];
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${path}.${key} must be a string`);
-  }
-  return value;
-}
-
-function requireBoolean(record: Record<string, unknown>, key: string, path: string): boolean {
-  const value = record[key];
-  if (typeof value !== "boolean") {
-    throw new Error(`${path}.${key} must be a boolean`);
-  }
-  return value;
-}
-
-function requireArray(value: unknown, path: string): unknown[] {
-  if (!Array.isArray(value)) {
-    throw new Error(`${path} must be an array`);
-  }
-  return value;
-}
-
-function validateActor(value: unknown, path: string): WorkspaceActor {
-  if (typeof value !== "string" || !ACTOR_PATTERN.test(value)) {
-    throw new Error(`${path} createdBy is invalid`);
-  }
-  return value as WorkspaceActor;
-}
-
-export function isWorkspaceActor(value: unknown): value is WorkspaceActor {
-  return typeof value === "string" && ACTOR_PATTERN.test(value);
-}
-
-function assertIntegerRange(value: unknown, path: string, min: number, max: number): number {
-  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
-    throw new Error(`${path} must be an integer from ${min} to ${max}`);
-  }
-  return value as number;
-}
-
-function validateGrid(value: unknown, path: string): WorkspaceGrid {
-  const record = assertRecord(value, path);
-  assertKnownKeys(record, ["x", "y", "w", "h"], path);
-  const grid = {
-    x: assertIntegerRange(record.x, `${path}.x`, 0, 11),
-    y: assertIntegerRange(record.y, `${path}.y`, 0, 499),
-    w: assertIntegerRange(record.w, `${path}.w`, 1, 12),
-    h: assertIntegerRange(record.h, `${path}.h`, 1, 20),
-  };
-  if (grid.x + grid.w > 12) {
-    throw new Error(`${path}.x + w must be 12 or less`);
-  }
-  return grid;
-}
-
-function assertJsonValue(value: unknown, path: string): JsonValue {
-  if (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value))
-  ) {
-    return value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry, index) => assertJsonValue(entry, `${path}[${index}]`));
-  }
-  if (isRecord(value)) {
-    const next: Record<string, JsonValue> = {};
-    for (const [key, entry] of Object.entries(value)) {
-      next[key] = assertJsonValue(entry, `${path}.${key}`);
-    }
-    return next;
-  }
-  throw new Error(`${path} must be JSON-serializable`);
-}
-
-function serializedBytes(value: unknown): number {
-  return Buffer.byteLength(JSON.stringify(value), "utf8");
-}
-
-function validateBinding(value: unknown, path: string): WorkspaceBinding {
-  const record = assertRecord(value, path);
-  const source = requireString(record, "source", path);
-  if (source === "rpc") {
-    assertKnownKeys(record, ["source", "method", "params"], path);
-    const method = requireString(record, "method", path);
-    if (!DATA_READ_RPC_ALLOWLIST.includes(method as (typeof DATA_READ_RPC_ALLOWLIST)[number])) {
-      throw new Error(
-        `${path}.method is not allowlisted; allowed: ${DATA_READ_RPC_ALLOWLIST.join(", ")}`,
-      );
-    }
-    const params =
-      record.params === undefined
-        ? undefined
-        : (assertJsonValue(
-            assertRecord(record.params, `${path}.params`),
-            `${path}.params`,
-          ) as Record<string, JsonValue>);
-    if (params !== undefined && serializedBytes(params) > MAX_RPC_BINDING_PARAMS_BYTES) {
-      throw new Error(`${path}.params must serialize to 8 KB or less`);
-    }
-    return { source, method, ...(params !== undefined ? { params } : {}) };
-  }
-  if (source === "file") {
-    assertKnownKeys(record, ["source", "path", "pointer"], path);
-    const bindingPath = requireString(record, "path", path);
-    normalizeWorkspaceDataLogicalPath(bindingPath);
-    const pointer = optionalString(record, "pointer", path);
-    return { source, path: bindingPath, ...(pointer !== undefined ? { pointer } : {}) };
-  }
-  if (source === "static") {
-    assertKnownKeys(record, ["source", "value"], path);
-    const jsonValue = assertJsonValue(record.value, `${path}.value`);
-    if (serializedBytes(jsonValue) > MAX_STATIC_BINDING_BYTES) {
-      throw new Error(`${path}.value must serialize to 8 KB or less`);
-    }
-    return { source, value: jsonValue };
-  }
-  throw new Error(`${path}.source is invalid`);
-}
-
-function validateBindingRecord(value: unknown, path: string): Record<string, WorkspaceBinding> {
-  const record = assertRecord(value, path);
-  return Object.fromEntries(
-    Object.entries(record).map(([key, entry]) => {
-      if (key === "__proto__" || !/^[A-Za-z0-9._-]{1,64}$/.test(key)) {
-        throw new Error(`${path}.${key} binding id is invalid`);
-      }
-      return [key, validateBinding(entry, `${path}.${key}`)];
-    }),
-  );
-}
-
-function validateWidget(value: unknown, path: string): WorkspaceWidget {
-  const record = assertRecord(value, path);
-  assertKnownKeys(
-    record,
-    ["id", "kind", "title", "grid", "collapsed", "hidden", "createdBy", "bindings", "props"],
-    path,
-  );
-  const id = requireString(record, "id", path);
-  if (!WIDGET_ID_PATTERN.test(id)) {
-    throw new Error(`${path}.id is invalid`);
-  }
-  const kind = requireString(record, "kind", path);
-  if (!BUILTIN_KINDS.has(kind) && !CUSTOM_KIND_PATTERN.test(kind)) {
-    // Name the alternatives: a caller that cannot see this file otherwise has to
-    // guess the widget set one rejected write at a time.
-    throw new Error(
-      `${path}.kind is invalid: expected custom:<name> or one of ${BUILTIN_WIDGET_KINDS.join(", ")}`,
-    );
-  }
-  const title = optionalString(record, "title", path);
-  if (title !== undefined && title.length > 80) {
-    throw new Error(`${path}.title must be 80 characters or fewer`);
-  }
-  const bindings =
-    record.bindings === undefined
-      ? undefined
-      : validateBindingRecord(record.bindings, `${path}.bindings`);
-  const props =
-    record.props === undefined ? undefined : assertJsonValue(record.props, `${path}.props`);
-  return {
-    id,
-    kind,
-    ...(title !== undefined ? { title } : {}),
-    grid: validateGrid(record.grid, `${path}.grid`),
-    collapsed: requireBoolean(record, "collapsed", path),
-    hidden: requireBoolean(record, "hidden", path),
-    createdBy: validateActor(record.createdBy, `${path}.createdBy`),
-    ...(bindings !== undefined ? { bindings } : {}),
-    ...(props !== undefined ? { props } : {}),
-  };
-}
-
-function validateTab(value: unknown, path: string): WorkspaceTab {
-  const record = assertRecord(value, path);
-  assertKnownKeys(
-    record,
-    ["slug", "title", "icon", "hidden", "layout", "createdBy", "widgets"],
-    path,
-  );
-  const slug = requireString(record, "slug", path);
-  if (!TAB_SLUG_PATTERN.test(slug)) {
-    throw new Error(`${path}.slug is invalid`);
-  }
-  const title = requireString(record, "title", path);
-  if (title.length < 1 || title.length > 80) {
-    throw new Error(`${path}.title must be 1-80 characters`);
-  }
-  const icon = optionalString(record, "icon", path);
-  if (icon !== undefined && icon.length > 40) {
-    throw new Error(`${path}.icon must be 40 characters or fewer`);
-  }
-  const layout = record.layout;
-  if (layout !== undefined && layout !== "grid" && layout !== "full") {
-    throw new Error(`${path}.layout must be "grid" or "full"`);
-  }
-  const widgets = requireArray(record.widgets, `${path}.widgets`);
-  if (widgets.length > 24) {
-    throw new Error(`${path}.widgets must contain at most 24 entries`);
-  }
-  if (layout === "full" && widgets.length > 1) {
-    throw new Error(`${path}.widgets must contain at most one entry for full layout`);
-  }
-  return {
-    slug,
-    title,
-    ...(icon !== undefined ? { icon } : {}),
-    hidden: requireBoolean(record, "hidden", path),
-    ...(layout !== undefined ? { layout } : {}),
-    createdBy: validateActor(record.createdBy, `${path}.createdBy`),
-    widgets: widgets.map((widget, index) => validateWidget(widget, `${path}.widgets[${index}]`)),
-  };
-}
-
-const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
-const WIDGET_FILE_PATH_PATTERN = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
-
-function validateApprovedFiles(value: unknown, path: string): Record<string, string> {
-  const record = assertRecord(value, path);
-  const files: Record<string, string> = {};
-  for (const [logicalPath, digest] of Object.entries(record)) {
-    if (!WIDGET_FILE_PATH_PATTERN.test(logicalPath) || logicalPath.includes("..")) {
-      throw new Error(`${path}.${logicalPath} is not a valid widget file path`);
-    }
-    if (typeof digest !== "string" || !SHA256_HEX_PATTERN.test(digest)) {
-      throw new Error(`${path}.${logicalPath} must be a sha256 hex digest`);
-    }
-    files[logicalPath] = digest;
-  }
-  return files;
-}
-
-function validateRegistryEntry(value: unknown, path: string): WorkspaceWidgetRegistryEntry {
-  const record = assertRecord(value, path);
-  assertKnownKeys(
-    record,
-    ["status", "createdBy", "approvedBy", "approvedAt", "approvedFiles"],
-    path,
-  );
-  const status = requireString(record, "status", path);
-  if (status !== "pending" && status !== "approved" && status !== "rejected") {
-    throw new Error(`${path}.status is invalid`);
-  }
-  const approvedBy =
-    record.approvedBy === undefined
-      ? undefined
-      : validateActor(record.approvedBy, `${path}.approvedBy`);
-  const approvedAt = optionalString(record, "approvedAt", path);
-  const approvedFiles =
-    record.approvedFiles === undefined
-      ? undefined
-      : validateApprovedFiles(record.approvedFiles, `${path}.approvedFiles`);
-  return {
-    status,
-    createdBy: validateActor(record.createdBy, `${path}.createdBy`),
-    ...(approvedBy !== undefined ? { approvedBy } : {}),
-    ...(approvedAt !== undefined ? { approvedAt } : {}),
-    ...(approvedFiles !== undefined ? { approvedFiles } : {}),
-  };
-}
-
-function validateWidgetsRegistry(value: unknown): Record<string, WorkspaceWidgetRegistryEntry> {
-  const record = assertRecord(value, "widgetsRegistry");
-  return Object.fromEntries(
-    Object.entries(record).map(([name, entry]) => {
-      if (!CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-        throw new Error(`widgetsRegistry.${name} name is invalid`);
-      }
-      return [name, validateRegistryEntry(entry, `widgetsRegistry.${name}`)];
-    }),
-  );
-}
-
-function validatePrefs(value: unknown, tabSlugs: Set<string>): WorkspaceDoc["prefs"] {
-  const record = assertRecord(value, "prefs");
-  assertKnownKeys(record, ["tabOrder"], "prefs");
-  const tabOrder = requireArray(record.tabOrder, "prefs.tabOrder");
-  const seen = new Set<string>();
-  const order = tabOrder.map((entry, index) => {
-    if (typeof entry !== "string" || !TAB_SLUG_PATTERN.test(entry)) {
-      throw new Error(`prefs.tabOrder[${index}] is invalid`);
-    }
-    if (!tabSlugs.has(entry)) {
-      throw new Error(`prefs.tabOrder[${index}] is not a tab slug`);
-    }
-    if (seen.has(entry)) {
-      throw new Error(`prefs.tabOrder contains duplicate slug: ${entry}`);
-    }
-    seen.add(entry);
-    return entry;
-  });
-  return { tabOrder: order };
-}
-
-function assertUniqueTabs(tabs: WorkspaceTab[]): Set<string> {
-  const slugs = new Set<string>();
-  for (const tab of tabs) {
-    if (slugs.has(tab.slug)) {
-      throw new Error(`duplicate tab slug: ${tab.slug}`);
-    }
-    slugs.add(tab.slug);
-  }
-  return slugs;
-}
-
-function assertUniqueWidgets(tabs: WorkspaceTab[]): void {
-  const ids = new Set<string>();
-  for (const tab of tabs) {
-    for (const widget of tab.widgets) {
-      if (ids.has(widget.id)) {
-        throw new Error(`duplicate widget id: ${widget.id}`);
-      }
-      ids.add(widget.id);
-    }
-  }
-}
-
-export function validateWorkspaceDoc(value: unknown): WorkspaceDoc {
-  const record = assertRecord(value, "workspaces");
-  assertKnownKeys(
-    record,
-    ["schemaVersion", "workspaceVersion", "tabs", "widgetsRegistry", "prefs"],
-    "workspaces",
-  );
-  if (record.schemaVersion !== CURRENT_WORKSPACE_SCHEMA_VERSION) {
-    throw new Error(`schemaVersion must be ${CURRENT_WORKSPACE_SCHEMA_VERSION}`);
-  }
-  const workspaceVersion = assertIntegerRange(
-    record.workspaceVersion,
-    "workspaceVersion",
-    0,
-    Number.MAX_SAFE_INTEGER,
-  );
-  const rawTabs = requireArray(record.tabs, "tabs");
-  if (rawTabs.length > 32) {
-    throw new Error("tabs must contain at most 32 entries");
-  }
-  const tabs = rawTabs.map((tab, index) => validateTab(tab, `tabs[${index}]`));
-  const tabSlugs = assertUniqueTabs(tabs);
-  assertUniqueWidgets(tabs);
-  return {
-    schemaVersion: CURRENT_WORKSPACE_SCHEMA_VERSION,
-    workspaceVersion,
-    tabs,
-    widgetsRegistry: validateWidgetsRegistry(record.widgetsRegistry),
-    prefs: validatePrefs(record.prefs, tabSlugs),
-  };
-}
diff --git a/extensions/workspaces/src/serve.test.ts b/extensions/workspaces/src/serve.test.ts
deleted file mode 100644
index f6e865ad345..00000000000
--- a/extensions/workspaces/src/serve.test.ts
+++ /dev/null
@@ -1,435 +0,0 @@
-import { execFile } from "node:child_process";
-import fs from "node:fs/promises";
-import type { ServerResponse } from "node:http";
-import os from "node:os";
-import path from "node:path";
-import { promisify } from "node:util";
-import { describe, expect, it } from "vitest";
-import { snapshotApprovedWidget } from "./manifest.js";
-import { serveWidgetAsset, WIDGETS_ROUTE_PREFIX } from "./serve.js";
-import { WorkspaceStore } from "./store.js";
-
-const execFileAsync = promisify(execFile);
-
-type CapturedResponse = {
-  statusCode: number;
-  headers: Record<string, string>;
-  body: string;
-  ended: boolean;
-};
-
-const PARSE_FRAME_TOKEN = "1111111111111111111111111111111111111111111";
-const EXPECTED_WIDGET_CSP =
-  "sandbox allow-scripts; default-src 'none'; script-src 'self' 'unsafe-inline'; " +
-  "style-src 'self' 'unsafe-inline'; " +
-  "img-src 'self' data:; font-src 'self' data:; connect-src 'none'; frame-ancestors 'self'";
-let activeFrameToken: string | null = null;
-
-/** Minimal ServerResponse stub capturing status, headers, and body. */
-function fakeResponse(): { res: ServerResponse; captured: CapturedResponse } {
-  const captured: CapturedResponse = { statusCode: 200, headers: {}, body: "", ended: false };
-  const res = {
-    get statusCode() {
-      return captured.statusCode;
-    },
-    set statusCode(value: number) {
-      captured.statusCode = value;
-    },
-    setHeader(name: string, value: string) {
-      captured.headers[name.toLowerCase()] = value;
-    },
-    end(chunk?: Buffer | string) {
-      if (chunk !== undefined) {
-        captured.body = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
-      }
-      captured.ended = true;
-    },
-  } as unknown as ServerResponse;
-  return { res, captured };
-}
-
-async function withApprovedWidget<T>(
-  run: (ctx: { stateDir: string; store: WorkspaceStore; widgetDir: string }) => Promise<T>,
-): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-serve-"));
-  try {
-    const store = new WorkspaceStore({ stateDir });
-    const widgetDir = path.join(stateDir, "workspaces", "widgets", "revenue-chart");
-    await fs.mkdir(widgetDir, { recursive: true });
-    await fs.writeFile(
-      path.join(widgetDir, "widget.json"),
-      JSON.stringify({
-        schemaVersion: 1,
-        name: "revenue-chart",
-        title: "Revenue Chart",
-        entrypoint: "index.html",
-        bindings: [],
-        capabilities: [],
-      }),
-    );
-    await fs.writeFile(path.join(widgetDir, "index.html"), "<!doctype html><h1>ok</h1>");
-    await fs.writeFile(path.join(widgetDir, "app.js"), "console.log(1)");
-    await fs.writeFile(path.join(widgetDir, "secret.mjs"), "export const x = 1");
-    // Approval freezes a digest of every servable file, exactly as the gateway
-    // method does; serving compares against it.
-    const { files: approvedFiles } = await snapshotApprovedWidget("revenue-chart", { stateDir });
-    store.mutate(
-      (draft) => {
-        draft.widgetsRegistry["revenue-chart"] = {
-          status: "approved",
-          createdBy: "user",
-          approvedBy: "user",
-          approvedAt: new Date().toISOString(),
-          approvedFiles,
-        };
-      },
-      { actor: "user" },
-    );
-    activeFrameToken = store.assetTokens.issue("revenue-chart", approvedFiles);
-    return await run({ stateDir, store, widgetDir });
-  } finally {
-    activeFrameToken = null;
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-function urlFor(name: string, rest: string): string {
-  return `${WIDGETS_ROUTE_PREFIX}/${activeFrameToken ?? PARSE_FRAME_TOKEN}/${name}/${rest}`;
-}
-
-describe("serveWidgetAsset security jail", () => {
-  it("serves an approved widget's index.html with strict headers", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      const handled = await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "index.html") },
-        res,
-        { store, stateDir },
-      );
-      expect(handled).toBe(true);
-      expect(captured.statusCode).toBe(200);
-      expect(captured.headers["content-type"]).toBe("text/html; charset=utf-8");
-      expect(captured.headers["content-security-policy"]).toBe(EXPECTED_WIDGET_CSP);
-      // The response itself enforces the same opaque-origin sandbox as the
-      // iframe, so opening this URL directly cannot regain same-origin access.
-      expect(captured.headers["content-security-policy"]).toContain("sandbox allow-scripts");
-      expect(captured.headers["content-security-policy"]).not.toContain("allow-same-origin");
-      expect(captured.headers["content-security-policy"]).toContain("connect-src 'none'");
-      expect(captured.headers["x-content-type-options"]).toBe("nosniff");
-      expect(captured.headers["referrer-policy"]).toBe("no-referrer");
-      expect(captured.body).toContain("<h1>ok</h1>");
-    });
-  });
-
-  it("injects a document-bound MessageChannel bootstrap before approved html", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        {
-          method: "GET",
-          pathname: urlFor("revenue-chart", "index.html"),
-        },
-        res,
-        { store, stateDir },
-      );
-
-      expect(captured.statusCode).toBe(200);
-      expect(captured.body).toContain("new MessageChannel()");
-      expect(captured.body).toContain(`token:"${activeFrameToken}"`);
-      expect(captured.body.startsWith("<!doctype html><script>")).toBe(true);
-      expect(captured.body.indexOf("new MessageChannel()")).toBeLessThan(
-        captured.body.indexOf("<h1>ok</h1>"),
-      );
-    });
-  });
-
-  it("404s a malformed frame token", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        {
-          method: "GET",
-          pathname: `${WIDGETS_ROUTE_PREFIX}/bad-token/revenue-chart/index.html`,
-        },
-        res,
-        { store, stateDir },
-      );
-
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("keeps leading comments and the doctype ahead of the bootstrap", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      const html = `<!-- license -->\n<!doctype html><h1>ok</h1>`;
-      await fs.writeFile(path.join(widgetDir, "index.html"), html);
-      const { files: approvedFiles } = await snapshotApprovedWidget("revenue-chart", { stateDir });
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry["revenue-chart"]!.approvedFiles = approvedFiles;
-        },
-        { actor: "user" },
-      );
-      activeFrameToken = store.assetTokens.issue("revenue-chart", approvedFiles);
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        {
-          method: "GET",
-          pathname: urlFor("revenue-chart", "index.html"),
-        },
-        res,
-        { store, stateDir },
-      );
-
-      expect(captured.body.startsWith(`<!-- license -->\n<!doctype html><script>`)).toBe(true);
-    });
-  });
-
-  it("serves a .js asset with the allowlisted content type + CSP + nosniff", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset({ method: "GET", pathname: urlFor("revenue-chart", "app.js") }, res, {
-        store,
-        stateDir,
-      });
-      expect(captured.statusCode).toBe(200);
-      expect(captured.headers["content-type"]).toBe("text/javascript; charset=utf-8");
-      expect(captured.headers["content-security-policy"]).toBe(EXPECTED_WIDGET_CSP);
-      expect(captured.headers["x-content-type-options"]).toBe("nosniff");
-    });
-  });
-
-  it("returns false (not handled) for a pathname outside the route", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res } = fakeResponse();
-      const handled = await serveWidgetAsset(
-        { method: "GET", pathname: "/plugins/canvas/host/x" },
-        res,
-        { store, stateDir },
-      );
-      expect(handled).toBe(false);
-    });
-  });
-
-  const traversalCases: Array<{ label: string; pathname: string }> = [
-    { label: "dot-dot traversal", pathname: urlFor("revenue-chart", "../secret.txt") },
-    { label: "encoded %2e%2e traversal", pathname: urlFor("revenue-chart", "%2e%2e/secret.txt") },
-    {
-      label: "absolute path",
-      pathname: `${WIDGETS_ROUTE_PREFIX}/${PARSE_FRAME_TOKEN}/revenue-chart//etc/passwd`,
-    },
-    { label: "backslash traversal", pathname: urlFor("revenue-chart", "..%5csecret.txt") },
-    {
-      label: "name charset violation",
-      pathname: `${WIDGETS_ROUTE_PREFIX}/${PARSE_FRAME_TOKEN}/..%2f..%2fx/index.html`,
-    },
-  ];
-
-  for (const { label, pathname } of traversalCases) {
-    it(`404s on ${label}`, async () => {
-      await withApprovedWidget(async ({ store, stateDir }) => {
-        const { res, captured } = fakeResponse();
-        await serveWidgetAsset({ method: "GET", pathname }, res, { store, stateDir });
-        expect(captured.statusCode).toBe(404);
-        // A 404 is still an attacker-influenced response from the widget origin,
-        // so it MUST carry the same strict CSP as a 200 (invariant I1/I4).
-        expect(captured.headers["content-security-policy"]).toBe(EXPECTED_WIDGET_CSP);
-        expect(captured.headers["referrer-policy"]).toBe("no-referrer");
-      });
-    });
-  }
-
-  it("404s (never 403) on a symlink that escapes the widget dir", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      const outsideFile = path.join(stateDir, "outside-secret.txt");
-      await fs.writeFile(outsideFile, "top secret");
-      await fs.symlink(outsideFile, path.join(widgetDir, "leak.txt"));
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "leak.txt") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s a post-approval hardlink even when its bytes match the approved file", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      const appPath = path.join(widgetDir, "app.js");
-      const approvedBytes = await fs.readFile(appPath);
-      const outsideFile = path.join(stateDir, "outside-app.js");
-      await fs.writeFile(outsideFile, approvedBytes);
-      await fs.rm(appPath);
-      await fs.link(outsideFile, appPath);
-
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset({ method: "GET", pathname: urlFor("revenue-chart", "app.js") }, res, {
-        store,
-        stateDir,
-      });
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s a symlink substituted for the approved widget directory", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      const outsideDir = path.join(stateDir, "outside-widget");
-      await fs.rename(widgetDir, outsideDir);
-      await fs.symlink(outsideDir, widgetDir, "dir");
-
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "index.html") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it.runIf(process.platform !== "win32")(
-    "404s a post-approval named pipe without blocking",
-    async () => {
-      await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-        const appPath = path.join(widgetDir, "app.js");
-        await fs.rm(appPath);
-        await execFileAsync("mkfifo", [appPath]);
-
-        const { res, captured } = fakeResponse();
-        await serveWidgetAsset(
-          { method: "GET", pathname: urlFor("revenue-chart", "app.js") },
-          res,
-          { store, stateDir },
-        );
-        expect(captured.statusCode).toBe(404);
-      });
-    },
-  );
-
-  it("404s on a non-GET method", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      for (const method of ["POST", "PUT", "DELETE", "OPTIONS"]) {
-        const { res, captured } = fakeResponse();
-        await serveWidgetAsset({ method, pathname: urlFor("revenue-chart", "index.html") }, res, {
-          store,
-          stateDir,
-        });
-        expect(captured.statusCode).toBe(404);
-      }
-    });
-  });
-
-  it("404s on a disallowed extension even when the file exists", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "secret.mjs") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s assets for a pending (not approved) widget", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const pendingDir = path.join(stateDir, "workspaces", "widgets", "pending-widget");
-      await fs.mkdir(pendingDir, { recursive: true });
-      await fs.writeFile(path.join(pendingDir, "index.html"), "<h1>pending</h1>");
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry["pending-widget"] = { status: "pending", createdBy: "agent:x" };
-        },
-        { actor: "user" },
-      );
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("pending-widget", "index.html") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s assets for a rejected widget", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const rejectedDir = path.join(stateDir, "workspaces", "widgets", "rejected-widget");
-      await fs.mkdir(rejectedDir, { recursive: true });
-      await fs.writeFile(path.join(rejectedDir, "index.html"), "<h1>rejected</h1>");
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry["rejected-widget"] = { status: "rejected", createdBy: "agent:x" };
-        },
-        { actor: "user" },
-      );
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("rejected-widget", "index.html") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s a missing file inside an approved widget dir", async () => {
-    await withApprovedWidget(async ({ store, stateDir }) => {
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "does-not-exist.css") },
-        res,
-        { store, stateDir },
-      );
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s a file whose bytes changed after approval", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      // The gate approves code, not a directory name. Rewriting the entrypoint
-      // after approval must not reach a browser.
-      await fs.writeFile(path.join(widgetDir, "index.html"), "<script>evil()</script>");
-
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset(
-        { method: "GET", pathname: urlFor("revenue-chart", "index.html") },
-        res,
-        { store, stateDir },
-      );
-
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s a file added after approval", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      await fs.writeFile(path.join(widgetDir, "late.js"), "evil()");
-
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset({ method: "GET", pathname: urlFor("revenue-chart", "late.js") }, res, {
-        store,
-        stateDir,
-      });
-
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-
-  it("404s an oversized file without reading it", async () => {
-    await withApprovedWidget(async ({ store, stateDir, widgetDir }) => {
-      // Approved files stay writable: a swapped-in giant asset must be refused on
-      // its size, not buffered and then hash-checked.
-      await fs.writeFile(path.join(widgetDir, "app.js"), Buffer.alloc(2 * 1024 * 1024 + 1));
-
-      const { res, captured } = fakeResponse();
-      await serveWidgetAsset({ method: "GET", pathname: urlFor("revenue-chart", "app.js") }, res, {
-        store,
-        stateDir,
-      });
-
-      expect(captured.statusCode).toBe(404);
-    });
-  });
-});
diff --git a/extensions/workspaces/src/serve.ts b/extensions/workspaces/src/serve.ts
deleted file mode 100644
index d2dca416618..00000000000
--- a/extensions/workspaces/src/serve.ts
+++ /dev/null
@@ -1,296 +0,0 @@
-// Static-file serving for approved custom widgets, under the `auth:"plugin"`
-// HTTP route. The authenticated gateway first mints a path-scoped capability,
-// bound to the widget and approved-file snapshot; every asset request validates
-// it before touching the registry or disk. Every rejection returns 404
-// (never 403) so the route never leaks whether a widget or file exists.
-//
-// The path jail combines strict logical-path normalization with the shared
-// race-safe rooted reader, which rejects symlinks, hardlinks, and escapes.
-
-import fs from "node:fs/promises";
-import type { ServerResponse } from "node:http";
-import path from "node:path";
-import { root as fsRoot } from "openclaw/plugin-sdk/security-runtime";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import {
-  CUSTOM_WIDGET_NAME_PATTERN,
-  matchesApprovedFile,
-  MAX_WIDGET_FILE_BYTES,
-  resolveWidgetDir,
-  WIDGET_CONTENT_TYPES,
-} from "./manifest.js";
-import type { WorkspaceStore } from "./store.js";
-
-export const WIDGETS_ROUTE_PREFIX = "/plugins/workspaces/widgets";
-
-// Spec §Server side: strict CSP on every widget response. `connect-src 'none'`
-// blocks script networking and `frame-ancestors 'self'` keeps the frame embeddable
-// only by the Control UI. Custom code receives only static workspace values: a
-// sandboxed child can navigate itself, so privileged RPC/file data stays in the
-// trusted built-in renderers.
-const WIDGET_CSP =
-  "sandbox allow-scripts; default-src 'none'; script-src 'self' 'unsafe-inline'; " +
-  "style-src 'self' 'unsafe-inline'; " +
-  "img-src 'self' data:; font-src 'self' data:; connect-src 'none'; frame-ancestors 'self'";
-
-type WidgetServeDeps = {
-  store: WorkspaceStore;
-  stateDir?: string;
-};
-
-type WidgetServeRequest = {
-  method: string | undefined;
-  /** URL pathname (no query/hash), already URL-decoded per segment by the caller. */
-  pathname: string;
-};
-
-const BRIDGE_TOKEN_PATTERN = /^[A-Za-z0-9_-]{20,100}$/;
-
-/**
- * Runs before approved widget bytes and creates a MessagePort owned by that exact
- * document. WindowProxy identity survives navigation; a port does not, so a
- * replacement page can never inherit the parent bridge.
- */
-function injectBridgeBootstrap(data: Buffer, bridgeToken: string | undefined): Buffer {
-  if (!bridgeToken || !BRIDGE_TOKEN_PATTERN.test(bridgeToken)) {
-    return data;
-  }
-  const bootstrap = `<script>(()=>{const channel=new MessageChannel();const listeners=new Set();const port=channel.port1;port.onmessage=(event)=>{for(const listener of listeners)listener(event)};port.start();Object.defineProperty(window,"openclawWorkspaceBridge",{configurable:false,writable:false,value:Object.freeze({postMessage:(message)=>port.postMessage(message),addEventListener:(type,listener)=>{if(type==="message")listeners.add(listener)},removeEventListener:(type,listener)=>{if(type==="message")listeners.delete(listener)}})});window.parent.postMessage({v:1,type:"workspace:bridge:init",token:"${bridgeToken}"},"*",[channel.port2])})();</script>`;
-  const html = data.toString("utf8");
-  const doctype = html.match(/^\uFEFF?(?:\s|<!--[\s\S]*?-->)*<!doctype[^>]*>/i)?.[0] ?? "";
-  return Buffer.from(`${doctype}${bootstrap}${html.slice(doctype.length)}`);
-}
-
-/** Copy of the canvas logical-path normalizer (documents.ts:79). */
-function normalizeLogicalPath(value: string): string {
-  const normalized = value.replaceAll("\\", "/").replace(/^\/+/, "");
-  const parts = normalized.split("/").filter(Boolean);
-  if (
-    parts.length === 0 ||
-    parts.some(
-      (part) => part === "." || part === ".." || part.includes(":") || hasControlCharacter(part),
-    )
-  ) {
-    throw new Error("widget logical path invalid");
-  }
-  return parts.join("/");
-}
-
-function hasControlCharacter(value: string): boolean {
-  for (const char of value) {
-    const code = char.charCodeAt(0);
-    if (code < 0x20 || code === 0x7f) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/** True when the pathname is under this route's prefix (so the route owns it). */
-function isWidgetRoutePath(pathname: string): boolean {
-  return pathname === WIDGETS_ROUTE_PREFIX || pathname.startsWith(`${WIDGETS_ROUTE_PREFIX}/`);
-}
-
-/**
- * Splits a request pathname under the widgets prefix into `{ name, logicalPath }`.
- * Returns null when the pathname is not under the prefix or is malformed. Each
- * segment is URL-decoded; a decode failure yields null (→ 404).
- */
-function parseWidgetRequestPath(
-  pathname: string,
-): { frameToken: string; name: string; logicalPath: string } | null {
-  const prefix = `${WIDGETS_ROUTE_PREFIX}/`;
-  if (!pathname.startsWith(prefix)) {
-    return null;
-  }
-  const rest = pathname.slice(prefix.length);
-  const rawSegments = rest.split("/");
-  const segments: string[] = [];
-  for (const segment of rawSegments) {
-    if (!segment) {
-      // A trailing/duplicated slash collapses; an empty leading segment is dropped.
-      continue;
-    }
-    try {
-      segments.push(decodeURIComponent(segment));
-    } catch {
-      return null;
-    }
-  }
-  if (segments.length < 3) {
-    return null;
-  }
-  const [frameToken, name, ...entry] = segments;
-  if (!frameToken || !name) {
-    return null;
-  }
-  if (!BRIDGE_TOKEN_PATTERN.test(frameToken)) {
-    return null;
-  }
-  // The charset pattern permits dots, so `.`/`..` slip through it — reject the
-  // traversal names explicitly (mirrors normalizeCanvasDocumentId, documents.ts:107).
-  if (name === "." || name === ".." || !CUSTOM_WIDGET_NAME_PATTERN.test(name)) {
-    return null;
-  }
-  let logicalPath: string;
-  try {
-    logicalPath = normalizeLogicalPath(entry.join("/"));
-  } catch {
-    return null;
-  }
-  return { frameToken, name, logicalPath };
-}
-
-/**
- * Content type for a logical path, or null when the extension is not servable.
- * The table lives in `manifest.ts` because approval hashes exactly this file set.
- */
-function extensionContentType(logicalPath: string): string | null {
-  const extension = path.extname(logicalPath).toLowerCase();
-  return WIDGET_CONTENT_TYPES[extension] ?? null;
-}
-
-/**
- * The strict security headers EVERY widget-route response must carry — 200 and
- * 404 alike. A 404 is still an attacker-influenced response served from the
- * widget origin, so it needs the same `connect-src 'none'` lockdown. Shared here
- * so the two response paths can never drift apart again. Content-Type is set
- * per-path (it differs) and is intentionally not included.
- */
-function setSecurityHeaders(res: ServerResponse): void {
-  res.setHeader("Content-Security-Policy", WIDGET_CSP);
-  res.setHeader("X-Content-Type-Options", "nosniff");
-  res.setHeader("Referrer-Policy", "no-referrer");
-  res.setHeader("Cache-Control", "no-store");
-}
-
-function notFound(res: ServerResponse): true {
-  res.statusCode = 404;
-  res.setHeader("Content-Type", "text/plain; charset=utf-8");
-  setSecurityHeaders(res);
-  res.end("not found");
-  return true;
-}
-
-/**
- * Resolves and serves a static asset for an approved custom widget, writing the
- * response directly. Returns true when the request was under this route (handled),
- * false when the pathname is not a widget path (caller may fall through).
- *
- * Every failure mode (wrong method, unknown/pending/rejected widget, jail
- * violation, disallowed extension, missing file) is a 404 — never 403 — so the
- * unauthenticated route reveals nothing about what exists on disk.
- */
-export async function serveWidgetAsset(
-  req: WidgetServeRequest,
-  res: ServerResponse,
-  deps: WidgetServeDeps,
-): Promise<boolean> {
-  // A pathname NOT under this route falls through (returns false); a pathname
-  // under the route but malformed (traversal, bad charset, encoded escape) is
-  // OWNED by this route and answered with 404 — never fall-through, never 403.
-  if (!isWidgetRoutePath(req.pathname)) {
-    return false;
-  }
-  const parsed = parseWidgetRequestPath(req.pathname);
-  if (!parsed) {
-    return notFound(res);
-  }
-  // Non-GET is not merely rejected — it is indistinguishable from a miss (404).
-  if (req.method !== "GET" && req.method !== "HEAD") {
-    return notFound(res);
-  }
-
-  const contentType = extensionContentType(parsed.logicalPath);
-  if (!contentType) {
-    return notFound(res);
-  }
-
-  // Reject guessed/expired tokens before even consulting the registry or disk.
-  if (!deps.store.assetTokens.isIssued(parsed.frameToken, parsed.name)) {
-    return notFound(res);
-  }
-
-  // Serving gate: only `status === "approved"` widgets are served AT ALL. This is
-  // belt-and-braces with the UI render gate (the UI never builds an iframe for a
-  // pending/rejected widget, and the server refuses its assets regardless).
-  let approvedFiles: Record<string, string> | undefined;
-  try {
-    const entry = deps.store.widgetEntry(parsed.name);
-    if (entry?.status !== "approved") {
-      return notFound(res);
-    }
-    approvedFiles = entry.approvedFiles;
-    if (
-      !approvedFiles ||
-      !deps.store.assetTokens.allows(parsed.frameToken, parsed.name, approvedFiles)
-    ) {
-      return notFound(res);
-    }
-  } catch {
-    return notFound(res);
-  }
-
-  const stateDir = path.resolve(deps.stateDir ?? resolveStateDir());
-  let widgetDir: string;
-  try {
-    widgetDir = resolveWidgetDir(parsed.name, stateDir);
-  } catch {
-    return notFound(res);
-  }
-  let data: Buffer;
-  try {
-    // Widget files stay writable after approval. Pin and validate the opened file
-    // so post-approval symlink, hardlink, and oversized swaps all fail closed.
-    const widgetRoot = await fsRoot(stateDir, {
-      hardlinks: "reject",
-      maxBytes: MAX_WIDGET_FILE_BYTES,
-      nonBlockingRead: true,
-      symlinks: "reject",
-    });
-    const widgetStat = await fs.lstat(widgetDir);
-    const widgetReal = await fs.realpath(widgetDir);
-    const expectedWidgetReal = path.join(widgetRoot.rootReal, "workspaces", "widgets", parsed.name);
-    if (
-      widgetStat.isSymbolicLink() ||
-      !widgetStat.isDirectory() ||
-      widgetReal !== expectedWidgetReal
-    ) {
-      return notFound(res);
-    }
-    const read = await widgetRoot.read(
-      path.posix.join("workspaces", "widgets", parsed.name, parsed.logicalPath),
-      {
-        hardlinks: "reject",
-        maxBytes: MAX_WIDGET_FILE_BYTES,
-        nonBlockingRead: true,
-        symlinks: "reject",
-      },
-    );
-    if (read.realPath !== widgetReal && !read.realPath.startsWith(`${widgetReal}${path.sep}`)) {
-      return notFound(res);
-    }
-    data = read.buffer;
-  } catch {
-    return notFound(res);
-  }
-
-  // The operator approved these exact bytes. A file edited or added after
-  // approval has no matching digest and is indistinguishable from a miss.
-  if (!matchesApprovedFile(approvedFiles, parsed.logicalPath, data)) {
-    return notFound(res);
-  }
-
-  res.statusCode = 200;
-  res.setHeader("Content-Type", contentType);
-  setSecurityHeaders(res);
-  if (req.method === "HEAD") {
-    res.end();
-  } else {
-    const body = contentType.startsWith("text/html")
-      ? injectBridgeBootstrap(data, parsed.frameToken)
-      : data;
-    res.end(body);
-  }
-  return true;
-}
diff --git a/extensions/workspaces/src/store.test.ts b/extensions/workspaces/src/store.test.ts
deleted file mode 100644
index 548d28a29df..00000000000
--- a/extensions/workspaces/src/store.test.ts
+++ /dev/null
@@ -1,339 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { DatabaseSync } from "node:sqlite";
-import { describe, expect, it, vi } from "vitest";
-import { DEFAULT_WORKSPACE } from "./default-workspace.js";
-import { validateWorkspaceDoc, type WorkspaceDoc } from "./schema.js";
-import { WorkspaceStore } from "./store.js";
-
-async function withStore<T>(run: (store: WorkspaceStore) => Promise<T> | T): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-"));
-  const store = new WorkspaceStore({ stateDir });
-  try {
-    return await run(store);
-  } finally {
-    store.close();
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-/** A doc carrying one scaffolded (pending) custom widget in the registry. */
-function docWithPendingWidget(store: WorkspaceStore): WorkspaceDoc {
-  return store.mutate(
-    (draft) => {
-      draft.widgetsRegistry.chart = { status: "pending", createdBy: "agent:finance" };
-    },
-    { actor: "agent:finance" },
-  ).doc;
-}
-
-describe("WorkspaceStore", () => {
-  it("seeds the default workspace on first read", async () => {
-    await withStore((store) => {
-      const doc = store.read();
-
-      expect(doc.tabs[0]).toMatchObject({ slug: "main", title: "Overview", createdBy: "system" });
-      expect(doc.workspaceVersion).toBe(1);
-      // A second read hits the single-slot cache and must agree with the DB.
-      expect(store.read()).toEqual(doc);
-    });
-  });
-
-  it("uses STRICT tables and durable connection pragmas", async () => {
-    await withStore((store) => {
-      const database = new DatabaseSync(store.dbPath, { readOnly: true });
-      try {
-        expect(
-          database
-            .prepare(
-              `SELECT name, strict FROM pragma_table_list
-               WHERE schema = 'main' AND type = 'table' AND name NOT LIKE 'sqlite_%'
-               ORDER BY name`,
-            )
-            .all(),
-        ).toEqual([
-          { name: "undo", strict: 1 },
-          { name: "workspace", strict: 1 },
-        ]);
-        expect(database.prepare("PRAGMA user_version").get()).toEqual({ user_version: 1 });
-        expect(database.prepare("PRAGMA journal_mode").get()).toEqual({ journal_mode: "wal" });
-      } finally {
-        database.close();
-      }
-    });
-  });
-
-  it("closes its WAL maintenance timer", async () => {
-    vi.useFakeTimers();
-    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-timer-"));
-    try {
-      const store = new WorkspaceStore({ stateDir });
-      expect(vi.getTimerCount()).toBe(1);
-      store.close();
-      expect(vi.getTimerCount()).toBe(0);
-    } finally {
-      vi.useRealTimers();
-      await fs.rm(stateDir, { recursive: true, force: true });
-    }
-  });
-
-  it("migrates an existing workspace and undo history to STRICT", async () => {
-    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-legacy-"));
-    const workspaceDir = path.join(stateDir, "workspaces");
-    const databasePath = path.join(workspaceDir, "workspaces.sqlite");
-    await fs.mkdir(workspaceDir, { recursive: true });
-    const legacy = new DatabaseSync(databasePath);
-    legacy.exec(`
-      CREATE TABLE workspace (
-        id INTEGER PRIMARY KEY CHECK (id = 1),
-        version INTEGER NOT NULL,
-        doc TEXT NOT NULL,
-        updated_ms INTEGER NOT NULL
-      );
-      CREATE TABLE undo (
-        version INTEGER PRIMARY KEY,
-        doc TEXT NOT NULL,
-        created_ms INTEGER NOT NULL
-      );
-    `);
-    const serialized = JSON.stringify(DEFAULT_WORKSPACE);
-    legacy.prepare("INSERT INTO workspace VALUES (1, 1, ?, 10)").run(serialized);
-    legacy.prepare("INSERT INTO undo VALUES (1, ?, 10)").run(serialized);
-    legacy.close();
-
-    const store = new WorkspaceStore({ stateDir });
-    try {
-      expect(store.read()).toEqual(DEFAULT_WORKSPACE);
-      const migrated = new DatabaseSync(databasePath, { readOnly: true });
-      try {
-        expect(
-          migrated
-            .prepare(
-              `SELECT name, strict FROM pragma_table_list
-               WHERE schema = 'main' AND type = 'table' AND name NOT LIKE 'sqlite_%'
-               ORDER BY name`,
-            )
-            .all(),
-        ).toEqual([
-          { name: "undo", strict: 1 },
-          { name: "workspace", strict: 1 },
-        ]);
-        expect(migrated.prepare("SELECT COUNT(*) AS count FROM undo").get()).toEqual({ count: 1 });
-      } finally {
-        migrated.close();
-      }
-    } finally {
-      store.close();
-      await fs.rm(stateDir, { recursive: true, force: true });
-    }
-  });
-
-  it("keeps a 20-entry undo ring and restores the newest snapshot as a NEW version", async () => {
-    await withStore((store) => {
-      store.read();
-      for (let index = 1; index <= 21; index += 1) {
-        store.mutate(
-          (draft) => {
-            draft.tabs[0]!.title = `Overview ${index}`;
-          },
-          { actor: "user" },
-        );
-      }
-      const beforeUndo = store.read();
-
-      const restored = store.undo();
-
-      expect(restored.tabs[0]?.title).toBe("Overview 20");
-      // Monotonic: connected UIs refetch only on a strictly newer version, so an
-      // undo that rewound `workspaceVersion` would never reach an open browser.
-      expect(restored.workspaceVersion).toBe(beforeUndo.workspaceVersion + 1);
-      expect(store.read()).toEqual(restored);
-    });
-  });
-
-  it("evicts the oldest undo snapshot past the ring size", async () => {
-    await withStore((store) => {
-      store.read();
-      for (let index = 1; index <= 25; index += 1) {
-        store.mutate(
-          (draft) => {
-            draft.tabs[0]!.title = `Overview ${index}`;
-          },
-          { actor: "user" },
-        );
-      }
-
-      // 20 snapshots survive, so 20 undos succeed and the 21st has nothing left.
-      for (let index = 0; index < 20; index += 1) {
-        store.undo();
-      }
-      expect(() => store.undo()).toThrow("no workspace undo snapshot available");
-    });
-  });
-
-  it("rolls back an oversized mutation, leaving no partial write and no undo entry", async () => {
-    await withStore((store) => {
-      const before = store.read();
-
-      expect(() =>
-        store.mutate(
-          (draft) => {
-            draft.tabs[0]!.widgets[0]!.props = { text: "x".repeat(300_000) };
-          },
-          { actor: "user" },
-        ),
-      ).toThrow("workspace document exceeds 256 KB");
-
-      expect(store.read()).toEqual(before);
-      expect(() => store.undo()).toThrow("no workspace undo snapshot available");
-    });
-  });
-
-  it("rolls back an invalid mutation without bumping the version", async () => {
-    await withStore((store) => {
-      const before = store.read();
-
-      expect(() =>
-        store.mutate(
-          (draft) => {
-            draft.tabs[0]!.slug = "Not A Slug";
-          },
-          { actor: "user" },
-        ),
-      ).toThrow(/slug is invalid/);
-
-      expect(store.read().workspaceVersion).toBe(before.workspaceVersion);
-    });
-  });
-
-  it("replace cannot self-approve a pending custom widget", async () => {
-    await withStore((store) => {
-      const doc = docWithPendingWidget(store);
-
-      // The attack: submit a whole document that already marks the widget approved.
-      const forged = validateWorkspaceDoc({
-        ...doc,
-        widgetsRegistry: {
-          chart: { status: "approved", createdBy: "agent:finance", approvedBy: "user" },
-        },
-      });
-      const result = store.replace(forged, { actor: "agent:finance" });
-
-      expect(result.doc.widgetsRegistry.chart).toEqual({
-        status: "pending",
-        createdBy: "agent:finance",
-      });
-      expect(store.widgetStatus("chart")).toBe("pending");
-    });
-  });
-
-  it("replace preserves registry decisions omitted by the incoming document", async () => {
-    await withStore((store) => {
-      const doc = docWithPendingWidget(store);
-      const replacement = validateWorkspaceDoc({ ...doc, widgetsRegistry: {} });
-
-      const result = store.replace(replacement, { actor: "agent:finance" });
-
-      expect(result.doc.widgetsRegistry.chart).toEqual({
-        status: "pending",
-        createdBy: "agent:finance",
-      });
-    });
-  });
-
-  it("does not restore a revoked widget approval through undo", async () => {
-    await withStore((store) => {
-      docWithPendingWidget(store);
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry.chart = {
-            status: "approved",
-            createdBy: "agent:finance",
-            approvedBy: "user",
-            approvedAt: "2026-07-11T00:00:00.000Z",
-            approvedFiles: { "index.html": "a".repeat(64) },
-          };
-        },
-        { actor: "user" },
-      );
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry.chart = {
-            status: "rejected",
-            createdBy: "agent:finance",
-            approvedBy: "user",
-            approvedAt: "2026-07-11T00:01:00.000Z",
-          };
-        },
-        { actor: "user" },
-      );
-
-      const restored = store.undo();
-
-      expect(restored.widgetsRegistry.chart).toMatchObject({ status: "rejected" });
-      expect(restored.widgetsRegistry.chart?.approvedFiles).toBeUndefined();
-    });
-  });
-
-  it("replace cannot forge provenance on new or existing entities", async () => {
-    await withStore((store) => {
-      const seeded = store.read();
-      const forged = validateWorkspaceDoc({
-        ...seeded,
-        tabs: [
-          // Existing system tab, relabelled as agent-authored.
-          { ...seeded.tabs[0]!, createdBy: "agent:evil" },
-          {
-            slug: "new",
-            title: "New",
-            hidden: false,
-            // Agent-created tab, relabelled as human-authored.
-            createdBy: "user",
-            widgets: [
-              {
-                id: "w1",
-                kind: "builtin:markdown",
-                grid: { x: 0, y: 0, w: 4, h: 2 },
-                collapsed: false,
-                hidden: false,
-                createdBy: "user",
-              },
-            ],
-          },
-        ],
-        prefs: { tabOrder: ["main", "new"] },
-      });
-
-      const { doc } = store.replace(forged, { actor: "agent:evil" });
-
-      expect(doc.tabs[0]?.createdBy).toBe("system");
-      expect(doc.tabs[1]?.createdBy).toBe("agent:evil");
-      expect(doc.tabs[1]?.widgets[0]?.createdBy).toBe("agent:evil");
-    });
-  });
-
-  it("replace cannot mint a registry entry for a widget that was never scaffolded", async () => {
-    await withStore((store) => {
-      const seeded = store.read();
-      // The attack: invent a registry name, get an operator to approve it, then
-      // write the code afterwards. Names that were never scaffolded are dropped.
-      const forged = validateWorkspaceDoc({
-        ...seeded,
-        widgetsRegistry: { evil: { status: "pending", createdBy: "agent:evil" } },
-      });
-
-      const { doc } = store.replace(forged, { actor: "agent:evil" });
-
-      expect(doc.widgetsRegistry).toEqual({});
-      expect(store.widgetStatus("evil")).toBeNull();
-    });
-  });
-
-  it("widgetStatus reports null for an unknown widget", async () => {
-    await withStore((store) => {
-      store.read();
-      expect(store.widgetStatus("nope")).toBeNull();
-    });
-  });
-});
diff --git a/extensions/workspaces/src/store.ts b/extensions/workspaces/src/store.ts
deleted file mode 100644
index be2b475a3d4..00000000000
--- a/extensions/workspaces/src/store.ts
+++ /dev/null
@@ -1,313 +0,0 @@
-// Workspaces store: the single writer for the workspace document.
-//
-// Storage split (AGENTS.md "Storage default: SQLite only"):
-// - the workspace document + its undo ring live in this plugin-owned SQLite DB,
-//   the same shape logbook uses ("frames on disk, everything else in one
-//   plugin-owned DB");
-// - agent-authored widget assets (`workspaces/widgets/<name>/`) and file-binding
-//   data (`workspaces/data/`) stay on disk, because those are named product
-//   artifacts: the agent authors them with ordinary file tools and the widget
-//   route serves their bytes.
-//
-// Every mutation is a single BEGIN IMMEDIATE transaction, so a read-modify-write
-// cycle cannot interleave with another writer. node:sqlite is synchronous, which
-// is why the mutator must be synchronous too: the transaction is the lock.
-//
-// There is deliberately no migration from the `workspace.json` this plugin used
-// while it was in review. The plugin has never been reachable from a release tag,
-// so no installation can hold that file, and compatibility here is opt-in per
-// AGENTS.md. Seeding the default workspace on an empty database is the only
-// first-read path.
-
-import { chmodSync, mkdirSync } from "node:fs";
-import path from "node:path";
-import { DatabaseSync } from "node:sqlite";
-import {
-  configureSqliteConnectionPragmas,
-  migrateSqliteSchemaToStrict,
-} from "openclaw/plugin-sdk/plugin-state-runtime";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import { WidgetAssetTokens } from "./asset-tokens.js";
-import { DEFAULT_WORKSPACE } from "./default-workspace.js";
-import {
-  validateWorkspaceDoc,
-  type WorkspaceActor,
-  type WorkspaceWidgetRegistryEntry,
-  type WorkspaceDoc,
-} from "./schema.js";
-
-type WorkspaceMutationOptions = { actor: WorkspaceActor };
-type WorkspaceMutationResult = { doc: WorkspaceDoc; changed: boolean };
-
-const MAX_WORKSPACE_BYTES = 256 * 1024;
-const UNDO_RING_SIZE = 20;
-const DIR_MODE = 0o700;
-const FILE_MODE = 0o600;
-const BUSY_TIMEOUT_MS = 5000;
-const SCHEMA_VERSION = 1;
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS workspace (
-  id INTEGER PRIMARY KEY CHECK (id = 1),
-  version INTEGER NOT NULL,
-  doc TEXT NOT NULL,
-  updated_ms INTEGER NOT NULL
-) STRICT;
-CREATE TABLE IF NOT EXISTS undo (
-  version INTEGER PRIMARY KEY,
-  doc TEXT NOT NULL,
-  created_ms INTEGER NOT NULL
-) STRICT;
-`;
-
-function serializeWorkspaceDoc(doc: WorkspaceDoc): string {
-  return JSON.stringify(doc);
-}
-
-function assertWorkspaceSize(serialized: string): void {
-  if (Buffer.byteLength(serialized, "utf8") > MAX_WORKSPACE_BYTES) {
-    throw new Error("workspace document exceeds 256 KB");
-  }
-}
-
-/**
- * Reconciles a whole-document replacement against what is already stored, inside
- * the write transaction. Two fields are never taken from the caller:
- *
- * - **the registry itself.** Entries are minted by `workspace_widget_scaffold` and
- *   nowhere else. Replacement preserves the complete current registry and ignores
- *   the incoming field: otherwise a caller could delete approval decisions or mint a `pending`
- *   entry for a name with no widget on disk, have an operator approve it, and only
- *   then write the code the operator "approved". Status likewise changes only
- *   through `workspaces.widget.approve` — a document that arrives already marked
- *   `approved` would skip the gate entirely and the asset route would serve it.
- * - **provenance (`createdBy`).** Otherwise an agent could stamp its own tabs and
- *   widgets `user`, or an operator could stamp `agent:<id>`, and the AI-provenance
- *   chip would be a lie. Existing entities keep their stamp; new ones get `actor`.
- */
-function reconcileReplace(
-  incoming: WorkspaceDoc,
-  current: WorkspaceDoc,
-  actor: WorkspaceActor,
-): WorkspaceDoc {
-  const widgetsRegistry: Record<string, WorkspaceWidgetRegistryEntry> = structuredClone(
-    current.widgetsRegistry,
-  );
-  const existingTabs = new Map(current.tabs.map((tab) => [tab.slug, tab]));
-  const existingWidgets = new Map(
-    current.tabs.flatMap((tab) => tab.widgets.map((widget) => [widget.id, widget] as const)),
-  );
-  return {
-    ...incoming,
-    widgetsRegistry,
-    tabs: incoming.tabs.map((tab) => ({
-      ...tab,
-      createdBy: existingTabs.get(tab.slug)?.createdBy ?? actor,
-      widgets: tab.widgets.map((widget) => ({
-        ...widget,
-        createdBy: existingWidgets.get(widget.id)?.createdBy ?? actor,
-      })),
-    })),
-  };
-}
-
-export class WorkspaceStore {
-  readonly stateDir: string;
-  readonly workspaceDir: string;
-  readonly dbPath: string;
-  private readonly db: DatabaseSync;
-  private readonly walMaintenance: ReturnType<typeof configureSqliteConnectionPragmas>;
-  readonly assetTokens = new WidgetAssetTokens();
-  /**
-   * Single-slot cache of the parsed document. This process is the only writer
-   * and every write goes through `commit()`, so the cache is exact rather than
-   * merely fresh — the capability-gated asset route can check approval status on
-   * every request without re-parsing a 256 KB document.
-   */
-  private cached: WorkspaceDoc | null = null;
-
-  constructor(options: { stateDir?: string } = {}) {
-    this.stateDir = options.stateDir ?? resolveStateDir();
-    this.workspaceDir = path.join(this.stateDir, "workspaces");
-    this.dbPath = path.join(this.workspaceDir, "workspaces.sqlite");
-    mkdirSync(this.workspaceDir, { recursive: true, mode: DIR_MODE });
-    const db = new DatabaseSync(this.dbPath);
-    let walMaintenance: ReturnType<typeof configureSqliteConnectionPragmas> | undefined;
-    try {
-      walMaintenance = configureSqliteConnectionPragmas(db, {
-        busyTimeoutMs: BUSY_TIMEOUT_MS,
-        databaseLabel: "workspaces",
-        databasePath: this.dbPath,
-        foreignKeys: true,
-        synchronous: "NORMAL",
-      });
-      // WAL/SHM sidecars inherit the main DB file's permissions.
-      chmodSync(this.dbPath, FILE_MODE);
-      const versionRow = db.prepare("PRAGMA user_version").get() as
-        | { user_version?: unknown }
-        | undefined;
-      const schemaVersion = Number(versionRow?.user_version ?? 0);
-      if (schemaVersion > SCHEMA_VERSION) {
-        throw new Error(
-          `Workspaces database uses newer schema version ${schemaVersion}; this build supports ${SCHEMA_VERSION}`,
-        );
-      }
-      db.exec(SCHEMA);
-      if (schemaVersion < SCHEMA_VERSION) {
-        migrateSqliteSchemaToStrict(db, SCHEMA, { databaseLabel: this.dbPath });
-        db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
-      }
-    } catch (error) {
-      walMaintenance?.close();
-      db.close();
-      throw error;
-    }
-    if (!walMaintenance) {
-      db.close();
-      throw new Error("Workspaces SQLite maintenance failed to initialize");
-    }
-    this.db = db;
-    this.walMaintenance = walMaintenance;
-  }
-
-  close(): void {
-    this.walMaintenance.close();
-    this.db.close();
-  }
-
-  read(): WorkspaceDoc {
-    if (this.cached) {
-      return structuredClone(this.cached);
-    }
-    const row = this.db.prepare("SELECT doc FROM workspace WHERE id = 1").get() as
-      | { doc: string }
-      | undefined;
-    if (!row) {
-      const seeded = validateWorkspaceDoc(structuredClone(DEFAULT_WORKSPACE));
-      this.commit(seeded, { snapshot: null });
-      return structuredClone(seeded);
-    }
-    const doc = validateWorkspaceDoc(JSON.parse(row.doc));
-    this.cached = doc;
-    return structuredClone(doc);
-  }
-
-  /** Registry entry for one custom widget, or null when it was never scaffolded. */
-  widgetEntry(name: string): WorkspaceWidgetRegistryEntry | null {
-    return this.read().widgetsRegistry[name] ?? null;
-  }
-
-  /** Approval status for one custom widget. */
-  widgetStatus(name: string): WorkspaceWidgetRegistryEntry["status"] | null {
-    return this.widgetEntry(name)?.status ?? null;
-  }
-
-  /**
-   * Applies `fn` to a draft of the current document and persists the result.
-   * `fn` must be synchronous: it runs inside the write transaction, which is what
-   * serializes concurrent RPC / CLI / agent-tool callers.
-   */
-  mutate(
-    fn: (draft: WorkspaceDoc) => WorkspaceDoc | void,
-    _options: WorkspaceMutationOptions,
-  ): WorkspaceMutationResult {
-    return this.transact((current) => {
-      const draft = structuredClone(current);
-      const returned = fn(draft);
-      return returned ?? draft;
-    });
-  }
-
-  /**
-   * Replaces the whole document (bulk authoring). Approval state and provenance
-   * are always reconciled against the stored document, so replace can neither
-   * self-approve a custom widget nor forge a `createdBy` stamp.
-   */
-  replace(doc: WorkspaceDoc, options: WorkspaceMutationOptions): WorkspaceMutationResult {
-    return this.transact((current) =>
-      reconcileReplace(structuredClone(doc), current, options.actor),
-    );
-  }
-
-  /**
-   * Restores the newest undo snapshot as a NEW version. The restored document is
-   * a fresh write, not a rewind: `workspaceVersion` stays monotonic so connected
-   * UIs — which refetch only on a strictly newer version — see the undo.
-   */
-  undo(): WorkspaceDoc {
-    return this.transact(
-      (current) => {
-        const row = this.db
-          .prepare("SELECT version, doc FROM undo ORDER BY version DESC LIMIT 1")
-          .get() as { version: number; doc: string } | undefined;
-        if (!row) {
-          throw new Error("no workspace undo snapshot available");
-        }
-        this.db.prepare("DELETE FROM undo WHERE version = ?").run(row.version);
-        // transact() stamps the next version, so the restored document lands as a
-        // forward write rather than a rewind.
-        const snapshot = validateWorkspaceDoc(JSON.parse(row.doc));
-        // Approval state is a separate operator decision, not layout history.
-        // Undo may restore tabs/widgets, but it must never revive a revoked
-        // approval or discard a registry decision made after the snapshot.
-        return { ...snapshot, widgetsRegistry: current.widgetsRegistry };
-      },
-      // An undo consumes a snapshot; it must not push one, or repeated undo would
-      // oscillate between the last two documents instead of walking history back.
-      { snapshot: false },
-    ).doc;
-  }
-
-  /**
-   * One BEGIN IMMEDIATE transaction: read current, derive next, snapshot the old
-   * document into the undo ring, write, trim. Any throw rolls the whole thing
-   * back, so a rejected write never leaves a partially applied document.
-   */
-  private transact(
-    derive: (current: WorkspaceDoc) => WorkspaceDoc,
-    options: { snapshot?: boolean } = {},
-  ): WorkspaceMutationResult {
-    this.db.exec("BEGIN IMMEDIATE");
-    try {
-      // Derive from what the transaction sees, never from the cache: the cache
-      // is a read-path accelerator, not the transaction's snapshot.
-      this.cached = null;
-      const current = this.read();
-      const next = validateWorkspaceDoc({
-        ...derive(current),
-        workspaceVersion: current.workspaceVersion + 1,
-      });
-      this.commit(next, { snapshot: options.snapshot === false ? null : current });
-      this.db.exec("COMMIT");
-      return { doc: next, changed: true };
-    } catch (error) {
-      this.db.exec("ROLLBACK");
-      this.cached = null;
-      throw error;
-    }
-  }
-
-  /** Persists `doc` as the current workspace, pushing `snapshot` onto the undo ring. */
-  private commit(doc: WorkspaceDoc, params: { snapshot: WorkspaceDoc | null }): void {
-    const serialized = serializeWorkspaceDoc(doc);
-    assertWorkspaceSize(serialized);
-    const now = Date.now();
-    if (params.snapshot) {
-      this.db
-        .prepare("INSERT OR REPLACE INTO undo (version, doc, created_ms) VALUES (?, ?, ?)")
-        .run(doc.workspaceVersion, serializeWorkspaceDoc(params.snapshot), now);
-      this.db
-        .prepare(
-          "DELETE FROM undo WHERE version NOT IN (SELECT version FROM undo ORDER BY version DESC LIMIT ?)",
-        )
-        .run(UNDO_RING_SIZE);
-    }
-    this.db
-      .prepare(
-        "INSERT INTO workspace (id, version, doc, updated_ms) VALUES (1, ?, ?, ?) " +
-          "ON CONFLICT(id) DO UPDATE SET version = excluded.version, doc = excluded.doc, updated_ms = excluded.updated_ms",
-      )
-      .run(doc.workspaceVersion, serialized, now);
-    this.cached = doc;
-  }
-}
diff --git a/extensions/workspaces/src/tools.test.ts b/extensions/workspaces/src/tools.test.ts
deleted file mode 100644
index 2a84c0c1c62..00000000000
--- a/extensions/workspaces/src/tools.test.ts
+++ /dev/null
@@ -1,422 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { Command } from "commander";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { Value } from "typebox/value";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { registerWorkspaceCli } from "./cli.js";
-import { registerWorkspaceGatewayMethods } from "./gateway.js";
-import { WorkspaceStore } from "./store.js";
-import { createWorkspaceTools } from "./tools.js";
-
-const gatewayRuntime = vi.hoisted(() => ({
-  callGatewayFromCli: vi.fn(),
-}));
-const pluginRuntime = vi.hoisted(() => ({
-  scope: undefined as
-    | { context?: { broadcast?: (event: string, payload: unknown) => void } }
-    | undefined,
-}));
-
-vi.mock("openclaw/plugin-sdk/gateway-runtime", async () => {
-  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/gateway-runtime")>(
-    "openclaw/plugin-sdk/gateway-runtime",
-  );
-  return {
-    ...actual,
-    callGatewayFromCli: gatewayRuntime.callGatewayFromCli,
-  };
-});
-
-vi.mock("openclaw/plugin-sdk/plugin-runtime", async () => {
-  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/plugin-runtime")>(
-    "openclaw/plugin-sdk/plugin-runtime",
-  );
-  return {
-    ...actual,
-    getPluginRuntimeGatewayRequestScope: () => pluginRuntime.scope,
-  };
-});
-
-async function withTempStateDir<T>(run: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-tools-"));
-  try {
-    return await run(stateDir);
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-function details(result: unknown): Record<string, unknown> {
-  return (result as { details?: Record<string, unknown> }).details ?? {};
-}
-
-function toolsByName(store: WorkspaceStore, broadcast?: (event: string, payload: unknown) => void) {
-  const api = {} as unknown as OpenClawPluginApi;
-  return new Map(
-    createWorkspaceTools({
-      api,
-      store,
-      ...(broadcast ? { broadcast } : {}),
-      context: { agentId: "main", sessionKey: "session-1" } as never,
-    }).map((tool) => [tool.name, tool]),
-  );
-}
-
-describe("workspace tools", () => {
-  beforeEach(() => {
-    gatewayRuntime.callGatewayFromCli.mockReset();
-    pluginRuntime.scope = undefined;
-  });
-
-  it("defines strict schemas for every workspace tool", () => {
-    const tools = toolsByName(new WorkspaceStore({ stateDir: "/tmp/unused" }));
-    expect([...tools.keys()]).toEqual([
-      "workspace_get",
-      "workspace_tab_create",
-      "workspace_tab_update",
-      "workspace_tab_delete",
-      "workspace_tabs_reorder",
-      "workspace_widget_add",
-      "workspace_widget_update",
-      "workspace_widget_move",
-      "workspace_widget_remove",
-      "workspace_layout_set",
-      "workspace_replace",
-      "workspace_widget_scaffold",
-      "workspace_undo",
-      "workspace_data_read",
-    ]);
-    const validSamples: Record<string, unknown> = {
-      workspace_get: {},
-      workspace_tab_create: { title: "Finance" },
-      workspace_tab_update: { slug: "main", hidden: true, layout: "full" },
-      workspace_tab_delete: { slug: "old" },
-      workspace_tabs_reorder: { order: ["main"] },
-      workspace_widget_add: {
-        tab: "main",
-        kind: "builtin:markdown",
-        grid: { x: 0, y: 0, w: 4, h: 2 },
-      },
-      workspace_widget_update: { tab: "main", id: "cost-today", collapsed: true },
-      workspace_widget_move: { tab: "main", id: "cost-today", grid: { x: 4, y: 0, w: 4, h: 2 } },
-      workspace_widget_remove: { tab: "main", id: "cost-today" },
-      workspace_layout_set: {
-        tab: "main",
-        layout: [{ id: "cost-today", grid: { x: 0, y: 0, w: 4, h: 2 } }],
-      },
-      workspace_replace: {
-        doc: {
-          schemaVersion: 1,
-          workspaceVersion: 1,
-          tabs: [
-            {
-              slug: "main",
-              title: "Main",
-              hidden: false,
-              createdBy: "system",
-              widgets: [],
-            },
-          ],
-          widgetsRegistry: {},
-          prefs: { tabOrder: ["main"] },
-        },
-      },
-      workspace_widget_scaffold: { name: "custom-card" },
-      workspace_undo: {},
-      workspace_data_read: { binding: { source: "static", value: { ok: true } } },
-    };
-    for (const [name, tool] of tools) {
-      expect(Value.Check(tool.parameters, validSamples[name])).toBe(true);
-      expect(Value.Check(tool.parameters, { ...(validSamples[name] as object), extra: true })).toBe(
-        false,
-      );
-    }
-  });
-
-  it("stamps tool provenance from context and rejects createdBy override params", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const broadcast = vi.fn();
-      const tools = toolsByName(store, broadcast);
-
-      await expect(
-        tools.get("workspace_tab_create")?.execute("call-1", {
-          title: "Bad",
-          createdBy: "user",
-        }),
-      ).rejects.toThrow("unexpected param");
-      await tools.get("workspace_tab_create")?.execute("call-2", {
-        title: "Finance",
-        slug: "finance",
-      });
-
-      expect(store.read().tabs.find((tab) => tab.slug === "finance")).toMatchObject({
-        createdBy: "agent:main",
-      });
-      expect(broadcast).toHaveBeenCalledTimes(1);
-      expect(broadcast).toHaveBeenCalledWith("plugin.workspaces.changed", {
-        workspaceVersion: 2,
-        changedTabSlug: "finance",
-        actor: "agent:main",
-      });
-    });
-  });
-
-  it("broadcasts through the active runtime gateway request scope", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const broadcast = vi.fn();
-      pluginRuntime.scope = { context: { broadcast } };
-      const tools = toolsByName(store);
-
-      await tools.get("workspace_tab_create")?.execute("call-1", {
-        title: "Runtime Scope",
-        slug: "runtime-scope",
-      });
-
-      expect(broadcast).toHaveBeenCalledTimes(1);
-      expect(broadcast).toHaveBeenCalledWith("plugin.workspaces.changed", {
-        workspaceVersion: 2,
-        changedTabSlug: "runtime-scope",
-        actor: "agent:main",
-      });
-    });
-  });
-
-  it("sanitizes agent workspace replacement provenance and approvals", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      // Seed an already-approved widget through the store primitive: `replace` is
-      // reconciled and by design cannot mint an approval.
-      store.mutate(
-        (draft) => {
-          draft.widgetsRegistry["approved-card"] = {
-            status: "approved",
-            createdBy: "user",
-            approvedBy: "user",
-            approvedAt: "2026-01-01T00:00:00.000Z",
-          };
-        },
-        { actor: "user" },
-      );
-
-      const tools = toolsByName(store);
-      const replacement = structuredClone(store.read());
-      replacement.tabs[0]!.createdBy = "agent:forged";
-      replacement.tabs.push({
-        slug: "agent-tab",
-        title: "Agent Tab",
-        hidden: false,
-        createdBy: "user",
-        widgets: [],
-      });
-      replacement.prefs.tabOrder.push("agent-tab");
-      replacement.widgetsRegistry["approved-card"] = {
-        status: "pending",
-        createdBy: "agent:forged",
-      };
-      replacement.widgetsRegistry["new-card"] = {
-        status: "approved",
-        createdBy: "user",
-        approvedBy: "user",
-        approvedAt: "2026-01-02T00:00:00.000Z",
-      };
-
-      await tools.get("workspace_replace")?.execute("call-1", { doc: replacement });
-
-      const next = store.read();
-      // Provenance is immutable once stamped: the agent cannot relabel the seeded
-      // system tab as its own, nor claim its own new tab was authored by a human.
-      expect(next.tabs.find((tab) => tab.slug === "main")?.createdBy).toBe("system");
-      expect(next.tabs.find((tab) => tab.slug === "agent-tab")?.createdBy).toBe("agent:main");
-      expect(next.widgetsRegistry["approved-card"]).toEqual({
-        status: "approved",
-        createdBy: "user",
-        approvedBy: "user",
-        approvedAt: "2026-01-01T00:00:00.000Z",
-      });
-      // A registry name the agent invented is dropped: only workspace_widget_scaffold
-      // mints entries, so an operator can never be asked to approve a name whose code
-      // does not exist yet.
-      expect(next.widgetsRegistry["new-card"]).toBeUndefined();
-    });
-  });
-
-  it("mutates widgets, reads data, and broadcasts one change per write", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const broadcast = vi.fn();
-      const tools = toolsByName(store, broadcast);
-
-      await tools.get("workspace_tab_create")?.execute("call-1", {
-        title: "Ops",
-        slug: "ops",
-      });
-      const addResult = details(
-        await tools.get("workspace_widget_add")?.execute("call-2", {
-          tab: "ops",
-          id: "notes",
-          kind: "builtin:markdown",
-          title: "Notes",
-          grid: { x: 0, y: 0, w: 4, h: 2 },
-          bindings: { value: { source: "static", value: "hello" } },
-        }),
-      );
-      expect(addResult.doc).toMatchObject({
-        tabs: [
-          expect.any(Object),
-          expect.objectContaining({
-            slug: "ops",
-            widgets: [expect.objectContaining({ id: "notes", title: "Notes" })],
-          }),
-        ],
-      });
-      await tools.get("workspace_widget_move")?.execute("call-3", {
-        tab: "ops",
-        id: "notes",
-        grid: { x: 4, y: 0, w: 4, h: 2 },
-      });
-      const data = details(
-        await tools.get("workspace_data_read")?.execute("call-4", {
-          binding: { source: "static", value: { ok: true } },
-        }),
-      );
-      expect(data).toEqual({ data: { ok: true } });
-      expect(broadcast).toHaveBeenCalledTimes(3);
-    });
-  });
-
-  it("scaffolds agent-authored widgets as pending with a standalone bridge template", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const tools = toolsByName(store);
-
-      await tools.get("workspace_widget_scaffold")?.execute("call-1", {
-        name: "agent-chart",
-        title: "Agent Chart",
-      });
-
-      const widgetDir = path.join(stateDir, "workspaces", "widgets", "agent-chart");
-      const htmlPath = path.join(widgetDir, "index.html");
-      const html = await fs.readFile(htmlPath, "utf8");
-      expect(html).toContain("workspace:ready");
-      expect(html).toContain("workspace:getData");
-      expect(html).toContain("function onData");
-      expect(html).not.toMatch(/https?:\/\//);
-      expect(store.read().widgetsRegistry["agent-chart"]).toMatchObject({
-        status: "pending",
-        createdBy: "agent:main",
-      });
-
-      await fs.writeFile(htmlPath, "custom implementation", "utf8");
-      await expect(
-        tools.get("workspace_widget_scaffold")?.execute("call-2", {
-          name: "agent-chart",
-          title: "Replacement",
-        }),
-      ).rejects.toThrow("widget already exists");
-      expect(await fs.readFile(htmlPath, "utf8")).toBe("custom implementation");
-      expect(store.read().widgetsRegistry["agent-chart"]).toMatchObject({
-        status: "pending",
-        createdBy: "agent:main",
-      });
-    });
-  });
-
-  it("workspace_widget_update applies a patch addressed by tab + id", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const tools = toolsByName(store);
-
-      // Regression: the tool passed its whole param record to the patch reader,
-      // whose allowlist rejects `tab`/`id` — so no call could ever succeed.
-      await tools.get("workspace_widget_update")?.execute("call-1", {
-        tab: "main",
-        id: "cost-today",
-        title: "Spend today",
-        collapsed: true,
-      });
-
-      const widget = store.read().tabs[0]?.widgets.find((entry) => entry.id === "cost-today");
-      expect(widget).toMatchObject({ title: "Spend today", collapsed: true });
-    });
-  });
-
-  it("workspace_data_read reports rpc bindings as client-resolved, not as a failure", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const tools = toolsByName(new WorkspaceStore({ stateDir }));
-
-      const result = await tools
-        .get("workspace_data_read")
-        ?.execute("call-1", { binding: { source: "rpc", method: "usage.cost" } });
-
-      const [entry] = result?.content ?? [];
-      expect(entry?.type === "text" && entry.text).toContain("binding_client_resolved");
-    });
-  });
-
-  it("rejects scaffold names that would escape the widgets directory", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const tools = toolsByName(store);
-
-      await expect(
-        tools.get("workspace_widget_scaffold")?.execute("call-1", { name: ".." }),
-      ).rejects.toThrow("widget name is invalid");
-      await expect(fs.stat(path.join(stateDir, "workspaces", "widget.json"))).rejects.toThrow();
-    });
-  });
-
-  it("shares one store between tool writes and CLI reads", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      const methods = new Map<string, Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1]>();
-      registerWorkspaceGatewayMethods({
-        api: {
-          registerGatewayMethod: vi.fn((method: string, handler) => methods.set(method, handler)),
-        } as unknown as OpenClawPluginApi,
-        store,
-      });
-      gatewayRuntime.callGatewayFromCli.mockImplementation(
-        async (method: string, _opts: unknown, params: unknown) => {
-          const respond = vi.fn();
-          await methods.get(method)?.({
-            params: params ?? {},
-            respond,
-            context: { broadcast: vi.fn() },
-          } as never);
-          const [ok, result, error] = respond.mock.calls[0] ?? [];
-          if (ok) {
-            return result;
-          }
-          throw new Error(error?.message ?? "gateway error");
-        },
-      );
-      const tools = toolsByName(store);
-      await tools.get("workspace_tab_create")?.execute("call-1", {
-        title: "Tool Tab",
-        slug: "tool-tab",
-      });
-
-      const program = new Command();
-      program.exitOverride();
-      program.configureOutput({ writeErr: () => {}, writeOut: () => {} });
-      registerWorkspaceCli({ program, stateDir });
-      const chunks: string[] = [];
-      const write = vi.spyOn(process.stdout, "write").mockImplementation((chunk): boolean => {
-        chunks.push(String(chunk));
-        return true;
-      });
-      try {
-        await program.parseAsync(["workspaces", "tabs", "list", "--json"], { from: "user" });
-      } finally {
-        write.mockRestore();
-      }
-      expect(JSON.parse(chunks.join(""))).toMatchObject({
-        tabs: [expect.any(Object), expect.objectContaining({ slug: "tool-tab" })],
-      });
-    });
-  });
-});
diff --git a/extensions/workspaces/src/tools.ts b/extensions/workspaces/src/tools.ts
deleted file mode 100644
index cfe59b67605..00000000000
--- a/extensions/workspaces/src/tools.ts
+++ /dev/null
@@ -1,919 +0,0 @@
-import { jsonResult } from "openclaw/plugin-sdk/core";
-import type {
-  AnyAgentTool,
-  OpenClawPluginApi,
-  OpenClawPluginToolContext,
-} from "openclaw/plugin-sdk/plugin-entry";
-import { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
-import { Type } from "typebox";
-import { workspaceBroadcast, type WorkspaceBroadcast } from "./broadcast.js";
-import {
-  WorkspaceBindingResolutionError,
-  DATA_READ_RPC_ALLOWLIST,
-  resolveBinding,
-  type ResolveBindingOptions,
-} from "./data-read.js";
-import { scaffoldWorkspaceWidget } from "./scaffold.js";
-import {
-  BUILTIN_WIDGET_KINDS,
-  isWorkspaceActor,
-  validateWorkspaceDoc,
-  type WorkspaceActor,
-  type WorkspaceBinding,
-  type WorkspaceGrid,
-  type WorkspaceTab,
-  type WorkspaceWidget,
-  type JsonValue,
-  type WorkspaceDoc,
-} from "./schema.js";
-import { WorkspaceStore } from "./store.js";
-
-type WorkspaceToolParams = {
-  api: OpenClawPluginApi;
-  context?: OpenClawPluginToolContext;
-  store?: WorkspaceStore;
-  broadcast?: WorkspaceBroadcast;
-  dataRead?: ResolveBindingOptions;
-};
-
-type MutationParams = {
-  store: WorkspaceStore;
-  actor: WorkspaceActor;
-  broadcast?: WorkspaceBroadcast;
-  changedTabSlug?: string;
-  mutate: (draft: WorkspaceDoc) => void | WorkspaceDoc;
-};
-
-const TAB_SLUG_PATTERN = /^[a-z0-9-]{1,40}$/;
-const WIDGET_ID_PATTERN = /^[A-Za-z0-9_-]{1,48}$/;
-const TOOL_DESCRIPTION_SUFFIX = " Call workspace_get first when you need the current document.";
-
-/**
- * Both lists below exist because a model can only see tool schemas. An agent that
- * has to brute-force the valid `kind` values or the rpc allowlist burns dozens of
- * round-trips against "kind is invalid" / "method is not allowlisted".
- */
-const WIDGET_KIND_DESCRIPTION = [
-  `Widget kind: custom:<name>, or one of ${BUILTIN_WIDGET_KINDS.join(", ")}.`,
-  "builtin:stat-card (big number; props {label?, format?: usd|percent|int}; binding id `value`),",
-  "builtin:markdown (props {markdown} or {text}, or a file binding of a .md file),",
-  "builtin:table (binding id `rows`; props {columns: string[]}),",
-  "builtin:iframe-embed (props {url}),",
-  "builtin:preview (props {url, defaultViewport?: desktop|tablet|mobile}, or binding id `value`; live sandboxed preview with reload and viewport controls),",
-  "builtin:sessions, builtin:usage, builtin:cron, builtin:instances, builtin:activity,",
-  "builtin:agent-status (binding id `value` to sessions.list; live Busy/Idle rows),",
-  "builtin:custom-widget-approvals (pending custom-widget registry decisions only; operator.approvals controls),",
-  "builtin:chart (binding id `value`; props {type?: line|bar|area|sparkline|gauge, min?: number, max?: number}; value is number[] or {points: Array<number|{y|value}>}).",
-  "Data widgets read their declared rpc binding; see workspace_get for a worked example.",
-].join(" ");
-
-const JsonSchema = Type.Unknown({
-  description: "JSON-compatible value. Per-kind shapes are described on `kind`.",
-});
-const GridSchema = Type.Object(
-  {
-    x: Type.Integer({ minimum: 0, maximum: 11, description: "Grid x column, 0-11." }),
-    y: Type.Integer({ minimum: 0, maximum: 499, description: "Grid row, 0-499." }),
-    w: Type.Integer({ minimum: 1, maximum: 12, description: "Grid width, 1-12." }),
-    h: Type.Integer({ minimum: 1, maximum: 20, description: "Grid height, 1-20." }),
-  },
-  { additionalProperties: false },
-);
-const BindingSchema = Type.Union([
-  Type.Object(
-    {
-      source: Type.Literal("rpc"),
-      method: Type.String({
-        description: `Allowlisted gateway read method, one of: ${DATA_READ_RPC_ALLOWLIST.join(", ")}.`,
-      }),
-      params: Type.Optional(
-        Type.Record(Type.String(), JsonSchema, {
-          description: "Bounded JSON parameters required by the selected gateway method.",
-        }),
-      ),
-    },
-    { additionalProperties: false },
-  ),
-  Type.Object(
-    {
-      source: Type.Literal("file"),
-      path: Type.String({ description: "Relative path under workspace/data." }),
-      pointer: Type.Optional(Type.String({ description: "Optional JSON pointer." })),
-    },
-    { additionalProperties: false },
-  ),
-  Type.Object(
-    {
-      source: Type.Literal("static"),
-      value: JsonSchema,
-    },
-    { additionalProperties: false },
-  ),
-]);
-const BindingsRecordSchema = Type.Record(Type.String(), BindingSchema, {
-  description: "Widget binding map keyed by binding id.",
-});
-const WidgetPatchSchema = Type.Object(
-  {
-    title: Type.Optional(Type.String({ description: "Widget title, 80 chars max." })),
-    grid: Type.Optional(GridSchema),
-    collapsed: Type.Optional(Type.Boolean({ description: "Collapse widget body." })),
-    hidden: Type.Optional(Type.Boolean({ description: "Hide widget." })),
-    bindings: Type.Optional(BindingsRecordSchema),
-    props: Type.Optional(JsonSchema),
-  },
-  { additionalProperties: false },
-);
-const WidgetInputSchema = Type.Object(
-  {
-    id: Type.Optional(Type.String({ description: "Optional unique widget id." })),
-    kind: Type.String({ description: WIDGET_KIND_DESCRIPTION }),
-    title: Type.Optional(Type.String({ description: "Widget title." })),
-    grid: GridSchema,
-    collapsed: Type.Optional(Type.Boolean({ description: "Initial collapsed state." })),
-    hidden: Type.Optional(Type.Boolean({ description: "Initial hidden state." })),
-    bindings: Type.Optional(BindingsRecordSchema),
-    props: Type.Optional(JsonSchema),
-  },
-  { additionalProperties: false },
-);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function readRecord(params: unknown, allowedKeys: readonly string[]): Record<string, unknown> {
-  if (!isRecord(params)) {
-    throw new Error("params must be an object");
-  }
-  for (const key of Object.keys(params)) {
-    if (!allowedKeys.includes(key)) {
-      throw new Error(`unexpected param: ${key}`);
-    }
-  }
-  return params;
-}
-
-function readRequiredString(
-  record: Record<string, unknown>,
-  key: string,
-  description = key,
-): string {
-  const value = record[key];
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`${description} is required`);
-  }
-  return value.trim();
-}
-
-function readOptionalString(record: Record<string, unknown>, key: string): string | undefined {
-  const value = record[key];
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== "string") {
-    throw new Error(`${key} must be a string`);
-  }
-  return value.trim();
-}
-
-function readOptionalBoolean(record: Record<string, unknown>, key: string): boolean | undefined {
-  const value = record[key];
-  if (value === undefined) {
-    return undefined;
-  }
-  if (typeof value !== "boolean") {
-    throw new Error(`${key} must be a boolean`);
-  }
-  return value;
-}
-
-function readSlug(record: Record<string, unknown>, key = "slug"): string {
-  const slug = readRequiredString(record, key, key);
-  if (!TAB_SLUG_PATTERN.test(slug)) {
-    throw new Error(`${key} is invalid`);
-  }
-  return slug;
-}
-
-function readWidgetId(record: Record<string, unknown>, key = "id"): string {
-  const id = readRequiredString(record, key, key);
-  if (!WIDGET_ID_PATTERN.test(id)) {
-    throw new Error(`${key} is invalid`);
-  }
-  return id;
-}
-
-function readGrid(value: unknown, pathName = "grid"): WorkspaceGrid {
-  if (!isRecord(value)) {
-    throw new Error(`${pathName} must be an object`);
-  }
-  for (const key of Object.keys(value)) {
-    if (!["x", "y", "w", "h"].includes(key)) {
-      throw new Error(`${pathName}.${key} is not allowed`);
-    }
-  }
-  return {
-    x: readGridInt(value.x, `${pathName}.x`, 0, 11),
-    y: readGridInt(value.y, `${pathName}.y`, 0, 499),
-    w: readGridInt(value.w, `${pathName}.w`, 1, 12),
-    h: readGridInt(value.h, `${pathName}.h`, 1, 20),
-  };
-}
-
-function readGridInt(value: unknown, pathName: string, min: number, max: number): number {
-  if (!Number.isInteger(value) || (value as number) < min || (value as number) > max) {
-    throw new Error(`${pathName} must be an integer from ${min} to ${max}`);
-  }
-  return value as number;
-}
-
-function readBindings(value: unknown): Record<string, WorkspaceBinding> | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  if (!isRecord(value)) {
-    throw new Error("bindings must be an object");
-  }
-  return value as Record<string, WorkspaceBinding>;
-}
-
-function slugBase(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40)
-    .replace(/-+$/g, "");
-}
-
-function makeUniqueSlug(title: string, tabs: WorkspaceTab[]): string {
-  const used = new Set(tabs.map((tab) => tab.slug));
-  const base = slugBase(title) || "tab";
-  if (!used.has(base)) {
-    return base;
-  }
-  for (let index = 2; index < 1000; index += 1) {
-    const suffix = `-${index}`;
-    const candidate = `${base.slice(0, 40 - suffix.length)}${suffix}`;
-    if (!used.has(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error("could not generate a unique tab slug");
-}
-
-function makeWidgetIdBase(value: string): string {
-  return (
-    value
-      .trim()
-      .toLowerCase()
-      .replace(/[^a-z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "")
-      .slice(0, 48)
-      .replace(/-+$/g, "") || "widget"
-  );
-}
-
-function makeUniqueWidgetId(widget: Record<string, unknown>, doc: WorkspaceDoc): string {
-  const existing = new Set(doc.tabs.flatMap((tab) => tab.widgets.map((entry) => entry.id)));
-  const explicit = widget.id;
-  if (explicit !== undefined) {
-    if (typeof explicit !== "string" || !WIDGET_ID_PATTERN.test(explicit)) {
-      throw new Error("widget.id is invalid");
-    }
-    if (existing.has(explicit)) {
-      throw new Error(`duplicate widget id: ${explicit}`);
-    }
-    return explicit;
-  }
-  const title =
-    typeof widget.title === "string"
-      ? widget.title
-      : typeof widget.kind === "string"
-        ? widget.kind
-        : "widget";
-  const base = makeWidgetIdBase(title);
-  if (!existing.has(base)) {
-    return base;
-  }
-  for (let index = 2; index < 1000; index += 1) {
-    const suffix = `-${index}`;
-    const candidate = `${base.slice(0, 48 - suffix.length)}${suffix}`;
-    if (!existing.has(candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error("could not generate a unique widget id");
-}
-
-function findTab(doc: WorkspaceDoc, slug: string): WorkspaceTab {
-  const tab = doc.tabs.find((entry) => entry.slug === slug);
-  if (!tab) {
-    throw new Error(`workspace tab not found: ${slug}`);
-  }
-  return tab;
-}
-
-function findWidget(tab: WorkspaceTab, id: string): WorkspaceWidget {
-  const widget = tab.widgets.find((entry) => entry.id === id);
-  if (!widget) {
-    throw new Error(`workspace widget not found: ${id}`);
-  }
-  return widget;
-}
-
-function readWidgetInput(
-  value: unknown,
-  doc: WorkspaceDoc,
-  actor: WorkspaceActor,
-): WorkspaceWidget {
-  const record = readRecord(value, [
-    "id",
-    "kind",
-    "title",
-    "grid",
-    "collapsed",
-    "hidden",
-    "bindings",
-    "props",
-  ]);
-  const title = readOptionalString(record, "title");
-  const bindings = readBindings(record.bindings);
-  return {
-    id: makeUniqueWidgetId(record, doc),
-    kind: readRequiredString(record, "kind", "kind"),
-    ...(title !== undefined ? { title } : {}),
-    grid: readGrid(record.grid),
-    collapsed: readOptionalBoolean(record, "collapsed") ?? false,
-    hidden: readOptionalBoolean(record, "hidden") ?? false,
-    createdBy: actor,
-    ...(bindings !== undefined ? { bindings } : {}),
-    ...(record.props !== undefined ? { props: record.props as JsonValue } : {}),
-  };
-}
-
-function readWidgetPatch(value: unknown): Partial<WorkspaceWidget> {
-  const record = readRecord(value, ["title", "grid", "collapsed", "hidden", "bindings", "props"]);
-  const title = readOptionalString(record, "title");
-  const collapsed = readOptionalBoolean(record, "collapsed");
-  const hidden = readOptionalBoolean(record, "hidden");
-  const bindings = readBindings(record.bindings);
-  return {
-    ...(title !== undefined ? { title } : {}),
-    ...(record.grid !== undefined ? { grid: readGrid(record.grid) } : {}),
-    ...(collapsed !== undefined ? { collapsed } : {}),
-    ...(hidden !== undefined ? { hidden } : {}),
-    ...(bindings !== undefined ? { bindings } : {}),
-    ...(record.props !== undefined ? { props: record.props as JsonValue } : {}),
-  };
-}
-
-function readLayout(value: unknown): Array<{ id: string; grid: WorkspaceGrid }> {
-  if (!Array.isArray(value)) {
-    throw new Error("layout must be an array");
-  }
-  return value.map((entry, index) => {
-    const record = readRecord(entry, ["id", "grid"]);
-    return {
-      id: readWidgetId(record),
-      grid: readGrid(record.grid, `layout[${index}].grid`),
-    };
-  });
-}
-
-function readOrder(value: unknown): string[] {
-  if (!Array.isArray(value)) {
-    throw new Error("order must be an array");
-  }
-  const seen = new Set<string>();
-  return value.map((entry, index) => {
-    if (typeof entry !== "string" || !TAB_SLUG_PATTERN.test(entry)) {
-      throw new Error(`order[${index}] is invalid`);
-    }
-    if (seen.has(entry)) {
-      throw new Error(`order contains duplicate slug: ${entry}`);
-    }
-    seen.add(entry);
-    return entry;
-  });
-}
-
-function appendMissingTabsToOrder(doc: WorkspaceDoc): void {
-  const seen = new Set(doc.prefs.tabOrder);
-  for (const tab of doc.tabs) {
-    if (!seen.has(tab.slug)) {
-      doc.prefs.tabOrder.push(tab.slug);
-    }
-  }
-}
-
-function contextOwner(ctx: OpenClawPluginToolContext | undefined): string {
-  const record = (ctx ?? {}) as Record<string, unknown>;
-  return (
-    (typeof record.agentId === "string" && record.agentId) ||
-    (typeof record.sessionKey === "string" && record.sessionKey) ||
-    (typeof record.sessionId === "string" && record.sessionId) ||
-    "agent"
-  );
-}
-
-function actorFromContext(ctx: OpenClawPluginToolContext | undefined): WorkspaceActor {
-  const normalized =
-    contextOwner(ctx)
-      .replace(/[^A-Za-z0-9._-]+/g, "-")
-      .replace(/^-+|-+$/g, "")
-      .slice(0, 64) || "agent";
-  const actor = `agent:${normalized}`;
-  if (!isWorkspaceActor(actor)) {
-    throw new Error("tool context owner cannot be used as workspace actor");
-  }
-  return actor;
-}
-
-function broadcastChange(
-  broadcast: WorkspaceBroadcast | undefined,
-  params: { doc: WorkspaceDoc; actor: WorkspaceActor; changedTabSlug?: string },
-) {
-  broadcast?.("plugin.workspaces.changed", {
-    workspaceVersion: params.doc.workspaceVersion,
-    ...(params.changedTabSlug ? { changedTabSlug: params.changedTabSlug } : {}),
-    actor: params.actor,
-  });
-}
-
-function resolveWorkspaceBroadcast(
-  broadcast: WorkspaceBroadcast | undefined,
-): WorkspaceBroadcast | undefined {
-  // The request scope only exists when the turn originated from a gateway RPC.
-  // A channel/cron/heartbeat turn falls back to the remembered server handle, so
-  // an agent edit still reaches every open Control UI.
-  return (
-    broadcast ?? getPluginRuntimeGatewayRequestScope()?.context?.broadcast ?? workspaceBroadcast()
-  );
-}
-
-async function runMutation(params: MutationParams) {
-  const result = params.store.mutate(params.mutate, { actor: params.actor });
-  broadcastChange(params.broadcast, {
-    doc: result.doc,
-    actor: params.actor,
-    changedTabSlug: params.changedTabSlug,
-  });
-  return jsonResult({ doc: result.doc, workspaceVersion: result.doc.workspaceVersion });
-}
-
-// Scaffold template (spec-50 §Scaffold): demonstrates the v1 handshake, getData +
-// onData(=push), theme tokens applied to CSS vars, ZERO external requests, and a
-// visible "built by <createdBy>" footer. Framework-free and < 100 lines.
-
-function toolDescription(text: string): string {
-  return `${text}${TOOL_DESCRIPTION_SUFFIX}`;
-}
-
-export function createWorkspaceTools(params: WorkspaceToolParams): AnyAgentTool[] {
-  const store = params.store ?? new WorkspaceStore();
-  const actor = actorFromContext(params.context);
-  const broadcast = resolveWorkspaceBroadcast(params.broadcast);
-  const mutationBase = {
-    store,
-    actor,
-    broadcast,
-  };
-  return [
-    {
-      name: "workspace_get",
-      label: "Workspace Get",
-      description: "Read the full Workspaces document so an agent can diff before mutating it.",
-      parameters: Type.Object({}, { additionalProperties: false }),
-      execute: async () => {
-        const doc = store.read();
-        return jsonResult({ doc, workspaceVersion: doc.workspaceVersion });
-      },
-    },
-    {
-      name: "workspace_tab_create",
-      label: "Workspace Tab Create",
-      description: toolDescription(
-        "Create a workspace tab. Slugs are lowercase letters, digits, and dashes, max 40 chars.",
-      ),
-      parameters: Type.Object(
-        {
-          title: Type.String({ description: "Tab title, 1-80 chars." }),
-          slug: Type.Optional(Type.String({ description: "Optional tab slug." })),
-          icon: Type.Optional(Type.String({ description: "Optional icon name." })),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["title", "slug", "icon"]);
-        const title = readRequiredString(record, "title", "title");
-        const icon = readOptionalString(record, "icon");
-        let changedTabSlug: string | undefined;
-        return await runMutation({
-          ...mutationBase,
-          mutate: (draft) => {
-            const slug =
-              record.slug === undefined ? makeUniqueSlug(title, draft.tabs) : readSlug(record);
-            if (draft.tabs.some((tab) => tab.slug === slug)) {
-              throw new Error(`workspace tab already exists: ${slug}`);
-            }
-            changedTabSlug = slug;
-            draft.tabs.push({
-              slug,
-              title,
-              ...(icon !== undefined ? { icon } : {}),
-              hidden: false,
-              createdBy: actor,
-              widgets: [],
-            });
-            draft.prefs.tabOrder.push(slug);
-          },
-          get changedTabSlug() {
-            return changedTabSlug;
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_tab_update",
-      label: "Workspace Tab Update",
-      description: toolDescription("Update a workspace tab title, icon, hidden state, or layout."),
-      parameters: Type.Object(
-        {
-          slug: Type.String({ description: "Tab slug." }),
-          title: Type.Optional(Type.String({ description: "New title." })),
-          icon: Type.Optional(Type.String({ description: "New icon." })),
-          hidden: Type.Optional(Type.Boolean({ description: "Hide or show the tab." })),
-          layout: Type.Optional(
-            Type.Union([Type.Literal("grid"), Type.Literal("full")], {
-              description: "Grid layout, or one full-bleed app widget.",
-            }),
-          ),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["slug", "title", "icon", "hidden", "layout"]);
-        const slug = readSlug(record);
-        const title = readOptionalString(record, "title");
-        const icon = readOptionalString(record, "icon");
-        const hidden = readOptionalBoolean(record, "hidden");
-        const layout = record.layout;
-        if (layout !== undefined && layout !== "grid" && layout !== "full") {
-          throw new Error('layout must be "grid" or "full"');
-        }
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: slug,
-          mutate: (draft) => {
-            Object.assign(findTab(draft, slug), {
-              ...(title !== undefined ? { title } : {}),
-              ...(icon !== undefined ? { icon } : {}),
-              ...(hidden !== undefined ? { hidden } : {}),
-              ...(layout !== undefined ? { layout } : {}),
-            });
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_tab_delete",
-      label: "Workspace Tab Delete",
-      description: toolDescription("Delete a workspace tab and all widgets inside it."),
-      parameters: Type.Object(
-        { slug: Type.String({ description: "Tab slug." }) },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["slug"]);
-        const slug = readSlug(record);
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: slug,
-          mutate: (draft) => {
-            const nextTabs = draft.tabs.filter((tab) => tab.slug !== slug);
-            if (nextTabs.length === draft.tabs.length) {
-              throw new Error(`workspace tab not found: ${slug}`);
-            }
-            draft.tabs = nextTabs;
-            draft.prefs.tabOrder = draft.prefs.tabOrder.filter((entry) => entry !== slug);
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_tabs_reorder",
-      label: "Workspace Tabs Reorder",
-      description: toolDescription("Set workspace tab order. Missing existing tabs are appended."),
-      parameters: Type.Object(
-        { order: Type.Array(Type.String({ description: "Tab slug." })) },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["order"]);
-        const order = readOrder(record.order);
-        return await runMutation({
-          ...mutationBase,
-          mutate: (draft) => {
-            const slugs = new Set(draft.tabs.map((tab) => tab.slug));
-            for (const slug of order) {
-              if (!slugs.has(slug)) {
-                throw new Error(`workspace tab not found: ${slug}`);
-              }
-            }
-            draft.prefs.tabOrder = order;
-            appendMissingTabsToOrder(draft);
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_widget_add",
-      label: "Workspace Widget Add",
-      description: toolDescription(
-        "Add a widget to a tab. Grid x+w must fit within the 12-column workspace grid.",
-      ),
-      parameters: Type.Object(
-        {
-          tab: Type.String({ description: "Target tab slug." }),
-          ...WidgetInputSchema.properties,
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, [
-          "tab",
-          "id",
-          "kind",
-          "title",
-          "grid",
-          "collapsed",
-          "hidden",
-          "bindings",
-          "props",
-        ]);
-        const tabSlug = readSlug(record, "tab");
-        const widgetInput = { ...record };
-        delete widgetInput.tab;
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: tabSlug,
-          mutate: (draft) => {
-            findTab(draft, tabSlug).widgets.push(readWidgetInput(widgetInput, draft, actor));
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_widget_update",
-      label: "Workspace Widget Update",
-      description: toolDescription("Patch a widget title, grid, visibility, bindings, or props."),
-      parameters: Type.Object(
-        {
-          tab: Type.String({ description: "Tab slug." }),
-          id: Type.String({ description: "Widget id." }),
-          ...WidgetPatchSchema.properties,
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, [
-          "tab",
-          "id",
-          "title",
-          "grid",
-          "collapsed",
-          "hidden",
-          "bindings",
-          "props",
-        ]);
-        const tabSlug = readSlug(record, "tab");
-        const id = readWidgetId(record);
-        // `tab` and `id` address the widget; everything else is the patch. Passing
-        // the whole record to readWidgetPatch made this tool uncallable: its reader
-        // rejects `tab`/`id` as unexpected params.
-        const { tab: _tab, id: _id, ...patchInput } = record;
-        const patch = readWidgetPatch(patchInput);
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: tabSlug,
-          mutate: (draft) => {
-            Object.assign(findWidget(findTab(draft, tabSlug), id), patch);
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_widget_move",
-      label: "Workspace Widget Move",
-      description: toolDescription(
-        "Move a widget by changing its grid OR moving it to another tab — exactly one of " +
-          "`grid` and `toTab`, never both. A cross-tab move keeps the widget's old grid " +
-          "position, so follow it with a second call to reposition.",
-      ),
-      parameters: Type.Object(
-        {
-          tab: Type.Optional(Type.String({ description: "Current tab slug for grid moves." })),
-          id: Type.String({ description: "Widget id." }),
-          grid: Type.Optional(GridSchema),
-          toTab: Type.Optional(Type.String({ description: "Destination tab slug." })),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["tab", "id", "grid", "toTab"]);
-        if (record.grid !== undefined && record.toTab !== undefined) {
-          throw new Error("workspace_widget_move accepts either grid or toTab, not both");
-        }
-        if (record.grid === undefined && record.toTab === undefined) {
-          throw new Error("workspace_widget_move requires grid or toTab");
-        }
-        const id = readWidgetId(record);
-        const changedTabSlug =
-          typeof record.toTab === "string"
-            ? record.toTab
-            : typeof record.tab === "string"
-              ? record.tab
-              : undefined;
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug,
-          mutate: (draft) => {
-            if (record.grid !== undefined) {
-              const tabSlug = readSlug(record, "tab");
-              findWidget(findTab(draft, tabSlug), id).grid = readGrid(record.grid);
-              return;
-            }
-            const toTab = readSlug(record, "toTab");
-            const destination = findTab(draft, toTab);
-            for (const tab of draft.tabs) {
-              const index = tab.widgets.findIndex((widget) => widget.id === id);
-              if (index >= 0) {
-                destination.widgets.push(tab.widgets.splice(index, 1)[0]!);
-                return;
-              }
-            }
-            throw new Error(`workspace widget not found: ${id}`);
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_widget_remove",
-      label: "Workspace Widget Remove",
-      description: toolDescription("Remove a widget from a tab."),
-      parameters: Type.Object(
-        {
-          tab: Type.String({ description: "Tab slug." }),
-          id: Type.String({ description: "Widget id." }),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["tab", "id"]);
-        const tabSlug = readSlug(record, "tab");
-        const id = readWidgetId(record);
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: tabSlug,
-          mutate: (draft) => {
-            const tab = findTab(draft, tabSlug);
-            const next = tab.widgets.filter((widget) => widget.id !== id);
-            if (next.length === tab.widgets.length) {
-              throw new Error(`workspace widget not found: ${id}`);
-            }
-            tab.widgets = next;
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_layout_set",
-      label: "Workspace Layout Set",
-      description: toolDescription("Batch-update widget grids for one tab."),
-      parameters: Type.Object(
-        {
-          tab: Type.String({ description: "Tab slug." }),
-          layout: Type.Array(
-            Type.Object(
-              { id: Type.String({ description: "Widget id." }), grid: GridSchema },
-              { additionalProperties: false },
-            ),
-          ),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["tab", "layout"]);
-        const tabSlug = readSlug(record, "tab");
-        const layout = readLayout(record.layout);
-        return await runMutation({
-          ...mutationBase,
-          changedTabSlug: tabSlug,
-          mutate: (draft) => {
-            const tab = findTab(draft, tabSlug);
-            for (const entry of layout) {
-              findWidget(tab, entry.id).grid = entry.grid;
-            }
-          },
-        });
-      },
-    },
-    {
-      name: "workspace_replace",
-      label: "Workspace Replace",
-      description: toolDescription(
-        "Replace the full workspace document after local validation and size/schema caps.",
-      ),
-      parameters: Type.Object({ doc: Type.Unknown() }, { additionalProperties: false }),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["doc"]);
-        const doc = validateWorkspaceDoc(record.doc);
-        const result = store.replace(doc, { actor });
-        broadcastChange(broadcast, { doc: result.doc, actor });
-        return jsonResult({ doc: result.doc, workspaceVersion: result.doc.workspaceVersion });
-      },
-    },
-    {
-      name: "workspace_widget_scaffold",
-      label: "Workspace Widget Scaffold",
-      description: toolDescription(
-        "Create a custom widget scaffold and register it as pending. Agent-authored widget code " +
-          "never renders until a human approves it, and there is no tool to approve it — ask the " +
-          "operator to approve from the Workspaces tab, or to run `openclaw workspaces " +
-          "widget-approve <name>`. Edit the scaffolded index.html to build the widget.",
-      ),
-      parameters: Type.Object(
-        {
-          name: Type.String({ description: "Custom widget name, A-Z a-z 0-9 . _ - only." }),
-          title: Type.Optional(Type.String({ description: "Widget display title." })),
-        },
-        { additionalProperties: false },
-      ),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["name", "title"]);
-        const scaffold = await scaffoldWorkspaceWidget({
-          name: readRequiredString(record, "name", "name"),
-          title: readOptionalString(record, "title"),
-          stateDir: store.stateDir,
-          createdBy: actor,
-        });
-        const result = store.mutate(
-          (draft) => {
-            draft.widgetsRegistry[scaffold.name] = {
-              status: "pending",
-              createdBy: actor,
-            };
-          },
-          { actor },
-        );
-        broadcastChange(broadcast, { doc: result.doc, actor });
-        return jsonResult({
-          ...scaffold,
-          registry: result.doc.widgetsRegistry[scaffold.name],
-          workspaceVersion: result.doc.workspaceVersion,
-        });
-      },
-    },
-    {
-      name: "workspace_undo",
-      label: "Workspace Undo",
-      description: "Restore the newest workspace undo snapshot.",
-      parameters: Type.Object({}, { additionalProperties: false }),
-      execute: async () => {
-        const doc = store.undo();
-        broadcastChange(broadcast, { doc, actor });
-        return jsonResult({ doc, workspaceVersion: doc.workspaceVersion });
-      },
-    },
-    {
-      name: "workspace_data_read",
-      label: "Workspace Data Read",
-      description:
-        "Resolve a workspace binding exactly as a widget sees it. `file` and `static` bindings " +
-        'return their data; an `rpc` binding returns { status: "binding_client_resolved" } ' +
-        "because only the trusted Control UI may call the gateway on a widget's behalf.",
-      parameters: Type.Object({ binding: BindingSchema }, { additionalProperties: false }),
-      execute: async (_toolCallId, rawParams) => {
-        const record = readRecord(rawParams, ["binding"]);
-        try {
-          return jsonResult({ data: await resolveBinding(record.binding, params.dataRead) });
-        } catch (error) {
-          // `rpc` bindings are resolved by the trusted Control UI over its own
-          // authenticated socket. That is the documented answer, not an error, so
-          // return it as a result the model can act on.
-          if (
-            error instanceof WorkspaceBindingResolutionError &&
-            error.code === "binding_client_resolved"
-          ) {
-            return jsonResult({ status: "binding_client_resolved", message: error.message });
-          }
-          throw error;
-        }
-      },
-    },
-  ];
-}
-/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/extensions/workspaces/src/ui-gateway-integration.test.ts b/extensions/workspaces/src/ui-gateway-integration.test.ts
deleted file mode 100644
index b5bdc6c8247..00000000000
--- a/extensions/workspaces/src/ui-gateway-integration.test.ts
+++ /dev/null
@@ -1,251 +0,0 @@
-// Wire-as-you-go integration test for the workspace UI <-> gateway seam.
-//
-// The two P1 contract bugs that shipped green did so because every existing test
-// mocked exactly ONE side of the boundary: the gateway suite drove handlers with
-// hand-built params, and the UI suite drove client fns against a canned mock
-// `request`. Neither exercised the REAL client param-builder against the REAL
-// handler against a REAL store, so drift between them was invisible.
-//
-// This test closes that gap. It is node-rooted so it can import the UI `.ts`
-// client and wires three real components with NO mocked responses:
-//   1. a real WorkspaceStore over a temp stateDir, seeded via the store's real
-//      replace() API, plus a real JSON data file under `<stateDir>/workspace/data`;
-//   2. the real gateway handlers from registerWorkspaceGatewayMethods();
-//   3. the real Control-UI client fns (resolveBinding / setWidgetCollapsed /
-//      moveWidget / removeWidgetFromTab / updateWidgetTitle) from
-//      ui/src/lib/workspace/index.ts.
-// The fake GatewayBrowserClient is REAL-ROUTING: its request(method, params)
-// looks up the matching registered handler, invokes it with a captured respond,
-// and resolves/throws from the actual respond payload — so real client params
-// flow into the real handler into the real store, and we read the store back to
-// prove the round-trip landed.
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import { describe, expect, it } from "vitest";
-import {
-  getWorkspaceState,
-  loadWorkspace,
-  moveWidget,
-  removeWidgetFromTab,
-  resolveBinding,
-  setWidgetCollapsed,
-  updateWidgetTitle,
-} from "../../../ui/src/lib/workspace/index.ts";
-import { registerWorkspaceGatewayMethods } from "./gateway.js";
-import type { WorkspaceWidget, WorkspaceDoc } from "./schema.js";
-import { WorkspaceStore } from "./store.js";
-
-type Handler = Parameters<OpenClawPluginApi["registerGatewayMethod"]>[1];
-type MethodOpts = Parameters<OpenClawPluginApi["registerGatewayMethod"]>[2];
-type RegisteredMethods = Map<string, { handler: Handler; opts: MethodOpts }>;
-// The GatewayBrowserClient shape the UI client fns require, derived from a real
-// signature so we never mock its type — we build a real-routing stand-in for it.
-type RoutingClient = NonNullable<Parameters<typeof loadWorkspace>[1]>;
-
-// One tab + one widget, seeded through the store's real replace() API.
-const SEED_DOC: WorkspaceDoc = {
-  schemaVersion: 1,
-  workspaceVersion: 0,
-  tabs: [
-    {
-      slug: "ops",
-      title: "Ops",
-      hidden: false,
-      createdBy: "user",
-      widgets: [
-        {
-          id: "revenue-card",
-          kind: "builtin:stat-card",
-          title: "Revenue",
-          grid: { x: 0, y: 0, w: 4, h: 2 },
-          collapsed: false,
-          hidden: false,
-          createdBy: "user",
-        },
-      ],
-    },
-  ],
-  widgetsRegistry: {},
-  prefs: { tabOrder: ["ops"] },
-};
-
-async function withTempStateDir<T>(run: (stateDir: string) => Promise<T>): Promise<T> {
-  const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-workspace-integ-"));
-  try {
-    return await run(stateDir);
-  } finally {
-    await fs.rm(stateDir, { recursive: true, force: true });
-  }
-}
-
-/** Register the REAL gateway handlers against `store` into a method map. */
-function registerHandlers(store: WorkspaceStore, stateDir: string): RegisteredMethods {
-  const methods: RegisteredMethods = new Map();
-  const api = {
-    registerGatewayMethod: (method: string, handler: Handler, opts: MethodOpts) => {
-      methods.set(method, { handler, opts });
-    },
-  } as unknown as OpenClawPluginApi;
-  registerWorkspaceGatewayMethods({ api, store, dataRead: { stateDir } });
-  return methods;
-}
-
-/**
- * A real-routing GatewayBrowserClient stand-in: request(method, params) invokes
- * the matching registered handler with a captured `respond`, then resolves the
- * respond payload (ok) or throws its error (not-ok). NOT a canned value — real
- * client params drive the real handler.
- */
-function createRoutingClient(methods: RegisteredMethods): RoutingClient {
-  const request = async (method: string, params?: unknown): Promise<unknown> => {
-    const entry = methods.get(method);
-    if (!entry) {
-      throw new Error(`gateway method not registered: ${method}`);
-    }
-    let captured:
-      | { ok: boolean; payload?: unknown; error?: { code?: string; message?: string } }
-      | undefined;
-    const respond = (
-      ok: boolean,
-      payload?: unknown,
-      error?: { code?: string; message?: string },
-    ) => {
-      captured = { ok, payload, error };
-    };
-    await entry.handler({
-      params: params ?? {},
-      respond,
-      context: { broadcast: () => {} },
-    } as never);
-    if (!captured) {
-      throw new Error(`gateway method did not respond: ${method}`);
-    }
-    if (!captured.ok) {
-      const err = new Error(captured.error?.message ?? `gateway method failed: ${method}`);
-      throw err;
-    }
-    return captured.payload;
-  };
-  return {
-    request,
-    addEventListener: () => () => {},
-  } as unknown as RoutingClient;
-}
-
-function findWidget(doc: WorkspaceDoc, slug: string, id: string): WorkspaceWidget {
-  const widget = doc.tabs.find((tab) => tab.slug === slug)?.widgets.find((w) => w.id === id);
-  if (!widget) {
-    throw new Error(`widget ${id} not found on tab ${slug}`);
-  }
-  return widget;
-}
-
-describe("workspace UI <-> gateway integration seam", () => {
-  it("round-trips real UI client params through real handlers into the persisted store", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      store.replace(SEED_DOC, { actor: "user" });
-
-      // Real data file for the file binding: a NESTED value behind a JSON pointer.
-      const dataDir = path.join(stateDir, "workspaces", "data");
-      await fs.mkdir(dataDir, { recursive: true });
-      await fs.writeFile(
-        path.join(dataDir, "metrics.json"),
-        JSON.stringify({ metrics: { revenue: 42 } }),
-        "utf8",
-      );
-
-      const methods = registerHandlers(store, stateDir);
-      const client = createRoutingClient(methods);
-      const state = getWorkspaceState({});
-
-      // --- get: the UI client consumes the real handler's response --------------
-      await loadWorkspace(state, client);
-      expect(state.loaded).toBe(true);
-      expect(state.error).toBeNull();
-      // Direct real-routing assertion on the get payload (independent of the UI's
-      // defensive normalize): the seeded tab/widget survive the round-trip.
-      const got = (await client.request("workspaces.get", {})) as { doc: WorkspaceDoc };
-      expect(findWidget(got.doc, "ops", "revenue-card").title).toBe("Revenue");
-
-      // --- (a) file binding: proves `{ binding }` + NO double pointer-apply -----
-      // The client sends the WHOLE binding under `{ binding }`; the handler's
-      // readParams whitelist accepts only `binding`, resolves the file AND applies
-      // the JSON pointer server-side, returning `{ data: 42 }`. The UI must NOT
-      // re-apply the pointer. If it did, applyPointer(42, "/metrics/revenue") would
-      // be `undefined` — so asserting the resolved value is exactly 42 catches both
-      // the pre-fix `{ path, pointer }` param shape (handler would reject it) and a
-      // double-apply regression.
-      const fileResult = await resolveBinding(client, {
-        source: "file",
-        path: "metrics.json",
-        pointer: "/metrics/revenue",
-      });
-      expect(fileResult).toEqual({ value: 42 });
-
-      // --- (b) mutations: each real client fn must land in the PERSISTED doc -----
-      // Every assertion reads the store back from disk, so it proves the real
-      // handler mutated real state (optimisticMutation swallows RPC errors into
-      // state.actionError instead of throwing, so a wrong param shape would leave
-      // the store unchanged — which these readbacks would catch).
-      await setWidgetCollapsed(state, client, {
-        slug: "ops",
-        widgetId: "revenue-card",
-        collapsed: true,
-      });
-      expect(findWidget(store.read(), "ops", "revenue-card").collapsed).toBe(true);
-
-      await updateWidgetTitle(state, client, {
-        slug: "ops",
-        widgetId: "revenue-card",
-        title: "Net Revenue",
-      });
-      expect(findWidget(store.read(), "ops", "revenue-card").title).toBe("Net Revenue");
-
-      await moveWidget(state, client, {
-        slug: "ops",
-        widgetId: "revenue-card",
-        grid: { x: 4, y: 1, w: 4, h: 3 },
-      });
-      expect(findWidget(store.read(), "ops", "revenue-card").grid).toEqual({
-        x: 4,
-        y: 1,
-        w: 4,
-        h: 3,
-      });
-
-      await removeWidgetFromTab(state, client, { slug: "ops", widgetId: "revenue-card" });
-      const afterRemove = store.read();
-      expect(afterRemove.tabs.find((tab) => tab.slug === "ops")?.widgets).toHaveLength(0);
-
-      // No mutation surfaced an error through the whole round-trip.
-      expect(state.actionError).toBeNull();
-    });
-  });
-
-  it("catches the shipped contract drift: the pre-fix `{ slug, widgetId }` mutation shape is rejected and never mutates the store", async () => {
-    await withTempStateDir(async (stateDir) => {
-      const store = new WorkspaceStore({ stateDir });
-      store.replace(SEED_DOC, { actor: "user" });
-      const methods = registerHandlers(store, stateDir);
-      const client = createRoutingClient(methods);
-
-      // The P1 bug sent the store's `{ slug, widgetId }` field names instead of the
-      // gateway's `{ tab, id }`. The real handler's readParams whitelist
-      // (tab, id, patch, actor) rejects `slug`/`widgetId` as unexpected params, so a
-      // regressed client fails loudly here rather than shipping green.
-      await expect(
-        client.request("workspaces.widget.update", {
-          slug: "ops",
-          widgetId: "revenue-card",
-          patch: { collapsed: true },
-        }),
-      ).rejects.toThrow(/unexpected param: slug/);
-
-      // The rejected call left the persisted widget untouched.
-      expect(findWidget(store.read(), "ops", "revenue-card").collapsed).toBe(false);
-    });
-  });
-});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3e7f76694f2..a1c769dee67 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1973,19 +1973,6 @@ importers:
         specifier: workspace:*
         version: link:../..
 
-  extensions/workspaces:
-    dependencies:
-      typebox:
-        specifier: 1.3.3
-        version: 1.3.3
-    devDependencies:
-      '@openclaw/plugin-sdk':
-        specifier: workspace:*
-        version: link:../../packages/plugin-sdk
-      openclaw:
-        specifier: workspace:*
-        version: link:../..
-
   extensions/xai:
     dependencies:
       typebox:
diff --git a/src/flows/doctor-core-checks.ts b/src/flows/doctor-core-checks.ts
index 0be464fee4e..ad4c84bd89d 100644
--- a/src/flows/doctor-core-checks.ts
+++ b/src/flows/doctor-core-checks.ts
@@ -37,6 +37,7 @@ import { getSkippedExecRefStaticError } from "../secrets/exec-resolution-policy.
 import type { SkillStatusEntry } from "../skills/discovery/status.js";
 import { resolveSkillWorkshopConfig } from "../skills/workshop/config.js";
 import { detectSkillWorkshopToolPolicyDiagnostic } from "../skills/workshop/tool-policy-diagnostic.js";
+import { removedWorkspacesStateCheck } from "./doctor-removed-workspaces-state-check.js";
 import { registerHealthCheck } from "./health-check-registry.js";
 import type { SplitHealthCheckInput } from "./health-check-runner-types.js";
 import type {
@@ -54,11 +55,9 @@ const GATEWAY_HEALTH_CHECK_ID = "core/doctor/gateway-health";
 const GATEWAY_SERVICES_EXTRA_CHECK_ID = "core/doctor/gateway-services/extra";
 const SESSION_LOCKS_CHECK_ID = "core/doctor/session-locks";
 const SKILL_WORKSHOP_TOOL_POLICY_CHECK_ID = "core/doctor/skill-workshop-tool-policy";
-
 type CoreHealthCheckContext = HealthCheckContext & {
   readonly deep?: boolean;
 };
-
 type CoreHealthRepairContext = HealthRepairContext & {
   readonly deep?: boolean;
 };
@@ -1133,6 +1132,7 @@ function createConvertedWorkflowChecks(
     claudeCliCheck,
     gatewayAuthCheck,
     legacyStateCheck,
+    removedWorkspacesStateCheck,
     legacyWhatsAppCrontabCheck,
     legacyCronStoreCheck,
     codexSessionRoutesCheck,
diff --git a/src/flows/doctor-health-contributions.test.ts b/src/flows/doctor-health-contributions.test.ts
index 6e9a98467c3..290b23500ea 100644
--- a/src/flows/doctor-health-contributions.test.ts
+++ b/src/flows/doctor-health-contributions.test.ts
@@ -576,8 +576,10 @@ describe("doctor health contributions", () => {
       ready: true,
       skipped: false,
     });
-    mocks.runDoctorHealthRepairs.mockResolvedValue({
-      config: {},
+    // Real repairs echo the input config unless they change it; mirror that so
+    // config-identity assertions downstream of a repair stay realistic.
+    mocks.runDoctorHealthRepairs.mockImplementation(async (input: { cfg?: unknown }) => ({
+      config: input.cfg ?? {},
       findings: [],
       remainingFindings: [],
       changes: [],
@@ -587,7 +589,7 @@ describe("doctor health contributions", () => {
       checksRun: 0,
       checksRepaired: 0,
       checksValidated: 0,
-    });
+    }));
     mocks.listHealthChecks.mockReset();
     mocks.listHealthChecks.mockReturnValue([
       { id: "core/example/internal", kind: "core" },
diff --git a/src/flows/doctor-health-contributions.ts b/src/flows/doctor-health-contributions.ts
index 63cb959aa0e..38498cf0ea9 100644
--- a/src/flows/doctor-health-contributions.ts
+++ b/src/flows/doctor-health-contributions.ts
@@ -518,6 +518,9 @@ async function runLegacyStateHealth(ctx: DoctorHealthFlowContext): Promise<void>
   const { detectLegacyStateMigrations, runLegacyStateMigrations } =
     await import("../commands/doctor-state-migrations.js");
   const { note } = await loadNoteModule();
+  // Settle retired-plugin state cleanup (may replace ctx.cfg) before the
+  // legacy-state detect/migrate pair reads the config.
+  await runCoreContributionHealthRepair(ctx, ["core/doctor/removed-workspaces-state"]);
   const legacyState = await detectLegacyStateMigrations({
     cfg: ctx.cfg,
     doctorOnlyStateMigrations: true,
@@ -1604,7 +1607,7 @@ function resolveDoctorHealthContributions(): DoctorHealthContribution[] {
     createDoctorHealthContribution({
       id: "doctor:legacy-state",
       label: "Legacy state",
-      healthCheckIds: ["core/doctor/legacy-state"],
+      healthCheckIds: ["core/doctor/legacy-state", "core/doctor/removed-workspaces-state"],
       run: runLegacyStateHealth,
     }),
     createDoctorHealthContribution({
diff --git a/src/flows/doctor-removed-workspaces-state-check.test.ts b/src/flows/doctor-removed-workspaces-state-check.test.ts
new file mode 100644
index 00000000000..80f25dd4b07
--- /dev/null
+++ b/src/flows/doctor-removed-workspaces-state-check.test.ts
@@ -0,0 +1,85 @@
+// Removed Workspaces state tests cover doctor detection and deletion.
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { withEnvAsync } from "../test-utils/env.js";
+import { removedWorkspacesStateCheck } from "./doctor-removed-workspaces-state-check.js";
+
+const runtime = { log() {}, error() {}, exit() {} };
+
+describe("removed Workspaces state doctor check", () => {
+  let root: string | undefined;
+
+  afterEach(async () => {
+    if (root !== undefined) {
+      await fs.rm(root, { force: true, recursive: true });
+      root = undefined;
+    }
+  });
+
+  it("previews and removes the stale plugin state directory", async () => {
+    root = await fs.mkdtemp(join(tmpdir(), "openclaw-workspaces-state-"));
+    const staleDir = join(root, "workspaces");
+    await fs.mkdir(join(staleDir, "assets"), { recursive: true });
+    await fs.writeFile(join(staleDir, "workspaces.sqlite"), "stale", "utf8");
+
+    await withEnvAsync({ OPENCLAW_STATE_DIR: root }, async () => {
+      const findings = await removedWorkspacesStateCheck.detect({
+        mode: "lint",
+        runtime,
+        cfg: {},
+      });
+      expect(findings).toEqual([
+        expect.objectContaining({
+          checkId: "core/doctor/removed-workspaces-state",
+          path: staleDir,
+          severity: "warning",
+        }),
+      ]);
+      await expect(
+        removedWorkspacesStateCheck.detect(
+          { mode: "fix", runtime, cfg: {} },
+          { paths: [join(root!, "other")] },
+        ),
+      ).resolves.toEqual([]);
+
+      const preview = await removedWorkspacesStateCheck.repair?.(
+        { mode: "fix", runtime, cfg: {}, dryRun: true },
+        findings,
+      );
+      expect(preview).toMatchObject({
+        changes: [expect.stringContaining("Would remove retired Workspaces plugin state")],
+        effects: [
+          {
+            action: "would-remove-retired-workspaces-state",
+            dryRunSafe: false,
+            kind: "state",
+            target: staleDir,
+          },
+        ],
+      });
+      await expect(fs.stat(staleDir)).resolves.toBeDefined();
+
+      const repaired = await removedWorkspacesStateCheck.repair?.(
+        { mode: "fix", runtime, cfg: {} },
+        findings,
+      );
+      expect(repaired).toMatchObject({
+        changes: [expect.stringContaining("Removed retired Workspaces plugin state")],
+        effects: [
+          {
+            action: "remove-retired-workspaces-state",
+            dryRunSafe: false,
+            kind: "state",
+            target: staleDir,
+          },
+        ],
+      });
+      await expect(fs.stat(staleDir)).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(
+        removedWorkspacesStateCheck.detect({ mode: "lint", runtime, cfg: {} }),
+      ).resolves.toEqual([]);
+    });
+  });
+});
diff --git a/src/flows/doctor-removed-workspaces-state-check.ts b/src/flows/doctor-removed-workspaces-state-check.ts
new file mode 100644
index 00000000000..2a88adb40cd
--- /dev/null
+++ b/src/flows/doctor-removed-workspaces-state-check.ts
@@ -0,0 +1,72 @@
+// Doctor cleanup for state left by the retired experimental Workspaces plugin.
+import { lstat, rm } from "node:fs/promises";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import type { HealthCheck, HealthRepairEffect } from "./health-checks.js";
+
+const CHECK_ID = "core/doctor/removed-workspaces-state";
+
+function resolveRemovedWorkspacesStateDir(): string {
+  return path.join(resolveStateDir(process.env), "workspaces");
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function repairEffect(target: string, dryRun: boolean): HealthRepairEffect {
+  return {
+    kind: "state",
+    action: dryRun ? "would-remove-retired-workspaces-state" : "remove-retired-workspaces-state",
+    target,
+    dryRunSafe: false,
+  };
+}
+
+export const removedWorkspacesStateCheck: HealthCheck = {
+  id: CHECK_ID,
+  kind: "core",
+  description: "State from the retired experimental Workspaces plugin has been removed.",
+  source: "doctor",
+  async detect(_ctx, scope) {
+    const target = resolveRemovedWorkspacesStateDir();
+    const scopedPaths = new Set(scope?.paths ?? []);
+    if ((scopedPaths.size > 0 && !scopedPaths.has(target)) || !(await pathExists(target))) {
+      return [];
+    }
+    return [
+      {
+        checkId: CHECK_ID,
+        severity: "warning",
+        message: `Retired Workspaces plugin state remains at ${target}.`,
+        path: target,
+        fixHint: "Run `openclaw doctor --fix` to remove the stale plugin state.",
+      },
+    ];
+  },
+  async repair(ctx) {
+    const target = resolveRemovedWorkspacesStateDir();
+    if (!(await pathExists(target))) {
+      return {
+        status: "skipped",
+        reason: "retired Workspaces plugin state no longer exists",
+        changes: [],
+      };
+    }
+    const dryRun = ctx.dryRun === true;
+    const effects = [repairEffect(target, dryRun)];
+    if (dryRun) {
+      return { changes: [`Would remove retired Workspaces plugin state at ${target}.`], effects };
+    }
+    await rm(target, { force: true, recursive: true });
+    return { changes: [`Removed retired Workspaces plugin state at ${target}.`], effects };
+  },
+};
diff --git a/src/plugins/bundled-plugin-metadata.test.ts b/src/plugins/bundled-plugin-metadata.test.ts
index 3c2ddeaae41..049c7063374 100644
--- a/src/plugins/bundled-plugin-metadata.test.ts
+++ b/src/plugins/bundled-plugin-metadata.test.ts
@@ -63,7 +63,6 @@ const EXPECTED_BUNDLED_STARTUP_PLUGIN_IDS = [
   "voice-call",
   "webhooks",
   "workboard",
-  "workspaces",
 ] as const;
 const EXPECTED_EMPTY_CONFIG_GATEWAY_STARTUP_PLUGIN_IDS = [
   "acpx",
diff --git a/ui/src/components/workspace-custom-widget.test.ts b/ui/src/components/workspace-custom-widget.test.ts
deleted file mode 100644
index b9e785f8b95..00000000000
--- a/ui/src/components/workspace-custom-widget.test.ts
+++ /dev/null
@@ -1,339 +0,0 @@
-import { nothing, render } from "lit";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { WorkspaceWidget, WidgetManifestView } from "../lib/workspace/types.ts";
-import {
-  loadWidgetManifestView,
-  renderCustomWidgetHost,
-  type CustomWidgetHostContext,
-} from "./workspace-custom-widget.ts";
-
-const BRIDGE_TOKEN = "11111111-1111-4111-8111-111111111111";
-const FRAME_EXPIRES_AT = Date.now() + 60 * 60 * 1000;
-
-function widget(overrides: Partial<WorkspaceWidget> = {}): WorkspaceWidget {
-  return {
-    id: "w_custom",
-    kind: "custom:revenue-chart",
-    title: "Revenue Chart",
-    grid: { x: 0, y: 0, w: 6, h: 4 },
-    collapsed: false,
-    bindings: { value: { source: "static", value: { revenue: 42 } } },
-    ...overrides,
-  };
-}
-
-function manifest(overrides?: Partial<WidgetManifestView>): WidgetManifestView {
-  return {
-    name: "revenue-chart",
-    frameToken: BRIDGE_TOKEN,
-    entrypoint: "index.html",
-    bindings: { value: { source: "static", value: null } },
-    capabilities: ["data:read"],
-    ...overrides,
-  };
-}
-
-function host(overrides?: Partial<CustomWidgetHostContext>): CustomWidgetHostContext {
-  return { client: null, basePath: "", sessionKey: "main", ...overrides };
-}
-
-function renderToContainer(template: unknown): HTMLElement {
-  const container = document.createElement("div");
-  document.body.appendChild(container);
-  render(template as never, container);
-  return container;
-}
-
-function connectRenderedWidget(params: {
-  widget?: WorkspaceWidget;
-  manifest?: WidgetManifestView;
-  context?: CustomWidgetHostContext;
-}) {
-  const container = renderToContainer(
-    renderCustomWidgetHost({
-      widget: params.widget ?? widget(),
-      manifest: params.manifest ?? manifest(),
-      context: params.context ?? host(),
-    }),
-  );
-  const iframe = container.querySelector("iframe");
-  if (!iframe) {
-    throw new Error("expected custom widget iframe");
-  }
-  const channel = new MessageChannel();
-  const posts: unknown[] = [];
-  channel.port1.addEventListener("message", (event) => posts.push(event.data));
-  channel.port1.start();
-  window.dispatchEvent(
-    new MessageEvent("message", {
-      data: { v: 1, type: "workspace:bridge:init", token: BRIDGE_TOKEN },
-      source: iframe.contentWindow,
-      ports: [channel.port2],
-    }),
-  );
-  return {
-    childPort: channel.port1,
-    container,
-    iframe,
-    posts,
-    disconnect: () => render(nothing, container),
-  };
-}
-
-afterEach(() => {
-  vi.restoreAllMocks();
-  document.body.innerHTML = "";
-});
-
-describe("loadWidgetManifestView", () => {
-  it("shapes an authenticated frame response into the bridge read model", async () => {
-    const request = vi.fn(async () => ({
-      frameToken: BRIDGE_TOKEN,
-      frameExpiresAt: FRAME_EXPIRES_AT,
-      manifest: {
-        entrypoint: "index.html",
-        bindings: [{ id: "value", source: "static", value: 1 }],
-        capabilities: ["data:read", "prompt:send"],
-      },
-    }));
-    const view = await loadWidgetManifestView({ request } as never, "revenue-chart");
-    expect(view).toEqual({
-      name: "revenue-chart",
-      frameToken: BRIDGE_TOKEN,
-      frameExpiresAt: FRAME_EXPIRES_AT,
-      entrypoint: "index.html",
-      bindings: { value: { source: "static", value: 1 } },
-      capabilities: ["data:read", "prompt:send"],
-    });
-  });
-
-  it("returns null when the authenticated frame request fails", async () => {
-    const request = vi.fn(async () => {
-      throw new Error("denied");
-    });
-    expect(await loadWidgetManifestView({ request } as never, "revenue-chart")).toBeNull();
-  });
-
-  it("drops prototype-setter binding ids", async () => {
-    const request = vi.fn(async () => ({
-      frameToken: BRIDGE_TOKEN,
-      frameExpiresAt: FRAME_EXPIRES_AT,
-      manifest: {
-        entrypoint: "index.html",
-        bindings: [{ id: "__proto__", source: "static", value: 1 }],
-        capabilities: ["data:read"],
-      },
-    }));
-
-    const view = await loadWidgetManifestView({ request } as never, "revenue-chart");
-    expect(Object.keys(view?.bindings ?? {})).toEqual([]);
-  });
-
-  it("refuses a manifest without the approved entrypoint", async () => {
-    const request = vi.fn(async () => ({
-      frameToken: "test-token-placeholder",
-      frameExpiresAt: FRAME_EXPIRES_AT,
-      manifest: {
-        bindings: [{ id: "value", source: "static", value: 1 }],
-        capabilities: ["data:read"],
-      },
-    }));
-
-    expect(await loadWidgetManifestView({ request } as never, "revenue-chart")).toBeNull();
-  });
-});
-
-describe("renderCustomWidgetHost DOM", () => {
-  it("renders an iframe whose sandbox is exactly allow-scripts", () => {
-    const container = renderToContainer(
-      renderCustomWidgetHost({ widget: widget(), manifest: manifest(), context: host() }),
-    );
-    const iframe = container.querySelector("iframe");
-    expect(iframe).not.toBeNull();
-    // The sandbox attribute is a CONSTANT — exactly "allow-scripts", nothing else.
-    expect(iframe?.getAttribute("sandbox")).toBe("allow-scripts");
-    const tokens = (iframe?.getAttribute("sandbox") ?? "").split(/\s+/).filter(Boolean);
-    expect(tokens).toEqual(["allow-scripts"]);
-    expect(tokens).not.toContain("allow-same-origin");
-    expect(tokens).not.toContain("allow-forms");
-    expect(tokens).not.toContain("allow-popups");
-    expect(tokens).not.toContain("allow-top-navigation");
-  });
-
-  it("sets referrerpolicy=no-referrer and the served src", () => {
-    const container = renderToContainer(
-      renderCustomWidgetHost({
-        widget: widget(),
-        manifest: manifest(),
-        context: host({ basePath: "/gw" }),
-      }),
-    );
-    const iframe = container.querySelector("iframe");
-    expect(iframe?.getAttribute("referrerpolicy")).toBe("no-referrer");
-    expect(iframe?.getAttribute("src")).toMatch(
-      new RegExp(`^/gw/plugins/workspaces/widgets/${BRIDGE_TOKEN}/revenue-chart/index\\.html$`),
-    );
-  });
-});
-
-describe("renderCustomWidgetHost bridge", () => {
-  it("drops a foreign bootstrap and accepts only its iframe document", async () => {
-    const container = renderToContainer(
-      renderCustomWidgetHost({ widget: widget(), manifest: manifest(), context: host() }),
-    );
-    const iframe = container.querySelector("iframe");
-    if (!iframe) {
-      throw new Error("expected custom widget iframe");
-    }
-    const foreign = document.createElement("iframe");
-    document.body.append(foreign);
-    const foreignChannel = new MessageChannel();
-    window.dispatchEvent(
-      new MessageEvent("message", {
-        data: { v: 1, type: "workspace:bridge:init", token: BRIDGE_TOKEN },
-        source: foreign.contentWindow,
-        ports: [foreignChannel.port2],
-      }),
-    );
-    const channel = new MessageChannel();
-    const posts: unknown[] = [];
-    channel.port1.addEventListener("message", (event) => posts.push(event.data));
-    channel.port1.start();
-    window.dispatchEvent(
-      new MessageEvent("message", {
-        data: { v: 1, type: "workspace:bridge:init", token: BRIDGE_TOKEN },
-        source: iframe.contentWindow,
-        ports: [channel.port2],
-      }),
-    );
-    channel.port1.postMessage({
-      v: 1,
-      type: "workspace:getData",
-      requestId: "r2",
-      bindingId: "value",
-    });
-
-    await vi.waitFor(() => expect(posts).toHaveLength(1));
-    expect(posts[0]).toMatchObject({
-      type: "workspace:data",
-      requestId: "r2",
-      bindingId: "value",
-    });
-    channel.port1.close();
-    foreignChannel.port1.close();
-    render(nothing, container);
-  });
-
-  it("sends an approved prompt with a gateway idempotency key", async () => {
-    const request = vi.fn(async () => ({ runId: "run-1", status: "started" }));
-    const connected = connectRenderedWidget({
-      manifest: manifest({ name: "prompt-send-test", capabilities: ["prompt:send"] }),
-      context: host({ client: { request } as never, confirmPrompt: () => true }),
-    });
-    connected.childPort.postMessage(
-      {
-        v: 1,
-        type: "workspace:sendPrompt",
-        requestId: "r1",
-        text: "Summarize this workspace",
-      },
-      [],
-    );
-
-    await vi.waitFor(() => expect(request).toHaveBeenCalledOnce());
-    expect(request).toHaveBeenCalledWith("chat.send", {
-      sessionKey: "main",
-      message: "Summarize this workspace",
-      deliver: false,
-      idempotencyKey: expect.stringMatching(/^[0-9a-f-]{36}$/i),
-    });
-    connected.childPort.close();
-    connected.disconnect();
-  });
-
-  it("closes the document port when the rendered widget detaches", async () => {
-    const connected = connectRenderedWidget({});
-    connected.disconnect();
-    connected.childPort.postMessage(
-      {
-        v: 1,
-        type: "workspace:getData",
-        requestId: "after-detach",
-        bindingId: "value",
-      },
-      [],
-    );
-
-    await new Promise<void>((resolve) => {
-      setTimeout(resolve, 10);
-    });
-    expect(connected.posts).toEqual([]);
-    connected.childPort.close();
-  });
-
-  it("rejects a second bootstrap for the same iframe document", async () => {
-    const connected = connectRenderedWidget({});
-    const replacementInit = Object.fromEntries([
-      ["v", 1],
-      ["type", "workspace:bridge:init"],
-      ["token", BRIDGE_TOKEN],
-    ]);
-    const replacement = new MessageChannel();
-    const replacementPosts: unknown[] = [];
-    replacement.port1.addEventListener("message", (event) => replacementPosts.push(event.data));
-    replacement.port1.start();
-    window.dispatchEvent(
-      new MessageEvent("message", {
-        data: replacementInit,
-        source: connected.iframe.contentWindow,
-        ports: [replacement.port2],
-      }),
-    );
-    replacement.port1.postMessage({
-      v: 1,
-      type: "workspace:getData",
-      requestId: "replacement",
-      bindingId: "value",
-    });
-
-    await new Promise<void>((resolve) => {
-      setTimeout(resolve, 10);
-    });
-    expect(replacementPosts).toEqual([]);
-    replacement.port1.close();
-    connected.childPort.close();
-    connected.disconnect();
-  });
-
-  it.each([
-    [{ source: "rpc", method: "sessions.delete" } as const],
-    [{ source: "rpc", method: "sessions.list" } as const],
-    [{ source: "file", path: "private.json" } as const],
-  ])("denies privileged binding %o without calling the gateway", async (binding) => {
-    const request = vi.fn(async () => ({ leaked: true }));
-    const connected = connectRenderedWidget({
-      widget: widget({ bindings: { value: binding } }),
-      manifest: manifest({ bindings: { value: binding } }),
-      context: host({ client: { request } as never }),
-    });
-    connected.childPort.postMessage(
-      {
-        v: 1,
-        type: "workspace:getData",
-        requestId: "r1",
-        bindingId: "value",
-      },
-      [],
-    );
-
-    await vi.waitFor(() => expect(connected.posts.length).toBeGreaterThan(0));
-    expect(connected.posts[0]).toMatchObject({
-      type: "workspace:error",
-      code: "binding_denied",
-      requestId: "r1",
-    });
-    expect(request).not.toHaveBeenCalled();
-    connected.childPort.close();
-    connected.disconnect();
-  });
-});
diff --git a/ui/src/components/workspace-custom-widget.ts b/ui/src/components/workspace-custom-widget.ts
deleted file mode 100644
index e1d0ac4c7a1..00000000000
--- a/ui/src/components/workspace-custom-widget.ts
+++ /dev/null
@@ -1,360 +0,0 @@
-// Sandboxed host for approved custom widgets (spec-50 §UI side). Renders the
-// `<iframe sandbox="allow-scripts">` and wires the parent side of the postMessage
-// bridge (`lib/workspace/bridge.ts`).
-//
-// SECURITY INVARIANTS (each has a test — the review gate):
-// - The sandbox attribute is the CONSTANT string "allow-scripts". Never config,
-//   never `allow-same-origin`/`allow-forms`/`allow-popups`/`allow-top-navigation`.
-//   The iframe's origin is therefore opaque (`null`).
-// - `referrerpolicy="no-referrer"` — the frame leaks no referrer.
-// - Window messages are accepted only for the one-time, token-bound MessagePort
-//   bootstrap injected before approved widget bytes. All bridge traffic then uses
-//   that document-owned port; navigation destroys it, while WindowProxy identity
-//   would incorrectly survive.
-// - Parent→child posts use targetOrigin "*" (opaque origin) and carry only static
-//   workspace values / theme tokens the manifest entitles the widget to. Privileged
-//   RPC/file data never enters agent-authored code: sandboxed children can navigate.
-
-import { html, type TemplateResult } from "lit";
-import { AsyncDirective } from "lit/async-directive.js";
-import { directive } from "lit/directive.js";
-import type { GatewayBrowserClient } from "../api/gateway.ts";
-import { generateUUID } from "../lib/uuid.ts";
-import {
-  createWidgetBridge,
-  type WidgetBridge,
-  type WidgetOutboundMessage,
-} from "../lib/workspace/bridge.ts";
-import type {
-  WorkspaceBinding,
-  WorkspaceWidget,
-  WorkspaceWidgetCapability,
-  WidgetManifestView,
-} from "../lib/workspace/types.ts";
-
-// Theme tokens exposed to widgets so agent-authored UIs match the active theme
-// (00 §7). Read from the document root's computed styles at getTheme time.
-const WIDGET_THEME_TOKENS = [
-  "--bg",
-  "--card",
-  "--card-foreground",
-  "--text",
-  "--muted",
-  "--border",
-  "--accent",
-  "--accent-foreground",
-  "--radius",
-  "--radius-sm",
-  "--font-sans",
-  "--font-mono",
-] as const;
-
-export type CustomWidgetHostContext = {
-  client: GatewayBrowserClient | null;
-  /** Gateway HTTP base path (from the app context); "" for same-origin root. */
-  basePath: string;
-  /** Session key for prompt dispatch via chat.send. */
-  sessionKey: string;
-  /** Operator confirm dialog quoting the prompt text; resolves true to send. */
-  confirmPrompt?: (text: string) => Promise<boolean> | boolean;
-  /** Read theme tokens; defaults to computed styles of the document root. */
-  readThemeTokens?: () => Record<string, string>;
-};
-
-/** Builds the served asset URL for a widget file under the plugin route. */
-function widgetAssetUrl(basePath: string, frameToken: string, name: string, file: string): string {
-  const base = basePath.replace(/\/+$/, "");
-  const encodedToken = encodeURIComponent(frameToken);
-  const encodedName = encodeURIComponent(name);
-  const encodedFile = file
-    .split("/")
-    .map((segment) => encodeURIComponent(segment))
-    .join("/");
-  return `${base}/plugins/workspaces/widgets/${encodedToken}/${encodedName}/${encodedFile}`;
-}
-
-function readThemeTokensFromRoot(): Record<string, string> {
-  const tokens: Record<string, string> = {};
-  if (typeof document === "undefined" || typeof getComputedStyle !== "function") {
-    return tokens;
-  }
-  const styles = getComputedStyle(document.documentElement);
-  for (const token of WIDGET_THEME_TOKENS) {
-    const value = styles.getPropertyValue(token).trim();
-    if (value) {
-      tokens[token] = value;
-    }
-  }
-  return tokens;
-}
-
-function primaryBindingByManifestId(
-  widget: WorkspaceWidget,
-  bindingId: string,
-): WorkspaceBinding | null {
-  const binding = widget.bindings?.[bindingId];
-  return binding ?? null;
-}
-
-function parseManifestBinding(value: unknown): { id: string; binding: WorkspaceBinding } | null {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return null;
-  }
-  const record = value as Record<string, unknown>;
-  const id = record.id;
-  if (typeof id !== "string" || id === "__proto__" || !/^[A-Za-z0-9._-]{1,64}$/.test(id)) {
-    return null;
-  }
-  if (record.source === "static" && Object.hasOwn(record, "value")) {
-    return { id, binding: { source: "static", value: record.value } };
-  }
-  return null;
-}
-
-/** Custom code may receive only static workspace values granted by its manifest. */
-function bindingMatchesManifestGrant(binding: WorkspaceBinding, grant: WorkspaceBinding): boolean {
-  return binding.source === "static" && grant.source === "static";
-}
-
-/** Fetches and shapes a widget's manifest into the bridge's read model. */
-export async function loadWidgetManifestView(
-  client: GatewayBrowserClient | null,
-  name: string,
-): Promise<WidgetManifestView | null> {
-  if (!client) {
-    return null;
-  }
-  try {
-    const payload: unknown = await client.request("workspaces.widget.frame", { name });
-    if (typeof payload !== "object" || payload === null) {
-      return null;
-    }
-    const response = payload as Record<string, unknown>;
-    const frameToken = response.frameToken;
-    const frameExpiresAt = response.frameExpiresAt;
-    const manifest = response.manifest;
-    if (
-      typeof frameToken !== "string" ||
-      typeof frameExpiresAt !== "number" ||
-      !Number.isFinite(frameExpiresAt) ||
-      frameExpiresAt <= Date.now() ||
-      typeof manifest !== "object" ||
-      manifest === null
-    ) {
-      return null;
-    }
-    const record = manifest as Record<string, unknown>;
-    const manifestBindings = Array.isArray(record.bindings) ? record.bindings : [];
-    // A null-prototype record keeps every accepted manifest id as data.
-    const bindings = Object.create(null) as Record<string, WorkspaceBinding>;
-    for (const value of manifestBindings) {
-      const parsedBinding = parseManifestBinding(value);
-      if (!parsedBinding || Object.hasOwn(bindings, parsedBinding.id)) {
-        return null;
-      }
-      bindings[parsedBinding.id] = parsedBinding.binding;
-    }
-    const capabilities = (Array.isArray(record.capabilities) ? record.capabilities : []).filter(
-      (cap): cap is WorkspaceWidgetCapability => cap === "data:read" || cap === "prompt:send",
-    );
-    // The approval gate hashes the manifest's declared entrypoint. Loading a
-    // different file would mount code the operator never approved.
-    const entrypoint = typeof record.entrypoint === "string" ? record.entrypoint : "";
-    if (!entrypoint) {
-      return null;
-    }
-    return { name, frameToken, frameExpiresAt, entrypoint, bindings, capabilities };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Wires the parent bridge for one iframe: manifest gating, binding resolution over
- * the trusted gateway client, theme tokens, and prompt dispatch. The returned
- * teardown removes the window listener and disposes the bridge.
- */
-function attachWidgetBridge(params: {
-  iframe: HTMLIFrameElement;
-  widget: WorkspaceWidget;
-  manifest: WidgetManifestView;
-  context: CustomWidgetHostContext;
-  bridgeToken: string;
-}): () => void {
-  // Workspaces has never shipped, so there are no released approved widgets on
-  // the old WindowProxy transport to migrate. Keeping that transport here would
-  // preserve the navigation capability this document-bound channel removes.
-  const { iframe, widget, manifest, context, bridgeToken } = params;
-  let bridge: WidgetBridge | null = null;
-  let port: MessagePort | null = null;
-  let disposed = false;
-
-  const createBridge = (connectedPort: MessagePort): WidgetBridge =>
-    createWidgetBridge({
-      manifest,
-      post: (message: WidgetOutboundMessage): void => connectedPort.postMessage(message, []),
-      assertBindingAllowed: (bindingId) => {
-        // Agent-authored frames can navigate themselves despite their sandbox/CSP.
-        // Never place privileged RPC/file data in them; built-in widgets own those
-        // bindings. Static values are already agent/operator-authored workspace data.
-        const binding = primaryBindingByManifestId(widget, bindingId);
-        const grant = manifest.bindings[bindingId];
-        if (!binding || !grant || !bindingMatchesManifestGrant(binding, grant)) {
-          return "binding_denied";
-        }
-        return null;
-      },
-      resolveBinding: async (bindingId) => {
-        const binding = primaryBindingByManifestId(widget, bindingId);
-        if (!binding) {
-          throw new Error(`binding not configured: ${bindingId}`);
-        }
-        if (binding.source !== "static") {
-          throw new Error(`binding not allowed: ${bindingId}`);
-        }
-        return binding.value;
-      },
-      resolveTheme: context.readThemeTokens ?? readThemeTokensFromRoot,
-      confirmPrompt: async (text) => {
-        if (context.confirmPrompt) {
-          return await context.confirmPrompt(text);
-        }
-        return typeof window !== "undefined" ? window.confirm(text) : false;
-      },
-      sendPrompt: async (text) => {
-        if (!context.client) {
-          throw new Error("Not connected.");
-        }
-        await context.client.request("chat.send", {
-          sessionKey: context.sessionKey,
-          message: text,
-          deliver: false,
-          idempotencyKey: generateUUID(),
-        });
-      },
-    });
-
-  const onBootstrap = (event: MessageEvent): void => {
-    if (
-      disposed ||
-      bridge ||
-      event.source !== iframe.contentWindow ||
-      event.ports.length !== 1 ||
-      typeof event.data !== "object" ||
-      event.data === null ||
-      event.data.v !== 1 ||
-      event.data.type !== "workspace:bridge:init" ||
-      event.data.token !== bridgeToken
-    ) {
-      return;
-    }
-    window.removeEventListener("message", onBootstrap);
-    port = event.ports[0] ?? null;
-    if (!port) {
-      return;
-    }
-    bridge = createBridge(port);
-    port.addEventListener("message", (message) => bridge?.handleMessage(message.data));
-    port.start();
-  };
-  const dispose = (): void => {
-    if (disposed) {
-      return;
-    }
-    disposed = true;
-    window.removeEventListener("message", onBootstrap);
-    port?.close();
-    bridge?.dispose();
-    port = null;
-    bridge = null;
-  };
-  window.addEventListener("message", onBootstrap);
-  return dispose;
-}
-
-/**
- * Lit directive that owns the iframe element's lifecycle: it constructs the
- * sandboxed iframe once, attaches the bridge, and tears both down on disconnect.
- * Using a directive (rather than re-rendering an `<iframe>` template) keeps the
- * frame from being recreated on every parent render, which would drop bridge
- * state and reload the widget.
- */
-class CustomWidgetFrameDirective extends AsyncDirective {
-  private iframe: HTMLIFrameElement | null = null;
-  private detach: (() => void) | null = null;
-  private key = "";
-
-  render(params: {
-    widget: WorkspaceWidget;
-    manifest: WidgetManifestView;
-    context: CustomWidgetHostContext;
-  }): HTMLElement {
-    const name = params.widget.kind.slice("custom:".length);
-    const assetUrl = widgetAssetUrl(
-      params.context.basePath,
-      params.manifest.frameToken,
-      name,
-      params.manifest.entrypoint,
-    );
-    const nextKey = `${params.widget.id}::${assetUrl}`;
-    if (this.iframe && this.key === nextKey) {
-      return this.iframe;
-    }
-    this.detach?.();
-    try {
-      const iframe = document.createElement("iframe");
-      // CONSTANT sandbox — do not templatize. Only script execution is granted.
-      iframe.setAttribute("sandbox", "allow-scripts");
-      iframe.setAttribute("referrerpolicy", "no-referrer");
-      iframe.setAttribute("loading", "lazy");
-      iframe.className = "workspace-widget__frame";
-      iframe.title = params.widget.title;
-      const bridgeToken = params.manifest.frameToken;
-      iframe.src = assetUrl;
-      iframe.setAttribute("data-test-id", "workspace-custom-widget-frame");
-      this.detach = attachWidgetBridge({
-        iframe,
-        widget: params.widget,
-        manifest: params.manifest,
-        context: params.context,
-        bridgeToken,
-      });
-      this.iframe = iframe;
-      this.key = nextKey;
-      return iframe;
-    } catch (error) {
-      // A directive's render runs at Lit COMMIT time, outside the try/catch in
-      // `renderWorkspaceWidgetBody`. A throw here would escape the per-cell error boundary
-      // and take down the whole tab, so the boundary has to exist here too.
-      this.detach = null;
-      this.iframe = null;
-      this.key = "";
-      const fallback = document.createElement("div");
-      fallback.className = "workspace-widget__error";
-      fallback.setAttribute("role", "alert");
-      fallback.setAttribute("data-test-id", "workspace-custom-widget-error");
-      fallback.textContent = error instanceof Error ? error.message : String(error);
-      return fallback;
-    }
-  }
-
-  override disconnected(): void {
-    this.detach?.();
-    this.detach = null;
-    this.iframe = null;
-    this.key = "";
-  }
-}
-
-const customWidgetFrame = directive(CustomWidgetFrameDirective);
-
-/** Renders the sandboxed iframe host for an approved custom widget. */
-export function renderCustomWidgetHost(params: {
-  widget: WorkspaceWidget;
-  manifest: WidgetManifestView;
-  context: CustomWidgetHostContext;
-}): TemplateResult {
-  return html`<div class="workspace-widget__custom" data-test-id="workspace-custom-widget">
-    ${customWidgetFrame(params)}
-  </div>`;
-}
diff --git a/ui/src/components/workspace-widget-cell.test.ts b/ui/src/components/workspace-widget-cell.test.ts
deleted file mode 100644
index 93a62205d87..00000000000
--- a/ui/src/components/workspace-widget-cell.test.ts
+++ /dev/null
@@ -1,173 +0,0 @@
-import { render } from "lit";
-import { describe, expect, it, vi } from "vitest";
-import type { WorkspaceBindingResult } from "../lib/workspace/index.ts";
-import type { WorkspaceWidget, WidgetManifestView } from "../lib/workspace/types.ts";
-import type { BuiltinWidgetContext } from "../lib/workspace/widgets/index.ts";
-import {
-  renderWidgetCell,
-  type WorkspaceCustomWidgetContext,
-  type WorkspaceWidgetCellCallbacks,
-} from "./workspace-widget-cell.ts";
-
-const BUILTIN_CONTEXT: BuiltinWidgetContext = {
-  basePath: "",
-  embed: { embedSandboxMode: "strict", allowExternalEmbedUrls: false },
-  preview: { getViewport: (_widgetId, fallback) => fallback, setViewport: vi.fn() },
-};
-
-function callbacks(): WorkspaceWidgetCellCallbacks {
-  return {
-    onToggleCollapse: vi.fn(),
-    onToggleMenu: vi.fn(),
-    onCloseMenu: vi.fn(),
-    onHide: vi.fn(),
-    onRemove: vi.fn(),
-    onEditTitle: vi.fn(),
-    onMoveToTab: vi.fn(),
-    onMovePointerDown: vi.fn(),
-    onResizePointerDown: vi.fn(),
-    onKeyboardNudge: vi.fn(),
-  };
-}
-
-function widget(overrides: Partial<WorkspaceWidget> = {}): WorkspaceWidget {
-  return {
-    id: "w1",
-    kind: "builtin:stat-card",
-    title: "Revenue",
-    grid: { x: 0, y: 0, w: 4, h: 2 },
-    collapsed: false,
-    ...overrides,
-  };
-}
-
-function customManifest(): WidgetManifestView {
-  return {
-    name: "chart",
-    frameToken: "11111111-1111-4111-8111-111111111111",
-    entrypoint: "index.html",
-    bindings: { value: { source: "static", value: null } },
-    capabilities: ["data:read"],
-  };
-}
-
-function customContext(
-  overrides: Partial<WorkspaceCustomWidgetContext> = {},
-): WorkspaceCustomWidgetContext {
-  return {
-    status: "approved",
-    createdBy: "user",
-    manifest: customManifest(),
-    host: { client: null, basePath: "", sessionKey: "main" },
-    onApprove: vi.fn(),
-    onReject: vi.fn(),
-    ...overrides,
-  };
-}
-
-function renderCell(params: {
-  widget?: WorkspaceWidget;
-  binding?: WorkspaceBindingResult | null;
-  custom?: WorkspaceCustomWidgetContext;
-  menuOpen?: boolean;
-}) {
-  const container = document.createElement("div");
-  render(
-    renderWidgetCell({
-      widget: params.widget ?? widget(),
-      binding: params.binding ?? { value: 1000 },
-      menuOpen: params.menuOpen ?? false,
-      pending: false,
-      dragging: false,
-      builtinContext: BUILTIN_CONTEXT,
-      callbacks: callbacks(),
-      custom: params.custom,
-    }),
-    container,
-  );
-  return container;
-}
-
-describe("renderWidgetCell", () => {
-  it("renders title, provenance, menu, body, and resize affordances", () => {
-    const container = renderCell({
-      widget: widget({ title: "Revenue (custom)", createdBy: "agent:finance" }),
-      menuOpen: true,
-    });
-    const title = container.querySelector(".workspace-widget__title");
-    expect(title?.textContent?.trim()).toBe("Revenue");
-    expect(title?.getAttribute("title")).toBe("Revenue (custom)");
-    expect(
-      container.querySelector(".workspace-widget__provenance")?.getAttribute("title"),
-    ).toContain("finance");
-    expect(container.querySelectorAll(".workspace-widget__menu-item")).toHaveLength(4);
-    expect(container.querySelector(".workspace-stat__value")?.textContent).toContain("1,000");
-    expect(container.querySelector(".workspace-widget__resize")).not.toBeNull();
-  });
-
-  it("hides the body and resize handle when collapsed", () => {
-    const container = renderCell({ widget: widget({ collapsed: true }) });
-    expect(container.querySelector(".workspace-widget__body")).toBeNull();
-    expect(container.querySelector(".workspace-widget__resize")).toBeNull();
-  });
-
-  it("contains binding failures inside the affected cell", () => {
-    const container = renderCell({ binding: { error: "binding failed" } });
-    expect(
-      container.querySelector('[data-test-id="workspace-widget-error"]')?.textContent,
-    ).toContain("binding failed");
-  });
-
-  it("renders approved custom widgets only after their manifest loads", () => {
-    expect(
-      renderCell({
-        widget: widget({ kind: "custom:chart" }),
-        custom: customContext(),
-      })
-        .querySelector("iframe")
-        ?.getAttribute("sandbox"),
-    ).toBe("allow-scripts");
-    const loading = renderCell({
-      widget: widget({ kind: "custom:chart" }),
-      custom: customContext({ manifest: null }),
-    });
-    expect(loading.querySelector("iframe")).toBeNull();
-    expect(loading.querySelector('[data-test-id="workspace-custom-loading"]')).not.toBeNull();
-  });
-
-  it("keeps pending widgets inert and routes approval actions", () => {
-    const onApprove = vi.fn();
-    const onReject = vi.fn();
-    const candidate = widget({ kind: "custom:chart", createdBy: "agent:layout" });
-    const container = renderCell({
-      widget: candidate,
-      custom: customContext({
-        status: "pending",
-        createdBy: "agent:scaffold",
-        manifest: null,
-        onApprove,
-        onReject,
-      }),
-    });
-    expect(container.querySelector("iframe")).toBeNull();
-    expect(
-      container.querySelector('[data-test-id="workspace-custom-pending"]')?.textContent,
-    ).toContain("scaffold");
-    container
-      .querySelector<HTMLButtonElement>('[data-test-id="workspace-custom-approve"]')
-      ?.click();
-    container.querySelector<HTMLButtonElement>('[data-test-id="workspace-custom-reject"]')?.click();
-    expect(onApprove).toHaveBeenCalledWith(candidate);
-    expect(onReject).toHaveBeenCalledWith(candidate);
-  });
-
-  it("keeps rejected custom widgets iframe-free", () => {
-    const container = renderCell({
-      widget: widget({ kind: "custom:chart" }),
-      custom: customContext({ status: "rejected", manifest: customManifest() }),
-    });
-
-    expect(container.querySelector("iframe")).toBeNull();
-    expect(container.querySelector('[data-test-id="workspace-custom-rejected"]')).not.toBeNull();
-  });
-});
diff --git a/ui/src/components/workspace-widget-cell.ts b/ui/src/components/workspace-widget-cell.ts
deleted file mode 100644
index b40d346674f..00000000000
--- a/ui/src/components/workspace-widget-cell.ts
+++ /dev/null
@@ -1,393 +0,0 @@
-// Cell chrome for a workspace widget: title bar, collapse toggle, kebab menu,
-// provenance badge, and a per-cell error boundary. Pure render fns (workboard
-// view idiom) — the Workspaces view owns state and passes callbacks in.
-//
-// The error boundary wraps the widget body render: a throw yields an error card in
-// this cell only, so the shell and sibling widgets are unaffected (spec-30).
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../i18n/index.ts";
-import { gridPlacementStyle } from "../lib/workspace/grid.ts";
-import { workspaceAgentProvenance, type WorkspaceBindingResult } from "../lib/workspace/index.ts";
-import type {
-  WorkspaceCreatedBy,
-  WorkspaceWidget,
-  WorkspaceWidgetStatus,
-  WidgetManifestView,
-} from "../lib/workspace/types.ts";
-import { getBuiltinRenderer, type BuiltinWidgetContext } from "../lib/workspace/widgets/index.ts";
-import { icons } from "./icons.ts";
-import { renderCustomWidgetHost, type CustomWidgetHostContext } from "./workspace-custom-widget.ts";
-import "./web-awesome.ts";
-
-export type WorkspaceWidgetCellCallbacks = {
-  onToggleCollapse: (widget: WorkspaceWidget) => void;
-  onToggleMenu: (widget: WorkspaceWidget) => void;
-  onCloseMenu: (widget: WorkspaceWidget) => void;
-  onHide: (widget: WorkspaceWidget) => void;
-  onRemove: (widget: WorkspaceWidget) => void;
-  onEditTitle: (widget: WorkspaceWidget) => void;
-  onMoveToTab: (widget: WorkspaceWidget) => void;
-  onMovePointerDown: (widget: WorkspaceWidget, event: PointerEvent) => void;
-  onResizePointerDown: (widget: WorkspaceWidget, event: PointerEvent) => void;
-  onKeyboardNudge: (
-    widget: WorkspaceWidget,
-    mode: "move" | "resize",
-    direction: "left" | "right" | "up" | "down",
-  ) => void;
-};
-
-/**
- * Custom-widget (`custom:<name>`) rendering context (L5). Passed only for custom
- * widgets; builtin widgets ignore it. Carries the registry approval status (gates
- * whether an iframe is ever built), the loaded manifest, the sandbox host context,
- * and the operator-only approve/reject actions for the pending placeholder.
- */
-export type WorkspaceCustomWidgetContext = {
-  status: WorkspaceWidgetStatus | null;
-  /** Provenance of the scaffolded code being approved, not its layout instance. */
-  createdBy?: WorkspaceCreatedBy;
-  manifest: WidgetManifestView | null;
-  host: CustomWidgetHostContext;
-  onApprove: (widget: WorkspaceWidget) => void;
-  onReject: (widget: WorkspaceWidget) => void;
-};
-
-type WorkspaceWidgetCellProps = {
-  widget: WorkspaceWidget;
-  /** Resolved binding value for the primary binding, or an error to surface. */
-  binding: WorkspaceBindingResult | null;
-  menuOpen: boolean;
-  pending: boolean;
-  /** When set, this cell is the live drag/resize ghost source. */
-  dragging: boolean;
-  /** Ambient context builtins may need (embed policy for iframe-embed). */
-  builtinContext: BuiltinWidgetContext;
-  callbacks: WorkspaceWidgetCellCallbacks;
-  /** Present for `custom:` widgets only (L5); builtin widgets leave this undefined. */
-  custom?: WorkspaceCustomWidgetContext;
-};
-
-/**
- * Visible widget title with a trailing " (custom)" provenance suffix stripped
- * (#8). The suffix is redundant with the AI/provenance chip and only causes
- * truncation; the full title is still exposed via the `title=` attribute.
- */
-function displayWidgetTitle(title: string): string {
-  return title.replace(/\s*\(custom\)\s*$/iu, "").trim() || title;
-}
-
-/** Renders the provenance chip when a widget was authored by an agent. */
-function renderProvenanceChip(widget: WorkspaceWidget): TemplateResult | typeof nothing {
-  const agentId = workspaceAgentProvenance(widget.createdBy);
-  if (!agentId) {
-    return nothing;
-  }
-  return html`<span
-    class="workspace-widget__provenance"
-    title=${t("workspaces.widget.provenanceTooltip", { agent: agentId })}
-    >${t("workspaces.widget.provenanceChip")}</span
-  >`;
-}
-
-function renderMenu(): TemplateResult {
-  return html`
-    <wa-dropdown-item class="workspace-widget__menu-item" value="edit-title">
-      ${t("workspaces.widget.menu.editTitle")}
-    </wa-dropdown-item>
-    <wa-dropdown-item class="workspace-widget__menu-item" value="move-to-tab">
-      ${t("workspaces.widget.menu.moveToTab")}
-    </wa-dropdown-item>
-    <wa-dropdown-item class="workspace-widget__menu-item" value="hide">
-      ${t("workspaces.widget.menu.hide")}
-    </wa-dropdown-item>
-    <wa-dropdown-item
-      class="workspace-widget__menu-item workspace-widget__menu-item--danger"
-      value="remove"
-      variant="danger"
-    >
-      ${t("workspaces.widget.menu.remove")}
-    </wa-dropdown-item>
-  `;
-}
-
-/**
- * Renders a builtin widget body via the L4 registry. A binding error is
- * re-thrown so the cell error boundary shows it inline; unknown/custom kinds
- * render a placeholder (L5 replaces custom with the sandboxed iframe host).
- */
-function renderBuiltinWidget(
-  widget: WorkspaceWidget,
-  binding: WorkspaceBindingResult | null,
-  ctx: BuiltinWidgetContext,
-): TemplateResult {
-  if (binding && "error" in binding) {
-    // A binding failure is data-level, not a render throw: show it inline so the
-    // widget stays mounted and refetches on the next broadcast.
-    throw new Error(binding.error);
-  }
-  const value = binding && "value" in binding ? binding.value : undefined;
-  const renderer = getBuiltinRenderer(widget.kind);
-  if (renderer) {
-    return renderer(widget, value, ctx);
-  }
-  if (widget.kind.startsWith("custom:")) {
-    // Custom widgets are dispatched by renderWorkspaceWidgetBody BEFORE this builtin path;
-    // reaching here means no L5 host context was supplied (e.g. a unit test
-    // rendering the builtin body in isolation). Neutral placeholder — never an
-    // iframe without a manifest.
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.customPlaceholder")}
-    </div>`;
-  }
-  return html`<div class="workspace-widget__placeholder">
-    ${t("workspaces.widget.unknownKind", { kind: widget.kind })}
-  </div>`;
-}
-
-/**
- * Renders a `custom:<name>` widget (L5). The registry status is the render gate,
- * mirroring the server's approved-only serving gate:
- * - `approved` → the sandboxed iframe host (only path that ever builds an iframe).
- * - `pending`  → a placeholder card with operator-only Approve/Reject.
- * - `rejected` / unknown → a neutral placeholder; NO iframe is constructed.
- */
-function renderCustomWidget(
-  widget: WorkspaceWidget,
-  custom: WorkspaceCustomWidgetContext,
-): TemplateResult {
-  if (custom.status === "approved") {
-    if (!custom.manifest) {
-      // Approved but the manifest has not loaded yet: hold the cell without an
-      // iframe until the manifest resolves (the parent re-renders on load).
-      return html`<div
-        class="workspace-widget__placeholder"
-        data-test-id="workspace-custom-loading"
-      >
-        ${t("workspaces.widget.customLoading")}
-      </div>`;
-    }
-    return renderCustomWidgetHost({
-      widget,
-      manifest: custom.manifest,
-      context: custom.host,
-    });
-  }
-  if (custom.status === "pending") {
-    const author = workspaceAgentProvenance(custom.createdBy);
-    return html`
-      <div
-        class="workspace-widget__approval"
-        role="group"
-        data-test-id="workspace-custom-pending"
-        aria-label=${t("workspaces.widget.approval.title")}
-      >
-        <div class="workspace-widget__approval-title">${t("workspaces.widget.approval.title")}</div>
-        <div class="workspace-widget__approval-sub">
-          ${author
-            ? t("workspaces.widget.approval.byAgent", { agent: author })
-            : t("workspaces.widget.approval.byUnknown")}
-        </div>
-        <div class="workspace-widget__approval-actions">
-          <button
-            class="btn btn--small btn--primary"
-            type="button"
-            data-test-id="workspace-custom-approve"
-            @click=${() => custom.onApprove(widget)}
-          >
-            ${t("workspaces.widget.approval.approve")}
-          </button>
-          <button
-            class="btn btn--small"
-            type="button"
-            data-test-id="workspace-custom-reject"
-            @click=${() => custom.onReject(widget)}
-          >
-            ${t("workspaces.widget.approval.reject")}
-          </button>
-        </div>
-      </div>
-    `;
-  }
-  return html`<div class="workspace-widget__placeholder" data-test-id="workspace-custom-rejected">
-    ${t("workspaces.widget.approval.unavailable")}
-  </div>`;
-}
-
-/**
- * Error boundary around the widget body. Any throw during the builtin render (a
- * broken widget, a bad binding) is caught and rendered as an error card in THIS
- * cell — siblings and the shell keep rendering (spec-30 acceptance criterion).
- */
-export function renderWorkspaceWidgetBody(
-  widget: WorkspaceWidget,
-  binding: WorkspaceBindingResult | null,
-  ctx: BuiltinWidgetContext,
-  callbacks: WorkspaceWidgetCellCallbacks,
-  custom?: WorkspaceCustomWidgetContext,
-): TemplateResult {
-  try {
-    // Builtins render eagerly inside this try. Custom widgets mount through a Lit
-    // directive whose render runs at commit time — outside this catch — so it
-    // carries its own boundary (`CustomWidgetFrameDirective.render`).
-    if (widget.kind.startsWith("custom:") && custom) {
-      return renderCustomWidget(widget, custom);
-    }
-    return renderBuiltinWidget(widget, binding, ctx);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return html`
-      <div class="workspace-widget__error" role="alert" data-test-id="workspace-widget-error">
-        <div class="workspace-widget__error-title">${t("workspaces.widget.errorTitle")}</div>
-        <div class="workspace-widget__error-humane">${t("workspaces.widget.errorHumane")}</div>
-        <details class="workspace-widget__error-detail">
-          <summary>${t("workspaces.widget.errorDetailSummary")}</summary>
-          <div class="workspace-widget__error-message">${message}</div>
-        </details>
-        <button class="btn btn--small" type="button" @click=${() => callbacks.onRemove(widget)}>
-          ${t("workspaces.widget.menu.remove")}
-        </button>
-      </div>
-    `;
-  }
-}
-
-export function renderWidgetCell(props: WorkspaceWidgetCellProps): TemplateResult {
-  const { widget, callbacks } = props;
-  const classes = [
-    "workspace-widget",
-    widget.collapsed ? "workspace-widget--collapsed" : "",
-    props.pending ? "workspace-widget--pending" : "",
-    props.dragging ? "workspace-widget--dragging" : "",
-  ]
-    .filter(Boolean)
-    .join(" ");
-  return html`
-    <section
-      class=${classes}
-      style=${gridPlacementStyle(widget.grid)}
-      data-widget-id=${widget.id}
-      data-test-id="workspace-widget"
-    >
-      <header
-        class="workspace-widget__bar"
-        @pointerdown=${(event: PointerEvent) => callbacks.onMovePointerDown(widget, event)}
-      >
-        <button
-          class="workspace-widget__collapse"
-          type="button"
-          aria-expanded=${widget.collapsed ? "false" : "true"}
-          aria-label=${widget.collapsed
-            ? t("workspaces.widget.expand")
-            : t("workspaces.widget.collapse")}
-          @pointerdown=${(event: PointerEvent) => event.stopPropagation()}
-          @click=${() => callbacks.onToggleCollapse(widget)}
-        >
-          ${widget.collapsed ? icons.chevronRight : icons.chevronDown}
-        </button>
-        <span class="workspace-widget__title" title=${widget.title}
-          >${displayWidgetTitle(widget.title)}</span
-        >
-        ${renderProvenanceChip(widget)}
-        <span
-          class="workspace-widget__handle"
-          role="button"
-          tabindex="0"
-          aria-label=${t("workspaces.widget.moveHandle")}
-          @keydown=${(event: KeyboardEvent) => handleNudgeKey(event, widget, "move", callbacks)}
-          >${icons.arrowUpDown}</span
-        >
-        <wa-dropdown
-          class="workspace-widget__menu"
-          placement="bottom-end"
-          .open=${props.menuOpen}
-          @pointerdown=${(event: PointerEvent) => event.stopPropagation()}
-          @wa-select=${(event: CustomEvent<{ item: { value?: string } }>) => {
-            switch (event.detail.item.value) {
-              case "edit-title":
-                callbacks.onEditTitle(widget);
-                break;
-              case "move-to-tab":
-                callbacks.onMoveToTab(widget);
-                break;
-              case "hide":
-                callbacks.onHide(widget);
-                break;
-              case "remove":
-                callbacks.onRemove(widget);
-                break;
-              case undefined:
-                break;
-            }
-          }}
-          @wa-show=${() => {
-            if (!props.menuOpen) {
-              callbacks.onToggleMenu(widget);
-            }
-          }}
-          @wa-hide=${() => {
-            if (props.menuOpen) {
-              callbacks.onCloseMenu(widget);
-            }
-          }}
-        >
-          <button
-            slot="trigger"
-            class="workspace-widget__menu-toggle"
-            type="button"
-            aria-label=${t("workspaces.widget.menuLabel")}
-          >
-            ${icons.moreHorizontal}
-          </button>
-          ${renderMenu()}
-        </wa-dropdown>
-      </header>
-      ${widget.collapsed
-        ? nothing
-        : html`
-            <div class="workspace-widget__body">
-              ${renderWorkspaceWidgetBody(
-                widget,
-                props.binding,
-                props.builtinContext,
-                callbacks,
-                props.custom,
-              )}
-            </div>
-            <span
-              class="workspace-widget__resize"
-              role="button"
-              tabindex="0"
-              aria-label=${t("workspaces.widget.resizeHandle")}
-              @pointerdown=${(event: PointerEvent) => callbacks.onResizePointerDown(widget, event)}
-              @keydown=${(event: KeyboardEvent) =>
-                handleNudgeKey(event, widget, "resize", callbacks)}
-            ></span>
-          `}
-    </section>
-  `;
-}
-
-/** Keyboard fallback for move/resize (a11y): arrow keys nudge by one grid unit. */
-function handleNudgeKey(
-  event: KeyboardEvent,
-  widget: WorkspaceWidget,
-  mode: "move" | "resize",
-  callbacks: WorkspaceWidgetCellCallbacks,
-): void {
-  const direction =
-    event.key === "ArrowLeft"
-      ? "left"
-      : event.key === "ArrowRight"
-        ? "right"
-        : event.key === "ArrowUp"
-          ? "up"
-          : event.key === "ArrowDown"
-            ? "down"
-            : null;
-  if (!direction) {
-    return;
-  }
-  event.preventDefault();
-  callbacks.onKeyboardNudge(widget, mode, direction);
-}
diff --git a/ui/src/e2e/workspace-chart.e2e.test.ts b/ui/src/e2e/workspace-chart.e2e.test.ts
deleted file mode 100644
index 4be4ecbc799..00000000000
--- a/ui/src/e2e/workspace-chart.e2e.test.ts
+++ /dev/null
@@ -1,131 +0,0 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import { chromium, type Browser, type Page } from "playwright";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  canRunPlaywrightChromium,
-  installMockGateway,
-  resolvePlaywrightChromiumExecutablePath,
-  startControlUiE2eServer,
-  type ControlUiE2eServer,
-} from "../test-helpers/control-ui-e2e.ts";
-
-const chromiumExecutablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
-const chromiumAvailable = canRunPlaywrightChromium(chromiumExecutablePath);
-const allowMissingChromium = process.env.OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM === "1";
-const describeControlUiE2e = chromiumAvailable || !allowMissingChromium ? describe : describe.skip;
-const proofDir = process.env.OPENCLAW_UI_E2E_ARTIFACT_DIR?.trim();
-
-const chartTypes = ["line", "bar", "area", "sparkline", "gauge"] as const;
-const chartValues = [8, 16, 11, 24, 20, 31];
-
-let browser: Browser;
-let server: ControlUiE2eServer;
-
-function workspaceDoc() {
-  return {
-    doc: {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [
-        {
-          slug: "charts",
-          title: "Chart gallery",
-          hidden: false,
-          createdBy: "agent:main",
-          widgets: chartTypes.map((type, index) => ({
-            id: `chart_${type}`,
-            kind: "builtin:chart",
-            title: `${type[0]?.toUpperCase()}${type.slice(1)} chart`,
-            grid:
-              index < 3
-                ? { x: index * 4, y: 0, w: 4, h: 3 }
-                : { x: 2 + (index - 3) * 4, y: 3, w: 4, h: 3 },
-            collapsed: false,
-            createdBy: "agent:main",
-            props: { type },
-            bindings: { value: { source: "static", value: chartValues } },
-          })),
-        },
-      ],
-      widgetsRegistry: {},
-      prefs: { tabOrder: ["charts"] },
-    },
-    workspaceVersion: 1,
-  };
-}
-
-async function captureProof(page: Page): Promise<void> {
-  if (!proofDir) {
-    return;
-  }
-  await mkdir(proofDir, { recursive: true });
-  await page.screenshot({
-    fullPage: true,
-    path: path.join(proofDir, "workspace-chart-gallery.png"),
-  });
-  const widgets = page.locator('[data-test-id="workspace-widget"]');
-  for (const [index, type] of chartTypes.entries()) {
-    await widgets
-      .nth(index)
-      .screenshot({ path: path.join(proofDir, `workspace-chart-${type}.png`) });
-  }
-}
-
-describeControlUiE2e("Control UI workspace chart widgets", () => {
-  beforeAll(async () => {
-    if (!chromiumAvailable) {
-      throw new Error(`Playwright Chromium is not available at ${chromiumExecutablePath}`);
-    }
-    server = await startControlUiE2eServer();
-    browser = await chromium.launch({ executablePath: chromiumExecutablePath });
-  });
-
-  afterAll(async () => {
-    await browser?.close();
-    await server?.close();
-  });
-
-  it("renders every trusted chart type with an accessible data summary", async () => {
-    const context = await browser.newContext({
-      locale: "en-US",
-      serviceWorkers: "block",
-      viewport: { height: 1000, width: 1440 },
-    });
-    const page = await context.newPage();
-    await installMockGateway(page, {
-      controlUiTabs: [
-        {
-          pluginId: "workspaces",
-          id: "workspaces",
-          label: "Workspaces",
-          group: "control",
-        },
-      ],
-      featureMethods: ["workspaces.get"],
-      methodResponses: { "workspaces.get": workspaceDoc() },
-    });
-
-    try {
-      const response = await page.goto(`${server.baseUrl}plugin?plugin=workspaces&id=workspaces`);
-      expect(response?.status()).toBe(200);
-      const widgets = page.locator('[data-test-id="workspace-widget"]');
-      await expect.poll(() => widgets.count()).toBe(chartTypes.length);
-
-      for (const [index, type] of chartTypes.entries()) {
-        const widget = widgets.nth(index);
-        const chart = widget.locator('[data-test-id="workspace-chart"]');
-        await chart.waitFor({ timeout: 10_000 });
-        expect(await widget.locator(`.workspace-chart--${type}`).count()).toBe(1);
-        expect(await chart.getAttribute("role")).toBe("img");
-        expect(await chart.getAttribute("aria-label")).toBe(
-          `${type[0]?.toUpperCase()}${type.slice(1)} chart: 6 data points, ranging from 8 to 31.`,
-        );
-      }
-
-      await captureProof(page);
-    } finally {
-      await context.close();
-    }
-  });
-});
diff --git a/ui/src/e2e/workspace-custom-widget.e2e.test.ts b/ui/src/e2e/workspace-custom-widget.e2e.test.ts
deleted file mode 100644
index f3b7d9dc5fc..00000000000
--- a/ui/src/e2e/workspace-custom-widget.e2e.test.ts
+++ /dev/null
@@ -1,495 +0,0 @@
-// Control UI E2E for the L5 sandboxed custom-widget host against a mocked Gateway
-// plus a page.route() that serves fixture widget assets with the REAL Content-
-// Security-Policy header the plugin route emits. Covers the acceptance security
-// list: approve flow, bridge getData round-trip with the L2 scaffold fixture,
-// foreign-window message dropped, CSP blocking fetch(), throwing-widget isolation,
-// and the constant sandbox attribute asserted in the DOM.
-import { chromium, type Browser, type Page, type Route } from "playwright";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  canRunPlaywrightChromium,
-  installMockGateway,
-  resolvePlaywrightChromiumExecutablePath,
-  startControlUiE2eServer,
-  type ControlUiE2eServer,
-} from "../test-helpers/control-ui-e2e.ts";
-
-const chromiumExecutablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
-const chromiumAvailable = canRunPlaywrightChromium(chromiumExecutablePath);
-const allowMissingChromium = process.env.OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM === "1";
-const describeControlUiE2e = chromiumAvailable || !allowMissingChromium ? describe : describe.skip;
-
-// The strict CSP the plugin serving route emits (serve.ts WIDGET_CSP). Reproduced
-// here so the fixture route mirrors production headers and the fetch()-blocked and
-// sandbox assertions run against realistic frame constraints.
-const WIDGET_CSP =
-  "sandbox allow-scripts; default-src 'none'; script-src 'self' 'unsafe-inline'; " +
-  "style-src 'self' 'unsafe-inline'; " +
-  "img-src 'self' data:; font-src 'self' data:; connect-src 'none'; frame-ancestors 'self'";
-
-let browser: Browser;
-let server: ControlUiE2eServer;
-const FRAME_TOKEN = "1111111111111111111111111111111111111111111";
-
-function workspaceGatewayScenario() {
-  return {
-    controlUiTabs: [
-      {
-        pluginId: "workspaces",
-        id: "workspaces",
-        label: "Workspaces",
-        group: "control",
-        order: -10,
-      },
-    ],
-    featureMethods: ["workspaces.get", "workspaces.widget.approve", "workspaces.widget.frame"],
-  };
-}
-
-function frameMethodResponse() {
-  return {
-    "workspaces.widget.frame": {
-      frameToken: FRAME_TOKEN,
-      frameExpiresAt: Date.now() + 60 * 60 * 1000,
-      manifest: {
-        schemaVersion: 1,
-        name: "revenue-chart",
-        title: "Revenue Chart",
-        entrypoint: "index.html",
-        bindings: [{ id: "value", source: "static", value: 0 }],
-        capabilities: ["data:read"],
-      },
-    },
-  };
-}
-
-function workspaceDoc(version: number, status: "pending" | "approved", title = "Revenue Chart") {
-  return {
-    doc: {
-      schemaVersion: 1,
-      workspaceVersion: version,
-      tabs: [
-        {
-          slug: "main",
-          title: "Main",
-          hidden: false,
-          createdBy: "agent:main",
-          widgets: [
-            {
-              id: "w_custom",
-              kind: "custom:revenue-chart",
-              title,
-              grid: { x: 0, y: 0, w: 6, h: 4 },
-              collapsed: false,
-              createdBy: "agent:main",
-              bindings: { value: { source: "static", value: { revenue: 4242 } } },
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: {
-        "revenue-chart": { status, createdBy: "agent:main" },
-      },
-      prefs: { tabOrder: ["main"] },
-    },
-    workspaceVersion: version,
-  };
-}
-
-// A framework-free fixture widget mirroring the L2 scaffold template: v1
-// handshake, getData round-trip rendering into #value, and (for the CSP test) an
-// attempt to fetch() that connect-src 'none' must block.
-const FIXTURE_WIDGET_HTML = `<!doctype html><html><head><meta charset="utf-8"><title>Revenue Chart</title></head>
-<body>
-<pre id="value">waiting</pre>
-<pre id="fetch">idle</pre>
-<footer id="footer">Built by agent:main</footer>
-<script>
-  const valueNode = document.getElementById("value");
-  const fetchNode = document.getElementById("fetch");
-  const bridge = window.openclawWorkspaceBridge;
-  function post(type, payload = {}) { bridge.postMessage({ v: 1, type, ...payload }); }
-  bridge.addEventListener("message", (event) => {
-    const m = event.data;
-    if (!m || m.v !== 1) return;
-    if (m.type === "workspace:data" || m.type === "workspace:push") {
-      valueNode.textContent = JSON.stringify(m.data);
-    } else if (m.type === "workspace:error") {
-      valueNode.textContent = "error:" + m.code;
-    }
-  });
-  post("workspace:ready");
-  post("workspace:getData", { requestId: "initial", bindingId: "value" });
-  // connect-src 'none' must reject this — the catch marks the widget as blocked.
-  fetch("https://example.com/leak").then(
-    () => { fetchNode.textContent = "fetch-allowed"; },
-    () => { fetchNode.textContent = "fetch-blocked"; },
-  );
-</script>
-</body></html>`;
-
-const THROWING_WIDGET_HTML = `<!doctype html><html><head><meta charset="utf-8"></head>
-<body><script>throw new Error("widget boom");</script></body></html>`;
-
-async function routeWidgetAssets(page: Page, html: string): Promise<void> {
-  await page.route("**/plugins/workspaces/widgets/*/revenue-chart/**", (route: Route) => {
-    const url = route.request().url();
-    const segments = new URL(url).pathname.split("/");
-    const widgetsIndex = segments.indexOf("widgets");
-    const bridgeToken = widgetsIndex >= 0 ? segments[widgetsIndex + 1] : null;
-    const bootstrap = bridgeToken
-      ? `<script>(()=>{const channel=new MessageChannel();const listeners=new Set();const port=channel.port1;port.onmessage=(event)=>{for(const listener of listeners)listener(event)};port.start();Object.defineProperty(window,"openclawWorkspaceBridge",{configurable:false,writable:false,value:Object.freeze({postMessage:(message)=>port.postMessage(message),addEventListener:(type,listener)=>{if(type==="message")listeners.add(listener)},removeEventListener:(type,listener)=>{if(type==="message")listeners.delete(listener)}})});window.parent.postMessage({v:1,type:"workspace:bridge:init",token:"${bridgeToken}"},"*",[channel.port2])})();</script>`
-      : "";
-    const doctype = html.match(/^\uFEFF?(?:\s|<!--[\s\S]*?-->)*<!doctype[^>]*>/i)?.[0] ?? "";
-    const body = `${doctype}${bootstrap}${html.slice(doctype.length)}`;
-    return route.fulfill({
-      status: 200,
-      contentType: "text/html; charset=utf-8",
-      headers: {
-        "Content-Security-Policy": WIDGET_CSP,
-        "X-Content-Type-Options": "nosniff",
-        "Referrer-Policy": "no-referrer",
-      },
-      body,
-    });
-  });
-}
-
-async function gotoWorkspaces(page: Page, e2eServer: ControlUiE2eServer) {
-  const response = await page.goto(`${e2eServer.baseUrl}plugin?plugin=workspaces&id=workspaces`);
-  expect(response?.status()).toBe(200);
-}
-
-async function newPage(): Promise<Page> {
-  const context = await browser.newContext({
-    locale: "en-US",
-    serviceWorkers: "block",
-    viewport: { height: 900, width: 1280 },
-  });
-  return context.newPage();
-}
-
-async function waitForTwoAnimationFrames(page: Page): Promise<void> {
-  await page.evaluate(
-    () =>
-      new Promise<void>((resolve) => {
-        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
-      }),
-  );
-}
-
-describeControlUiE2e("Control UI custom-widget host mocked Gateway E2E", () => {
-  beforeAll(async () => {
-    if (!chromiumAvailable) {
-      throw new Error(
-        `Playwright Chromium is not installed or cannot start at ${chromiumExecutablePath}.`,
-      );
-    }
-    server = await startControlUiE2eServer();
-    browser = await chromium.launch({ executablePath: chromiumExecutablePath });
-  });
-
-  afterAll(async () => {
-    await browser?.close();
-    await server?.close();
-  });
-
-  it("renders a pending widget as an approval card with NO iframe, then approves it", async () => {
-    const page = await newPage();
-    await routeWidgetAssets(page, FIXTURE_WIDGET_HTML);
-    const gateway = await installMockGateway(page, {
-      ...workspaceGatewayScenario(),
-      methodResponses: {
-        ...frameMethodResponse(),
-        "workspaces.get": workspaceDoc(1, "pending"),
-        "workspaces.widget.approve": { ok: true },
-      },
-    });
-    try {
-      await gotoWorkspaces(page, server);
-      // Pending → approval card, no iframe.
-      await page.locator('[data-test-id="workspace-custom-pending"]').waitFor({ timeout: 10_000 });
-      expect(await page.locator("iframe").count()).toBe(0);
-
-      // Approve → workspaces.widget.approve RPC, then a broadcast delivers the
-      // approved doc; the iframe host mounts.
-      await gateway.deferNext("workspaces.get");
-      await page.locator('[data-test-id="workspace-custom-approve"]').click();
-      await gateway.waitForRequest("workspaces.widget.approve");
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 2 });
-      await gateway.resolveDeferred("workspaces.get", workspaceDoc(2, "approved"));
-
-      const frame = page.locator('[data-test-id="workspace-custom-widget-frame"]');
-      await frame.waitFor({ timeout: 10_000 });
-      // Sandbox attribute is EXACTLY "allow-scripts".
-      expect(await frame.getAttribute("sandbox")).toBe("allow-scripts");
-      expect(await frame.getAttribute("referrerpolicy")).toBe("no-referrer");
-    } finally {
-      await page.context().close();
-    }
-  });
-
-  it("keeps the newest workspace when older reloads succeed or fail last", async () => {
-    const page = await newPage();
-    const gateway = await installMockGateway(page, {
-      ...workspaceGatewayScenario(),
-      methodResponses: {
-        "workspaces.get": workspaceDoc(1, "pending", "Initial"),
-      },
-    });
-    try {
-      await gotoWorkspaces(page, server);
-      const title = page.locator(".workspace-widget__title");
-      await expect.poll(() => title.textContent()).toBe("Initial");
-      await waitForTwoAnimationFrames(page);
-      const initialRequestCount = (await gateway.getRequests("workspaces.get")).length;
-
-      await gateway.deferNext("workspaces.get");
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 2 });
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.get")).length)
-        .toBe(initialRequestCount + 1);
-
-      await gateway.deferNext("workspaces.get");
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 3 });
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.get")).length)
-        .toBe(initialRequestCount + 2);
-
-      const requests = await gateway.getRequests("workspaces.get");
-      const olderRequest = requests.at(-2);
-      const newerRequest = requests.at(-1);
-      expect(olderRequest?.id).toEqual(expect.any(String));
-      expect(newerRequest?.id).toEqual(expect.any(String));
-
-      await gateway.deliverLatest({
-        type: "res",
-        id: newerRequest?.id,
-        ok: true,
-        payload: workspaceDoc(3, "pending", "Newest"),
-      });
-      await expect.poll(() => title.textContent()).toBe("Newest");
-
-      await gateway.deliverLatest({
-        type: "res",
-        id: olderRequest?.id,
-        ok: true,
-        payload: workspaceDoc(2, "pending", "Stale"),
-      });
-      await waitForTwoAnimationFrames(page);
-
-      expect(await title.textContent()).toBe("Newest");
-
-      await gateway.deferNext("workspaces.get");
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 4 });
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.get")).length)
-        .toBe(initialRequestCount + 3);
-
-      await gateway.deferNext("workspaces.get");
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 5 });
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.get")).length)
-        .toBe(initialRequestCount + 4);
-
-      const failureRequests = await gateway.getRequests("workspaces.get");
-      const olderFailedRequest = failureRequests.at(-2);
-      const newerSuccessfulRequest = failureRequests.at(-1);
-      expect(olderFailedRequest?.id).toEqual(expect.any(String));
-      expect(newerSuccessfulRequest?.id).toEqual(expect.any(String));
-
-      await gateway.deliverLatest({
-        type: "res",
-        id: newerSuccessfulRequest?.id,
-        ok: true,
-        payload: workspaceDoc(5, "pending", "Newest after error"),
-      });
-      await expect.poll(() => title.textContent()).toBe("Newest after error");
-
-      await gateway.deliverLatest({
-        type: "res",
-        id: olderFailedRequest?.id,
-        ok: false,
-        error: { code: "UNAVAILABLE", message: "stale failure" },
-      });
-      await waitForTwoAnimationFrames(page);
-
-      expect(await title.textContent()).toBe("Newest after error");
-    } finally {
-      await page.context().close();
-    }
-  });
-
-  it("round-trips getData with the fixture widget and blocks fetch() via CSP", async () => {
-    const page = await newPage();
-    await routeWidgetAssets(page, FIXTURE_WIDGET_HTML);
-    await installMockGateway(page, {
-      ...workspaceGatewayScenario(),
-      methodResponses: {
-        ...frameMethodResponse(),
-        "workspaces.get": workspaceDoc(2, "approved"),
-      },
-    });
-    try {
-      await gotoWorkspaces(page, server);
-      const frameEl = page.locator('[data-test-id="workspace-custom-widget-frame"]');
-      await frameEl.waitFor({ timeout: 10_000 });
-      const frame = page.frameLocator('[data-test-id="workspace-custom-widget-frame"]');
-      // Bridge getData round-trip: the parent resolves the static binding and the
-      // widget renders it.
-      await expect
-        .poll(async () => frame.locator("#value").textContent(), { timeout: 10_000 })
-        .toContain("4242");
-      // connect-src 'none' blocks the widget's fetch().
-      await expect
-        .poll(async () => frame.locator("#fetch").textContent(), { timeout: 10_000 })
-        .toBe("fetch-blocked");
-    } finally {
-      await page.context().close();
-    }
-  });
-
-  it("drops a postMessage from a foreign window (identity accept filter)", async () => {
-    const page = await newPage();
-    await routeWidgetAssets(page, FIXTURE_WIDGET_HTML);
-    await installMockGateway(page, {
-      ...workspaceGatewayScenario(),
-      methodResponses: {
-        ...frameMethodResponse(),
-        "workspaces.get": workspaceDoc(2, "approved"),
-      },
-    });
-    try {
-      await gotoWorkspaces(page, server);
-      const frameEl = page.locator('[data-test-id="workspace-custom-widget-frame"]');
-      await frameEl.waitFor({ timeout: 10_000 });
-      const frame = page.frameLocator('[data-test-id="workspace-custom-widget-frame"]');
-      await expect
-        .poll(async () => frame.locator("#value").textContent(), { timeout: 10_000 })
-        .toContain("4242");
-      // Post a spoofed data message from the PARENT window (event.source !== the
-      // iframe's contentWindow). The bridge must ignore it: #value stays the
-      // legitimate value and never shows the injected marker.
-      await frame.locator("#value").evaluate((node) => {
-        type SpoofObservationWindow = Window & {
-          openclawSawSpoofed?: boolean;
-          openclawSpoofObserver?: MutationObserver;
-        };
-        const targetWindow = window as SpoofObservationWindow;
-        const valueNode = node as HTMLElement;
-        const recordSpoof = () => {
-          if (valueNode.textContent?.includes("SPOOFED")) {
-            targetWindow.openclawSawSpoofed = true;
-          }
-        };
-        targetWindow.openclawSawSpoofed = false;
-        targetWindow.openclawSpoofObserver?.disconnect();
-        targetWindow.openclawSpoofObserver = new MutationObserver(recordSpoof);
-        targetWindow.openclawSpoofObserver.observe(valueNode, {
-          characterData: true,
-          childList: true,
-          subtree: true,
-        });
-        recordSpoof();
-      });
-      await page.evaluate(async () => {
-        await new Promise<void>((resolve) => {
-          const onMessage = (event: MessageEvent) => {
-            const data = event.data as { requestId?: string } | undefined;
-            if (event.source !== window || data?.requestId !== "x") {
-              return;
-            }
-            window.removeEventListener("message", onMessage);
-            resolve();
-          };
-          window.addEventListener("message", onMessage);
-          window.postMessage(
-            { v: 1, type: "workspace:data", requestId: "x", bindingId: "value", data: "SPOOFED" },
-            "*",
-          );
-        });
-      });
-      await frame.locator("#value").evaluate(async () => {
-        type WidgetBridge = {
-          postMessage: (message: unknown) => void;
-          addEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
-          removeEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
-        };
-        const bridge = (window as Window & { openclawWorkspaceBridge?: WidgetBridge })
-          .openclawWorkspaceBridge;
-        if (!bridge) {
-          throw new Error("workspace bridge unavailable");
-        }
-        await new Promise<void>((resolve) => {
-          const onMessage = (event: MessageEvent) => {
-            const data = event.data as { requestId?: string } | undefined;
-            if (data?.requestId !== "after-spoof") {
-              return;
-            }
-            bridge.removeEventListener("message", onMessage);
-            resolve();
-          };
-          bridge.addEventListener("message", onMessage);
-          const barrierRequest = {
-            v: 1,
-            type: "workspace:getData",
-            requestId: "after-spoof",
-            bindingId: "value",
-          };
-          // oxlint-disable-next-line unicorn/require-post-message-target-origin -- This is a MessagePort-style widget bridge, not Window.postMessage.
-          bridge.postMessage(barrierRequest);
-        });
-      });
-      const sawSpoofed = await frame.locator("#value").evaluate((node) => {
-        type SpoofObservationWindow = Window & {
-          openclawSawSpoofed?: boolean;
-          openclawSpoofObserver?: MutationObserver;
-        };
-        const targetWindow = window as SpoofObservationWindow;
-        targetWindow.openclawSpoofObserver?.disconnect();
-        return targetWindow.openclawSawSpoofed === true || node.textContent?.includes("SPOOFED");
-      });
-      expect(sawSpoofed).toBe(false);
-    } finally {
-      await page.context().close();
-    }
-  });
-
-  it("isolates a throwing widget to its own cell (kill test)", async () => {
-    const page = await newPage();
-    await routeWidgetAssets(page, THROWING_WIDGET_HTML);
-    await installMockGateway(page, {
-      ...workspaceGatewayScenario(),
-      methodResponses: {
-        ...frameMethodResponse(),
-        "workspaces.get": workspaceDoc(2, "approved"),
-      },
-    });
-    try {
-      await gotoWorkspaces(page, server);
-      // The host frame still mounts; the throw happens INSIDE the sandboxed iframe
-      // and cannot break the parent shell (the tab strip and cell stay present).
-      await page
-        .locator('[data-test-id="workspace-custom-widget-frame"]')
-        .waitFor({ timeout: 10_000 });
-      await page.locator('[data-test-id="workspace-widget"]').waitFor({ timeout: 10_000 });
-      // The parent SHELL survives the widget's throw: the workspace section and its
-      // tab strip remain rendered and interactive (the throw is contained to the
-      // opaque-origin iframe). We assert shell survival rather than the absence of a
-      // pageerror string, because a sandboxed frame's own uncaught error can surface
-      // on the parent as an opaque-origin SecurityError — which itself confirms the
-      // iframe is cross-origin/isolated, not that the shell broke.
-      await expect.poll(async () => page.locator('[data-test-id="workspace"]').count()).toBe(1);
-      await expect
-        .poll(async () => page.locator('[data-test-id="workspace-tab"]').count())
-        .toBeGreaterThan(0);
-      // No error leaked into the PARENT document body (the throw text stays inside
-      // the sandboxed frame, never rendered by the shell).
-      expect(await page.locator('[data-test-id="workspace"]').textContent()).not.toContain(
-        "widget boom",
-      );
-    } finally {
-      await page.context().close();
-    }
-  });
-});
diff --git a/ui/src/e2e/workspace-full-bleed.e2e.test.ts b/ui/src/e2e/workspace-full-bleed.e2e.test.ts
deleted file mode 100644
index 3319bd68a65..00000000000
--- a/ui/src/e2e/workspace-full-bleed.e2e.test.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import { chromium, type Browser, type Page } from "playwright";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  canRunPlaywrightChromium,
-  installMockGateway,
-  resolvePlaywrightChromiumExecutablePath,
-  startControlUiE2eServer,
-  type ControlUiE2eServer,
-} from "../test-helpers/control-ui-e2e.ts";
-
-const chromiumExecutablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
-const chromiumAvailable = canRunPlaywrightChromium(chromiumExecutablePath);
-const allowMissingChromium = process.env.OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM === "1";
-const describeControlUiE2e = chromiumAvailable || !allowMissingChromium ? describe : describe.skip;
-const proofDir = process.env.OPENCLAW_UI_E2E_ARTIFACT_DIR?.trim();
-const baselineOnly = process.env.OPENCLAW_UI_E2E_BASELINE === "1";
-
-let browser: Browser;
-let server: ControlUiE2eServer;
-
-function workspaceDoc() {
-  return {
-    doc: {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [
-        {
-          slug: "release-room",
-          title: "Release room",
-          hidden: false,
-          layout: baselineOnly ? "grid" : "full",
-          createdBy: "agent:main",
-          widgets: [
-            {
-              id: "release_room_app",
-              kind: "builtin:iframe-embed",
-              title: "Release room app",
-              grid: { x: 2, y: 0, w: 8, h: 6 },
-              collapsed: false,
-              createdBy: "agent:main",
-              props: { url: "/full-bleed-proof" },
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: {},
-      prefs: { tabOrder: ["release-room"] },
-    },
-    workspaceVersion: 1,
-  };
-}
-
-async function capture(page: Page, name: string): Promise<void> {
-  if (!proofDir) {
-    return;
-  }
-  await mkdir(proofDir, { recursive: true });
-  await page.screenshot({ fullPage: true, path: path.join(proofDir, name) });
-}
-
-describeControlUiE2e("Control UI full-bleed workspace tabs", () => {
-  beforeAll(async () => {
-    if (!chromiumAvailable) {
-      throw new Error(`Playwright Chromium is not available at ${chromiumExecutablePath}`);
-    }
-    server = await startControlUiE2eServer();
-    browser = await chromium.launch({ executablePath: chromiumExecutablePath });
-  });
-
-  afterAll(async () => {
-    await browser?.close();
-    await server?.close();
-  });
-
-  it("removes grid chrome and lets the single sandboxed app fill the tab", async () => {
-    const context = await browser.newContext({
-      locale: "en-US",
-      serviceWorkers: "block",
-      viewport: { height: 900, width: 1440 },
-    });
-    const page = await context.newPage();
-    await page.route("**/full-bleed-proof", (route) =>
-      route.fulfill({
-        contentType: "text/html",
-        body: `<!doctype html><style>
-          body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: #071a2b; color: #e8f4ff; font: 18px system-ui; }
-          main { width: min(760px, 80%); padding: 48px; border: 1px solid #3278a8; border-radius: 18px; background: #0d2942; }
-          h1 { margin-top: 0; color: #62d9ff; } .status { color: #8ce99a; }
-        </style><main><p class="status">All systems ready</p><h1>Release room</h1><p>One app. The whole workspace tab.</p></main>`,
-      }),
-    );
-    await installMockGateway(page, {
-      controlUiTabs: [
-        { pluginId: "workspaces", id: "workspaces", label: "Workspaces", group: "control" },
-      ],
-      featureMethods: ["workspaces.get"],
-      methodResponses: { "workspaces.get": workspaceDoc() },
-    });
-
-    try {
-      const response = await page.goto(`${server.baseUrl}plugin?plugin=workspaces&id=workspaces`);
-      expect(response?.status()).toBe(200);
-      await page.locator('[data-test-id="workspace-onboarding-dismiss"]').click();
-      const frame = page.locator('[data-test-id="workspace-embed-frame"]');
-      await frame.waitFor({ timeout: 10_000 });
-      expect(await frame.getAttribute("sandbox")).toBe("allow-scripts");
-
-      if (baselineOnly) {
-        expect(await page.locator('[data-test-id="workspace-grid"]').count()).toBe(1);
-        expect(await page.locator('[data-test-id="workspace-widget"]').count()).toBe(1);
-        await capture(page, "workspace-full-bleed-before.png");
-        return;
-      }
-
-      const fullBleed = page.locator('[data-test-id="workspace-fullbleed"]');
-      await fullBleed.waitFor();
-      expect(await page.locator('[data-test-id="workspace-grid"]').count()).toBe(0);
-      expect(await page.locator('[data-test-id="workspace-widget"]').count()).toBe(0);
-      const [containerBox, frameBox] = await Promise.all([
-        fullBleed.boundingBox(),
-        frame.boundingBox(),
-      ]);
-      expect(containerBox).not.toBeNull();
-      expect(frameBox).not.toBeNull();
-      expect(Math.abs(frameBox!.width - containerBox!.width)).toBeLessThan(2);
-      expect(Math.abs(frameBox!.height - containerBox!.height)).toBeLessThan(2);
-      expect(frameBox!.height).toBeGreaterThanOrEqual(480);
-      await capture(page, "workspace-full-bleed-after.png");
-    } finally {
-      await context.close();
-    }
-  });
-});
diff --git a/ui/src/e2e/workspace-operations.e2e.test.ts b/ui/src/e2e/workspace-operations.e2e.test.ts
deleted file mode 100644
index 3bf743d80d5..00000000000
--- a/ui/src/e2e/workspace-operations.e2e.test.ts
+++ /dev/null
@@ -1,193 +0,0 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import { chromium, type Browser, type Page } from "playwright";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  canRunPlaywrightChromium,
-  installMockGateway,
-  resolvePlaywrightChromiumExecutablePath,
-  startControlUiE2eServer,
-  type ControlUiE2eServer,
-} from "../test-helpers/control-ui-e2e.ts";
-
-const chromiumExecutablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
-const chromiumAvailable = canRunPlaywrightChromium(chromiumExecutablePath);
-const allowMissingChromium = process.env.OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM === "1";
-const describeControlUiE2e = chromiumAvailable || !allowMissingChromium ? describe : describe.skip;
-const proofDir = process.env.OPENCLAW_UI_E2E_ARTIFACT_DIR?.trim();
-const baselineOnly = process.env.OPENCLAW_UI_E2E_BASELINE === "1";
-
-let browser: Browser;
-let server: ControlUiE2eServer;
-
-function workspaceDoc(
-  workspaceVersion = 1,
-  pending: readonly string[] = ["sales-map", "unsafe-card"],
-) {
-  return {
-    doc: {
-      schemaVersion: 1,
-      workspaceVersion,
-      tabs: [
-        {
-          slug: "operations",
-          title: "Operations",
-          hidden: false,
-          createdBy: "agent:main",
-          widgets: [
-            {
-              id: "agent_status",
-              kind: "builtin:agent-status",
-              title: "Agent status",
-              grid: { x: 0, y: 0, w: 7, h: 4 },
-              collapsed: false,
-              createdBy: "agent:main",
-              bindings: { value: { source: "rpc", method: "sessions.list" } },
-            },
-            {
-              id: "custom_widget_approvals",
-              kind: "builtin:custom-widget-approvals",
-              title: "Pending custom widgets",
-              grid: { x: 7, y: 0, w: 5, h: 4 },
-              collapsed: false,
-              createdBy: "agent:main",
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: Object.fromEntries(
-        pending.map((name) => [
-          name,
-          {
-            status: "pending",
-            createdBy: name === "sales-map" ? "agent:sales" : "agent:security",
-          },
-        ]),
-      ),
-      prefs: { tabOrder: ["operations"] },
-    },
-    workspaceVersion,
-  };
-}
-
-function sessions(active: boolean) {
-  return {
-    count: 2,
-    sessions: [
-      {
-        key: "agent:main:main",
-        displayName: "Release coordinator",
-        hasActiveRun: active,
-        goal: active
-          ? { objective: "Validate workspace operations", tokensUsed: 72, tokenBudget: 100 }
-          : undefined,
-      },
-      { key: "agent:reviewer:main", displayName: "Review agent", hasActiveRun: false },
-    ],
-  };
-}
-
-async function capture(page: Page, name: string): Promise<void> {
-  if (!proofDir) {
-    return;
-  }
-  await mkdir(proofDir, { recursive: true });
-  await page.screenshot({ fullPage: true, path: path.join(proofDir, name) });
-}
-
-describeControlUiE2e("Control UI workspace operations widgets", () => {
-  beforeAll(async () => {
-    if (!chromiumAvailable) {
-      throw new Error(`Playwright Chromium is not available at ${chromiumExecutablePath}`);
-    }
-    server = await startControlUiE2eServer();
-    browser = await chromium.launch({ executablePath: chromiumExecutablePath });
-  });
-
-  afterAll(async () => {
-    await browser?.close();
-    await server?.close();
-  });
-
-  it("refreshes live status and completes the bounded custom-widget approval flow", async () => {
-    const context = await browser.newContext({
-      locale: "en-US",
-      serviceWorkers: "block",
-      viewport: { height: 900, width: 1440 },
-    });
-    const page = await context.newPage();
-    const gateway = await installMockGateway(page, {
-      controlUiTabs: [
-        { pluginId: "workspaces", id: "workspaces", label: "Workspaces", group: "control" },
-      ],
-      featureMethods: [
-        "sessions.list",
-        "sessions.subscribe",
-        "workspaces.get",
-        "workspaces.widget.approve",
-      ],
-      methodResponses: {
-        "sessions.list": sessions(false),
-        "sessions.subscribe": { ok: true },
-        "workspaces.get": workspaceDoc(),
-        "workspaces.widget.approve": { ok: true },
-      },
-    });
-
-    try {
-      const response = await page.goto(`${server.baseUrl}plugin?plugin=workspaces&id=workspaces`);
-      expect(response?.status()).toBe(200);
-      await page.locator('[data-test-id="workspace-onboarding-dismiss"]').click();
-      await page.locator('[data-test-id="workspace-grid"]').waitFor({ timeout: 10_000 });
-      if (baselineOnly) {
-        await capture(page, "workspace-operations-before.png");
-        return;
-      }
-
-      const status = page.locator('[data-test-id="workspace-agent-status"]');
-      const decisions = page.locator('[data-test-id="workspace-custom-widget-approvals"]');
-      await status.waitFor({ timeout: 10_000 });
-      await decisions.waitFor({ timeout: 10_000 });
-
-      expect(await status.textContent()).toContain("Idle");
-      expect(await decisions.locator("li").count()).toBe(2);
-
-      await gateway.setMethodResponse("sessions.list", sessions(true));
-      const statusRequests = (await gateway.getRequests("sessions.list")).length;
-      await gateway.emitGatewayEvent("sessions.changed", {
-        key: "agent:main:main",
-        hasActiveRun: true,
-        status: "running",
-      });
-      await expect
-        .poll(async () => (await gateway.getRequests("sessions.list")).length)
-        .toBeGreaterThan(statusRequests);
-      await expect.poll(() => status.textContent()).toContain("Busy");
-      await capture(page, "workspace-operations-live-and-pending.png");
-
-      const salesRow = decisions.locator("li", { hasText: "sales-map" });
-      await salesRow.locator('[data-test-id="workspace-custom-widget-approve"]').click();
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.widget.approve")).at(-1)?.params)
-        .toEqual({ name: "sales-map", decision: "approved" });
-      await gateway.setMethodResponse("workspaces.get", workspaceDoc(2, ["unsafe-card"]));
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 2 });
-      await expect.poll(() => decisions.locator("li").count()).toBe(1);
-
-      const unsafeRow = decisions.locator("li", { hasText: "unsafe-card" });
-      await unsafeRow.locator('[data-test-id="workspace-custom-widget-reject"]').click();
-      await expect
-        .poll(async () => (await gateway.getRequests("workspaces.widget.approve")).at(-1)?.params)
-        .toEqual({ name: "unsafe-card", decision: "rejected" });
-      await gateway.setMethodResponse("workspaces.get", workspaceDoc(3, []));
-      await gateway.emitGatewayEvent("plugin.workspaces.changed", { workspaceVersion: 3 });
-      await expect.poll(() => decisions.count()).toBe(0);
-      await expect
-        .poll(() => page.locator('[data-widget-id="custom_widget_approvals"]').textContent())
-        .toContain("No custom widgets are awaiting approval");
-      await capture(page, "workspace-operations-decisions-complete.png");
-    } finally {
-      await context.close();
-    }
-  });
-});
diff --git a/ui/src/e2e/workspace-preview.e2e.test.ts b/ui/src/e2e/workspace-preview.e2e.test.ts
deleted file mode 100644
index d302ed1d761..00000000000
--- a/ui/src/e2e/workspace-preview.e2e.test.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import { chromium, type Browser, type Page } from "playwright";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  canRunPlaywrightChromium,
-  installMockGateway,
-  resolvePlaywrightChromiumExecutablePath,
-  startControlUiE2eServer,
-  type ControlUiE2eServer,
-} from "../test-helpers/control-ui-e2e.ts";
-
-const chromiumExecutablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
-const chromiumAvailable = canRunPlaywrightChromium(chromiumExecutablePath);
-const allowMissingChromium = process.env.OPENCLAW_UI_E2E_ALLOW_MISSING_CHROMIUM === "1";
-const describeControlUiE2e = chromiumAvailable || !allowMissingChromium ? describe : describe.skip;
-const proofDir = process.env.OPENCLAW_UI_E2E_ARTIFACT_DIR?.trim();
-
-let browser: Browser;
-let server: ControlUiE2eServer;
-
-function workspaceDoc() {
-  return {
-    doc: {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [
-        {
-          slug: "previews",
-          title: "Secure previews",
-          hidden: false,
-          createdBy: "agent:main",
-          widgets: [
-            {
-              id: "preview_allowed",
-              kind: "builtin:preview",
-              title: "Local app preview",
-              grid: { x: 0, y: 0, w: 8, h: 5 },
-              collapsed: false,
-              createdBy: "agent:main",
-              props: { url: "/stale", defaultViewport: "desktop" },
-              bindings: { value: { source: "static", value: "/preview-proof" } },
-            },
-            {
-              id: "preview_blocked",
-              kind: "builtin:preview",
-              title: "Blocked external preview",
-              grid: { x: 8, y: 0, w: 4, h: 5 },
-              collapsed: false,
-              createdBy: "agent:main",
-              props: { url: "https://blocked.example" },
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: {},
-      prefs: { tabOrder: ["previews"] },
-    },
-    workspaceVersion: 1,
-  };
-}
-
-async function capture(page: Page, name: string): Promise<void> {
-  if (!proofDir) {
-    return;
-  }
-  await mkdir(proofDir, { recursive: true });
-  await page.screenshot({ fullPage: true, path: path.join(proofDir, name) });
-}
-
-describeControlUiE2e("Control UI secure preview widget", () => {
-  beforeAll(async () => {
-    if (!chromiumAvailable) {
-      throw new Error(`Playwright Chromium is not available at ${chromiumExecutablePath}`);
-    }
-    server = await startControlUiE2eServer();
-    browser = await chromium.launch({ executablePath: chromiumExecutablePath });
-  });
-
-  afterAll(async () => {
-    await browser?.close();
-    await server?.close();
-  });
-
-  it("renders an allowed bound origin, blocks an external origin, and preserves controls", async () => {
-    const context = await browser.newContext({
-      locale: "en-US",
-      serviceWorkers: "block",
-      viewport: { height: 900, width: 1440 },
-    });
-    const page = await context.newPage();
-    let previewRequests = 0;
-    await page.route("**/preview-proof", async (route) => {
-      previewRequests += 1;
-      await route.fulfill({
-        contentType: "text/html",
-        body: `<!doctype html><style>body{margin:0;font:24px system-ui;background:#13293d;color:#fff;display:grid;place-items:center;height:100vh}strong{color:#62d9ff}</style><p><strong>Allowed</strong> same-origin preview</p>`,
-      });
-    });
-    await installMockGateway(page, {
-      controlUiTabs: [
-        {
-          pluginId: "workspaces",
-          id: "workspaces",
-          label: "Workspaces",
-          group: "control",
-        },
-      ],
-      featureMethods: ["workspaces.get"],
-      methodResponses: { "workspaces.get": workspaceDoc() },
-    });
-
-    try {
-      const response = await page.goto(`${server.baseUrl}plugin?plugin=workspaces&id=workspaces`);
-      expect(response?.status()).toBe(200);
-      const allowed = page.locator('[data-widget-id="preview_allowed"]');
-      const blocked = page.locator('[data-widget-id="preview_blocked"]');
-      const frame = allowed.locator('[data-test-id="workspace-preview-frame"]');
-      await frame.waitFor({ timeout: 10_000 });
-      await blocked.locator('[data-test-id="workspace-preview-blocked"]').waitFor();
-      expect(await frame.getAttribute("src")).toBe("/preview-proof");
-      expect(await frame.getAttribute("sandbox")).toBe("allow-scripts");
-      expect(await frame.getAttribute("sandbox")).not.toContain("allow-same-origin");
-      expect(await blocked.locator('[data-test-id="workspace-preview-frame"]').count()).toBe(0);
-      await expect.poll(() => previewRequests).toBeGreaterThan(0);
-      await capture(page, "workspace-preview-allowed-and-blocked.png");
-
-      await allowed.locator('[data-test-id="workspace-preview-viewport-mobile"]').click();
-      await expect
-        .poll(() => allowed.locator(".workspace-preview__frame-wrap--mobile").count())
-        .toBe(1);
-      expect(
-        await allowed
-          .locator('[data-test-id="workspace-preview-viewport-mobile"]')
-          .getAttribute("aria-pressed"),
-      ).toBe("true");
-      await capture(page, "workspace-preview-mobile.png");
-
-      const requestsBeforeReload = previewRequests;
-      await allowed.locator('[data-test-id="workspace-preview-reload"]').click();
-      await expect.poll(() => previewRequests).toBeGreaterThan(requestsBeforeReload);
-      expect(await allowed.locator(".workspace-preview__frame-wrap--mobile").count()).toBe(1);
-    } finally {
-      await context.close();
-    }
-  });
-});
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 7a200d992e2..9ee2c5d456e 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -2430,133 +2430,6 @@ export const en: TranslationMap = {
       submit: "Ask",
     },
   },
-  workspaces: {
-    tabs: {
-      label: "Workspaces",
-      hidden: "Hidden ({count})",
-    },
-    error: {
-      title: "Couldn't load your workspaces",
-      subtitle: "Something went wrong loading your workspaces. Try reloading.",
-      detailSummary: "Show details",
-    },
-    header: {
-      subtitle: "Arrange widgets and tabs for this workspace.",
-    },
-    onboarding: {
-      title: "Build your first workspace tab",
-      primary: "Ask your agent to build a tab.",
-      secondary: "Or create one from the command line:",
-    },
-    empty: {
-      onboardingTitle: "No workspaces yet",
-      onboardingSubtitle:
-        "Ask your agent to build a workspace, or create one from the command line.",
-      onboardingCommand: "openclaw workspaces tabs create --title Main",
-      tabTitle: "This workspace is empty",
-      tabSubtitle: "Ask your agent to add a widget, or add one yourself.",
-      noVisibleTabs: "Every workspace tab is hidden. Restore one from the hidden menu.",
-    },
-    widget: {
-      collapse: "Collapse widget",
-      expand: "Expand widget",
-      moveHandle: "Move widget",
-      resizeHandle: "Resize widget",
-      menuLabel: "Widget options",
-      provenanceChip: "AI",
-      provenanceTooltip: "Built by {agent}",
-      errorTitle: "This widget couldn't load",
-      errorHumane: "This widget ran into a problem while rendering.",
-      errorDetailSummary: "Show details",
-      customPlaceholder: "Custom widget — coming soon.",
-      customLoading: "Loading custom widget…",
-      approval: {
-        title: "Custom widget awaiting approval",
-        byAgent: "Built by {agent}",
-        byUnknown: "Built by an unknown agent",
-        approve: "Approve",
-        reject: "Reject",
-        unavailable:
-          "This custom widget isn't available. Ask your agent to rebuild it, or remove it.",
-      },
-      markdownEmpty: "No content yet.",
-      unknownKind: "Unknown widget type: {kind}",
-      editTitleTitle: "Edit widget title",
-      editTitleLabel: "Widget title",
-      moveToTabTitle: "Move to tab",
-      moveToTabEmpty: "There are no other tabs to move this widget to.",
-      menu: {
-        editTitle: "Edit title",
-        moveToTab: "Move to tab…",
-        hide: "Hide",
-        remove: "Remove",
-      },
-      stat: {
-        empty: "—",
-      },
-      table: {
-        empty: "No rows to show.",
-        more: "+{count} more",
-      },
-      chart: {
-        empty: "No data to chart.",
-        invalid: "This chart has invalid data or options.",
-        label: "Chart",
-        summary: "{title}: {count} data points, ranging from {min} to {max}.",
-      },
-      sessions: {
-        empty: "No sessions yet.",
-      },
-      agentStatus: {
-        empty: "No agents or sessions yet.",
-        busy: "Busy",
-        idle: "Idle",
-        progress: "{percent}% complete",
-      },
-      customWidgetApprovals: {
-        empty: "No custom widgets are awaiting approval.",
-        kind: "Custom widget",
-        requestedBy: "Requested by {agent}",
-        approve: "Approve",
-        reject: "Reject",
-        permissionRequired: "Approval permission required",
-      },
-      usage: {
-        cost: "Cost",
-        tokens: "Tokens",
-      },
-      cron: {
-        empty: "No scheduled jobs.",
-        next: "Next {time}",
-        noNext: "Not scheduled",
-      },
-      instances: {
-        empty: "No connected instances.",
-        idle: "Idle for {duration}",
-      },
-      activity: {
-        empty: "No recent activity.",
-      },
-      embed: {
-        missing: "This embed has no URL yet.",
-        blockedExternal: "External embeds are disabled by your gateway policy.",
-        blockedScheme: "This embed URL uses an unsupported scheme.",
-      },
-      preview: {
-        missing: "This preview has no URL yet.",
-        blockedExternal: "External previews are disabled by your gateway policy.",
-        blockedScheme: "This preview URL uses an unsupported scheme.",
-        toolbar: "Preview controls",
-        reload: "Reload preview",
-        viewport: {
-          label: "Preview viewport",
-          desktop: "Desktop",
-          tablet: "Tablet",
-          mobile: "Mobile",
-        },
-      },
-    },
-  },
   workboard: {
     disabledHelpStart: "Workboard is disabled. Enable",
     enableConfigKey: "plugins.entries.workboard.enabled = true",
diff --git a/ui/src/lib/workspace/approval-state.ts b/ui/src/lib/workspace/approval-state.ts
deleted file mode 100644
index 760270fc193..00000000000
--- a/ui/src/lib/workspace/approval-state.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import type { WorkspaceDocument } from "./types.ts";
-
-/** Unlock decisions only after the canonical registry confirms their transition. */
-export function reconcilePendingApprovalNames(
-  pendingNames: Set<string>,
-  workspace: WorkspaceDocument,
-): void {
-  for (const name of pendingNames) {
-    if (workspace.widgetsRegistry[name]?.status !== "pending") {
-      pendingNames.delete(name);
-    }
-  }
-}
diff --git a/ui/src/lib/workspace/bridge.test.ts b/ui/src/lib/workspace/bridge.test.ts
deleted file mode 100644
index 6cde2ee89c2..00000000000
--- a/ui/src/lib/workspace/bridge.test.ts
+++ /dev/null
@@ -1,363 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { createWidgetBridge, type WidgetOutboundMessage } from "./bridge.ts";
-import type { WidgetManifestView } from "./types.ts";
-
-type WidgetBridgeDeps = Parameters<typeof createWidgetBridge>[0];
-
-let testWidgetSequence = 0;
-
-function waitForWidgetBridge(assertion: () => void) {
-  return vi.waitFor(assertion, { interval: 1 });
-}
-
-beforeEach(() => {
-  testWidgetSequence += 1;
-});
-
-function manifest(overrides?: Partial<WidgetManifestView>): WidgetManifestView {
-  return {
-    name: `revenue-chart-${testWidgetSequence}`,
-    frameToken: "11111111-1111-4111-8111-111111111111",
-    entrypoint: "index.html",
-    bindings: { value: { source: "static", value: null } },
-    capabilities: ["data:read"],
-    ...overrides,
-  };
-}
-
-function makeBridge(overrides?: Partial<WidgetBridgeDeps>) {
-  const posted: WidgetOutboundMessage[] = [];
-  const deps: WidgetBridgeDeps = {
-    manifest: manifest(),
-    resolveBinding: async () => ({ ok: true }),
-    resolveTheme: () => ({ "--accent": "#ff0000" }),
-    confirmPrompt: async () => true,
-    sendPrompt: async () => undefined,
-    post: (message) => posted.push(message),
-    ...overrides,
-  };
-  return { bridge: createWidgetBridge(deps), posted };
-}
-
-describe("createWidgetBridge accept filter", () => {
-  it("drops malformed messages and counts them", () => {
-    const { bridge } = makeBridge();
-    expect(bridge.handleMessage({ v: 2, type: "workspace:ready" })).toBe(false);
-    expect(bridge.handleMessage({ type: "workspace:getData" })).toBe(false);
-    expect(bridge.handleMessage("garbage")).toBe(false);
-    expect(bridge.droppedCount).toBe(3);
-  });
-
-  it("accepts a ready handshake", () => {
-    const { bridge } = makeBridge();
-    expect(bridge.handleMessage({ v: 1, type: "workspace:ready" })).toBe(true);
-    expect(bridge.droppedCount).toBe(0);
-  });
-});
-
-describe("getData binding gating", () => {
-  it("denies data access when data:read was not approved", async () => {
-    const resolveBinding = vi.fn(async () => ({ ok: true }));
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: [] }),
-      resolveBinding,
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:getData", requestId: "r1", bindingId: "value" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({ type: "workspace:error", code: "capability_denied" });
-    expect(resolveBinding).not.toHaveBeenCalled();
-  });
-
-  it("resolves a declared binding and posts data", async () => {
-    const { bridge, posted } = makeBridge({ resolveBinding: async () => ({ revenue: 42 }) });
-    bridge.handleMessage({ v: 1, type: "workspace:getData", requestId: "r1", bindingId: "value" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toEqual({
-      v: 1,
-      type: "workspace:data",
-      requestId: "r1",
-      bindingId: "value",
-      data: { revenue: 42 },
-    });
-  });
-
-  it("denies an undeclared binding with binding_denied and never calls the resolver", async () => {
-    const resolveBinding = vi.fn(async () => ({ ok: true }));
-    const { bridge, posted } = makeBridge({ resolveBinding });
-    bridge.handleMessage({ v: 1, type: "workspace:getData", requestId: "r1", bindingId: "secret" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({
-      type: "workspace:error",
-      code: "binding_denied",
-      requestId: "r1",
-    });
-    expect(resolveBinding).not.toHaveBeenCalled();
-  });
-
-  it("posts a timeout error when the resolver overruns getDataTimeoutMs", async () => {
-    vi.useFakeTimers();
-    try {
-      const { bridge, posted } = makeBridge({
-        getDataTimeoutMs: 10_000,
-        resolveBinding: () => new Promise(() => {}),
-      });
-      bridge.handleMessage({
-        v: 1,
-        type: "workspace:getData",
-        requestId: "r1",
-        bindingId: "value",
-      });
-      await vi.advanceTimersByTimeAsync(10_001);
-      expect(posted[0]).toMatchObject({
-        type: "workspace:error",
-        code: "timeout",
-        requestId: "r1",
-      });
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});
-
-describe("getTheme", () => {
-  it("returns the theme tokens", () => {
-    const { bridge, posted } = makeBridge({ resolveTheme: () => ({ "--bg": "#000" }) });
-    bridge.handleMessage({ v: 1, type: "workspace:getTheme", requestId: "t1" });
-    expect(posted[0]).toEqual({
-      v: 1,
-      type: "workspace:theme",
-      requestId: "t1",
-      tokens: { "--bg": "#000" },
-    });
-  });
-});
-
-describe("sendPrompt capability + confirm + rate limit", () => {
-  it("denies without a dialog when the capability is absent", async () => {
-    const confirmPrompt = vi.fn(async () => true);
-    const sendPrompt = vi.fn(async () => undefined);
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: ["data:read"] }),
-      confirmPrompt,
-      sendPrompt,
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p1", text: "hi" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({ type: "workspace:error", code: "capability_denied" });
-    expect(confirmPrompt).not.toHaveBeenCalled();
-    expect(sendPrompt).not.toHaveBeenCalled();
-  });
-
-  it("shows the dialog and sends nothing when the operator declines", async () => {
-    const sendPrompt = vi.fn(async () => undefined);
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: ["data:read", "prompt:send"] }),
-      confirmPrompt: async () => false,
-      sendPrompt,
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p1", text: "hi" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({ type: "workspace:error", code: "prompt_declined" });
-    expect(sendPrompt).not.toHaveBeenCalled();
-  });
-
-  it("sends exactly once when the operator confirms", async () => {
-    const sendPrompt = vi.fn(async () => undefined);
-    const confirmPrompt = vi.fn(async () => true);
-    const { bridge } = makeBridge({
-      manifest: manifest({ capabilities: ["prompt:send"] }),
-      confirmPrompt,
-      sendPrompt,
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p1", text: "do it" });
-    await waitForWidgetBridge(() => expect(sendPrompt).toHaveBeenCalledTimes(1));
-    expect(confirmPrompt).toHaveBeenCalledWith("do it");
-    expect(sendPrompt).toHaveBeenCalledWith("do it");
-  });
-
-  it("rate-limits to at most one in-flight prompt", async () => {
-    let resolveConfirm!: (ok: boolean) => void;
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: ["prompt:send"] }),
-      confirmPrompt: () =>
-        new Promise<boolean>((resolve) => {
-          resolveConfirm = resolve;
-        }),
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p1", text: "one" });
-    // Second request while the first confirm is still pending → rate_limited.
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p2", text: "two" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({
-      type: "workspace:error",
-      code: "rate_limited",
-      requestId: "p2",
-    });
-    resolveConfirm(false);
-  });
-
-  it("rate-limits to 10 sends per minute", async () => {
-    const clock = 0;
-    let sent = 0;
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: ["prompt:send"] }),
-      confirmPrompt: async () => true,
-      sendPrompt: async () => {
-        sent += 1;
-      },
-      now: () => clock,
-    });
-    // Fire sequentially, awaiting each send so `promptInFlight` clears before the
-    // next (the in-flight limit is exercised by a separate test).
-    for (let i = 0; i < 10; i += 1) {
-      bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: `p${i}`, text: "x" });
-      await waitForWidgetBridge(() => expect(sent).toBe(i + 1));
-    }
-    expect(posted).toHaveLength(0);
-    // The 11th within the same rolling minute is rejected.
-    bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "p10", text: "x" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({ type: "workspace:error", code: "rate_limited" });
-    expect(sent).toBe(10);
-  });
-});
-
-describe("push", () => {
-  it("posts a push for a declared binding", async () => {
-    const { bridge, posted } = makeBridge({ resolveBinding: async () => 7 });
-    await bridge.push("value");
-    expect(posted[0]).toEqual({ v: 1, type: "workspace:push", bindingId: "value", data: 7 });
-  });
-
-  it("ignores a push for an undeclared binding", async () => {
-    const { bridge, posted } = makeBridge();
-    await bridge.push("secret");
-    expect(posted).toHaveLength(0);
-  });
-
-  it("ignores a push when data:read was not approved", async () => {
-    const resolveBinding = vi.fn(async () => 7);
-    const { bridge, posted } = makeBridge({
-      manifest: manifest({ capabilities: [] }),
-      resolveBinding,
-    });
-    await bridge.push("value");
-    expect(posted).toHaveLength(0);
-    expect(resolveBinding).not.toHaveBeenCalled();
-  });
-});
-
-describe("dispose", () => {
-  it("stops handling messages after dispose", () => {
-    const { bridge } = makeBridge();
-    bridge.dispose();
-    expect(bridge.handleMessage({ v: 1, type: "workspace:ready" })).toBe(false);
-  });
-});
-
-describe("rate-limit state persists across bridge re-instantiation (remount)", () => {
-  // Exhaust the per-minute budget on one bridge, then dispose + recreate a fresh
-  // bridge for the SAME widget name (simulating an iframe remount) and assert the
-  // budget did NOT reset — the next send is still rate_limited within the window.
-  it("keeps the budget for the same widget name after dispose + recreate", async () => {
-    const clock = 1_000_000;
-    let sent = 0;
-    const makeNamed = () => {
-      const posted: WidgetOutboundMessage[] = [];
-      const bridge = createWidgetBridge({
-        manifest: manifest({ name: "remount-widget", capabilities: ["prompt:send"] }),
-        resolveBinding: async () => null,
-        resolveTheme: () => ({}),
-        confirmPrompt: async () => true,
-        sendPrompt: async () => {
-          sent += 1;
-        },
-        post: (message) => posted.push(message),
-        now: () => clock,
-      });
-      return { bridge, posted };
-    };
-
-    const first = makeNamed();
-    for (let i = 0; i < 10; i += 1) {
-      first.bridge.handleMessage({
-        v: 1,
-        type: "workspace:sendPrompt",
-        requestId: `a${i}`,
-        text: "x",
-      });
-      await waitForWidgetBridge(() => expect(sent).toBe(i + 1));
-    }
-    // Remount: dispose the exhausted bridge and build a fresh one for the same name.
-    first.bridge.dispose();
-    const second = makeNamed();
-    second.bridge.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "b0", text: "x" });
-    await waitForWidgetBridge(() => expect(second.posted).toHaveLength(1));
-    // Budget survived the remount → still rate_limited, no extra send.
-    expect(second.posted[0]).toMatchObject({ type: "workspace:error", code: "rate_limited" });
-    expect(sent).toBe(10);
-  });
-
-  it("gives a DIFFERENT widget name its own independent budget", async () => {
-    const clock = 2_000_000;
-    let sentA = 0;
-    let sentB = 0;
-    const bridgeA = createWidgetBridge({
-      manifest: manifest({ name: "widget-a", capabilities: ["prompt:send"] }),
-      resolveBinding: async () => null,
-      resolveTheme: () => ({}),
-      confirmPrompt: async () => true,
-      sendPrompt: async () => {
-        sentA += 1;
-      },
-      post: () => {},
-      now: () => clock,
-    });
-    const postedB: WidgetOutboundMessage[] = [];
-    const bridgeB = createWidgetBridge({
-      manifest: manifest({ name: "widget-b", capabilities: ["prompt:send"] }),
-      resolveBinding: async () => null,
-      resolveTheme: () => ({}),
-      confirmPrompt: async () => true,
-      sendPrompt: async () => {
-        sentB += 1;
-      },
-      post: (message) => postedB.push(message),
-      now: () => clock,
-    });
-    // Exhaust widget-a's budget.
-    for (let i = 0; i < 10; i += 1) {
-      bridgeA.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: `a${i}`, text: "x" });
-      await waitForWidgetBridge(() => expect(sentA).toBe(i + 1));
-    }
-    // widget-b is unaffected — its first send succeeds.
-    bridgeB.handleMessage({ v: 1, type: "workspace:sendPrompt", requestId: "b0", text: "x" });
-    await waitForWidgetBridge(() => expect(sentB).toBe(1));
-    expect(postedB).toHaveLength(0);
-  });
-});
-
-describe("resolve-time binding re-check", () => {
-  it("does not push a binding the gate denies (never calls resolveBinding)", async () => {
-    const resolveBinding = vi.fn(async () => 1);
-    const { bridge, posted } = makeBridge({
-      resolveBinding,
-      assertBindingAllowed: () => "binding_denied",
-    });
-    await bridge.push("value");
-    expect(posted).toHaveLength(0);
-    expect(resolveBinding).not.toHaveBeenCalled();
-  });
-
-  it("allows a getData when the gate returns null", async () => {
-    const resolveBinding = vi.fn(async () => 42);
-    const { bridge, posted } = makeBridge({
-      resolveBinding,
-      assertBindingAllowed: () => null,
-    });
-    bridge.handleMessage({ v: 1, type: "workspace:getData", requestId: "r1", bindingId: "value" });
-    await waitForWidgetBridge(() => expect(posted).toHaveLength(1));
-    expect(posted[0]).toMatchObject({ type: "workspace:data", data: 42 });
-    expect(resolveBinding).toHaveBeenCalledOnce();
-  });
-});
diff --git a/ui/src/lib/workspace/bridge.ts b/ui/src/lib/workspace/bridge.ts
deleted file mode 100644
index 93b81c56b8e..00000000000
--- a/ui/src/lib/workspace/bridge.ts
+++ /dev/null
@@ -1,326 +0,0 @@
-// Parent side of the custom-widget postMessage bridge (00 §6, spec-50 §Bridge).
-//
-// DOM-free and unit-testable: the browser host (`workspace-custom-widget.ts`)
-// wires a real iframe + window listener to `createWidgetBridge`, but every
-// security decision — accept filter, manifest gating, capability checks, rate
-// limiting, timeouts — lives here so it can be tested without a DOM.
-//
-// SECURITY MODEL (normative):
-// - The child's origin is opaque (`null`) because the iframe is sandboxed without
-//   `allow-same-origin`. The host accepts one token-bound bootstrap from the
-//   iframe, then all traffic uses that document's MessagePort. Navigation loses
-//   the port, unlike the iframe's stable WindowProxy.
-// - A widget may only request bindings declared in the manifest the operator
-//   approved. Undeclared bindingId → `workspace:error {code:"binding_denied"}`.
-// - `sendPrompt` requires the manifest `prompt:send` capability AND an operator
-//   confirm per invocation AND a rate limit (1 in-flight, 10/min).
-// - Parent→child posts always use targetOrigin "*" (opaque origin), carrying only
-//   binding data / theme tokens the widget is entitled to — never secrets.
-
-import { isRecord } from "@openclaw/normalization-core/record-coerce";
-import type { WidgetManifestView } from "./types.ts";
-
-const BRIDGE_ENVELOPE_VERSION = 1;
-
-/** child→parent message types. */
-type WidgetInboundType =
-  | "workspace:ready"
-  | "workspace:getData"
-  | "workspace:getTheme"
-  | "workspace:sendPrompt";
-
-type WidgetErrorCode =
-  | "binding_denied"
-  | "capability_denied"
-  | "rate_limited"
-  | "prompt_declined"
-  | "timeout"
-  | "resolve_failed"
-  | "malformed";
-
-export type WidgetOutboundMessage =
-  | { v: 1; type: "workspace:data"; requestId: string; bindingId: string; data: unknown }
-  | { v: 1; type: "workspace:push"; bindingId: string; data: unknown }
-  | { v: 1; type: "workspace:theme"; requestId: string; tokens: Record<string, string> }
-  | { v: 1; type: "workspace:error"; requestId?: string; code: WidgetErrorCode; message: string };
-
-/** Injected side effects — real implementations live in the browser host. */
-type WidgetBridgeDeps = {
-  manifest: WidgetManifestView;
-  /** Resolve a manifest-declared binding by id. */
-  resolveBinding: (bindingId: string) => Promise<unknown>;
-  /**
-   * Resolve-time gate run BEFORE `resolveBinding`. Return a WidgetErrorCode to
-   * deny without resolving the binding, or null to allow. Optional; when omitted,
-   * every declared binding is allowed to resolve.
-   */
-  assertBindingAllowed?: (bindingId: string) => WidgetErrorCode | null;
-  /** Current theme tokens (CSS custom-property values from the document root). */
-  resolveTheme: () => Record<string, string>;
-  /** Operator confirm dialog quoting the exact prompt text; resolves true to send. */
-  confirmPrompt: (text: string) => Promise<boolean>;
-  /** Dispatch the prompt through the existing chat-send path. */
-  sendPrompt: (text: string) => Promise<void>;
-  /** Post a message to the child (host wires targetOrigin "*"). */
-  post: (message: WidgetOutboundMessage) => void;
-  /** getData answer deadline; posts a timeout error if the resolver overruns. Default 10s. */
-  getDataTimeoutMs?: number;
-  /** Injectable clock for tests. */
-  now?: () => number;
-};
-
-export type WidgetBridge = {
-  /** Handle one already-source-verified inbound message. Returns true if accepted. */
-  handleMessage: (data: unknown) => boolean;
-  /** Push fresh data for a declared binding to the child (broadcast-driven). */
-  push: (bindingId: string) => Promise<void>;
-  /** Count of messages dropped by the accept filter (well-formedness). For tests. */
-  readonly droppedCount: number;
-  dispose: () => void;
-};
-
-const DEFAULT_GET_DATA_TIMEOUT_MS = 10_000;
-const PROMPT_RATE_WINDOW_MS = 60_000;
-const PROMPT_RATE_MAX = 10;
-
-/**
- * sendPrompt rate-limit state, keyed by STABLE widget identity (the custom widget
- * name), NOT the iframe/bridge instance. The lit host recreates the iframe (and a
- * fresh bridge) on layout drag / tab switch / widget re-add, so per-closure state
- * would let a widget reset its "10/min + 1 in-flight" cap simply by triggering a
- * remount. Persisting this at module scope keyed by name closes that hole: the
- * rolling window survives bridge re-instantiation. Each distinct widget name has
- * its own independent budget.
- */
-type PromptRateState = { timestamps: number[]; inFlight: boolean };
-const promptRateStates = new Map<string, PromptRateState>();
-
-function getPromptRateState(widgetName: string): PromptRateState {
-  let state = promptRateStates.get(widgetName);
-  if (!state) {
-    state = { timestamps: [], inFlight: false };
-    promptRateStates.set(widgetName, state);
-  }
-  return state;
-}
-
-/** Test-only: reset all persisted rate-limit budgets. */
-
-const INBOUND_TYPES = new Set<WidgetInboundType>([
-  "workspace:ready",
-  "workspace:getData",
-  "workspace:getTheme",
-  "workspace:sendPrompt",
-]);
-
-/**
- * Well-formedness filter: a valid inbound message is an object with `v === 1` and
- * a known `type`. Anything else is dropped silently (counted for tests). This runs
- * after the host has moved traffic onto the approved document's MessagePort.
- */
-function isWellFormedInbound(
-  data: unknown,
-): data is { v: 1; type: WidgetInboundType } & Record<string, unknown> {
-  return (
-    isRecord(data) &&
-    data.v === BRIDGE_ENVELOPE_VERSION &&
-    typeof data.type === "string" &&
-    INBOUND_TYPES.has(data.type as WidgetInboundType)
-  );
-}
-
-/** Creates the parent-side bridge for one approved custom widget. */
-export function createWidgetBridge(deps: WidgetBridgeDeps): WidgetBridge {
-  const now = deps.now ?? (() => Date.now());
-  const getDataTimeoutMs = deps.getDataTimeoutMs ?? DEFAULT_GET_DATA_TIMEOUT_MS;
-  const declaredBindingIds = new Set(Object.keys(deps.manifest.bindings));
-  const capabilities = new Set(deps.manifest.capabilities);
-  let dropped = 0;
-  let disposed = false;
-  // Rate-limit state is keyed by the widget NAME (stable identity), so it persists
-  // across bridge re-instantiation when the iframe is recreated.
-  const rateState = getPromptRateState(deps.manifest.name);
-  const pendingTimers = new Set<ReturnType<typeof setTimeout>>();
-
-  function error(code: WidgetErrorCode, message: string, requestId?: string): void {
-    deps.post({
-      v: 1,
-      type: "workspace:error",
-      ...(requestId !== undefined ? { requestId } : {}),
-      code,
-      message,
-    });
-  }
-
-  async function handleGetData(requestId: string, bindingId: string): Promise<void> {
-    if (!capabilities.has("data:read")) {
-      error("capability_denied", "widget lacks the data:read capability", requestId);
-      return;
-    }
-    if (!declaredBindingIds.has(bindingId)) {
-      // A widget cannot request a binding the operator did not approve.
-      error("binding_denied", `binding not declared in manifest: ${bindingId}`, requestId);
-      return;
-    }
-    // Resolve-time gate: host-specific grant mismatches are denied before any
-    // resolver or gateway access.
-    const denied = deps.assertBindingAllowed?.(bindingId);
-    if (denied) {
-      error(denied, `binding not allowed: ${bindingId}`, requestId);
-      return;
-    }
-    let settled = false;
-    const timer = setTimeout(() => {
-      if (settled || disposed) {
-        return;
-      }
-      settled = true;
-      pendingTimers.delete(timer);
-      error("timeout", "binding resolution timed out", requestId);
-    }, getDataTimeoutMs);
-    pendingTimers.add(timer);
-    try {
-      const data = await deps.resolveBinding(bindingId);
-      if (settled || disposed) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timer);
-      pendingTimers.delete(timer);
-      deps.post({ v: 1, type: "workspace:data", requestId, bindingId, data });
-    } catch (err) {
-      if (settled || disposed) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timer);
-      pendingTimers.delete(timer);
-      error("resolve_failed", err instanceof Error ? err.message : String(err), requestId);
-    }
-  }
-
-  function handleGetTheme(requestId: string): void {
-    deps.post({ v: 1, type: "workspace:theme", requestId, tokens: deps.resolveTheme() });
-  }
-
-  async function handleSendPrompt(requestId: string, text: string): Promise<void> {
-    if (!capabilities.has("prompt:send")) {
-      // Denied WITHOUT showing a dialog — the capability gate is first.
-      error("capability_denied", "widget lacks the prompt:send capability", requestId);
-      return;
-    }
-    // Rate limit: at most one in-flight prompt and 10 per rolling minute, keyed by
-    // widget name so a remount cannot reset the budget.
-    const cutoff = now() - PROMPT_RATE_WINDOW_MS;
-    rateState.timestamps = rateState.timestamps.filter((ts) => ts > cutoff);
-    if (rateState.inFlight || rateState.timestamps.length >= PROMPT_RATE_MAX) {
-      error("rate_limited", "prompt send rate limit exceeded", requestId);
-      return;
-    }
-    rateState.inFlight = true;
-    try {
-      const confirmed = await deps.confirmPrompt(text);
-      if (disposed) {
-        return;
-      }
-      if (!confirmed) {
-        // Deny path sends NOTHING.
-        error("prompt_declined", "operator declined the prompt", requestId);
-        return;
-      }
-      rateState.timestamps.push(now());
-      await deps.sendPrompt(text);
-    } catch (err) {
-      if (!disposed) {
-        error("resolve_failed", err instanceof Error ? err.message : String(err), requestId);
-      }
-    } finally {
-      rateState.inFlight = false;
-    }
-  }
-
-  function handleMessage(data: unknown): boolean {
-    if (disposed) {
-      return false;
-    }
-    if (!isWellFormedInbound(data)) {
-      dropped += 1;
-      return false;
-    }
-    switch (data.type) {
-      case "workspace:ready":
-        return true;
-      case "workspace:getData": {
-        const requestId = typeof data.requestId === "string" ? data.requestId : null;
-        const bindingId = typeof data.bindingId === "string" ? data.bindingId : null;
-        if (requestId === null || bindingId === null) {
-          dropped += 1;
-          return false;
-        }
-        void handleGetData(requestId, bindingId);
-        return true;
-      }
-      case "workspace:getTheme": {
-        const requestId = typeof data.requestId === "string" ? data.requestId : null;
-        if (requestId === null) {
-          dropped += 1;
-          return false;
-        }
-        handleGetTheme(requestId);
-        return true;
-      }
-      case "workspace:sendPrompt": {
-        const requestId = typeof data.requestId === "string" ? data.requestId : null;
-        const text = typeof data.text === "string" ? data.text : null;
-        if (requestId === null || text === null || !text.trim()) {
-          dropped += 1;
-          return false;
-        }
-        void handleSendPrompt(requestId, text);
-        return true;
-      }
-      default:
-        dropped += 1;
-        return false;
-    }
-  }
-
-  async function push(bindingId: string): Promise<void> {
-    if (
-      disposed ||
-      !capabilities.has("data:read") ||
-      !declaredBindingIds.has(bindingId) ||
-      deps.assertBindingAllowed?.(bindingId)
-    ) {
-      // A disallowed binding is never pushed (same gate as getData; silent for push).
-      return;
-    }
-    try {
-      const data = await deps.resolveBinding(bindingId);
-      if (!disposed) {
-        deps.post({ v: 1, type: "workspace:push", bindingId, data });
-      }
-    } catch {
-      // Push is best-effort; a failed refresh keeps the last value on the child.
-    }
-  }
-
-  return {
-    handleMessage,
-    push,
-    get droppedCount() {
-      return dropped;
-    },
-    dispose() {
-      disposed = true;
-      for (const timer of pendingTimers) {
-        clearTimeout(timer);
-      }
-      pendingTimers.clear();
-      // Release the in-flight lock so a remount can send again, but PRESERVE the
-      // rolling-window timestamps — clearing them would reopen the very reset hole
-      // this state exists to close.
-      rateState.inFlight = false;
-    },
-  };
-}
diff --git a/ui/src/lib/workspace/grid.test.ts b/ui/src/lib/workspace/grid.test.ts
deleted file mode 100644
index b43cfb890a8..00000000000
--- a/ui/src/lib/workspace/grid.test.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  beginDrag,
-  collides,
-  gridPlacementStyle,
-  gridRowCount,
-  nudgeRect,
-  resolveDrop,
-  updateDrag,
-  WORKSPACE_GRID_GAP,
-} from "./grid.ts";
-import type { WorkspaceWidget } from "./types.ts";
-
-function widget(id: string, x: number, y: number, w: number, h: number): WorkspaceWidget {
-  return { id, kind: "builtin:stat-card", title: id, grid: { x, y, w, h }, collapsed: false };
-}
-
-describe("workspace grid public operations", () => {
-  it("snaps pointer movement using computed column width and gaps", () => {
-    const drag = beginDrag({
-      widget: widget("a", 0, 0, 4, 2),
-      mode: "move",
-      clientX: 0,
-      clientY: 0,
-      metrics: { width: 720 },
-    });
-    expect(drag.columnWidth).toBe(49);
-    expect(updateDrag(drag, 122, 68)).toEqual({ x: 2, y: 1, w: 4, h: 2 });
-  });
-
-  it("clamps drag and keyboard operations to server grid bounds", () => {
-    const drag = beginDrag({
-      widget: widget("a", 10, 498, 4, 20),
-      mode: "resize",
-      clientX: 0,
-      clientY: 0,
-      metrics: { width: 720 },
-    });
-    expect(updateDrag(drag, 1_000, 1_000)).toEqual({ x: 0, y: 498, w: 12, h: 20 });
-    expect(nudgeRect({ x: 0, y: 499, w: 2, h: 1 }, "move", "down")).toEqual({
-      x: 0,
-      y: 499,
-      w: 2,
-      h: 1,
-    });
-    expect(nudgeRect({ x: 0, y: 0, w: 1, h: 1 }, "resize", "left")).toEqual({
-      x: 0,
-      y: 0,
-      w: 1,
-      h: 1,
-    });
-  });
-
-  it("treats touching edges as free and overlapping cells as collisions", () => {
-    const widgets = [widget("a", 0, 0, 4, 2), widget("b", 4, 0, 4, 2)];
-    expect(collides({ x: 8, y: 0, w: 4, h: 2 }, widgets, "c")).toBe(false);
-    expect(collides({ x: 3, y: 1, w: 4, h: 2 }, widgets, "c")).toBe(true);
-    expect(collides({ x: 0, y: 0, w: 4, h: 2 }, widgets, "a")).toBe(false);
-  });
-
-  it("offers the nearest expected free slot for an overlapping drop", () => {
-    const widgets = [widget("a", 0, 0, 10, 1)];
-    expect(resolveDrop({ requested: { x: 0, y: 0, w: 2, h: 1 }, widgets, widgetId: "b" })).toEqual({
-      x: 0,
-      y: 1,
-      w: 2,
-      h: 1,
-    });
-  });
-
-  it("never proposes a slot beyond the store's last row", () => {
-    const widgets = [widget("a", 0, 495, 12, 5)];
-    const slot = resolveDrop({
-      requested: { x: 0, y: 498, w: 4, h: 2 },
-      widgets,
-      widgetId: "b",
-    });
-    expect(slot === null || slot.y + slot.h - 1 <= 499).toBe(true);
-    if (slot) {
-      expect(collides(slot, widgets, "b")).toBe(false);
-    }
-  });
-
-  it("renders placement, row count, and the shared gap contract", () => {
-    expect(gridPlacementStyle({ x: 8, y: 3, w: 4, h: 1 })).toBe(
-      "grid-column: 9 / span 4; grid-row: 4 / span 1",
-    );
-    expect(gridRowCount([widget("a", 0, 0, 4, 2), widget("b", 4, 1, 4, 3)])).toBe(4);
-    expect(WORKSPACE_GRID_GAP).toBe(12);
-  });
-});
diff --git a/ui/src/lib/workspace/grid.ts b/ui/src/lib/workspace/grid.ts
deleted file mode 100644
index b26ed0bc76c..00000000000
--- a/ui/src/lib/workspace/grid.ts
+++ /dev/null
@@ -1,230 +0,0 @@
-// Grid math + hand-rolled pointer drag/drop + resize for the Workspaces view.
-//
-// Pure functions only — no DOM, no gateway. The view wires pointer events to
-// `beginDrag`/`updateDrag` and reads back a snapped ghost rect; on drop it asks
-// `resolveDrop` for the final placement (rejecting overlaps, offering the nearest
-// free slot per spec-30). Keeping the geometry here makes it unit-testable and
-// keeps the view a thin renderer (workboard three-way split).
-
-import { WORKSPACE_GRID_COLUMNS, type WorkspaceGridRect, type WorkspaceWidget } from "./types.ts";
-
-/** Fixed row height + gutter, in CSS pixels (spec-30 §Grid). */
-export const WORKSPACE_ROW_HEIGHT = 56;
-export const WORKSPACE_GRID_GAP = 12;
-/** Mirrors the store's grid bounds (`schema.ts` validateGrid). */
-const WORKSPACE_GRID_MAX_Y = 499;
-const WORKSPACE_GRID_MAX_HEIGHT = 20;
-
-type WorkspaceDragMode = "move" | "resize";
-
-export type WorkspaceDragState = {
-  widgetId: string;
-  mode: WorkspaceDragMode;
-  /** Grid rect at the moment the drag started. */
-  originRect: WorkspaceGridRect;
-  /** Pointer client coords at drag start. */
-  originClientX: number;
-  originClientY: number;
-  /** Live snapped rect, updated as the pointer moves. */
-  ghostRect: WorkspaceGridRect;
-  /** Width of one grid column in pixels, captured from the grid element. */
-  columnWidth: number;
-};
-
-type WorkspaceGridMetrics = {
-  /** Pixel width of the grid content box. */
-  width: number;
-};
-
-/** Column width in pixels given the grid content width. Gaps sit between cells. */
-function columnWidth(metrics: WorkspaceGridMetrics): number {
-  const totalGap = WORKSPACE_GRID_GAP * (WORKSPACE_GRID_COLUMNS - 1);
-  return Math.max(1, (metrics.width - totalGap) / WORKSPACE_GRID_COLUMNS);
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
-/** Snap a fractional column delta to whole grid units. */
-function snapCells(deltaPx: number, unitPx: number): number {
-  if (unitPx <= 0) {
-    return 0;
-  }
-  return Math.round(deltaPx / (unitPx + WORKSPACE_GRID_GAP));
-}
-
-/**
- * Clamp a rect into the grid the store will accept. The bounds mirror
- * `extensions/workspaces/src/schema.ts` exactly: a rect the UI lets you build but
- * the server rejects shows up as an optimistic move that snaps back.
- */
-function clampRect(rect: WorkspaceGridRect): WorkspaceGridRect {
-  const w = clamp(rect.w, 1, WORKSPACE_GRID_COLUMNS);
-  const h = clamp(rect.h, 1, WORKSPACE_GRID_MAX_HEIGHT);
-  const x = clamp(rect.x, 0, WORKSPACE_GRID_COLUMNS - w);
-  const y = clamp(rect.y, 0, WORKSPACE_GRID_MAX_Y);
-  return { x, y, w, h };
-}
-
-/** Do two grid rects share any cell? Touching edges do NOT overlap. */
-function rectsOverlap(a: WorkspaceGridRect, b: WorkspaceGridRect): boolean {
-  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
-}
-
-/** Rects of every widget except the one identified by `exceptId`. */
-function otherRects(widgets: readonly WorkspaceWidget[], exceptId: string): WorkspaceGridRect[] {
-  return widgets.filter((widget) => widget.id !== exceptId).map((widget) => widget.grid);
-}
-
-/** Does `rect` overlap any widget other than `exceptId`? */
-export function collides(
-  rect: WorkspaceGridRect,
-  widgets: readonly WorkspaceWidget[],
-  exceptId: string,
-): boolean {
-  return otherRects(widgets, exceptId).some((other) => rectsOverlap(rect, other));
-}
-
-/** Begin a drag/resize gesture from a pointer-down on a widget's chrome. */
-export function beginDrag(params: {
-  widget: WorkspaceWidget;
-  mode: WorkspaceDragMode;
-  clientX: number;
-  clientY: number;
-  metrics: WorkspaceGridMetrics;
-}): WorkspaceDragState {
-  return {
-    widgetId: params.widget.id,
-    mode: params.mode,
-    originRect: { ...params.widget.grid },
-    originClientX: params.clientX,
-    originClientY: params.clientY,
-    ghostRect: { ...params.widget.grid },
-    columnWidth: columnWidth(params.metrics),
-  };
-}
-
-/** Advance a drag with the current pointer position; returns the snapped ghost rect. */
-export function updateDrag(
-  drag: WorkspaceDragState,
-  clientX: number,
-  clientY: number,
-): WorkspaceGridRect {
-  const rowUnit = WORKSPACE_ROW_HEIGHT;
-  const deltaCols = snapCells(clientX - drag.originClientX, drag.columnWidth);
-  const deltaRows = snapCells(clientY - drag.originClientY, rowUnit);
-  const next =
-    drag.mode === "move"
-      ? {
-          x: drag.originRect.x + deltaCols,
-          y: drag.originRect.y + deltaRows,
-          w: drag.originRect.w,
-          h: drag.originRect.h,
-        }
-      : {
-          x: drag.originRect.x,
-          y: drag.originRect.y,
-          w: drag.originRect.w + deltaCols,
-          h: drag.originRect.h + deltaRows,
-        };
-  const clamped = clampRect(next);
-  drag.ghostRect = clamped;
-  return clamped;
-}
-
-/**
- * Resolve where a dropped widget lands. Overlapping drops are rejected (spec-30:
- * "reject drops that overlap, offer nearest free slot"); the nearest collision-free
- * slot to the requested position is returned instead. Returns null only if the
- * grid genuinely has no free slot for the widget's size (defensive; the grid is
- * unbounded downward so this is unreachable in practice).
- */
-export function resolveDrop(params: {
-  requested: WorkspaceGridRect;
-  widgets: readonly WorkspaceWidget[];
-  widgetId: string;
-}): WorkspaceGridRect | null {
-  const requested = clampRect(params.requested);
-  if (!collides(requested, params.widgets, params.widgetId)) {
-    return requested;
-  }
-  return nearestFreeSlot(requested, params.widgets, params.widgetId);
-}
-
-/**
- * Search outward from the requested position (increasing Manhattan-ish rings) for
- * the closest slot that fits `requested`'s size without colliding. The grid grows
- * downward, so a fit is always found within a bounded number of rows.
- */
-function nearestFreeSlot(
-  requested: WorkspaceGridRect,
-  widgets: readonly WorkspaceWidget[],
-  widgetId: string,
-): WorkspaceGridRect | null {
-  const w = clamp(requested.w, 1, WORKSPACE_GRID_COLUMNS);
-  const h = Math.max(1, requested.h);
-  const maxX = WORKSPACE_GRID_COLUMNS - w;
-  const occupiedRows = otherRects(widgets, widgetId).reduce(
-    (max, rect) => Math.max(max, rect.y + rect.h),
-    0,
-  );
-  // One extra band below everything usually guarantees a free row, but never search
-  // past the last row the store accepts: a slot at y=500 would be "nearest" and then
-  // rejected by schema validation, snapping the drop back.
-  const maxY = Math.min(Math.max(requested.y, occupiedRows) + h, WORKSPACE_GRID_MAX_Y - h + 1);
-  let best: { rect: WorkspaceGridRect; distance: number } | null = null;
-  for (let y = 0; y <= maxY; y += 1) {
-    // Past the requested row every further row is at least one unit farther away,
-    // and the closest slot on it is directly below the requested column. Stop only
-    // once even that ideal slot could not beat the best found — breaking on the
-    // first row that merely HAS a fit would return a far same-row slot over a
-    // near one a row down.
-    if (best && y >= requested.y && y - requested.y >= best.distance) {
-      break;
-    }
-    for (let x = 0; x <= maxX; x += 1) {
-      const candidate: WorkspaceGridRect = { x, y, w, h };
-      if (collides(candidate, widgets, widgetId)) {
-        continue;
-      }
-      const distance = Math.abs(x - requested.x) + Math.abs(y - requested.y);
-      if (!best || distance < best.distance) {
-        best = { rect: candidate, distance };
-      }
-    }
-  }
-  return best?.rect ?? null;
-}
-
-/** CSS grid-column/grid-row shorthand for a rect (1-based grid lines). */
-export function gridPlacementStyle(rect: WorkspaceGridRect): string {
-  return [
-    `grid-column: ${rect.x + 1} / span ${rect.w}`,
-    `grid-row: ${rect.y + 1} / span ${rect.h}`,
-  ].join("; ");
-}
-
-/** Total rows a set of widgets spans (for sizing the grid's min-height). */
-export function gridRowCount(widgets: readonly WorkspaceWidget[]): number {
-  return widgets.reduce((max, widget) => Math.max(max, widget.grid.y + widget.grid.h), 0);
-}
-
-const KEYBOARD_MOVE_STEP = 1;
-
-/** Nudge a rect by keyboard for the a11y move/resize fallback (spec-30). */
-export function nudgeRect(
-  rect: WorkspaceGridRect,
-  mode: WorkspaceDragMode,
-  direction: "left" | "right" | "up" | "down",
-): WorkspaceGridRect {
-  const step = KEYBOARD_MOVE_STEP;
-  if (mode === "move") {
-    const dx = direction === "left" ? -step : direction === "right" ? step : 0;
-    const dy = direction === "up" ? -step : direction === "down" ? step : 0;
-    return clampRect({ ...rect, x: rect.x + dx, y: rect.y + dy });
-  }
-  const dw = direction === "left" ? -step : direction === "right" ? step : 0;
-  const dh = direction === "up" ? -step : direction === "down" ? step : 0;
-  return clampRect({ ...rect, w: rect.w + dw, h: rect.h + dh });
-}
diff --git a/ui/src/lib/workspace/index.test.ts b/ui/src/lib/workspace/index.test.ts
deleted file mode 100644
index 69599e29b5f..00000000000
--- a/ui/src/lib/workspace/index.test.ts
+++ /dev/null
@@ -1,872 +0,0 @@
-import { expectDefined } from "@openclaw/normalization-core";
-import { describe, expect, it, vi } from "vitest";
-import type { GatewayBrowserClient } from "../../api/gateway.ts";
-import {
-  approveWidget,
-  cancelWorkspaceLoadIntent,
-  clearActiveDrag,
-  getWorkspaceState,
-  hideWidget,
-  loadWorkspace,
-  moveWidget,
-  moveWidgetToTab,
-  registerActiveDrag,
-  removeWidgetFromTab,
-  resolveBinding,
-  setActiveWorkspaceSlug,
-  updateWidgetTitle,
-  startBindingPolling,
-  stopWorkspace,
-  subscribeToWorkspaceEvents,
-} from "./index.ts";
-import type { WorkspaceDocument } from "./types.ts";
-
-type MockClient = Pick<GatewayBrowserClient, "request" | "addEventListener">;
-
-function mockClient(overrides: Partial<MockClient> = {}): GatewayBrowserClient {
-  return {
-    request: vi.fn(async () => ({})),
-    addEventListener: vi.fn(() => () => {}),
-    ...overrides,
-  } as unknown as GatewayBrowserClient;
-}
-
-const sampleDoc = {
-  schemaVersion: 1,
-  workspaceVersion: 3,
-  tabs: [
-    {
-      slug: "main",
-      title: "Main",
-      hidden: false,
-      widgets: [
-        {
-          id: "w1",
-          kind: "builtin:stat-card",
-          title: "Revenue",
-          grid: { x: 0, y: 0, w: 4, h: 2 },
-          collapsed: false,
-          createdBy: "agent:finance",
-        },
-      ],
-    },
-    { slug: "archive", title: "Archive", hidden: true, widgets: [] },
-  ],
-  prefs: { tabOrder: ["archive", "main"] },
-};
-
-function sampleWorkspace(overrides: Partial<WorkspaceDocument> = {}): WorkspaceDocument {
-  return {
-    ...structuredClone(sampleDoc),
-    widgetsRegistry: {},
-    ...overrides,
-  };
-}
-
-describe("approveWidget", () => {
-  it("suppresses duplicate decisions while the first request is pending", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace({
-      widgetsRegistry: { "sales-map": { status: "pending" } },
-    });
-    let resolveRequest!: () => void;
-    const request = vi.fn(
-      () =>
-        new Promise<void>((resolve) => {
-          resolveRequest = resolve;
-        }),
-    );
-    const client = mockClient({ request: request as never });
-
-    const first = approveWidget(state, client, { name: "sales-map", decision: "approved" });
-    const duplicate = approveWidget(state, client, { name: "sales-map", decision: "rejected" });
-
-    expect(request).toHaveBeenCalledOnce();
-    expect(state.pendingApprovalNames.has("sales-map")).toBe(true);
-    await duplicate;
-    resolveRequest();
-    await first;
-    expect(state.pendingApprovalNames.has("sales-map")).toBe(true);
-
-    const refreshed = sampleWorkspace({
-      workspaceVersion: 4,
-      widgetsRegistry: { "sales-map": { status: "approved" } },
-    });
-    await loadWorkspace(
-      state,
-      mockClient({
-        request: vi.fn(async () => ({ doc: refreshed, workspaceVersion: 4 })) as never,
-      }),
-    );
-    expect(state.pendingApprovalNames.has("sales-map")).toBe(false);
-  });
-
-  it("unlocks a pending custom widget after a failed decision", async () => {
-    const state = getWorkspaceState({});
-    const client = mockClient({
-      request: vi.fn(async () => {
-        throw new Error("decision failed");
-      }) as never,
-    });
-
-    await approveWidget(state, client, { name: "sales-map", decision: "approved" });
-
-    expect(state.pendingApprovalNames.has("sales-map")).toBe(false);
-    expect(state.actionError).toBe("decision failed");
-  });
-});
-
-describe("loadWorkspace", () => {
-  it("fetches and stores the workspace, seeding the active slug", async () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    const client = mockClient({
-      // Real gateway shape: workspaces.get returns { doc, workspaceVersion }.
-      request: vi.fn(async () => ({ doc: sampleDoc, workspaceVersion: 3 })) as never,
-    });
-    await loadWorkspace(state, client, { requestedSlug: "archive" });
-    expect(state.loaded).toBe(true);
-    // The workspace actually populates (tabs present), not an empty fallback.
-    expect(state.workspace?.workspaceVersion).toBe(3);
-    expect(state.workspace?.tabs).toHaveLength(2);
-    expect(state.activeSlug).toBe("archive");
-  });
-
-  it("keeps a newer workspace when an older reload finishes last", async () => {
-    const state = getWorkspaceState({});
-    const resolveRequests: Array<(value: unknown) => void> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequests.push(resolve);
-          }),
-      ) as never,
-    });
-
-    const olderLoad = loadWorkspace(state, client);
-    const newerLoad = loadWorkspace(state, client, { silent: true });
-    expect(resolveRequests).toHaveLength(2);
-
-    const newer = sampleWorkspace({ workspaceVersion: 4 });
-    expectDefined(newer.tabs[0], "newer tab").title = "Newest";
-    resolveRequests[1]?.({ doc: newer, workspaceVersion: 4 });
-    await newerLoad;
-    expect(state.loading).toBe(false);
-
-    resolveRequests[0]?.({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await olderLoad;
-
-    expect(state.workspace?.workspaceVersion).toBe(4);
-    expect(state.workspace?.tabs[0]?.title).toBe("Newest");
-  });
-
-  it("accepts a higher workspace version from an older request without restoring its navigation", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    state.activeSlug = "main";
-    const resolveRequests: Array<(value: unknown) => void> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequests.push(resolve);
-          }),
-      ) as never,
-    });
-
-    const olderLoad = loadWorkspace(state, client, { requestedSlug: "archive" });
-    const newerLoad = loadWorkspace(state, client, { requestedSlug: null });
-
-    resolveRequests[1]?.({
-      doc: sampleWorkspace({ workspaceVersion: 4 }),
-      workspaceVersion: 4,
-    });
-    await newerLoad;
-
-    const highestVersion = sampleWorkspace({ workspaceVersion: 5 });
-    expectDefined(highestVersion.tabs[0], "highest-version tab").title = "Latest";
-    resolveRequests[0]?.({ doc: highestVersion, workspaceVersion: 5 });
-    await olderLoad;
-
-    expect(state.workspace?.workspaceVersion).toBe(5);
-    expect(state.workspace?.tabs[0]?.title).toBe("Latest");
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("preserves requested navigation when a silent reload supersedes it", async () => {
-    const state = getWorkspaceState({});
-    const resolveRequests: Array<(value: unknown) => void> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequests.push(resolve);
-          }),
-      ) as never,
-    });
-
-    const foregroundLoad = loadWorkspace(state, client, { requestedSlug: "archive" });
-    const silentLoad = loadWorkspace(state, client, { requestedSlug: null, silent: true });
-
-    resolveRequests[1]?.({
-      doc: sampleWorkspace({ workspaceVersion: 4 }),
-      workspaceVersion: 4,
-    });
-    await silentLoad;
-    expect(state.activeSlug).toBe("archive");
-
-    resolveRequests[0]?.({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await foregroundLoad;
-    expect(state.activeSlug).toBe("archive");
-    expect(state.workspace?.workspaceVersion).toBe(4);
-  });
-
-  it("retains requested navigation after a superseding silent failure", async () => {
-    const state = getWorkspaceState({});
-    const requests: Array<{
-      resolve: (value: unknown) => void;
-      reject: (error: Error) => void;
-    }> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve, reject) => {
-            requests.push({ resolve, reject });
-          }),
-      ) as never,
-    });
-
-    const requestedLoad = loadWorkspace(state, client, { requestedSlug: "archive" });
-    const failedSilentLoad = loadWorkspace(state, client, { silent: true });
-    requests[1]?.reject(new Error("temporary failure"));
-    await failedSilentLoad;
-
-    const retryLoad = loadWorkspace(state, client, { silent: true });
-    requests[2]?.resolve({
-      doc: sampleWorkspace({ workspaceVersion: 4 }),
-      workspaceVersion: 4,
-    });
-    await retryLoad;
-    expect(state.activeSlug).toBe("archive");
-
-    requests[0]?.resolve({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await requestedLoad;
-    expect(state.activeSlug).toBe("archive");
-  });
-
-  it("applies retained navigation when an older request supplies the first document", async () => {
-    const state = getWorkspaceState({});
-    const requests: Array<{
-      resolve: (value: unknown) => void;
-      reject: (error: Error) => void;
-    }> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve, reject) => {
-            requests.push({ resolve, reject });
-          }),
-      ) as never,
-    });
-
-    const requestedLoad = loadWorkspace(state, client, { requestedSlug: "archive" });
-    const failedSilentLoad = loadWorkspace(state, client, { silent: true });
-    requests[1]?.reject(new Error("temporary failure"));
-    await failedSilentLoad;
-
-    requests[0]?.resolve({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await requestedLoad;
-
-    expect(state.workspace?.workspaceVersion).toBe(3);
-    expect(state.activeSlug).toBe("archive");
-    expect(state.error).toBe("temporary failure");
-  });
-
-  it("invalidates captured navigation when the successful document lacks the requested tab", async () => {
-    const state = getWorkspaceState({});
-    const requests: Array<{
-      resolve: (value: unknown) => void;
-      reject: (error: Error) => void;
-    }> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve, reject) => {
-            requests.push({ resolve, reject });
-          }),
-      ) as never,
-    });
-
-    const requestedLoad = loadWorkspace(state, client, { requestedSlug: "future" });
-    const silentLoad = loadWorkspace(state, client, { silent: true });
-    requests[0]?.resolve({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await requestedLoad;
-    expect(state.activeSlug).toBe("main");
-
-    const laterWorkspace = sampleWorkspace({
-      workspaceVersion: 4,
-      tabs: [
-        ...sampleWorkspace().tabs,
-        { slug: "future", title: "Future", hidden: false, widgets: [] },
-      ],
-    });
-    requests[1]?.resolve({ doc: laterWorkspace, workspaceVersion: 4 });
-    await silentLoad;
-
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("cancels older navigation intent on a newer foreground reload", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    state.activeSlug = "main";
-    const resolveRequests: Array<(value: unknown) => void> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequests.push(resolve);
-          }),
-      ) as never,
-    });
-
-    const requestedLoad = loadWorkspace(state, client, { requestedSlug: "archive" });
-    const foregroundReload = loadWorkspace(state, client, { requestedSlug: null });
-
-    resolveRequests[1]?.({
-      doc: sampleWorkspace({ workspaceVersion: 4 }),
-      workspaceVersion: 4,
-    });
-    await foregroundReload;
-    expect(state.activeSlug).toBe("main");
-
-    resolveRequests[0]?.({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await requestedLoad;
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("cancels pending navigation when the deep link returns to the active tab", async () => {
-    const state = getWorkspaceState({});
-    const workspace = sampleWorkspace();
-    state.workspace = workspace;
-    state.activeSlug = "main";
-    let resolveRequest: ((value: unknown) => void) | undefined;
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequest = resolve;
-          }),
-      ) as never,
-    });
-
-    const reload = loadWorkspace(state, client, { requestedSlug: "archive" });
-    setActiveWorkspaceSlug(state, workspace, "main");
-    resolveRequest?.({ doc: sampleWorkspace({ workspaceVersion: 4 }), workspaceVersion: 4 });
-    await reload;
-
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("cancels pending navigation when the deep link is removed", async () => {
-    const state = getWorkspaceState({});
-    const workspace = sampleWorkspace();
-    state.workspace = workspace;
-    state.activeSlug = "main";
-    const client = mockClient({
-      request: vi.fn(async () => ({
-        doc: sampleWorkspace({ workspaceVersion: 4 }),
-        workspaceVersion: 4,
-      })) as never,
-    });
-
-    const reload = loadWorkspace(state, client, { requestedSlug: "archive" });
-    cancelWorkspaceLoadIntent(state);
-    await reload;
-
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("settles requested navigation against a newer current workspace", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace({ workspaceVersion: 5 });
-    state.activeSlug = "main";
-    state.error = "previous failure";
-    const client = mockClient({
-      request: vi.fn(async () => ({
-        doc: sampleWorkspace({ workspaceVersion: 4 }),
-        workspaceVersion: 4,
-      })) as never,
-    });
-
-    await loadWorkspace(state, client, { requestedSlug: "archive" });
-
-    expect(state.workspace?.workspaceVersion).toBe(5);
-    expect(state.activeSlug).toBe("archive");
-    expect(state.error).toBeNull();
-  });
-
-  it("keeps the active tab when requested navigation fails and retries the intent", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    state.activeSlug = "main";
-    const request = vi
-      .fn()
-      .mockRejectedValueOnce(new Error("reload failed"))
-      .mockResolvedValueOnce({
-        doc: sampleWorkspace({ workspaceVersion: 4 }),
-        workspaceVersion: 4,
-      });
-    const client = mockClient({ request: request as never });
-
-    await loadWorkspace(state, client, { requestedSlug: "archive" });
-    expect(state.activeSlug).toBe("main");
-
-    await loadWorkspace(state, client, { requestedSlug: "archive" });
-    expect(state.activeSlug).toBe("archive");
-    expect(state.workspace?.workspaceVersion).toBe(4);
-  });
-
-  it("treats a null requested slug as absent during reload", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    state.activeSlug = "archive";
-    const client = mockClient({
-      request: vi.fn(async () => ({
-        doc: sampleWorkspace({ workspaceVersion: 4 }),
-        workspaceVersion: 4,
-      })) as never,
-    });
-
-    await loadWorkspace(state, client, { requestedSlug: null });
-    expect(state.activeSlug).toBe("archive");
-  });
-
-  it("preserves a newer tab selection while requested navigation is pending", async () => {
-    const state = getWorkspaceState({});
-    const workspace = sampleWorkspace({
-      tabs: [
-        ...sampleWorkspace().tabs,
-        { slug: "other", title: "Other", hidden: false, widgets: [] },
-      ],
-    });
-    state.workspace = workspace;
-    state.activeSlug = "main";
-    let resolveRequest: ((value: unknown) => void) | undefined;
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequest = resolve;
-          }),
-      ) as never,
-    });
-
-    const reload = loadWorkspace(state, client, { requestedSlug: "archive" });
-    setActiveWorkspaceSlug(state, workspace, "other");
-    setActiveWorkspaceSlug(state, workspace, "main");
-    resolveRequest?.({
-      doc: { ...workspace, workspaceVersion: 4 },
-      workspaceVersion: 4,
-    });
-    await reload;
-
-    expect(state.activeSlug).toBe("main");
-  });
-
-  it("defers matching deep-link reconciliation until the loaded tab exists", async () => {
-    const state = getWorkspaceState({});
-    const currentWorkspace = sampleWorkspace();
-    state.workspace = currentWorkspace;
-    state.activeSlug = "main";
-    let resolveRequest: ((value: unknown) => void) | undefined;
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequest = resolve;
-          }),
-      ) as never,
-    });
-
-    const reload = loadWorkspace(state, client, { requestedSlug: "new-tab" });
-    setActiveWorkspaceSlug(state, currentWorkspace, "new-tab");
-    expect(state.activeSlug).toBe("main");
-
-    resolveRequest?.({
-      doc: sampleWorkspace({
-        workspaceVersion: 4,
-        tabs: [
-          ...currentWorkspace.tabs,
-          { slug: "new-tab", title: "New", hidden: false, widgets: [] },
-        ],
-      }),
-      workspaceVersion: 4,
-    });
-    await reload;
-    expect(state.activeSlug).toBe("new-tab");
-  });
-
-  it("keeps loading owned by the newest foreground reload", async () => {
-    const state = getWorkspaceState({});
-    const resolveRequests: Array<(value: unknown) => void> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve) => {
-            resolveRequests.push(resolve);
-          }),
-      ) as never,
-    });
-
-    const olderLoad = loadWorkspace(state, client);
-    const newerLoad = loadWorkspace(state, client);
-    expect(state.loading).toBe(true);
-
-    resolveRequests[0]?.({ doc: sampleWorkspace(), workspaceVersion: 3 });
-    await olderLoad;
-    expect(state.loading).toBe(true);
-
-    resolveRequests[1]?.({
-      doc: sampleWorkspace({ workspaceVersion: 4 }),
-      workspaceVersion: 4,
-    });
-    await newerLoad;
-    expect(state.loading).toBe(false);
-    expect(state.workspace?.workspaceVersion).toBe(4);
-  });
-
-  it("ignores an older reload error after a newer workspace loads", async () => {
-    const state = getWorkspaceState({});
-    const requests: Array<{
-      resolve: (value: unknown) => void;
-      reject: (error: Error) => void;
-    }> = [];
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((resolve, reject) => {
-            requests.push({ resolve, reject });
-          }),
-      ) as never,
-    });
-
-    const olderLoad = loadWorkspace(state, client);
-    const newerLoad = loadWorkspace(state, client, { silent: true });
-    expect(requests).toHaveLength(2);
-
-    requests[1]?.resolve({ doc: sampleWorkspace({ workspaceVersion: 4 }), workspaceVersion: 4 });
-    await newerLoad;
-    requests[0]?.reject(new Error("stale failure"));
-    await olderLoad;
-
-    expect(state.workspace?.workspaceVersion).toBe(4);
-    expect(state.error).toBeNull();
-    expect(state.loading).toBe(false);
-  });
-
-  it("records an error on failure", async () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    const client = mockClient({
-      request: vi.fn(async () => {
-        throw new Error("boom");
-      }) as never,
-    });
-    await loadWorkspace(state, client);
-    expect(state.error).toBe("boom");
-    expect(state.loaded).toBe(false);
-  });
-});
-
-describe("optimistic workspace mutations", () => {
-  it("uses the gateway tab/id wire contract for every widget mutation", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    const request = vi.fn(async () => ({}));
-    const client = mockClient({ request: request as never });
-
-    await moveWidget(state, client, {
-      slug: "main",
-      widgetId: "w1",
-      grid: { x: 8, y: 0, w: 4, h: 2 },
-    });
-    expect(request).toHaveBeenLastCalledWith("workspaces.widget.move", {
-      tab: "main",
-      id: "w1",
-      grid: { x: 8, y: 0, w: 4, h: 2 },
-    });
-
-    await updateWidgetTitle(state, client, { slug: "main", widgetId: "w1", title: "Renamed" });
-    expect(request).toHaveBeenLastCalledWith("workspaces.widget.update", {
-      tab: "main",
-      id: "w1",
-      patch: { title: "Renamed" },
-    });
-
-    await hideWidget(state, client, { slug: "main", widgetId: "w1" });
-    expect(request).toHaveBeenLastCalledWith("workspaces.widget.update", {
-      tab: "main",
-      id: "w1",
-      patch: { hidden: true },
-    });
-
-    state.workspace = sampleWorkspace();
-    await removeWidgetFromTab(state, client, { slug: "main", widgetId: "w1" });
-    expect(request).toHaveBeenLastCalledWith("workspaces.widget.remove", {
-      tab: "main",
-      id: "w1",
-    });
-
-    state.workspace = sampleWorkspace();
-    await moveWidgetToTab(state, client, {
-      fromSlug: "main",
-      toSlug: "archive",
-      widgetId: "w1",
-    });
-    expect(request).toHaveBeenLastCalledWith("workspaces.widget.move", {
-      tab: "main",
-      id: "w1",
-      toTab: "archive",
-    });
-  });
-
-  it("rolls back a rejected mutation and surfaces its error", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    const client = mockClient({
-      request: vi.fn(async () => {
-        throw new Error("rejected");
-      }) as never,
-    });
-
-    await moveWidget(state, client, {
-      slug: "main",
-      widgetId: "w1",
-      grid: { x: 8, y: 0, w: 4, h: 2 },
-    });
-
-    expect(state.workspace?.tabs[0]?.widgets[0]?.grid).toEqual({ x: 0, y: 0, w: 4, h: 2 });
-    expect(state.actionError).toBe("rejected");
-    expect(state.pendingWidgetIds.has("w1")).toBe(false);
-  });
-
-  it("serializes overlapping writes so both failures fully revert", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    const rejectors: Array<(error: Error) => void> = [];
-    const request = vi.fn(
-      () =>
-        new Promise((_resolve, reject) => {
-          rejectors.push(reject);
-        }),
-    );
-    const client = mockClient({ request: request as never });
-
-    const first = moveWidget(state, client, {
-      slug: "main",
-      widgetId: "w1",
-      grid: { x: 8, y: 0, w: 4, h: 2 },
-    });
-    await vi.waitFor(() => expect(rejectors).toHaveLength(1));
-    const second = updateWidgetTitle(state, client, {
-      slug: "main",
-      widgetId: "w1",
-      title: "Rejected title",
-    });
-    expect(request).toHaveBeenCalledOnce();
-
-    rejectors[0]?.(new Error("first rejected"));
-    await vi.waitFor(() => expect(rejectors).toHaveLength(2));
-    rejectors[1]?.(new Error("second rejected"));
-    await Promise.all([first, second]);
-
-    expect(state.workspace?.tabs[0]?.widgets[0]).toMatchObject({
-      title: "Revenue",
-      grid: { x: 0, y: 0, w: 4, h: 2 },
-    });
-    expect(state.pendingWidgetIds.has("w1")).toBe(false);
-  });
-
-  it("does not overwrite a fresher reload when an older mutation rejects", async () => {
-    const state = getWorkspaceState({});
-    state.workspace = sampleWorkspace();
-    let rejectMutation!: (error: Error) => void;
-    const client = mockClient({
-      request: vi.fn(
-        () =>
-          new Promise((_resolve, reject) => {
-            rejectMutation = reject;
-          }),
-      ) as never,
-    });
-
-    const mutation = moveWidget(state, client, {
-      slug: "main",
-      widgetId: "w1",
-      grid: { x: 8, y: 0, w: 4, h: 2 },
-    });
-    await vi.waitFor(() => expect(typeof rejectMutation).toBe("function"));
-
-    const fresher = sampleWorkspace({ workspaceVersion: 4 });
-    expectDefined(fresher.tabs[0], "fresher tab").widgets[0]!.title = "Revenue (v4)";
-    state.workspace = fresher;
-    rejectMutation(new Error("rejected"));
-    await mutation;
-
-    expect(state.workspace).toBe(fresher);
-    expect(state.workspace?.workspaceVersion).toBe(4);
-    expect(state.workspace?.tabs[0]?.widgets[0]?.title).toBe("Revenue (v4)");
-  });
-});
-
-describe("live-update subscription", () => {
-  it("tears down the listener on stop", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    const unsubscribe = vi.fn();
-    const client = mockClient({
-      addEventListener: vi.fn(() => unsubscribe) as never,
-    });
-    subscribeToWorkspaceEvents(host, state, client);
-    stopWorkspace(host);
-    expect(unsubscribe).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe("binding resolution", () => {
-  it("resolves static bindings from the literal value", async () => {
-    const result = await resolveBinding(null, { source: "static", value: 42 });
-    expect(result).toEqual({ value: 42 });
-  });
-
-  it("resolves rpc bindings on the client and applies the pointer", async () => {
-    const request = vi.fn(async () => ({ revenue: 1000 }));
-    const client = mockClient({ request: request as never });
-    const result = await resolveBinding(client, {
-      source: "rpc",
-      method: "workspaces.stats",
-      params: { scope: "month" },
-      pointer: "/revenue",
-    });
-    expect(result).toEqual({ value: 1000 });
-    expect(request).toHaveBeenCalledWith("workspaces.stats", { scope: "month" });
-  });
-
-  it("resolves usage.cost bindings in the browser's local calendar day", async () => {
-    const request = vi.fn(async () => ({ totals: { totalCost: 1 } }));
-    const client = mockClient({ request: request as never });
-
-    await resolveBinding(client, {
-      source: "rpc",
-      method: "usage.cost",
-      params: { days: 1 },
-    });
-
-    expect(request).toHaveBeenCalledWith("usage.cost", {
-      days: 1,
-      mode: "specific",
-      timeZone: expect.any(String),
-      utcOffset: expect.stringMatching(/^UTC[+-]/),
-    });
-  });
-
-  it("preserves an explicit usage.cost timezone mode", async () => {
-    const request = vi.fn(async () => ({}));
-    const client = mockClient({ request: request as never });
-
-    await resolveBinding(client, {
-      source: "rpc",
-      method: "usage.cost",
-      params: { days: 1, mode: "utc" },
-    });
-
-    expect(request).toHaveBeenCalledWith("usage.cost", { days: 1, mode: "utc" });
-  });
-
-  it("resolves file bindings via workspaces.data.read matching the real gateway contract", async () => {
-    // Contract with the gateway (extensions/workspace gateway.ts + data-read.ts):
-    //   - workspaces.data.read's readParams whitelist accepts ONLY `binding` and
-    //     rejects any other top-level key, so the client MUST send the whole binding.
-    //   - the server resolves the file AND applies the JSON pointer, returning the
-    //     final value under `data`; the client MUST NOT re-apply the pointer.
-    // This mirrors the server's real response shape (already-pointed `data`), so a
-    // regression to the old `{ path, pointer }` + client-side re-apply would fail here.
-    const request = vi.fn(async () => ({ data: 7 }));
-    const client = mockClient({ request: request as never });
-    const result = await resolveBinding(client, {
-      source: "file",
-      path: "q3.json",
-      pointer: "/q3/total",
-    });
-    expect(request).toHaveBeenCalledWith("workspaces.data.read", {
-      binding: { source: "file", path: "q3.json", pointer: "/q3/total" },
-    });
-    expect(result).toEqual({ value: 7 });
-  });
-
-  it("returns an error result when resolution throws", async () => {
-    const client = mockClient({
-      request: vi.fn(async () => {
-        throw new Error("no data");
-      }) as never,
-    });
-    const result = await resolveBinding(client, { source: "rpc", method: "x" });
-    expect(result).toEqual({ error: "no data" });
-  });
-});
-
-describe("active drag cancellation", () => {
-  it("cancels a registered drag from stopWorkspace", () => {
-    const host = {};
-    const cancel = vi.fn();
-    registerActiveDrag(host, cancel);
-    stopWorkspace(host);
-    expect(cancel).toHaveBeenCalledTimes(1);
-    // Idempotent: a second stop does not re-invoke the (already cleared) teardown.
-    stopWorkspace(host);
-    expect(cancel).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not cancel a drag that already settled and cleared itself", () => {
-    const host = {};
-    const cancel = vi.fn();
-    registerActiveDrag(host, cancel);
-    clearActiveDrag(host); // normal pointerup path clears without cancelling
-    stopWorkspace(host);
-    expect(cancel).not.toHaveBeenCalled();
-  });
-});
-
-describe("data-refresh polling", () => {
-  it("stops ticking after stopWorkspace — no orphan timer", () => {
-    vi.useFakeTimers();
-    try {
-      const host = {};
-      const onTick = vi.fn();
-      startBindingPolling(host, mockClient(), onTick, 10_000);
-      vi.advanceTimersByTime(10_000);
-      expect(onTick).toHaveBeenCalledTimes(1);
-      stopWorkspace(host); // tab-leave / disconnect
-      vi.advanceTimersByTime(60_000);
-      expect(onTick).toHaveBeenCalledTimes(1);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it("a null client stops any running timer", () => {
-    vi.useFakeTimers();
-    try {
-      const host = {};
-      const onTick = vi.fn();
-      startBindingPolling(host, mockClient(), onTick, 10_000);
-      startBindingPolling(host, null, onTick, 10_000); // disconnect
-      vi.advanceTimersByTime(30_000);
-      expect(onTick).not.toHaveBeenCalled();
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});
diff --git a/ui/src/lib/workspace/index.ts b/ui/src/lib/workspace/index.ts
deleted file mode 100644
index 295e7fd4f4a..00000000000
--- a/ui/src/lib/workspace/index.ts
+++ /dev/null
@@ -1,838 +0,0 @@
-// Control UI controller for Workspaces: gateway state, live-update
-// subscription, optimistic mutations with revert, and the minimal builtin binding
-// resolver (spec-30 scope: stat-card + markdown; L4 extends the registry).
-//
-// Follows the workboard three-way split — this module owns all logic; the view is
-// pure render fns and the page/controller is thin lifecycle glue.
-
-import { isRecord } from "@openclaw/normalization-core/record-coerce";
-import type { GatewayBrowserClient, GatewayEventFrame } from "../../api/gateway.ts";
-import { buildSessionUsageDateParams } from "../sessions/usage.ts";
-import { reconcilePendingApprovalNames } from "./approval-state.ts";
-import { resolveActiveSlug } from "./tab-selection.ts";
-export {
-  customWidgetName,
-  customWidgetStatus,
-  findTab,
-  hiddenTabs,
-  orderedTabs,
-  visibleTabs,
-} from "./tab-selection.ts";
-import {
-  WORKSPACE_GRID_COLUMNS,
-  workspaceAgentProvenance,
-  type WorkspaceBinding,
-  type WorkspaceChangedEvent,
-  type WorkspaceGridRect,
-  type WorkspaceTab,
-  type WorkspaceWidget,
-  type WorkspaceWidgetRegistryEntry,
-  type WorkspaceWidgetStatus,
-  type WorkspaceDocument,
-} from "./types.ts";
-
-const CHANGED_EVENT = "plugin.workspaces.changed";
-
-export type WorkspaceUiState = {
-  loading: boolean;
-  loadGeneration: number;
-  loadingGeneration: number | null;
-  loaded: boolean;
-  error: string | null;
-  workspace: WorkspaceDocument | null;
-  /** Slug of the workspace tab in view; null until the doc resolves a default. */
-  activeSlug: string | null;
-  /** Monotonic user/load selection revision used to reject stale navigation intent. */
-  activeSlugRevision: number;
-  /** Whether the hidden-tabs overflow menu is open. */
-  hiddenMenuOpen: boolean;
-  /** Widgets with an in-flight mutation, for optimistic-state affordances. */
-  pendingWidgetIds: Set<string>;
-  /** Custom-widget names with an in-flight approval decision. */
-  pendingApprovalNames: Set<string>;
-  /** Transient error surfaced after a failed mutation (reverted state + toast). */
-  actionError: string | null;
-  requestUpdate: (() => void) | null;
-};
-
-type WorkspaceHost = object;
-
-const workspaceStates = new WeakMap<WorkspaceHost, WorkspaceUiState>();
-const workspaceEventUnsubscribers = new WeakMap<WorkspaceHost, () => void>();
-const workspaceEventClients = new WeakMap<WorkspaceHost, GatewayBrowserClient>();
-// Per-host data-refresh polling: a single interval per host that fires the view's
-// tick (re-resolve data-widget bindings) only while the document is visible.
-const workspacePollTimers = new WeakMap<WorkspaceHost, ReturnType<typeof setInterval>>();
-const workspacePollActive = new WeakMap<WorkspaceHost, boolean>();
-const workspaceMutationQueues = new WeakMap<WorkspaceUiState, Promise<void>>();
-type WorkspaceLoadIntent = { slug: string; activeSlugRevision: number };
-const workspaceLoadIntents = new WeakMap<WorkspaceUiState, WorkspaceLoadIntent>();
-
-/** Default data-refresh interval (ms); the L4 spec's 30–60s window, floored at 10s. */
-const WORKSPACE_POLL_INTERVAL_MS = 45_000;
-// Per-host teardown for an in-flight hand-rolled drag: the view registers window
-// pointermove/pointerup listeners while dragging, so a tab-switch/disconnect that
-// calls stopWorkspace must cancel the drag (remove listeners, neutralize the
-// pending pointerup) rather than leak closures over the now-stale view state.
-const workspaceActiveDragCancel = new WeakMap<WorkspaceHost, () => void>();
-
-/**
- * Register the teardown for an active drag on `host`. The view calls this when a
- * drag begins; `cancel` must remove its window listeners and make any later
- * pointerup a no-op. A previously registered drag is cancelled first so only one
- * drag is ever live per host.
- */
-export function registerActiveDrag(host: WorkspaceHost, cancel: () => void): void {
-  workspaceActiveDragCancel.get(host)?.();
-  workspaceActiveDragCancel.set(host, cancel);
-}
-
-/** Clear the active-drag teardown for `host` once the drag settles normally. */
-export function clearActiveDrag(host: WorkspaceHost): void {
-  workspaceActiveDragCancel.delete(host);
-}
-
-/** Cancel any in-flight drag on `host` (used by stopWorkspace and re-registration). */
-function cancelActiveDrag(host: WorkspaceHost): void {
-  const cancel = workspaceActiveDragCancel.get(host);
-  if (cancel) {
-    workspaceActiveDragCancel.delete(host);
-    cancel();
-  }
-}
-
-export function getWorkspaceState(host: WorkspaceHost): WorkspaceUiState {
-  let state = workspaceStates.get(host);
-  if (!state) {
-    state = {
-      loading: false,
-      loadGeneration: 0,
-      loadingGeneration: null,
-      loaded: false,
-      error: null,
-      workspace: null,
-      activeSlug: null,
-      activeSlugRevision: 0,
-      hiddenMenuOpen: false,
-      pendingWidgetIds: new Set(),
-      pendingApprovalNames: new Set(),
-      actionError: null,
-      requestUpdate: null,
-    };
-    workspaceStates.set(host, state);
-  }
-  return state;
-}
-
-function notify(state: WorkspaceUiState): void {
-  state.requestUpdate?.();
-}
-
-function readString(value: unknown, fallback = ""): string {
-  return typeof value === "string" ? value : fallback;
-}
-
-function readNumber(value: unknown, fallback = 0): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-
-function normalizeRect(value: unknown): WorkspaceGridRect {
-  const record = isRecord(value) ? value : {};
-  const w = Math.min(WORKSPACE_GRID_COLUMNS, Math.max(1, Math.trunc(readNumber(record.w, 4))));
-  const h = Math.max(1, Math.trunc(readNumber(record.h, 2)));
-  const x = Math.min(WORKSPACE_GRID_COLUMNS - w, Math.max(0, Math.trunc(readNumber(record.x, 0))));
-  const y = Math.max(0, Math.trunc(readNumber(record.y, 0)));
-  return { x, y, w, h };
-}
-
-function normalizeBinding(value: unknown): WorkspaceBinding | null {
-  if (!isRecord(value)) {
-    return null;
-  }
-  const source = value.source;
-  if (source !== "rpc" && source !== "file" && source !== "static") {
-    return null;
-  }
-  return {
-    source,
-    ...(typeof value.method === "string" ? { method: value.method } : {}),
-    ...(typeof value.path === "string" ? { path: value.path } : {}),
-    ...(typeof value.pointer === "string" ? { pointer: value.pointer } : {}),
-    ...(isRecord(value.params) ? { params: value.params } : {}),
-    ...("value" in value ? { value: value.value } : {}),
-  };
-}
-
-function normalizeBindings(value: unknown): Record<string, WorkspaceBinding> | undefined {
-  if (!isRecord(value)) {
-    return undefined;
-  }
-  const bindings: Record<string, WorkspaceBinding> = {};
-  for (const [key, raw] of Object.entries(value)) {
-    const binding = normalizeBinding(raw);
-    if (binding) {
-      bindings[key] = binding;
-    }
-  }
-  return Object.keys(bindings).length ? bindings : undefined;
-}
-
-function normalizeWidget(value: unknown): WorkspaceWidget | null {
-  if (!isRecord(value)) {
-    return null;
-  }
-  const id = readString(value.id).trim();
-  const kind = readString(value.kind).trim();
-  if (!id || !kind) {
-    return null;
-  }
-  return {
-    id,
-    kind,
-    title: readString(value.title),
-    grid: normalizeRect(value.grid),
-    collapsed: value.collapsed === true,
-    ...(typeof value.createdBy === "string" ? { createdBy: value.createdBy } : {}),
-    ...(normalizeBindings(value.bindings) ? { bindings: normalizeBindings(value.bindings) } : {}),
-    ...(isRecord(value.props) ? { props: value.props } : {}),
-  };
-}
-
-function normalizeTab(value: unknown): WorkspaceTab | null {
-  if (!isRecord(value)) {
-    return null;
-  }
-  const slug = readString(value.slug).trim();
-  if (!slug) {
-    return null;
-  }
-  // A hidden widget never enters the UI read model, so the grid, the collision
-  // math, and layout persistence all agree on one widget list without re-checking
-  // the flag. The document still holds it: an agent, the CLI, or undo can bring it
-  // back. The Control UI has no un-hide affordance by design.
-  const widgets = Array.isArray(value.widgets)
-    ? value.widgets
-        .filter((raw) => !(isRecord(raw) && raw.hidden === true))
-        .map(normalizeWidget)
-        .filter((w): w is WorkspaceWidget => w !== null)
-    : [];
-  return {
-    slug,
-    title: readString(value.title, slug),
-    hidden: value.hidden === true,
-    widgets,
-    ...(value.layout === "grid" || value.layout === "full" ? { layout: value.layout } : {}),
-    ...(typeof value.icon === "string" ? { icon: value.icon } : {}),
-    ...(typeof value.createdBy === "string" ? { createdBy: value.createdBy } : {}),
-  };
-}
-
-const WIDGET_STATUSES = new Set<WorkspaceWidgetStatus>(["pending", "approved", "rejected"]);
-
-function normalizeRegistryEntry(value: unknown): WorkspaceWidgetRegistryEntry | null {
-  if (!isRecord(value)) {
-    return null;
-  }
-  const status = value.status;
-  if (typeof status !== "string" || !WIDGET_STATUSES.has(status as WorkspaceWidgetStatus)) {
-    return null;
-  }
-  return {
-    status: status as WorkspaceWidgetStatus,
-    ...(typeof value.createdBy === "string" ? { createdBy: value.createdBy } : {}),
-    ...(typeof value.approvedBy === "string" ? { approvedBy: value.approvedBy } : {}),
-    ...(typeof value.approvedAt === "string" ? { approvedAt: value.approvedAt } : {}),
-  };
-}
-
-function normalizeWidgetsRegistry(value: unknown): Record<string, WorkspaceWidgetRegistryEntry> {
-  if (!isRecord(value)) {
-    return {};
-  }
-  const registry: Record<string, WorkspaceWidgetRegistryEntry> = {};
-  for (const [name, raw] of Object.entries(value)) {
-    const entry = normalizeRegistryEntry(raw);
-    if (entry) {
-      registry[name] = entry;
-    }
-  }
-  return registry;
-}
-
-function normalizeWorkspace(payload: unknown): WorkspaceDocument {
-  const record = isRecord(payload) ? payload : {};
-  const tabs = Array.isArray(record.tabs)
-    ? record.tabs.map(normalizeTab).filter((tab): tab is WorkspaceTab => tab !== null)
-    : [];
-  const prefsRecord = isRecord(record.prefs) ? record.prefs : {};
-  const tabOrder = Array.isArray(prefsRecord.tabOrder)
-    ? prefsRecord.tabOrder.filter((slug): slug is string => typeof slug === "string")
-    : [];
-  return {
-    schemaVersion: readNumber(record.schemaVersion, 1),
-    workspaceVersion: readNumber(record.workspaceVersion, 0),
-    tabs,
-    prefs: { tabOrder },
-    widgetsRegistry: normalizeWidgetsRegistry(record.widgetsRegistry),
-  };
-}
-
-function applyActiveWorkspaceSlug(
-  state: WorkspaceUiState,
-  workspace: WorkspaceDocument,
-  requestedSlug: string | null,
-): void {
-  state.activeSlug = resolveActiveSlug(workspace, requestedSlug);
-  state.activeSlugRevision += 1;
-}
-
-/** Apply explicit navigation and invalidate navigation intent owned by older loads. */
-export function setActiveWorkspaceSlug(
-  state: WorkspaceUiState,
-  workspace: WorkspaceDocument,
-  requestedSlug: string | null,
-): void {
-  const intent = workspaceLoadIntents.get(state);
-  if (intent?.slug === requestedSlug) {
-    return;
-  }
-  if (requestedSlug === state.activeSlug) {
-    if (intent) {
-      workspaceLoadIntents.delete(state);
-      state.activeSlugRevision += 1;
-    }
-    return;
-  }
-  workspaceLoadIntents.delete(state);
-  applyActiveWorkspaceSlug(state, workspace, requestedSlug);
-}
-
-/** Cancel load-owned navigation while preserving the current tab selection. */
-export function cancelWorkspaceLoadIntent(state: WorkspaceUiState): void {
-  if (workspaceLoadIntents.delete(state)) {
-    state.activeSlugRevision += 1;
-  }
-}
-
-function formatError(error: unknown): string {
-  if (error instanceof Error && error.message.trim()) {
-    return error.message.trim();
-  }
-  if (typeof error === "string" && error.trim()) {
-    return error.trim();
-  }
-  return "Unknown workspace error.";
-}
-
-/** Load the workspace document; seeds `activeSlug` from the requested deep-link slug. */
-export async function loadWorkspace(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  opts?: { requestedSlug?: string | null; silent?: boolean },
-): Promise<void> {
-  if (!client) {
-    return;
-  }
-  let intent: WorkspaceLoadIntent | undefined;
-  if (opts?.requestedSlug != null) {
-    intent = {
-      slug: opts.requestedSlug,
-      activeSlugRevision: state.activeSlugRevision,
-    };
-    workspaceLoadIntents.set(state, intent);
-  } else if (opts?.silent) {
-    intent = workspaceLoadIntents.get(state);
-  } else if (!opts?.silent) {
-    workspaceLoadIntents.delete(state);
-  }
-  // Carry navigation intent into a superseding silent refresh without exposing
-  // an unvalidated slug as the active selection before a load succeeds.
-  const generation = ++state.loadGeneration;
-  if (!opts?.silent) {
-    state.loadingGeneration = generation;
-    state.loading = true;
-    state.error = null;
-    notify(state);
-  }
-  let staleDocumentApplied = false;
-  try {
-    const payload = await client.request("workspaces.get", {});
-    const workspace = normalizeWorkspace(
-      // workspaces.get responds { doc, workspaceVersion } — read `doc`
-      // (a bare payload is tolerated for forward-compat).
-      isRecord(payload) && "doc" in payload ? payload.doc : payload,
-    );
-    const currentVersion = state.workspace?.workspaceVersion;
-    if (generation !== state.loadGeneration) {
-      // Request generation owns navigation and status, but workspaceVersion owns
-      // document freshness when handlers complete out of order.
-      if (currentVersion === undefined || workspace.workspaceVersion > currentVersion) {
-        const retainedIntent = workspaceLoadIntents.get(state);
-        const retainedIntentIsCurrent =
-          retainedIntent?.activeSlugRevision === state.activeSlugRevision;
-        state.workspace = workspace;
-        reconcilePendingApprovalNames(state.pendingApprovalNames, workspace);
-        state.activeSlug = resolveActiveSlug(
-          workspace,
-          retainedIntentIsCurrent ? retainedIntent.slug : state.activeSlug,
-        );
-        if (retainedIntentIsCurrent && workspaceLoadIntents.get(state) === retainedIntent) {
-          workspaceLoadIntents.delete(state);
-          // Consuming the shared intent invalidates copies already captured by
-          // newer in-flight loads, so they cannot revive removed navigation.
-          state.activeSlugRevision += 1;
-        }
-        state.loaded = true;
-        staleDocumentApplied = true;
-      }
-      return;
-    }
-    if (currentVersion !== undefined && workspace.workspaceVersion < currentVersion) {
-      if (state.workspace && intent?.activeSlugRevision === state.activeSlugRevision) {
-        applyActiveWorkspaceSlug(state, state.workspace, intent.slug);
-      }
-      if (workspaceLoadIntents.get(state) === intent) {
-        workspaceLoadIntents.delete(state);
-      }
-      state.error = null;
-      state.loaded = true;
-      return;
-    }
-    const requestedSlug =
-      intent && intent.activeSlugRevision === state.activeSlugRevision
-        ? intent.slug
-        : state.activeSlug;
-    state.workspace = workspace;
-    reconcilePendingApprovalNames(state.pendingApprovalNames, workspace);
-    applyActiveWorkspaceSlug(state, workspace, requestedSlug);
-    if (workspaceLoadIntents.get(state) === intent) {
-      workspaceLoadIntents.delete(state);
-    }
-    state.error = null;
-    state.loaded = true;
-  } catch (err) {
-    if (generation === state.loadGeneration) {
-      // Retain intent for a later silent retry; explicit navigation or foreground
-      // reload cancels it through the owner paths above.
-      state.error = formatError(err);
-    }
-  } finally {
-    const isCurrent = generation === state.loadGeneration;
-    let shouldNotify = isCurrent || staleDocumentApplied;
-    if (state.loadingGeneration === generation || (isCurrent && state.loadingGeneration !== null)) {
-      // A current silent completion supersedes any older foreground owner; keep
-      // no spinner tied to a response that can only finish stale.
-      state.loadingGeneration = null;
-      state.loading = false;
-      shouldNotify = true;
-    }
-    if (shouldNotify) {
-      notify(state);
-    }
-  }
-}
-
-/**
- * Subscribe to `plugin.workspaces.changed` and refetch on a newer version (skips
- * stale/own-echo events by comparing `workspaceVersion`). Push path per spec-30 —
- * the WS client surfaces event frames via `addEventListener`.
- */
-export function subscribeToWorkspaceEvents(
-  host: WorkspaceHost,
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-): void {
-  if (!client) {
-    stopWorkspaceEvents(host);
-    return;
-  }
-  if (workspaceEventClients.get(host) === client) {
-    return;
-  }
-  stopWorkspaceEvents(host);
-  const unsubscribe = client.addEventListener((evt: GatewayEventFrame) => {
-    if (evt.event !== CHANGED_EVENT) {
-      return;
-    }
-    const payload = isRecord(evt.payload) ? (evt.payload as WorkspaceChangedEvent) : undefined;
-    const incomingVersion = readNumber(payload?.workspaceVersion, Number.NaN);
-    const currentVersion = state.workspace?.workspaceVersion ?? -1;
-    // Skip our own echo / stale replays: only a strictly newer version refetches.
-    if (Number.isFinite(incomingVersion) && incomingVersion <= currentVersion) {
-      return;
-    }
-    void loadWorkspace(state, client, { silent: true });
-  });
-  workspaceEventUnsubscribers.set(host, unsubscribe);
-  workspaceEventClients.set(host, client);
-}
-
-function stopWorkspaceEvents(host: WorkspaceHost): void {
-  workspaceEventUnsubscribers.get(host)?.();
-  workspaceEventUnsubscribers.delete(host);
-  workspaceEventClients.delete(host);
-}
-
-/**
- * Start (idempotently) the per-host data-refresh timer. The timer fires `onTick`
- * every `intervalMs`, but ONLY while the document is visible — a background tab
- * skips the tick so we don't hammer the gateway when nobody's watching. Passing a
- * null client stops any running timer (disconnect). A second call with a live
- * client is a no-op so re-renders don't stack timers.
- */
-export function startBindingPolling(
-  host: WorkspaceHost,
-  client: GatewayBrowserClient | null,
-  onTick: () => void,
-  intervalMs: number = WORKSPACE_POLL_INTERVAL_MS,
-): void {
-  if (!client) {
-    stopBindingPolling(host);
-    return;
-  }
-  if (workspacePollActive.get(host)) {
-    return;
-  }
-  const clamped = Math.max(10_000, intervalMs);
-  const timer = setInterval(() => {
-    // Visibility gate: only refresh when the tab is foreground. On a hidden tab
-    // (or SSR/no-document env) we skip; the next visible render re-resolves.
-    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
-      return;
-    }
-    onTick();
-  }, clamped);
-  workspacePollTimers.set(host, timer);
-  workspacePollActive.set(host, true);
-}
-
-/** Stop the per-host data-refresh timer (tab-leave/disconnect). */
-function stopBindingPolling(host: WorkspaceHost): void {
-  const timer = workspacePollTimers.get(host);
-  if (timer !== undefined) {
-    clearInterval(timer);
-    workspacePollTimers.delete(host);
-  }
-  workspacePollActive.delete(host);
-}
-
-/** Full lifecycle teardown for the bundled-view `stop` hook. */
-export function stopWorkspace(host: WorkspaceHost): void {
-  cancelActiveDrag(host);
-  stopWorkspaceEvents(host);
-  stopBindingPolling(host);
-}
-
-function replaceWidget(
-  workspace: WorkspaceDocument,
-  slug: string,
-  widgetId: string,
-  update: (widget: WorkspaceWidget) => WorkspaceWidget,
-): WorkspaceDocument {
-  return {
-    ...workspace,
-    tabs: workspace.tabs.map((tab) =>
-      tab.slug !== slug
-        ? tab
-        : {
-            ...tab,
-            widgets: tab.widgets.map((widget) =>
-              widget.id === widgetId ? update(widget) : widget,
-            ),
-          },
-    ),
-  };
-}
-
-function removeWidget(
-  workspace: WorkspaceDocument,
-  slug: string,
-  widgetId: string,
-): WorkspaceDocument {
-  return {
-    ...workspace,
-    tabs: workspace.tabs.map((tab) =>
-      tab.slug !== slug
-        ? tab
-        : { ...tab, widgets: tab.widgets.filter((widget) => widget.id !== widgetId) },
-    ),
-  };
-}
-
-/**
- * Run an optimistic mutation: apply `optimistic` locally, fire the RPC, and revert
- * to the pre-mutation snapshot on failure (surfacing `actionError` for a toast).
- * All shell mutations funnel through here so revert semantics stay consistent.
- */
-async function optimisticMutation(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: {
-    widgetId: string;
-    optimistic: (workspace: WorkspaceDocument) => WorkspaceDocument;
-    method: string;
-    rpcParams: Record<string, unknown>;
-  },
-): Promise<void> {
-  const previous = workspaceMutationQueues.get(state) ?? Promise.resolve();
-  const current = previous
-    .catch(() => undefined)
-    .then(async () => {
-      await runOptimisticMutation(state, client, params);
-    });
-  workspaceMutationQueues.set(state, current);
-  await current.finally(() => {
-    if (workspaceMutationQueues.get(state) === current) {
-      workspaceMutationQueues.delete(state);
-    }
-  });
-}
-
-async function runOptimisticMutation(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: {
-    widgetId: string;
-    optimistic: (workspace: WorkspaceDocument) => WorkspaceDocument;
-    method: string;
-    rpcParams: Record<string, unknown>;
-  },
-): Promise<void> {
-  if (!client || !state.workspace) {
-    return;
-  }
-  const previous = state.workspace;
-  const optimistic = params.optimistic(previous);
-  state.workspace = optimistic;
-  state.pendingWidgetIds.add(params.widgetId);
-  state.actionError = null;
-  notify(state);
-  try {
-    await client.request(params.method, params.rpcParams);
-  } catch (err) {
-    // Revert ONLY if we are still showing the exact optimistic doc we installed.
-    // A concurrent loadWorkspace (e.g. a plugin.workspaces.changed refetch) may
-    // have landed a FRESHER doc while the RPC was in flight; reverting to the
-    // stale pre-mutation snapshot in that case would stomp the fresher state.
-    if (state.workspace === optimistic) {
-      state.workspace = previous;
-    }
-    state.actionError = formatError(err);
-  } finally {
-    state.pendingWidgetIds.delete(params.widgetId);
-    notify(state);
-  }
-}
-
-export function moveWidget(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { slug: string; widgetId: string; grid: WorkspaceGridRect },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.move",
-    rpcParams: { tab: params.slug, id: params.widgetId, grid: params.grid },
-    optimistic: (workspace) =>
-      replaceWidget(workspace, params.slug, params.widgetId, (widget) => ({
-        ...widget,
-        grid: params.grid,
-      })),
-  });
-}
-
-export function setWidgetCollapsed(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { slug: string; widgetId: string; collapsed: boolean },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.update",
-    rpcParams: { tab: params.slug, id: params.widgetId, patch: { collapsed: params.collapsed } },
-    optimistic: (workspace) =>
-      replaceWidget(workspace, params.slug, params.widgetId, (widget) => ({
-        ...widget,
-        collapsed: params.collapsed,
-      })),
-  });
-}
-
-export function updateWidgetTitle(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { slug: string; widgetId: string; title: string },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.update",
-    rpcParams: { tab: params.slug, id: params.widgetId, patch: { title: params.title } },
-    optimistic: (workspace) =>
-      replaceWidget(workspace, params.slug, params.widgetId, (widget) => ({
-        ...widget,
-        title: params.title,
-      })),
-  });
-}
-
-export function hideWidget(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { slug: string; widgetId: string },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.update",
-    rpcParams: { tab: params.slug, id: params.widgetId, patch: { hidden: true } },
-    optimistic: (workspace) => removeWidget(workspace, params.slug, params.widgetId),
-  });
-}
-
-export function removeWidgetFromTab(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { slug: string; widgetId: string },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.remove",
-    rpcParams: { tab: params.slug, id: params.widgetId },
-    optimistic: (workspace) => removeWidget(workspace, params.slug, params.widgetId),
-  });
-}
-
-export function moveWidgetToTab(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { fromSlug: string; toSlug: string; widgetId: string },
-): Promise<void> {
-  return optimisticMutation(state, client, {
-    widgetId: params.widgetId,
-    method: "workspaces.widget.move",
-    rpcParams: { tab: params.fromSlug, id: params.widgetId, toTab: params.toSlug },
-    optimistic: (workspace) => {
-      const source = workspace.tabs.find((tab) => tab.slug === params.fromSlug);
-      const widget = source?.widgets.find((w) => w.id === params.widgetId);
-      if (!widget) {
-        return workspace;
-      }
-      return {
-        ...workspace,
-        tabs: workspace.tabs.map((tab) => {
-          if (tab.slug === params.fromSlug) {
-            return { ...tab, widgets: tab.widgets.filter((w) => w.id !== params.widgetId) };
-          }
-          if (tab.slug === params.toSlug) {
-            return { ...tab, widgets: [...tab.widgets, widget] };
-          }
-          return tab;
-        }),
-      };
-    },
-  });
-}
-
-/**
- * Approve or reject a pending custom widget → `workspaces.widget.approve`
- * (`operator.approvals`). The registry is not part of the optimistic widget model, so this fires
- * the RPC and lets the resulting `plugin.workspaces.changed` broadcast refetch the
- * new status; a failure surfaces `actionError` for the toast.
- */
-export async function approveWidget(
-  state: WorkspaceUiState,
-  client: GatewayBrowserClient | null,
-  params: { name: string; decision: "approved" | "rejected" },
-): Promise<void> {
-  if (!client) {
-    return;
-  }
-  if (state.pendingApprovalNames.has(params.name)) {
-    return;
-  }
-  state.pendingApprovalNames.add(params.name);
-  state.actionError = null;
-  notify(state);
-  try {
-    await client.request("workspaces.widget.approve", {
-      name: params.name,
-      decision: params.decision,
-    });
-  } catch (err) {
-    state.actionError = formatError(err);
-    state.pendingApprovalNames.delete(params.name);
-  } finally {
-    notify(state);
-  }
-}
-
-// --- Minimal builtin binding resolution (spec-30 scope; L4 extends) ----------
-
-export type WorkspaceBindingResult = { value: unknown } | { error: string };
-
-/**
- * Resolve a widget binding into a value the builtin renderers consume. Wire is:
- * - `static`: literal value from the binding.
- * - `rpc`: resolved CLIENT-SIDE on the page's own gateway client (00 §3 amendment).
- * - `file`: served by `workspaces.data.read`; the JSON pointer is applied here.
- *
- * `workspaces.data.read` serves file/static only and answers rpc bindings with
- * `{ code: "binding_client_resolved" }`, so rpc never routes through it.
- */
-export async function resolveBinding(
-  client: GatewayBrowserClient | null,
-  binding: WorkspaceBinding,
-): Promise<WorkspaceBindingResult> {
-  try {
-    if (binding.source === "static") {
-      return { value: binding.value };
-    }
-    if (!client) {
-      return { error: "Not connected." };
-    }
-    if (binding.source === "rpc") {
-      if (!binding.method) {
-        return { error: "Binding is missing an rpc method." };
-      }
-      const params =
-        binding.method === "usage.cost" && binding.params?.mode === undefined
-          ? { ...binding.params, ...buildSessionUsageDateParams("local") }
-          : (binding.params ?? {});
-      const value = await client.request(binding.method, params);
-      return { value: applyPointer(value, binding.pointer) };
-    }
-    // file: `workspaces.data.read` accepts ONLY a `binding` param (its readParams
-    // whitelist rejects anything else), and it resolves the file AND applies the
-    // JSON pointer server-side, returning the final value under `data`. So we send
-    // the whole binding and must NOT re-apply the pointer here (that would
-    // double-resolve it).
-    const payload = await client.request("workspaces.data.read", { binding });
-    return { value: isRecord(payload) && "data" in payload ? payload.data : payload };
-  } catch (err) {
-    return { error: formatError(err) };
-  }
-}
-
-/** Apply a JSON pointer (RFC 6901 subset) to a value; returns the value if empty. */
-function applyPointer(value: unknown, pointer: string | undefined): unknown {
-  if (!pointer) {
-    return value;
-  }
-  const segments = pointer
-    .split("/")
-    .slice(1)
-    .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-  let current: unknown = value;
-  for (const segment of segments) {
-    if (Array.isArray(current)) {
-      const index = Number(segment);
-      current = Number.isInteger(index) ? current[index] : undefined;
-    } else if (isRecord(current)) {
-      current = current[segment];
-    } else {
-      return undefined;
-    }
-  }
-  return current;
-}
-
-export { workspaceAgentProvenance };
diff --git a/ui/src/lib/workspace/tab-selection.ts b/ui/src/lib/workspace/tab-selection.ts
deleted file mode 100644
index 18d1fe555cf..00000000000
--- a/ui/src/lib/workspace/tab-selection.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-import type { WorkspaceDocument, WorkspaceTab, WorkspaceWidgetStatus } from "./types.ts";
-
-/** The `custom:<name>` widget name, or null for builtin/unknown kinds. */
-export function customWidgetName(kind: string): string | null {
-  return kind.startsWith("custom:") ? kind.slice("custom:".length) || null : null;
-}
-
-/** Registry status for a custom widget kind, or null when not a tracked custom widget. */
-export function customWidgetStatus(
-  workspace: WorkspaceDocument,
-  kind: string,
-): WorkspaceWidgetStatus | null {
-  const name = customWidgetName(kind);
-  if (!name) {
-    return null;
-  }
-  return workspace.widgetsRegistry[name]?.status ?? null;
-}
-
-/**
- * Tabs in display order: honor `prefs.tabOrder` first, then any doc-order tabs the
- * ordering omits, so a partial `tabOrder` still shows every tab.
- */
-export function orderedTabs(workspace: WorkspaceDocument): WorkspaceTab[] {
-  const bySlug = new Map(workspace.tabs.map((tab) => [tab.slug, tab]));
-  const ordered: WorkspaceTab[] = [];
-  const seen = new Set<string>();
-  for (const slug of workspace.prefs.tabOrder) {
-    const tab = bySlug.get(slug);
-    if (tab && !seen.has(slug)) {
-      ordered.push(tab);
-      seen.add(slug);
-    }
-  }
-  for (const tab of workspace.tabs) {
-    if (!seen.has(tab.slug)) {
-      ordered.push(tab);
-      seen.add(tab.slug);
-    }
-  }
-  return ordered;
-}
-
-export function visibleTabs(workspace: WorkspaceDocument): WorkspaceTab[] {
-  return orderedTabs(workspace).filter((tab) => !tab.hidden);
-}
-
-export function hiddenTabs(workspace: WorkspaceDocument): WorkspaceTab[] {
-  return orderedTabs(workspace).filter((tab) => tab.hidden);
-}
-
-export function findTab(
-  workspace: WorkspaceDocument,
-  slug: string | null,
-): WorkspaceTab | undefined {
-  if (!slug) {
-    return undefined;
-  }
-  return workspace.tabs.find((tab) => tab.slug === slug);
-}
-
-/** Resolve the requested tab or the first available fallback. */
-export function resolveActiveSlug(
-  workspace: WorkspaceDocument,
-  requested: string | null,
-): string | null {
-  const requestedTab = findTab(workspace, requested);
-  if (requestedTab) {
-    return requestedTab.slug;
-  }
-  const firstVisible = visibleTabs(workspace)[0];
-  return firstVisible?.slug ?? orderedTabs(workspace)[0]?.slug ?? null;
-}
diff --git a/ui/src/lib/workspace/types.ts b/ui/src/lib/workspace/types.ts
deleted file mode 100644
index 40ceb8c7b43..00000000000
--- a/ui/src/lib/workspace/types.ts
+++ /dev/null
@@ -1,118 +0,0 @@
-// Control UI workspace types mirror the Workspaces plugin document schema.
-//
-// KEEP IN SYNC: the plugin store in `extensions/workspaces/` owns the canonical
-// schema (00-vision-and-architecture §1). These are the UI-side read models the
-// bundled Workspaces view renders from; only the fields the shell reads are
-// modelled here, and every payload is normalized defensively on load because the
-// gateway boundary is untyped.
-
-export const WORKSPACE_GRID_COLUMNS = 12;
-
-/** Provenance stamp: who authored a tab or widget. `agent:<id>` renders a chip. */
-export type WorkspaceCreatedBy = string;
-
-type WorkspaceWidgetKind = string;
-type WorkspaceTabLayout = "grid" | "full";
-
-type WorkspaceBindingSource = "rpc" | "file" | "static";
-
-export type WorkspaceBinding = {
-  source: WorkspaceBindingSource;
-  /** `rpc` bindings name an allowlisted read method resolved client-side. */
-  method?: string;
-  /** `file` bindings name a path under the plugin's data dir. */
-  path?: string;
-  /** JSON pointer into the resolved document. */
-  pointer?: string;
-  params?: Record<string, unknown>;
-  /** `static` bindings carry their value inline. */
-  value?: unknown;
-};
-
-export type WorkspaceGridRect = {
-  x: number;
-  y: number;
-  w: number;
-  h: number;
-};
-
-export type WorkspaceWidget = {
-  id: string;
-  kind: WorkspaceWidgetKind;
-  title: string;
-  grid: WorkspaceGridRect;
-  collapsed: boolean;
-  createdBy?: WorkspaceCreatedBy;
-  bindings?: Record<string, WorkspaceBinding>;
-  props?: Record<string, unknown>;
-};
-
-export type WorkspaceTab = {
-  slug: string;
-  title: string;
-  icon?: string;
-  hidden: boolean;
-  layout?: WorkspaceTabLayout;
-  createdBy?: WorkspaceCreatedBy;
-  widgets: WorkspaceWidget[];
-};
-
-type WorkspacePrefs = {
-  tabOrder: string[];
-};
-
-/** Custom-widget registry status (00 §6). Only `approved` widgets get an iframe. */
-export type WorkspaceWidgetStatus = "pending" | "approved" | "rejected";
-
-/** UI read model of one `widgetsRegistry` entry (custom-widget approval state). */
-export type WorkspaceWidgetRegistryEntry = {
-  status: WorkspaceWidgetStatus;
-  createdBy?: WorkspaceCreatedBy;
-  approvedBy?: WorkspaceCreatedBy;
-  approvedAt?: string;
-};
-
-export type WorkspaceDocument = {
-  schemaVersion: number;
-  workspaceVersion: number;
-  tabs: WorkspaceTab[];
-  prefs: WorkspacePrefs;
-  /** Custom-widget install/approval state, keyed by widget name (`custom:<name>`). */
-  widgetsRegistry: Record<string, WorkspaceWidgetRegistryEntry>;
-};
-
-/** Capability names a custom widget may hold (00 §2). */
-export type WorkspaceWidgetCapability = "data:read" | "prompt:send";
-
-/**
- * The subset of a custom widget's `widget.json` manifest the parent bridge needs
- * to gate child requests: the approved binding grants and capabilities. Loaded
- * on demand by the host through the authenticated plugin gateway.
- */
-export type WidgetManifestView = {
-  name: string;
-  /** Server-minted capability used in every approved asset path and bridge bootstrap. */
-  frameToken: string;
-  /** Server expiry for the in-memory capability; the host refreshes before this time. */
-  frameExpiresAt?: number;
-  /** The file the sandboxed iframe loads; the manifest declares it. */
-  entrypoint: string;
-  bindings: Record<string, WorkspaceBinding>;
-  capabilities: WorkspaceWidgetCapability[];
-};
-
-/** Payload of the `plugin.workspaces.changed` broadcast (01-conventions §Event naming). */
-export type WorkspaceChangedEvent = {
-  workspaceVersion: number;
-  changedTabSlug?: string;
-  actor?: string;
-};
-
-/** Provenance is an agent authorship when the stamp is prefixed `agent:`. */
-export function workspaceAgentProvenance(createdBy: WorkspaceCreatedBy | undefined): string | null {
-  if (typeof createdBy !== "string") {
-    return null;
-  }
-  const trimmed = createdBy.trim();
-  return trimmed.startsWith("agent:") ? trimmed.slice("agent:".length) || "agent" : null;
-}
diff --git a/ui/src/lib/workspace/widgets/activity.ts b/ui/src/lib/workspace/widgets/activity.ts
deleted file mode 100644
index a79229c9652..00000000000
--- a/ui/src/lib/workspace/widgets/activity.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-// builtin:activity — a compact recent-activity feed over `cron.runs` (scope
-// "all"). Binding value shape: `{ entries: CronRunLogEntry[] }` (see
-// ui/src/api/types.ts CronRunLogEntry). Each entry is a completed run with a ts,
-// job name, status, and optional summary.
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import { clampText, formatDateTimeMs } from "../../format.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-const DEFAULT_LIMIT = 20;
-
-type ActivityEntryModel = {
-  ts: number | null;
-  title: string;
-  detail: string | null;
-  status: string | null;
-};
-
-type ActivityModel = {
-  entries: ActivityEntryModel[];
-  total: number;
-};
-
-function entryTitle(entry: Record<string, unknown>): string {
-  const name = entry.jobName ?? entry.jobId ?? entry.action;
-  return typeof name === "string" && name.trim() ? name : "run";
-}
-
-function mapActivity(widget: WorkspaceWidget, value: unknown): ActivityModel {
-  const raw = isRecord(value) && Array.isArray(value.entries) ? value.entries : [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  const records = raw.filter(isRecord);
-  const entries = records
-    .map((entry) => ({
-      ts: toFiniteNumber(entry.ts) ?? null,
-      title: entryTitle(entry),
-      detail:
-        typeof entry.summary === "string" && entry.summary.trim()
-          ? clampText(entry.summary, 120)
-          : typeof entry.error === "string" && entry.error.trim()
-            ? clampText(entry.error, 120)
-            : null,
-      status: typeof entry.status === "string" ? entry.status : null,
-    }))
-    .slice(0, limit);
-  return { entries, total: records.length };
-}
-
-function statusClass(status: string | null): string {
-  if (status === "ok") {
-    return "workspace-badge--ok";
-  }
-  if (status === "error") {
-    return "workspace-badge--error";
-  }
-  return "workspace-badge--muted";
-}
-
-export function renderActivity(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapActivity(widget, value);
-  if (model.entries.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.activity.empty")}
-    </div>`;
-  }
-  return html`
-    <ul class="workspace-feed" data-test-id="workspace-activity">
-      ${model.entries.map(
-        (entry) => html`
-          <li class="workspace-feed__row">
-            <div class="workspace-feed__head">
-              <span class="workspace-feed__title">${entry.title}</span>
-              ${entry.status
-                ? html`<span class="workspace-badge ${statusClass(entry.status)}"
-                    >${entry.status}</span
-                  >`
-                : nothing}
-              ${entry.ts !== null
-                ? html`<span class="workspace-feed__time">${formatDateTimeMs(entry.ts)}</span>`
-                : nothing}
-            </div>
-            ${entry.detail
-              ? html`<div class="workspace-feed__detail">${entry.detail}</div>`
-              : nothing}
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/agent-status.ts b/ui/src/lib/workspace/widgets/agent-status.ts
deleted file mode 100644
index b87d55d9f0e..00000000000
--- a/ui/src/lib/workspace/widgets/agent-status.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-// Trusted status view over the same read-only sessions.list payload used by the
-// sessions builtin. It never performs RPCs or exposes session write actions.
-
-import { html, nothing, type TemplateResult } from "lit";
-import type { SessionRunStatus } from "../../../api/types.ts";
-import { t } from "../../../i18n/index.ts";
-import { clampText } from "../../format.ts";
-import { isSessionRunActive } from "../../session-run-state.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-const DEFAULT_LIMIT = 8;
-
-type AgentStatusRowModel = {
-  key: string;
-  label: string;
-  active: boolean;
-  task: string | null;
-  progress: number | null;
-};
-
-type AgentStatusModel = {
-  rows: AgentStatusRowModel[];
-  activeCount: number;
-  total: number;
-};
-
-function rowLabel(row: Record<string, unknown>, key: string): string {
-  const display = row.displayName ?? row.label ?? row.subject ?? row.channel;
-  return typeof display === "string" && display.trim() ? display : key;
-}
-
-function rowTask(row: Record<string, unknown>): string | null {
-  const goal = isRecord(row.goal) ? row.goal : undefined;
-  const objective = goal && typeof goal.objective === "string" ? goal.objective.trim() : "";
-  return objective ? clampText(objective, 100) : null;
-}
-
-function rowProgress(row: Record<string, unknown>): number | null {
-  const goal = isRecord(row.goal) ? row.goal : undefined;
-  if (!goal) {
-    return null;
-  }
-  const used = toFiniteNumber(goal.tokensUsed);
-  const budget = toFiniteNumber(goal.tokenBudget);
-  if (used === undefined || budget === undefined || budget <= 0) {
-    return null;
-  }
-  return Math.min(1, Math.max(0, used / budget));
-}
-
-function mapAgentStatus(widget: WorkspaceWidget, value: unknown): AgentStatusModel {
-  const raw = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.sessions)
-      ? value.sessions
-      : [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  const rows = raw
-    .filter(isRecord)
-    .map((row) => {
-      const key = typeof row.key === "string" ? row.key : "";
-      return {
-        key,
-        label: rowLabel(row, key),
-        active: isSessionRunActive({
-          hasActiveRun: typeof row.hasActiveRun === "boolean" ? row.hasActiveRun : undefined,
-          status: typeof row.status === "string" ? (row.status as SessionRunStatus) : undefined,
-        }),
-        task: rowTask(row),
-        progress: rowProgress(row),
-      };
-    })
-    .filter((row) => row.key);
-  return {
-    rows: rows.slice(0, limit),
-    activeCount: rows.filter((row) => row.active).length,
-    total: rows.length,
-  };
-}
-
-export function renderAgentStatus(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapAgentStatus(widget, value);
-  if (model.rows.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.agentStatus.empty")}
-    </div>`;
-  }
-  return html`
-    <ul class="workspace-list workspace-agent-status" data-test-id="workspace-agent-status">
-      ${model.rows.map(
-        (row) => html`
-          <li class="workspace-list__row">
-            <span
-              class="workspace-dot ${row.active ? "workspace-dot--live" : ""}"
-              aria-hidden="true"
-            ></span>
-            <span class="workspace-list__label">${row.label}</span>
-            <span
-              class="workspace-badge ${row.active
-                ? "workspace-badge--ok"
-                : "workspace-badge--muted"}"
-            >
-              ${row.active
-                ? t("workspaces.widget.agentStatus.busy")
-                : t("workspaces.widget.agentStatus.idle")}
-            </span>
-            ${row.task ? html`<span class="workspace-list__meta">${row.task}</span>` : nothing}
-            ${row.progress !== null
-              ? html`<span class="workspace-list__meta"
-                  >${t("workspaces.widget.agentStatus.progress", {
-                    percent: String(Math.round(row.progress * 100)),
-                  })}</span
-                >`
-              : nothing}
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/chart.ts b/ui/src/lib/workspace/widgets/chart.ts
deleted file mode 100644
index 37306fdc384..00000000000
--- a/ui/src/lib/workspace/widgets/chart.ts
+++ /dev/null
@@ -1,275 +0,0 @@
-import { html, svg, type SVGTemplateResult, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-type ChartType = "line" | "bar" | "area" | "sparkline" | "gauge";
-
-type ChartDataResult = { ok: true; values: number[] } | { ok: false; reason: string };
-type ChartModel =
-  | { status: "empty" }
-  | { status: "error"; reason: string }
-  | {
-      status: "ready";
-      type: ChartType;
-      values: number[];
-      min: number;
-      max: number;
-      dataMin: number;
-      dataMax: number;
-    };
-
-const CHART_TYPES = new Set<ChartType>(["line", "bar", "area", "sparkline", "gauge"]);
-const MAX_CHART_POINTS = 500;
-const VIEW_WIDTH = 100;
-const VIEW_HEIGHT = 40;
-const PADDING = 2;
-
-function greaterFiniteBound(value: number): number | undefined {
-  if (value === Number.MAX_VALUE) {
-    return undefined;
-  }
-  return value >= 0 ? Math.min(value * 2 || 1, Number.MAX_VALUE) : value / 2;
-}
-
-function lesserFiniteBound(value: number): number | undefined {
-  if (value === -Number.MAX_VALUE) {
-    return undefined;
-  }
-  return value <= 0 ? Math.max(value * 2 || -1, -Number.MAX_VALUE) : value / 2;
-}
-
-function pointValue(value: unknown): number | undefined {
-  if (typeof value === "number") {
-    return Number.isFinite(value) ? value : undefined;
-  }
-  if (!isRecord(value)) {
-    return undefined;
-  }
-  return toFiniteNumber(value.y) ?? toFiniteNumber(value.value);
-}
-
-function normalizeChartData(value: unknown): ChartDataResult {
-  const points = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.points)
-      ? value.points
-      : null;
-  if (points === null) {
-    return { ok: false, reason: "expected an array or an object with a points array" };
-  }
-  if (points.length > MAX_CHART_POINTS) {
-    return { ok: false, reason: `chart data exceeds ${MAX_CHART_POINTS} points` };
-  }
-  const values: number[] = [];
-  for (const point of points) {
-    const numeric = pointValue(point);
-    if (numeric === undefined) {
-      return { ok: false, reason: "every chart point must contain a finite numeric value" };
-    }
-    values.push(numeric);
-  }
-  return { ok: true, values };
-}
-
-function mapChart(widget: WorkspaceWidget, value: unknown): ChartModel {
-  const props = widgetProps(widget);
-  const rawType = props.type === undefined ? "line" : props.type;
-  if (typeof rawType !== "string" || !CHART_TYPES.has(rawType as ChartType)) {
-    return { status: "error", reason: "unsupported chart type" };
-  }
-  const data = normalizeChartData(value);
-  if (!data.ok) {
-    return { status: "error", reason: data.reason };
-  }
-  const configuredMin = props.min === undefined ? undefined : toFiniteNumber(props.min);
-  const configuredMax = props.max === undefined ? undefined : toFiniteNumber(props.max);
-  if (
-    (props.min !== undefined && configuredMin === undefined) ||
-    (props.max !== undefined && configuredMax === undefined)
-  ) {
-    return { status: "error", reason: "chart bounds must be finite numbers" };
-  }
-  if (
-    configuredMin !== undefined &&
-    configuredMax !== undefined &&
-    configuredMin >= configuredMax
-  ) {
-    return { status: "error", reason: "chart minimum must be less than maximum" };
-  }
-  if (data.values.length === 0) {
-    return { status: "empty" };
-  }
-  const dataMin = Math.min(...data.values);
-  const dataMax = Math.max(...data.values);
-  const includesZeroByDefault = rawType === "bar" || rawType === "gauge";
-  let min = configuredMin ?? (includesZeroByDefault ? Math.min(dataMin, 0) : dataMin);
-  let max = configuredMax ?? (includesZeroByDefault ? Math.max(dataMax, 0) : dataMax);
-  if (min >= max) {
-    if (configuredMin !== undefined) {
-      const expanded = greaterFiniteBound(min);
-      if (expanded === undefined) {
-        return { status: "error", reason: "chart bounds cannot form a finite range" };
-      }
-      max = expanded;
-    } else if (configuredMax !== undefined) {
-      const expanded = lesserFiniteBound(max);
-      if (expanded === undefined) {
-        return { status: "error", reason: "chart bounds cannot form a finite range" };
-      }
-      min = expanded;
-    } else if (min > 0) {
-      min = lesserFiniteBound(min) ?? min;
-    } else if (max < 0) {
-      max = greaterFiniteBound(max) ?? max;
-    } else {
-      min = -1;
-      max = 1;
-    }
-  }
-  return {
-    status: "ready",
-    type: rawType as ChartType,
-    values: data.values,
-    min,
-    max,
-    dataMin,
-    dataMax,
-  };
-}
-
-function xScale(index: number, count: number): number {
-  return count === 1
-    ? VIEW_WIDTH / 2
-    : PADDING + (index / (count - 1)) * (VIEW_WIDTH - PADDING * 2);
-}
-
-function yScale(value: number, min: number, max: number): number {
-  const boundedValue = Math.min(Math.max(value, min), max);
-  const scale = Math.max(Math.abs(boundedValue), Math.abs(min), Math.abs(max), 1);
-  const fraction = (boundedValue / scale - min / scale) / (max / scale - min / scale);
-  return VIEW_HEIGHT - PADDING - fraction * (VIEW_HEIGHT - PADDING * 2);
-}
-
-function linePoints(model: Extract<ChartModel, { status: "ready" }>): string {
-  return model.values
-    .map(
-      (value, index) =>
-        `${xScale(index, model.values.length)},${yScale(value, model.min, model.max)}`,
-    )
-    .join(" ");
-}
-
-function drawLine(model: Extract<ChartModel, { status: "ready" }>): SVGTemplateResult {
-  if (model.values.length === 1) {
-    return svg`<circle
-      class="workspace-chart__point"
-      cx=${xScale(0, 1)}
-      cy=${yScale(model.values[0]!, model.min, model.max)}
-      r="1.5"
-    />`;
-  }
-  return svg`<polyline class="workspace-chart__line" fill="none" points=${linePoints(model)} />`;
-}
-
-function drawArea(model: Extract<ChartModel, { status: "ready" }>): SVGTemplateResult {
-  const first = xScale(0, model.values.length);
-  const last = xScale(model.values.length - 1, model.values.length);
-  const baseline = VIEW_HEIGHT - PADDING;
-  return svg`<g>
-    <polygon class="workspace-chart__area" points=${`${first},${baseline} ${linePoints(model)} ${last},${baseline}`} />
-    ${drawLine(model)}
-  </g>`;
-}
-
-function drawBars(model: Extract<ChartModel, { status: "ready" }>): SVGTemplateResult {
-  const slot = (VIEW_WIDTH - PADDING * 2) / model.values.length;
-  const gap = Math.min(1, slot * 0.2);
-  const baseline = yScale(Math.min(Math.max(0, model.min), model.max), model.min, model.max);
-  return svg`<g class="workspace-chart__bars">
-    ${model.values.map((value, index) => {
-      const y = yScale(value, model.min, model.max);
-      const height = Math.abs(baseline - y);
-      return svg`<rect
-        x=${PADDING + index * slot + gap / 2}
-        y=${Math.min(y, baseline)}
-        width=${slot - gap}
-        height=${height === 0 ? 0 : Math.max(height, 0.5)}
-      />`;
-    })}
-  </g>`;
-}
-
-function drawGauge(model: Extract<ChartModel, { status: "ready" }>): SVGTemplateResult {
-  const current = model.values.at(-1) ?? model.min;
-  const scale = Math.max(Math.abs(current), Math.abs(model.min), Math.abs(model.max), 1);
-  const fraction = (current / scale - model.min / scale) / (model.max / scale - model.min / scale);
-  const bounded = Math.min(Math.max(fraction, 0), 1);
-  const centerX = VIEW_WIDTH / 2;
-  const centerY = VIEW_HEIGHT - PADDING;
-  const radius = VIEW_HEIGHT - PADDING * 2;
-  const polar = (position: number) => {
-    const angle = Math.PI - position * Math.PI;
-    return {
-      x: centerX + radius * Math.cos(angle),
-      y: centerY - radius * Math.sin(angle),
-    };
-  };
-  const start = polar(0);
-  const end = polar(1);
-  const currentPoint = polar(bounded);
-  return svg`<g class="workspace-chart__gauge">
-    <path class="workspace-chart__gauge-track" fill="none" d=${`M ${start.x} ${start.y} A ${radius} ${radius} 0 0 1 ${end.x} ${end.y}`} />
-    <path class="workspace-chart__gauge-fill" fill="none" d=${`M ${start.x} ${start.y} A ${radius} ${radius} 0 0 1 ${currentPoint.x} ${currentPoint.y}`} />
-    <line class="workspace-chart__gauge-needle" x1=${centerX} y1=${centerY} x2=${currentPoint.x} y2=${currentPoint.y} />
-  </g>`;
-}
-
-function drawChart(model: Extract<ChartModel, { status: "ready" }>): SVGTemplateResult {
-  switch (model.type) {
-    case "bar":
-      return drawBars(model);
-    case "area":
-      return drawArea(model);
-    case "gauge":
-      return drawGauge(model);
-    default:
-      return drawLine(model);
-  }
-}
-
-export function renderChart(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapChart(widget, value);
-  if (model.status === "empty") {
-    return html`<div class="workspace-widget__placeholder" data-test-id="workspace-chart-empty">
-      ${t("workspaces.widget.chart.empty")}
-    </div>`;
-  }
-  if (model.status === "error") {
-    return html`<div
-      class="workspace-widget__error"
-      data-test-id="workspace-chart-error"
-      role="status"
-    >
-      <span class="workspace-widget__error-title">${t("workspaces.widget.chart.invalid")}</span>
-    </div>`;
-  }
-  const label = widget.title || t("workspaces.widget.chart.label");
-  return html`<div class="workspace-chart workspace-chart--${model.type}">
-    <svg
-      class="workspace-chart__svg"
-      viewBox="0 0 ${VIEW_WIDTH} ${VIEW_HEIGHT}"
-      preserveAspectRatio="none"
-      role="img"
-      aria-label=${t("workspaces.widget.chart.summary", {
-        title: label,
-        count: String(model.values.length),
-        min: String(model.dataMin),
-        max: String(model.dataMax),
-      })}
-      data-test-id="workspace-chart"
-    >
-      ${drawChart(model)}
-    </svg>
-  </div>`;
-}
diff --git a/ui/src/lib/workspace/widgets/cron.ts b/ui/src/lib/workspace/widgets/cron.ts
deleted file mode 100644
index 2767d08b42e..00000000000
--- a/ui/src/lib/workspace/widgets/cron.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-// builtin:cron — next runs + last status per job over `cron.list`. Binding value
-// shape: `{ jobs: CronJob[] }` where each job carries `state.nextRunAtMs` and
-// `state.lastRunStatus` (see ui/src/api/types.ts CronJob / CronJobState).
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import { formatDateTimeMs } from "../../format.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-const DEFAULT_LIMIT = 8;
-
-type CronJobModel = {
-  id: string;
-  name: string;
-  enabled: boolean;
-  nextRunAtMs: number | null;
-  lastStatus: string | null;
-};
-
-type CronModel = {
-  jobs: CronJobModel[];
-  total: number;
-};
-
-function jobStatus(state: Record<string, unknown> | undefined): string | null {
-  if (!state) {
-    return null;
-  }
-  const status = state.lastRunStatus ?? state.lastStatus;
-  return typeof status === "string" ? status : null;
-}
-
-function mapCron(widget: WorkspaceWidget, value: unknown): CronModel {
-  const raw = isRecord(value) && Array.isArray(value.jobs) ? value.jobs : [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  const records = raw.filter(isRecord);
-  const jobs = records
-    .map((job) => {
-      const state = isRecord(job.state) ? job.state : undefined;
-      return {
-        id: typeof job.id === "string" ? job.id : "",
-        name: typeof job.name === "string" && job.name.trim() ? job.name : (job.id as string) || "",
-        enabled: job.enabled !== false,
-        nextRunAtMs: state ? (toFiniteNumber(state.nextRunAtMs) ?? null) : null,
-        lastStatus: jobStatus(state),
-      };
-    })
-    .filter((job) => job.id)
-    .slice(0, limit);
-  return { jobs, total: records.length };
-}
-
-function statusClass(status: string | null): string {
-  if (status === "ok") {
-    return "workspace-badge--ok";
-  }
-  if (status === "error") {
-    return "workspace-badge--error";
-  }
-  return "workspace-badge--muted";
-}
-
-export function renderCron(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapCron(widget, value);
-  if (model.jobs.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.cron.empty")}
-    </div>`;
-  }
-  return html`
-    <ul class="workspace-list workspace-cron" data-test-id="workspace-cron">
-      ${model.jobs.map(
-        (job) => html`
-          <li class="workspace-list__row ${job.enabled ? "" : "workspace-list__row--disabled"}">
-            <span class="workspace-list__label">${job.name}</span>
-            <span class="workspace-list__meta">
-              ${job.nextRunAtMs !== null
-                ? t("workspaces.widget.cron.next", { time: formatDateTimeMs(job.nextRunAtMs) })
-                : t("workspaces.widget.cron.noNext")}
-            </span>
-            ${job.lastStatus
-              ? html`<span class="workspace-badge ${statusClass(job.lastStatus)}"
-                  >${job.lastStatus}</span
-                >`
-              : nothing}
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/custom-widget-approvals.ts b/ui/src/lib/workspace/widgets/custom-widget-approvals.ts
deleted file mode 100644
index 476b185ee39..00000000000
--- a/ui/src/lib/workspace/widgets/custom-widget-approvals.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-// Pending custom-widget decisions only. The source is derived from the trusted
-// workspace registry; controls appear only with operator.approvals access.
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import { workspaceAgentProvenance } from "../types.ts";
-import type { WorkspaceDocument, WorkspaceWidget } from "../types.ts";
-import {
-  toFiniteNumber,
-  widgetProps,
-  type BuiltinWidgetContext,
-  type CustomWidgetApprovalDecision,
-  type CustomWidgetApprovalsSource,
-  type PendingCustomWidgetApproval,
-} from "./types.ts";
-
-const DEFAULT_LIMIT = 8;
-
-type CustomWidgetApprovalsModel = { items: PendingCustomWidgetApproval[]; total: number };
-
-function toRegistryDecision(decision: CustomWidgetApprovalDecision): "approved" | "rejected" {
-  return decision === "approve" ? "approved" : "rejected";
-}
-
-export function buildCustomWidgetApprovalsSource(
-  workspace: WorkspaceDocument,
-  deciding: ReadonlySet<string>,
-  resolve?: (name: string, decision: "approved" | "rejected") => void,
-): CustomWidgetApprovalsSource {
-  const pending = Object.entries(workspace.widgetsRegistry)
-    .filter(([, entry]) => entry.status === "pending")
-    .map(([name, entry]) => ({
-      id: name,
-      title: name,
-      requestedBy: workspaceAgentProvenance(entry.createdBy),
-      deciding: deciding.has(name),
-    }));
-  return {
-    pending,
-    ...(resolve
-      ? { onDecide: (item, decision) => resolve(item.id, toRegistryDecision(decision)) }
-      : {}),
-  };
-}
-
-function mapCustomWidgetApprovals(
-  widget: WorkspaceWidget,
-  source: CustomWidgetApprovalsSource | undefined,
-): CustomWidgetApprovalsModel {
-  const pending = source?.pending.filter((item) => item.id) ?? [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  return { items: pending.slice(0, limit), total: pending.length };
-}
-
-export function renderCustomWidgetApprovals(
-  widget: WorkspaceWidget,
-  _value: unknown,
-  ctx: BuiltinWidgetContext,
-): TemplateResult {
-  const source = ctx.customWidgetApprovals;
-  const model = mapCustomWidgetApprovals(widget, source);
-  if (model.items.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.customWidgetApprovals.empty")}
-    </div>`;
-  }
-  return html`
-    <ul
-      class="workspace-list workspace-custom-widget-approvals"
-      data-test-id="workspace-custom-widget-approvals"
-    >
-      ${model.items.map(
-        (item) => html`
-          <li class="workspace-list__row workspace-custom-widget-approvals__row">
-            <span class="workspace-badge workspace-badge--muted"
-              >${t("workspaces.widget.customWidgetApprovals.kind")}</span
-            >
-            <span class="workspace-list__label">${item.title}</span>
-            ${item.requestedBy
-              ? html`<span
-                  class="workspace-list__meta workspace-custom-widget-approvals__requested-by"
-                  >${t("workspaces.widget.customWidgetApprovals.requestedBy", {
-                    agent: item.requestedBy,
-                  })}</span
-                >`
-              : nothing}
-            <span class="workspace-custom-widget-approvals__actions">
-              <button
-                class="btn btn--small btn--primary"
-                type="button"
-                data-test-id="workspace-custom-widget-approve"
-                ?disabled=${!source?.onDecide || item.deciding}
-                @click=${() => source?.onDecide?.(item, "approve")}
-              >
-                ${t("workspaces.widget.customWidgetApprovals.approve")}
-              </button>
-              <button
-                class="btn btn--small"
-                type="button"
-                data-test-id="workspace-custom-widget-reject"
-                ?disabled=${!source?.onDecide || item.deciding}
-                @click=${() => source?.onDecide?.(item, "reject")}
-              >
-                ${t("workspaces.widget.customWidgetApprovals.reject")}
-              </button>
-            </span>
-            ${source?.onDecide
-              ? nothing
-              : html`<span
-                  class="workspace-list__meta workspace-custom-widget-approvals__permission"
-                  role="note"
-                  >${t("workspaces.widget.customWidgetApprovals.permissionRequired")}</span
-                >`}
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/iframe-embed.ts b/ui/src/lib/workspace/widgets/iframe-embed.ts
deleted file mode 100644
index 2f7c1300477..00000000000
--- a/ui/src/lib/workspace/widgets/iframe-embed.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-// builtin:iframe-embed — an embedded URL (dev-server preview, hosted report).
-//
-// `props.url` is authored by whoever added the widget, which includes an agent —
-// and a builtin needs no approval. So this embed is capped at the `"scripts"`
-// sandbox ceiling: `embedSandboxMode: "trusted"` grants `allow-same-origin` for
-// chat embeds, and a same-origin scripted frame pointed at the Control UI could
-// read the parent's storage and script it. The chat path avoids this by allowing
-// same-origin only for canvas host paths (`sanitizeCanvasEntryUrl`); here the
-// ceiling does the same job without a path allowlist.
-// External http(s) URLs stay blocked unless `config.allowExternalEmbedUrls`.
-
-import { html, nothing, type TemplateResult } from "lit";
-import { ref, type Ref } from "lit/directives/ref.js";
-import { t } from "../../../i18n/index.ts";
-import { resolveEmbedSandbox } from "../../chat/tool-display.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import type { BuiltinWidgetContext } from "./types.ts";
-import { widgetProps } from "./types.ts";
-
-/**
- * Hard cap on the embed sandbox. `allow-same-origin` is never granted, whatever
- * the operator configured for chat embeds — see the module comment.
- */
-const EMBED_SANDBOX_CEILING = "scripts" as const;
-
-function resolveWorkspaceEmbedSandbox(
-  mode: BuiltinWidgetContext["embed"]["embedSandboxMode"],
-): string {
-  return resolveEmbedSandbox(mode, EMBED_SANDBOX_CEILING);
-}
-
-type EmbedUrlDecision =
-  | { status: "missing" }
-  | { status: "blocked"; reason: "external" | "scheme"; url: string }
-  | { status: "ok"; url: string; external: boolean };
-
-/**
- * Resolve `props.url` against the embed policy. Relative URLs and same-origin
- * absolute URLs are internal and always allowed. Absolute http(s) URLs to a
- * different origin are external and require `allowExternalEmbedUrls`. Any other
- * scheme (javascript:, data:, file:, …) is rejected outright.
- */
-export function evaluateEmbedUrl(
-  rawUrl: unknown,
-  policy: { allowExternalEmbedUrls: boolean },
-  origin?: string,
-): EmbedUrlDecision {
-  if (typeof rawUrl !== "string" || !rawUrl.trim()) {
-    return { status: "missing" };
-  }
-  const url = rawUrl.trim();
-  const base = origin ?? (typeof window !== "undefined" ? window.location.origin : undefined);
-  let parsed: URL;
-  try {
-    // A relative URL resolves against the current origin; an absolute URL keeps
-    // its own. Without a base, relative URLs cannot be classified — treat as
-    // internal (they cannot escape the current document).
-    parsed = base ? new URL(url, base) : new URL(url);
-  } catch {
-    // Relative URL with no base to resolve against: internal by construction.
-    return { status: "ok", url, external: false };
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    return { status: "blocked", reason: "scheme", url };
-  }
-  const external = base ? parsed.origin !== new URL(base).origin : true;
-  if (external && !policy.allowExternalEmbedUrls) {
-    return { status: "blocked", reason: "external", url };
-  }
-  return { status: "ok", url, external };
-}
-
-export function renderWorkspaceEmbedFrame(params: {
-  widget: WorkspaceWidget;
-  url: string;
-  ctx: BuiltinWidgetContext;
-  className: string;
-  testId: string;
-  frameRef?: Ref<HTMLIFrameElement>;
-}): TemplateResult {
-  return html`<iframe
-    class=${params.className}
-    data-test-id=${params.testId}
-    ${params.frameRef ? ref(params.frameRef) : nothing}
-    src=${params.url}
-    title=${params.widget.title}
-    sandbox=${resolveWorkspaceEmbedSandbox(params.ctx.embed.embedSandboxMode)}
-    referrerpolicy="no-referrer"
-    loading="lazy"
-  ></iframe>`;
-}
-
-export function renderIframeEmbed(
-  widget: WorkspaceWidget,
-  _value: unknown,
-  ctx: BuiltinWidgetContext,
-): TemplateResult {
-  const decision = evaluateEmbedUrl(widgetProps(widget).url, {
-    allowExternalEmbedUrls: ctx.embed.allowExternalEmbedUrls,
-  });
-  if (decision.status === "missing") {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.embed.missing")}
-    </div>`;
-  }
-  if (decision.status === "blocked") {
-    return html`<div class="workspace-widget__placeholder" data-test-id="workspace-embed-blocked">
-      ${decision.reason === "external"
-        ? t("workspaces.widget.embed.blockedExternal")
-        : t("workspaces.widget.embed.blockedScheme")}
-    </div>`;
-  }
-  return renderWorkspaceEmbedFrame({
-    widget,
-    url: decision.url,
-    ctx,
-    className: "workspace-embed__frame",
-    testId: "workspace-embed-frame",
-  });
-}
diff --git a/ui/src/lib/workspace/widgets/index.ts b/ui/src/lib/workspace/widgets/index.ts
deleted file mode 100644
index af205e5239e..00000000000
--- a/ui/src/lib/workspace/widgets/index.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-// Registry of L4 builtin widget renderers, consumed by the widget cell's
-// dispatch (ui/src/components/workspace-widget-cell.ts). Keys are the bare kind
-// (`builtin:<name>` with the prefix stripped). Adding a builtin = add a module +
-// one entry here; the plugin schema's BUILTIN_KIND_PATTERN must list the same
-// names (extensions/workspaces/src/schema.ts).
-
-import { renderActivity } from "./activity.ts";
-import { renderAgentStatus } from "./agent-status.ts";
-import { renderChart } from "./chart.ts";
-import { renderCron } from "./cron.ts";
-import { renderCustomWidgetApprovals } from "./custom-widget-approvals.ts";
-import { renderIframeEmbed } from "./iframe-embed.ts";
-import { renderInstances } from "./instances.ts";
-import { renderMarkdown } from "./markdown.ts";
-import { renderPreview } from "./preview.ts";
-import { renderSessions } from "./sessions.ts";
-import { renderStatCard } from "./stat-card.ts";
-import { renderTable } from "./table.ts";
-import type { BuiltinWidgetRenderer } from "./types.ts";
-import { renderUsage } from "./usage.ts";
-
-const BUILTIN_WIDGET_RENDERERS: Record<string, BuiltinWidgetRenderer> = {
-  "stat-card": (widget, value) => renderStatCard(widget, value),
-  markdown: (widget, value) => renderMarkdown(widget, value),
-  table: (widget, value) => renderTable(widget, value),
-  "iframe-embed": renderIframeEmbed,
-  preview: renderPreview,
-  sessions: (widget, value, context) => renderSessions(widget, value, context.basePath),
-  usage: (widget, value) => renderUsage(widget, value),
-  cron: (widget, value) => renderCron(widget, value),
-  instances: (widget, value) => renderInstances(widget, value),
-  activity: (widget, value) => renderActivity(widget, value),
-  chart: (widget, value) => renderChart(widget, value),
-  "agent-status": (widget, value) => renderAgentStatus(widget, value),
-  "custom-widget-approvals": renderCustomWidgetApprovals,
-};
-
-export function getBuiltinRenderer(kind: string): BuiltinWidgetRenderer | undefined {
-  const name = kind.startsWith("builtin:") ? kind.slice("builtin:".length) : kind;
-  return BUILTIN_WIDGET_RENDERERS[name];
-}
-
-export type { BuiltinWidgetContext } from "./types.ts";
diff --git a/ui/src/lib/workspace/widgets/instances.ts b/ui/src/lib/workspace/widgets/instances.ts
deleted file mode 100644
index df6be4497b5..00000000000
--- a/ui/src/lib/workspace/widgets/instances.ts
+++ /dev/null
@@ -1,101 +0,0 @@
-// builtin:instances — connected instances + health over `system-presence`
-// (PresenceEntry[]; see ui/src/api/types.ts). Each entry is a live gateway/node
-// presence row; the widget shows the host/instance, mode, and an idle-derived
-// health dot. Thin re-implementation — the instances page owns its own masking
-// and refresh state.
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import { formatMs } from "../../format.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-const DEFAULT_LIMIT = 8;
-// A presence row idle beyond this window renders as degraded rather than live.
-const HEALTHY_IDLE_SECONDS = 120;
-
-type InstanceModel = {
-  id: string;
-  detail: string | null;
-  healthy: boolean;
-  lastInputMs: number | null;
-};
-
-type InstancesModel = {
-  instances: InstanceModel[];
-  total: number;
-};
-
-function instanceId(entry: Record<string, unknown>): string {
-  const candidate = entry.instanceId ?? entry.host ?? entry.ip ?? entry.deviceFamily;
-  return typeof candidate === "string" && candidate.trim() ? candidate : "";
-}
-
-function instanceDetail(entry: Record<string, unknown>): string | null {
-  const parts = [entry.mode, entry.platform, entry.version].filter(
-    (part): part is string => typeof part === "string" && part.trim().length > 0,
-  );
-  return parts.length > 0 ? parts.join(" · ") : null;
-}
-
-function mapInstances(widget: WorkspaceWidget, value: unknown): InstancesModel {
-  const raw = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.presence)
-      ? value.presence
-      : isRecord(value) && Array.isArray(value.nodes)
-        ? value.nodes
-        : [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  const records = raw.filter(isRecord);
-  const instances = records
-    .map((entry) => {
-      const lastInputSeconds = toFiniteNumber(entry.lastInputSeconds);
-      return {
-        id: instanceId(entry),
-        detail: instanceDetail(entry),
-        healthy: lastInputSeconds === undefined || lastInputSeconds <= HEALTHY_IDLE_SECONDS,
-        lastInputMs: lastInputSeconds !== undefined ? lastInputSeconds * 1000 : null,
-      };
-    })
-    .filter((entry) => entry.id)
-    .slice(0, limit);
-  return { instances, total: records.length };
-}
-
-export function renderInstances(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapInstances(widget, value);
-  if (model.instances.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.instances.empty")}
-    </div>`;
-  }
-  return html`
-    <ul class="workspace-list workspace-instances" data-test-id="workspace-instances">
-      ${model.instances.map(
-        (instance) => html`
-          <li class="workspace-list__row">
-            <span
-              class="workspace-dot ${instance.healthy
-                ? "workspace-dot--ok"
-                : "workspace-dot--warn"}"
-              aria-hidden="true"
-            ></span>
-            <span class="workspace-list__label">${instance.id}</span>
-            ${instance.detail
-              ? html`<span class="workspace-list__meta">${instance.detail}</span>`
-              : nothing}
-            ${instance.lastInputMs !== null
-              ? html`<span class="workspace-list__meta"
-                  >${t("workspaces.widget.instances.idle", {
-                    duration: formatMs(instance.lastInputMs),
-                  })}</span
-                >`
-              : nothing}
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/markdown.ts b/ui/src/lib/workspace/widgets/markdown.ts
deleted file mode 100644
index 9e63df1ef8e..00000000000
--- a/ui/src/lib/workspace/widgets/markdown.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// builtin:markdown — renders a markdown body from a `content` binding (file /
-// static) or `props.markdown` / `props.text`. Reuses the repo's sanitizing
-// markdown util so the same allowlist/sanitizer governs workspace and chat.
-
-import { html, type TemplateResult } from "lit";
-import { unsafeHTML } from "lit/directives/unsafe-html.js";
-import { toSanitizedMarkdownHtml } from "../../../components/markdown.ts";
-import { t } from "../../../i18n/index.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { widgetProps } from "./types.ts";
-
-function mapMarkdownSource(widget: WorkspaceWidget, value: unknown): string {
-  const props = widgetProps(widget);
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof props.markdown === "string") {
-    return props.markdown;
-  }
-  if (typeof props.text === "string") {
-    return props.text;
-  }
-  return "";
-}
-
-export function renderMarkdown(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const source = mapMarkdownSource(widget, value);
-  if (!source.trim()) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.markdownEmpty")}
-    </div>`;
-  }
-  return html`<div class="workspace-markdown markdown-body">
-    ${unsafeHTML(toSanitizedMarkdownHtml(source))}
-  </div>`;
-}
diff --git a/ui/src/lib/workspace/widgets/preview.ts b/ui/src/lib/workspace/widgets/preview.ts
deleted file mode 100644
index c45e89f4d12..00000000000
--- a/ui/src/lib/workspace/widgets/preview.ts
+++ /dev/null
@@ -1,105 +0,0 @@
-// builtin:preview — an agent-authored live URL with reload and viewport controls.
-// It deliberately shares iframe-embed's URL gate and sandbox ceiling: even an
-// operator-trusted chat embed must not grant this builtin same-origin access.
-
-import { html, type TemplateResult } from "lit";
-import { createRef } from "lit/directives/ref.js";
-import { t } from "../../../i18n/index.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { evaluateEmbedUrl, renderWorkspaceEmbedFrame } from "./iframe-embed.ts";
-import type { BuiltinWidgetContext, PreviewViewport } from "./types.ts";
-import { widgetProps } from "./types.ts";
-
-const PREVIEW_VIEWPORTS: readonly PreviewViewport[] = ["desktop", "tablet", "mobile"];
-
-function mapPreviewViewport(widget: WorkspaceWidget): PreviewViewport {
-  const raw = widgetProps(widget).defaultViewport;
-  return raw === "tablet" || raw === "mobile" ? raw : "desktop";
-}
-
-function viewportClass(viewport: PreviewViewport): string {
-  return `workspace-preview__frame-wrap workspace-preview__frame-wrap--${viewport}`;
-}
-
-export function renderPreview(
-  widget: WorkspaceWidget,
-  value: unknown,
-  ctx: BuiltinWidgetContext,
-): TemplateResult {
-  // A declared primary binding owns the preview URL, including malformed
-  // values. Falling back to props would hide broken or hostile binding data.
-  const hasBinding = Object.hasOwn(widget.bindings ?? {}, "value");
-  const rawUrl = hasBinding ? value : widgetProps(widget).url;
-  const decision = evaluateEmbedUrl(rawUrl, {
-    allowExternalEmbedUrls: ctx.embed.allowExternalEmbedUrls,
-  });
-  if (decision.status === "missing") {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.preview.missing")}
-    </div>`;
-  }
-  if (decision.status === "blocked") {
-    return html`<div class="workspace-widget__placeholder" data-test-id="workspace-preview-blocked">
-      ${decision.reason === "external"
-        ? t("workspaces.widget.preview.blockedExternal")
-        : t("workspaces.widget.preview.blockedScheme")}
-    </div>`;
-  }
-
-  const selectedViewport = ctx.preview.getViewport(widget.id, mapPreviewViewport(widget));
-  const frameRef = createRef<HTMLIFrameElement>();
-
-  const reload = () => {
-    const frame = frameRef.value;
-    const src = frame?.getAttribute("src");
-    if (frame && src !== null && src !== undefined) {
-      frame.setAttribute("src", src);
-    }
-  };
-
-  return html`<div class="workspace-preview">
-    <div
-      class="workspace-preview__toolbar"
-      role="toolbar"
-      aria-label=${t("workspaces.widget.preview.toolbar")}
-    >
-      <div
-        class="workspace-preview__viewports"
-        role="group"
-        aria-label=${t("workspaces.widget.preview.viewport.label")}
-      >
-        ${PREVIEW_VIEWPORTS.map(
-          (viewport) => html`<button
-            class="workspace-preview__viewport"
-            type="button"
-            data-test-id=${`workspace-preview-viewport-${viewport}`}
-            aria-label=${t(`workspaces.widget.preview.viewport.${viewport}`)}
-            aria-pressed=${String(viewport === selectedViewport)}
-            @click=${() => ctx.preview.setViewport(widget.id, viewport)}
-          >
-            ${t(`workspaces.widget.preview.viewport.${viewport}`)}
-          </button>`,
-        )}
-      </div>
-      <button
-        class="workspace-preview__reload"
-        type="button"
-        data-test-id="workspace-preview-reload"
-        aria-label=${t("workspaces.widget.preview.reload")}
-        @click=${reload}
-      >
-        ${t("workspaces.widget.preview.reload")}
-      </button>
-    </div>
-    <div class=${viewportClass(selectedViewport)}>
-      ${renderWorkspaceEmbedFrame({
-        widget,
-        url: decision.url,
-        ctx,
-        className: "workspace-embed__frame workspace-preview__frame",
-        testId: "workspace-preview-frame",
-        frameRef,
-      })}
-    </div>
-  </div>`;
-}
diff --git a/ui/src/lib/workspace/widgets/sessions.ts b/ui/src/lib/workspace/widgets/sessions.ts
deleted file mode 100644
index 751b317323f..00000000000
--- a/ui/src/lib/workspace/widgets/sessions.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-// builtin:sessions — latest-N sessions with a live-run dot; each row links to the
-// chat route for that session. Thin re-implementation over `sessions.list`
-// (NOT the sessions page's welded view fns). Binding value shape:
-// `{ sessions: GatewaySessionRow[] }` or a bare row array.
-
-import { html, nothing, type TemplateResult } from "lit";
-import type { SessionRunStatus } from "../../../api/types.ts";
-import { pathForRoute } from "../../../app-route-paths.ts";
-import { t } from "../../../i18n/index.ts";
-import { formatDateTimeMs } from "../../format.ts";
-import { isSessionRunActive } from "../../session-run-state.ts";
-import { searchForSession } from "../../sessions/navigation.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-const DEFAULT_LIMIT = 6;
-
-type SessionsRowModel = {
-  key: string;
-  label: string;
-  active: boolean;
-  updatedAt: number | null;
-};
-
-type SessionsModel = {
-  rows: SessionsRowModel[];
-  total: number;
-};
-
-function rowLabel(row: Record<string, unknown>, key: string): string {
-  const display = row.displayName ?? row.label ?? row.subject ?? row.channel;
-  return typeof display === "string" && display.trim() ? display : key;
-}
-
-function mapSessions(widget: WorkspaceWidget, value: unknown): SessionsModel {
-  const raw = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.sessions)
-      ? value.sessions
-      : [];
-  const limitProp = toFiniteNumber(widgetProps(widget).limit);
-  const limit = limitProp && limitProp > 0 ? Math.trunc(limitProp) : DEFAULT_LIMIT;
-  const records = raw.filter(isRecord);
-  const rows = records
-    .map((row) => {
-      const key = typeof row.key === "string" ? row.key : "";
-      return {
-        key,
-        label: rowLabel(row, key),
-        active: isSessionRunActive({
-          hasActiveRun: typeof row.hasActiveRun === "boolean" ? row.hasActiveRun : undefined,
-          status: typeof row.status === "string" ? (row.status as SessionRunStatus) : undefined,
-        }),
-        updatedAt: toFiniteNumber(row.updatedAt) ?? null,
-      };
-    })
-    .filter((row) => row.key)
-    .slice(0, limit);
-  return { rows, total: records.length };
-}
-
-export function renderSessions(
-  widget: WorkspaceWidget,
-  value: unknown,
-  basePath = "",
-): TemplateResult {
-  const model = mapSessions(widget, value);
-  if (model.rows.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.sessions.empty")}
-    </div>`;
-  }
-  const chatPath = pathForRoute("chat", basePath);
-  return html`
-    <ul class="workspace-list workspace-sessions" data-test-id="workspace-sessions">
-      ${model.rows.map(
-        (row) => html`
-          <li class="workspace-list__row">
-            <a class="workspace-list__link" href=${`${chatPath}${searchForSession(row.key)}`}>
-              <span
-                class="workspace-dot ${row.active ? "workspace-dot--live" : ""}"
-                aria-hidden="true"
-              ></span>
-              <span class="workspace-list__label">${row.label}</span>
-              ${row.updatedAt !== null
-                ? html`<span class="workspace-list__meta">${formatDateTimeMs(row.updatedAt)}</span>`
-                : nothing}
-            </a>
-          </li>
-        `,
-      )}
-    </ul>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/stat-card.ts b/ui/src/lib/workspace/widgets/stat-card.ts
deleted file mode 100644
index 5e385bf3b13..00000000000
--- a/ui/src/lib/workspace/widgets/stat-card.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-// builtin:stat-card — big number + label. One binding (`value`). `props.format`
-// controls presentation (usd | int | percent | raw). When the binding resolves a
-// structured payload (e.g. `usage.cost`), `props.metric` selects a field from it
-// so a stat-card can front a rich RPC without a binding pointer (rpc bindings
-// carry no pointer — see extensions/workspace schema).
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber, widgetProps } from "./types.ts";
-
-type StatCardModel = {
-  /** The display string for the primary value, or null when unavailable. */
-  display: string | null;
-  /** Inner label; null when it would merely repeat the widget title. */
-  label: string | null;
-};
-
-/** Named metrics selectable from a structured binding payload via `props.metric`. */
-function selectMetric(value: unknown, metric: string): unknown {
-  if (!isRecord(value)) {
-    return undefined;
-  }
-  const totals = isRecord(value.totals) ? value.totals : undefined;
-  switch (metric) {
-    case "todayCost":
-      return totals?.totalCost ?? value.totalCost;
-    case "todayTokens":
-      return totals?.totalTokens ?? value.totalTokens;
-    default:
-      return value[metric];
-  }
-}
-
-function formatStatValue(value: unknown, format: unknown): string | null {
-  if (value === undefined || value === null) {
-    return null;
-  }
-  const numeric = toFiniteNumber(value);
-  if (format === "usd" && numeric !== undefined) {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency: "USD" }).format(numeric);
-  }
-  if (format === "percent" && numeric !== undefined) {
-    return new Intl.NumberFormat(undefined, { style: "percent", maximumFractionDigits: 1 }).format(
-      numeric,
-    );
-  }
-  if ((format === "int" || format === "integer") && numeric !== undefined) {
-    return new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(numeric);
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (numeric !== undefined) {
-    return new Intl.NumberFormat(undefined).format(numeric);
-  }
-  return JSON.stringify(value);
-}
-
-function mapStatCard(widget: WorkspaceWidget, value: unknown): StatCardModel {
-  const props = widgetProps(widget);
-  const metric = typeof props.metric === "string" ? props.metric : null;
-  const selected = metric ? selectMetric(value, metric) : value;
-  const resolved = selected !== undefined ? selected : props.value;
-  const label = typeof props.label === "string" ? props.label : widget.title;
-  // #6 nit: drop the inner label when it merely repeats the widget title —
-  // the cell already renders `widget.title` in the bar.
-  const dedupedLabel = label && label !== widget.title ? label : null;
-  return { display: formatStatValue(resolved, props.format), label: dedupedLabel };
-}
-
-export function renderStatCard(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapStatCard(widget, value);
-  return html`
-    <div class="workspace-stat">
-      <div class="workspace-stat__value">${model.display ?? t("workspaces.widget.stat.empty")}</div>
-      ${model.label ? html`<div class="workspace-stat__label">${model.label}</div>` : nothing}
-    </div>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/table.ts b/ui/src/lib/workspace/widgets/table.ts
deleted file mode 100644
index a296f701e25..00000000000
--- a/ui/src/lib/workspace/widgets/table.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-// builtin:table — compact table over an array binding (`rows`: file JSON array /
-// static / rpc). `props.columns` is a picklist of keys to show (defaults to the
-// union of the first row's keys). Shows the first N rows and a "+M more" footer.
-
-import { html, nothing, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, widgetProps } from "./types.ts";
-
-const DEFAULT_ROW_LIMIT = 8;
-
-type TableModel = {
-  columns: string[];
-  rows: Array<Record<string, unknown>>;
-  shown: number;
-  total: number;
-};
-
-/** Pull an array of row records out of the binding value or `props.rows`. */
-function resolveRows(widget: WorkspaceWidget, value: unknown): Array<Record<string, unknown>> {
-  const candidate = Array.isArray(value)
-    ? value
-    : isRecord(value) && Array.isArray(value.rows)
-      ? value.rows
-      : Array.isArray(widgetProps(widget).rows)
-        ? (widgetProps(widget).rows as unknown[])
-        : [];
-  return candidate.filter(isRecord);
-}
-
-function resolveColumns(widget: WorkspaceWidget, rows: Array<Record<string, unknown>>): string[] {
-  const declared = widgetProps(widget).columns;
-  if (Array.isArray(declared)) {
-    const picked = declared.filter((entry): entry is string => typeof entry === "string");
-    if (picked.length > 0) {
-      return picked;
-    }
-  }
-  const firstRow = rows[0];
-  return firstRow ? Object.keys(firstRow) : [];
-}
-
-function rowLimit(widget: WorkspaceWidget): number {
-  const raw = widgetProps(widget).limit;
-  return typeof raw === "number" && Number.isFinite(raw) && raw > 0
-    ? Math.min(Math.trunc(raw), 100)
-    : DEFAULT_ROW_LIMIT;
-}
-
-function mapTable(widget: WorkspaceWidget, value: unknown): TableModel {
-  const all = resolveRows(widget, value);
-  const limit = rowLimit(widget);
-  const rows = all.slice(0, limit);
-  return { columns: resolveColumns(widget, rows), rows, shown: rows.length, total: all.length };
-}
-
-function renderCell(value: unknown): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  return JSON.stringify(value);
-}
-
-export function renderTable(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapTable(widget, value);
-  if (model.total === 0 || model.columns.length === 0) {
-    return html`<div class="workspace-widget__placeholder">
-      ${t("workspaces.widget.table.empty")}
-    </div>`;
-  }
-  const remaining = model.total - model.shown;
-  return html`
-    <div class="workspace-table">
-      <table class="workspace-table__grid">
-        <thead>
-          <tr>
-            ${model.columns.map((column) => html`<th scope="col">${column}</th>`)}
-          </tr>
-        </thead>
-        <tbody>
-          ${model.rows.map(
-            (row) => html`
-              <tr>
-                ${model.columns.map((column) => html`<td>${renderCell(row[column])}</td>`)}
-              </tr>
-            `,
-          )}
-        </tbody>
-      </table>
-      ${remaining > 0
-        ? html`<div class="workspace-table__footer">
-            ${t("workspaces.widget.table.more", { count: String(remaining) })}
-          </div>`
-        : nothing}
-    </div>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/types.ts b/ui/src/lib/workspace/widgets/types.ts
deleted file mode 100644
index 28a2c106c96..00000000000
--- a/ui/src/lib/workspace/widgets/types.ts
+++ /dev/null
@@ -1,73 +0,0 @@
-// Contract for the L4 builtin widget library. Each builtin is a pure render
-// function keyed by its kind (`builtin:<name>`); the widget cell dispatches
-// through the registry (`./index.ts`). Data-shape mapping lives in exported,
-// separately-unit-tested `map*` helpers per widget so the RPC payload → view
-// model transform is verifiable without a DOM.
-//
-// Renderers NEVER fetch: they receive the already-resolved primary binding
-// value (the L3 view resolves the first declared binding on the page's gateway
-// client) plus the widget's `props`. A binding error is surfaced by the cell's
-// error boundary before a renderer runs, so renderers only see values.
-
-import type { TemplateResult } from "lit";
-import type { ApplicationConfigCapability } from "../../../app/config.ts";
-import type { WorkspaceWidget } from "../types.ts";
-
-export type CustomWidgetApprovalDecision = "approve" | "reject";
-export type PendingCustomWidgetApproval = {
-  id: string;
-  title: string;
-  requestedBy: string | null;
-  deciding: boolean;
-};
-export type CustomWidgetApprovalsSource = {
-  pending: PendingCustomWidgetApproval[];
-  onDecide?: (item: PendingCustomWidgetApproval, decision: CustomWidgetApprovalDecision) => void;
-};
-
-/** Ambient context a builtin may need beyond its own binding value. */
-export type BuiltinWidgetContext = {
-  /** Control UI mount path used by builtins that link to another app route. */
-  basePath: string;
-  /** Control UI embed policy — only the iframe-embed widget consumes it. */
-  embed: Pick<
-    ApplicationConfigCapability["current"],
-    "embedSandboxMode" | "allowExternalEmbedUrls"
-  >;
-  /** Ephemeral preview UI state owned by the workspace view, never the document. */
-  preview: {
-    getViewport: (widgetId: string, fallback: PreviewViewport) => PreviewViewport;
-    setViewport: (widgetId: string, viewport: PreviewViewport) => void;
-  };
-  /** Pending custom-widget decisions; no exec or plugin approval queues are exposed. */
-  customWidgetApprovals?: CustomWidgetApprovalsSource;
-};
-
-export type PreviewViewport = "desktop" | "tablet" | "mobile";
-
-/** A builtin widget renderer: pure, side-effect-free, throws only on real bugs. */
-export type BuiltinWidgetRenderer = (
-  widget: WorkspaceWidget,
-  value: unknown,
-  ctx: BuiltinWidgetContext,
-) => TemplateResult;
-
-export function widgetProps(widget: WorkspaceWidget): Record<string, unknown> {
-  return widget.props ?? {};
-}
-
-export function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** Coerce a possibly-string numeric field to a finite number, else undefined. */
-export function toFiniteNumber(value: unknown): number | undefined {
-  if (typeof value === "number") {
-    return Number.isFinite(value) ? value : undefined;
-  }
-  if (typeof value === "string" && value.trim()) {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : undefined;
-  }
-  return undefined;
-}
diff --git a/ui/src/lib/workspace/widgets/usage.ts b/ui/src/lib/workspace/widgets/usage.ts
deleted file mode 100644
index 517b3cdef45..00000000000
--- a/ui/src/lib/workspace/widgets/usage.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-// builtin:usage — a today/window cost + tokens mini-summary over `usage.cost`.
-// Binding value shape: `{ totals: CostUsageTotals }` (see
-// src/infra/session-cost-usage.types.ts). Thin re-implementation — the usage
-// page's own view fns are welded to its filter state.
-
-import { html, type TemplateResult } from "lit";
-import { t } from "../../../i18n/index.ts";
-import { formatCost, formatTokens } from "../../format.ts";
-import type { WorkspaceWidget } from "../types.ts";
-import { isRecord, toFiniteNumber } from "./types.ts";
-
-type UsageModel = {
-  cost: number;
-  tokens: number;
-};
-
-function mapUsage(_widget: WorkspaceWidget, value: unknown): UsageModel {
-  const totals = isRecord(value) && isRecord(value.totals) ? value.totals : {};
-  const cost = toFiniteNumber(totals.totalCost) ?? 0;
-  const tokens = toFiniteNumber(totals.totalTokens) ?? 0;
-  return { cost, tokens };
-}
-
-export function renderUsage(widget: WorkspaceWidget, value: unknown): TemplateResult {
-  const model = mapUsage(widget, value);
-  return html`
-    <div class="workspace-usage" data-test-id="workspace-usage">
-      <div class="workspace-usage__metric">
-        <div class="workspace-usage__value">${formatCost(model.cost)}</div>
-        <div class="workspace-usage__label">${t("workspaces.widget.usage.cost")}</div>
-      </div>
-      <div class="workspace-usage__metric">
-        <div class="workspace-usage__value">${formatTokens(model.tokens)}</div>
-        <div class="workspace-usage__label">${t("workspaces.widget.usage.tokens")}</div>
-      </div>
-    </div>
-  `;
-}
diff --git a/ui/src/lib/workspace/widgets/widgets.test.ts b/ui/src/lib/workspace/widgets/widgets.test.ts
deleted file mode 100644
index a12a9e91fa5..00000000000
--- a/ui/src/lib/workspace/widgets/widgets.test.ts
+++ /dev/null
@@ -1,585 +0,0 @@
-// Focused renderer tests for builtin data shapes and empty/error affordances.
-
-import { render } from "lit";
-import { describe, expect, it, vi } from "vitest";
-import type { WorkspaceWidget } from "../types.ts";
-import { renderActivity } from "./activity.ts";
-import { renderAgentStatus } from "./agent-status.ts";
-import { renderChart } from "./chart.ts";
-import { renderCron } from "./cron.ts";
-import {
-  buildCustomWidgetApprovalsSource,
-  renderCustomWidgetApprovals,
-} from "./custom-widget-approvals.ts";
-import { renderIframeEmbed } from "./iframe-embed.ts";
-import { renderInstances } from "./instances.ts";
-import { renderMarkdown } from "./markdown.ts";
-import { renderPreview } from "./preview.ts";
-import { renderSessions } from "./sessions.ts";
-import { renderStatCard } from "./stat-card.ts";
-import { renderTable } from "./table.ts";
-import type { BuiltinWidgetContext } from "./types.ts";
-import { renderUsage } from "./usage.ts";
-
-function widget(overrides: Partial<WorkspaceWidget> = {}): WorkspaceWidget {
-  return {
-    id: "w1",
-    kind: "builtin:stat-card",
-    title: "Widget",
-    grid: { x: 0, y: 0, w: 4, h: 2 },
-    collapsed: false,
-    ...overrides,
-  };
-}
-
-function renderToContainer(template: unknown): HTMLElement {
-  const container = document.createElement("div");
-  render(template as never, container);
-  return container;
-}
-
-const STRICT_EMBED: BuiltinWidgetContext = {
-  basePath: "",
-  embed: { embedSandboxMode: "strict", allowExternalEmbedUrls: false },
-  preview: { getViewport: (_widgetId, fallback) => fallback, setViewport: vi.fn() },
-};
-
-describe("agent-status mapping", () => {
-  it("maps only keyed sessions and clamps goal progress", () => {
-    const container = renderToContainer(
-      renderAgentStatus(widget({ props: { limit: 2 } }), {
-        sessions: [
-          {
-            key: "agent:one",
-            displayName: "One",
-            hasActiveRun: true,
-            goal: { objective: "Ship the workspace", tokensUsed: 125, tokenBudget: 100 },
-          },
-          { key: "agent:two", status: "idle" },
-          { displayName: "missing key" },
-        ],
-      }),
-    );
-    expect(container.querySelectorAll(".workspace-list__row")).toHaveLength(2);
-    expect(container.textContent).toContain("Ship the workspace");
-    expect(container.textContent).toContain("100");
-    expect(container.textContent).not.toContain("missing key");
-  });
-
-  it("renders accessible status text and an empty state", () => {
-    const populated = renderToContainer(
-      renderAgentStatus(widget(), { sessions: [{ key: "agent:one", hasActiveRun: true }] }),
-    );
-    expect(
-      populated.querySelector("[data-test-id='workspace-agent-status']")?.textContent,
-    ).toContain("Busy");
-    const empty = renderToContainer(renderAgentStatus(widget(), { sessions: [] }));
-    expect(empty.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("custom-widget-approvals mapping", () => {
-  it("exposes only pending custom-widget registry entries", () => {
-    const decisions: Array<[string, "approved" | "rejected"]> = [];
-    const source = buildCustomWidgetApprovalsSource(
-      {
-        schemaVersion: 1,
-        workspaceVersion: 3,
-        tabs: [],
-        prefs: { tabOrder: [] },
-        widgetsRegistry: {
-          pending: { status: "pending", createdBy: "agent:builder" },
-          approved: { status: "approved", createdBy: "agent:builder" },
-        },
-      },
-      new Set(),
-      (name, decision) => decisions.push([name, decision]),
-    );
-    expect(source.pending).toEqual([
-      { id: "pending", title: "pending", requestedBy: "builder", deciding: false },
-    ]);
-    source.onDecide?.(source.pending[0]!, "reject");
-    expect(decisions).toEqual([["pending", "rejected"]]);
-  });
-
-  it("limits rows and renders permission-aware decision controls", () => {
-    const source = {
-      pending: [
-        { id: "one", title: "one", requestedBy: null, deciding: false },
-        { id: "two", title: "two", requestedBy: "builder", deciding: false },
-      ],
-      onDecide: () => undefined,
-    };
-    const container = renderToContainer(
-      renderCustomWidgetApprovals(widget({ props: { limit: 1 } }), undefined, {
-        ...STRICT_EMBED,
-        customWidgetApprovals: source,
-      }),
-    );
-    expect(container.querySelectorAll(".workspace-list__row")).toHaveLength(1);
-    expect(container.querySelectorAll("button")).toHaveLength(2);
-    expect(container.querySelector("button")?.disabled).toBe(false);
-    expect(container.textContent).toContain("Approve");
-    expect(container.textContent).toContain("Reject");
-
-    const restricted = renderToContainer(
-      renderCustomWidgetApprovals(widget(), undefined, {
-        ...STRICT_EMBED,
-        customWidgetApprovals: { pending: source.pending },
-      }),
-    );
-    expect(
-      Array.from(restricted.querySelectorAll("button")).every((button) => button.disabled),
-    ).toBe(true);
-    expect(restricted.textContent).toContain("Approval permission required");
-  });
-});
-
-describe("stat-card mapping", () => {
-  it("renders the value and omits a duplicate label", () => {
-    const container = renderToContainer(
-      renderStatCard(widget({ title: "Cost", props: { label: "Cost", format: "usd" } }), 9),
-    );
-    expect(container.querySelector(".workspace-stat__value")?.textContent).toContain("$9");
-    expect(container.querySelector(".workspace-stat__label")).toBeNull();
-  });
-});
-
-describe("markdown mapping", () => {
-  it("renders an empty state when there is no content", () => {
-    const container = renderToContainer(renderMarkdown(widget(), ""));
-    expect(container.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("table mapping", () => {
-  const rows = [
-    { name: "a", cost: 1 },
-    { name: "b", cost: 2 },
-    { name: "c", cost: 3 },
-  ];
-
-  it("accepts { rows } payloads and renders a +N more footer", () => {
-    const container = renderToContainer(renderTable(widget({ props: { limit: 2 } }), { rows }));
-    expect(container.querySelector(".workspace-table__footer")?.textContent).toContain("1");
-  });
-
-  it("renders an empty state for no rows", () => {
-    const container = renderToContainer(renderTable(widget(), []));
-    expect(container.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("sessions mapping", () => {
-  it("renders a link per session and an empty state", () => {
-    const populated = renderToContainer(
-      renderSessions(widget(), { sessions: [{ key: "main:1", displayName: "One" }] }, "/openclaw"),
-    );
-    expect(populated.querySelector(".workspace-list__link")?.getAttribute("href")).toBe(
-      "/openclaw/chat?session=main%3A1",
-    );
-    const empty = renderToContainer(renderSessions(widget(), { sessions: [] }));
-    expect(empty.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("usage mapping", () => {
-  it("renders both cost and token metrics", () => {
-    const container = renderToContainer(
-      renderUsage(widget(), { totals: { totalCost: 5, totalTokens: 2000 } }),
-    );
-    const values = [...container.querySelectorAll(".workspace-usage__value")].map(
-      (n) => n.textContent,
-    );
-    expect(values).toHaveLength(2);
-  });
-});
-
-describe("cron mapping", () => {
-  it("renders an empty state without jobs", () => {
-    const container = renderToContainer(renderCron(widget(), { jobs: [] }));
-    expect(container.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("instances mapping", () => {
-  it("accepts a { presence } wrapper and renders an empty state", () => {
-    const populated = renderToContainer(
-      renderInstances(widget(), { presence: [{ instanceId: "gw-1" }] }),
-    );
-    expect(populated.querySelector(".workspace-instances")).not.toBeNull();
-    const empty = renderToContainer(renderInstances(widget(), []));
-    expect(empty.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("activity mapping", () => {
-  it("renders an empty state for no entries", () => {
-    const container = renderToContainer(renderActivity(widget(), { entries: [] }));
-    expect(container.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-  });
-});
-
-describe("chart mapping", () => {
-  it("renders single-point and constant series visibly", () => {
-    const line = renderToContainer(renderChart(widget({ props: { type: "line" } }), [5]));
-    expect(line.querySelector(".workspace-chart__point")).not.toBeNull();
-
-    const bars = renderToContainer(renderChart(widget({ props: { type: "bar" } }), [5, 5]));
-    expect(
-      [...bars.querySelectorAll(".workspace-chart__bars rect")].every(
-        (bar) => Number(bar.getAttribute("height")) > 0.5,
-      ),
-    ).toBe(true);
-
-    const zeroBars = renderToContainer(renderChart(widget({ props: { type: "bar" } }), [0, 0]));
-    expect(
-      [...zeroBars.querySelectorAll(".workspace-chart__bars rect")].every(
-        (bar) => Number(bar.getAttribute("height")) === 0,
-      ),
-    ).toBe(true);
-  });
-
-  it("keeps extreme finite ranges within valid SVG coordinates", () => {
-    const container = renderToContainer(
-      renderChart(widget(), [-Number.MAX_VALUE, Number.MAX_VALUE]),
-    );
-    const points = container.querySelector("polyline")?.getAttribute("points") ?? "";
-    expect(points).not.toMatch(/NaN|Infinity/);
-
-    const constant = renderToContainer(renderChart(widget(), [Number.MAX_VALUE]));
-    expect(constant.querySelector("circle")?.outerHTML).not.toMatch(/NaN|Infinity/);
-
-    const gauge = renderToContainer(
-      renderChart(widget({ props: { type: "gauge" } }), [-Number.MAX_VALUE, Number.MAX_VALUE]),
-    );
-    expect(gauge.querySelector(".workspace-chart__gauge")?.outerHTML).not.toMatch(/NaN|Infinity/);
-
-    const bounded = renderToContainer(renderChart(widget({ props: { min: 0, max: 1 } }), [1e308]));
-    expect(bounded.querySelector("svg")?.outerHTML).not.toMatch(/NaN|Infinity/);
-
-    const subnormalMin = renderToContainer(
-      renderChart(widget({ props: { min: Number.MIN_VALUE } }), [Number.MIN_VALUE]),
-    );
-    expect(subnormalMin.querySelector("svg")?.outerHTML).not.toMatch(/NaN|Infinity/);
-
-    const subnormalMax = renderToContainer(
-      renderChart(widget({ props: { max: -Number.MIN_VALUE } }), [-Number.MIN_VALUE]),
-    );
-    expect(subnormalMax.querySelector("svg")?.outerHTML).not.toMatch(/NaN|Infinity/);
-
-    for (const [props, values] of [
-      [{ min: 10 }, [1, 2]],
-      [{ max: -10 }, [-2, -1]],
-    ] as const) {
-      const oneSided = renderToContainer(renderChart(widget({ props }), values));
-      expect(oneSided.querySelector("svg")?.outerHTML).not.toMatch(/NaN|Infinity/);
-      expect(oneSided.querySelector('[data-test-id="workspace-chart-error"]')).toBeNull();
-    }
-  });
-
-  it("announces data extrema rather than configured axis bounds", () => {
-    const container = renderToContainer(
-      renderChart(widget({ title: "Revenue", props: { min: 0, max: 10 } }), [2, 7]),
-    );
-    expect(container.querySelector("svg")?.getAttribute("aria-label")).toContain(
-      "ranging from 2 to 7",
-    );
-  });
-
-  it("renders responsive accessible line, bar, area, sparkline, and gauge charts", () => {
-    for (const type of ["line", "bar", "area", "sparkline", "gauge"] as const) {
-      const container = renderToContainer(
-        renderChart(widget({ title: "Revenue", props: { type, min: 0, max: 10 } }), [2, 7]),
-      );
-      const svg = container.querySelector('[data-test-id="workspace-chart"]');
-      expect(svg?.getAttribute("role")).toBe("img");
-      expect(svg?.getAttribute("aria-label")).toContain("Revenue");
-      expect(svg?.getAttribute("viewBox")).toBe("0 0 100 40");
-      expect(container.querySelector(`.workspace-chart--${type}`)).not.toBeNull();
-    }
-  });
-
-  it("renders localized empty and invalid-data states without an svg", () => {
-    const empty = renderToContainer(renderChart(widget(), []));
-    expect(empty.querySelector('[data-test-id="workspace-chart-empty"]')).not.toBeNull();
-    expect(empty.querySelector("svg")).toBeNull();
-
-    for (const props of [{ min: "bad" }, { min: 10, max: 2 }, { min: 4, max: 4 }]) {
-      const invalidEmpty = renderToContainer(renderChart(widget({ props }), []));
-      expect(invalidEmpty.querySelector('[data-test-id="workspace-chart-error"]')).not.toBeNull();
-      expect(invalidEmpty.querySelector("svg")).toBeNull();
-    }
-
-    const invalid = renderToContainer(renderChart(widget(), [1, "bad"]));
-    expect(invalid.querySelector('[data-test-id="workspace-chart-error"]')).not.toBeNull();
-    expect(invalid.querySelector("svg")).toBeNull();
-
-    for (const [configuredWidget, value] of [
-      [widget({ props: { type: "pie" } }), [1]],
-      [widget({ props: { type: null } }), [1]],
-      [widget({ props: { min: 10, max: 2 } }), [4]],
-      [widget(), { points: [{ label: "missing value" }] }],
-      [widget(), { points: Array.from({ length: 501 }, () => 1) }],
-    ] as const) {
-      const error = renderToContainer(renderChart(configuredWidget, value));
-      expect(error.querySelector('[data-test-id="workspace-chart-error"]')).not.toBeNull();
-      expect(error.querySelector("svg")).toBeNull();
-    }
-  });
-
-  it("accepts the documented point shapes through the 500-point limit", () => {
-    const wrapped = renderToContainer(
-      renderChart(widget(), { points: [1, { y: 2 }, { value: 3 }] }),
-    );
-    expect(wrapped.querySelector('[data-test-id="workspace-chart"]')).not.toBeNull();
-
-    const capped = renderToContainer(
-      renderChart(
-        widget(),
-        Array.from({ length: 500 }, () => 1),
-      ),
-    );
-    expect(capped.querySelector('[data-test-id="workspace-chart"]')).not.toBeNull();
-
-    const denseBars = renderToContainer(
-      renderChart(
-        widget({ props: { type: "bar" } }),
-        Array.from({ length: 500 }, (_, index) => index % 2),
-      ),
-    );
-    const slotWidth = (100 - 2 * 2) / 500;
-    expect(
-      [...denseBars.querySelectorAll("rect")].every(
-        (bar) => Number(bar.getAttribute("width")) <= slotWidth,
-      ),
-    ).toBe(true);
-  });
-});
-
-describe("iframe-embed render × sandbox mode", () => {
-  it("emits a sandboxed frame for an allowed URL (strict → empty sandbox attr)", () => {
-    const container = renderToContainer(
-      renderIframeEmbed(widget({ props: { url: "/preview" } }), null, STRICT_EMBED),
-    );
-    const frame = container.querySelector<HTMLIFrameElement>(
-      '[data-test-id="workspace-embed-frame"]',
-    );
-    expect(frame).not.toBeNull();
-    expect(frame?.getAttribute("sandbox")).toBe("");
-  });
-
-  it("scripts mode grants allow-scripts", () => {
-    const container = renderToContainer(
-      renderIframeEmbed(widget({ props: { url: "/preview" } }), null, {
-        basePath: "",
-        embed: { embedSandboxMode: "scripts", allowExternalEmbedUrls: false },
-        preview: STRICT_EMBED.preview,
-      }),
-    );
-    const frame = container.querySelector<HTMLIFrameElement>(
-      '[data-test-id="workspace-embed-frame"]',
-    );
-    expect(frame?.getAttribute("sandbox")).toBe("allow-scripts");
-  });
-
-  it("never grants allow-same-origin, even when the operator trusts chat embeds", () => {
-    // `props.url` is agent-authored and a builtin needs no approval, so a
-    // same-origin scripted frame would hand the widget the parent's origin.
-    const container = renderToContainer(
-      renderIframeEmbed(widget({ props: { url: "/preview" } }), null, {
-        basePath: "",
-        embed: { embedSandboxMode: "trusted", allowExternalEmbedUrls: false },
-        preview: STRICT_EMBED.preview,
-      }),
-    );
-    const frame = container.querySelector<HTMLIFrameElement>(
-      '[data-test-id="workspace-embed-frame"]',
-    );
-    expect(frame?.getAttribute("sandbox")).toBe("allow-scripts");
-    expect(frame?.getAttribute("sandbox")).not.toContain("allow-same-origin");
-  });
-
-  it("shows a blocked placeholder for an external URL under strict policy", () => {
-    const container = renderToContainer(
-      renderIframeEmbed(widget({ props: { url: "https://evil.example" } }), null, STRICT_EMBED),
-    );
-    expect(container.querySelector('[data-test-id="workspace-embed-blocked"]')).not.toBeNull();
-    expect(container.querySelector('[data-test-id="workspace-embed-frame"]')).toBeNull();
-  });
-});
-
-describe("preview widget", () => {
-  it("renders its URL with the workspace embed sandbox ceiling", () => {
-    const container = renderToContainer(
-      renderPreview(widget({ props: { url: "/preview" } }), undefined, {
-        basePath: "",
-        embed: { embedSandboxMode: "trusted", allowExternalEmbedUrls: false },
-        preview: STRICT_EMBED.preview,
-      }),
-    );
-    const frame = container.querySelector<HTMLIFrameElement>(
-      '[data-test-id="workspace-preview-frame"]',
-    );
-    expect(frame?.getAttribute("src")).toBe("/preview");
-    expect(frame?.getAttribute("sandbox")).toBe("allow-scripts");
-    expect(frame?.getAttribute("sandbox")).not.toContain("allow-same-origin");
-    expect(frame?.getAttribute("referrerpolicy")).toBe("no-referrer");
-  });
-
-  it("reloads the mounted frame without reading its content window", () => {
-    const container = renderToContainer(
-      renderPreview(widget({ props: { url: "/preview" } }), undefined, STRICT_EMBED),
-    );
-    const frame = container.querySelector<HTMLIFrameElement>(
-      '[data-test-id="workspace-preview-frame"]',
-    );
-    expect(frame).not.toBeNull();
-    const setAttribute = vi.spyOn(frame!, "setAttribute");
-    container
-      .querySelector<HTMLButtonElement>('[data-test-id="workspace-preview-reload"]')
-      ?.click();
-    expect(setAttribute).toHaveBeenCalledWith("src", "/preview");
-  });
-
-  it("exposes labeled controls and updates the selected viewport state", () => {
-    let selected: "desktop" | "tablet" | "mobile" | undefined;
-    const context: BuiltinWidgetContext = {
-      ...STRICT_EMBED,
-      preview: {
-        getViewport: (_widgetId, fallback) => selected ?? fallback,
-        setViewport: (_widgetId, viewport) => {
-          selected = viewport;
-        },
-      },
-    };
-    const previewWidget = widget({ props: { url: "/preview", defaultViewport: "tablet" } });
-    const container = renderToContainer(renderPreview(previewWidget, undefined, context));
-    expect(container.querySelector('[role="toolbar"]')?.getAttribute("aria-label")).toBeTruthy();
-    expect(container.querySelector('[role="group"]')?.getAttribute("aria-label")).toBeTruthy();
-    const tablet = container.querySelector<HTMLButtonElement>(
-      '[data-test-id="workspace-preview-viewport-tablet"]',
-    );
-    const mobile = container.querySelector<HTMLButtonElement>(
-      '[data-test-id="workspace-preview-viewport-mobile"]',
-    );
-    expect(tablet?.getAttribute("aria-pressed")).toBe("true");
-    expect(mobile?.getAttribute("aria-pressed")).toBe("false");
-    mobile?.click();
-    expect(selected).toBe("mobile");
-    render(renderPreview(previewWidget, undefined, context), container);
-    expect(
-      container
-        .querySelector('[data-test-id="workspace-preview-viewport-tablet"]')
-        ?.getAttribute("aria-pressed"),
-    ).toBe("false");
-    expect(
-      container
-        .querySelector('[data-test-id="workspace-preview-viewport-mobile"]')
-        ?.getAttribute("aria-pressed"),
-    ).toBe("true");
-    expect(container.querySelector(".workspace-preview__frame-wrap")?.className).toContain(
-      "workspace-preview__frame-wrap--mobile",
-    );
-  });
-
-  it.each(["bogus", 42])("defaults malformed viewport prop %j to desktop", (defaultViewport) => {
-    const container = renderToContainer(
-      renderPreview(
-        widget({ props: { url: "/preview", defaultViewport } }),
-        undefined,
-        STRICT_EMBED,
-      ),
-    );
-
-    expect(container.querySelector(".workspace-preview__frame-wrap")?.className).toContain(
-      "workspace-preview__frame-wrap--desktop",
-    );
-  });
-
-  it("uses a bound URL instead of props and does not hide malformed binding data", () => {
-    const bound = renderToContainer(
-      renderPreview(
-        widget({
-          props: { url: "/stale" },
-          bindings: { value: { source: "static", value: "/bound" } },
-        }),
-        "/bound",
-        STRICT_EMBED,
-      ),
-    );
-    expect(
-      bound.querySelector('[data-test-id="workspace-preview-frame"]')?.getAttribute("src"),
-    ).toBe("/bound");
-
-    const malformed = renderToContainer(
-      renderPreview(
-        widget({
-          props: { url: "/fallback" },
-          bindings: { value: { source: "static", value: 42 } },
-        }),
-        42,
-        STRICT_EMBED,
-      ),
-    );
-    expect(malformed.querySelector('[data-test-id="workspace-preview-frame"]')).toBeNull();
-
-    const missing = renderToContainer(
-      renderPreview(
-        widget({
-          props: { url: "/fallback" },
-          bindings: { value: { source: "static" } },
-        }),
-        undefined,
-        STRICT_EMBED,
-      ),
-    );
-    expect(missing.querySelector('[data-test-id="workspace-preview-frame"]')).toBeNull();
-
-    const unrelated = renderToContainer(
-      renderPreview(
-        widget({
-          props: { url: "/configured" },
-          bindings: { other: { source: "static", value: "/ignored" } },
-        }),
-        "/ignored",
-        STRICT_EMBED,
-      ),
-    );
-    expect(
-      unrelated.querySelector('[data-test-id="workspace-preview-frame"]')?.getAttribute("src"),
-    ).toBe("/configured");
-  });
-
-  it("allows policy-approved external URLs and blocks external or unsafe URLs by default", () => {
-    const allowed = renderToContainer(
-      renderPreview(
-        widget({
-          bindings: {
-            value: { source: "static", value: "https://preview.example" },
-          },
-        }),
-        "https://preview.example",
-        {
-          ...STRICT_EMBED,
-          embed: { embedSandboxMode: "strict", allowExternalEmbedUrls: true },
-        },
-      ),
-    );
-    expect(
-      allowed.querySelector('[data-test-id="workspace-preview-frame"]')?.getAttribute("src"),
-    ).toBe("https://preview.example");
-
-    for (const value of [undefined, 42, "https://evil.example", "javascript:alert(1)"]) {
-      const container = renderToContainer(
-        renderPreview(
-          widget({ bindings: { value: { source: "static", value } } }),
-          value,
-          STRICT_EMBED,
-        ),
-      );
-      expect(container.querySelector('[data-test-id="workspace-preview-frame"]')).toBeNull();
-      expect(container.querySelector(".workspace-widget__placeholder")).not.toBeNull();
-    }
-  });
-});
diff --git a/ui/src/pages/plugin/plugin-page.test.ts b/ui/src/pages/plugin/plugin-page.test.ts
index 40488505d4d..af0397233db 100644
--- a/ui/src/pages/plugin/plugin-page.test.ts
+++ b/ui/src/pages/plugin/plugin-page.test.ts
@@ -627,16 +627,19 @@ describe("PluginPage", () => {
   });
 
   it("does not install an earlier bundled view after switching away and back", async () => {
-    const firstWorkspaceLoad = deferred<TestBundledView>();
-    const currentWorkspaceLoad = deferred<TestBundledView>();
-    const logbookLoad = deferred<TestBundledView>();
+    const firstLogbookLoad = deferred<TestBundledView>();
+    const currentLogbookLoad = deferred<TestBundledView>();
     const hello: GatewayHelloOk = {
       type: "hello-ok",
       protocol: 3,
       auth: { role: "operator", scopes: ["operator.write"] },
       controlUiTabs: [
-        { pluginId: "workspaces", id: "workspaces", label: "Workspaces" },
         { pluginId: "logbook", id: "logbook", label: "Logbook" },
+        {
+          pluginId: "external-plugin",
+          id: "panel",
+          label: "External panel",
+        },
       ],
     };
     const snapshot: ApplicationGatewaySnapshot = {
@@ -651,34 +654,32 @@ describe("PluginPage", () => {
     };
     const page = document.createElement(deferredPluginPageTag) as DeferredPluginPage;
     page.loads = new Map([
-      ["workspaces/workspaces", [firstWorkspaceLoad.promise, currentWorkspaceLoad.promise]],
-      ["logbook/logbook", [logbookLoad.promise]],
+      ["logbook/logbook", [firstLogbookLoad.promise, currentLogbookLoad.promise]],
     ]);
-    page.pluginId = "workspaces";
-    page.tabId = "workspaces";
+    page.pluginId = "logbook";
+    page.tabId = "logbook";
     (page as unknown as { context: ApplicationContext<RouteId> }).context = {
       gateway: { snapshot, subscribe: () => () => undefined },
     } as unknown as ApplicationContext<RouteId>;
 
     document.body.append(page);
     try {
+      await page.updateComplete;
+      page.pluginId = "external-plugin";
+      page.tabId = "panel";
       await page.updateComplete;
       page.pluginId = "logbook";
       page.tabId = "logbook";
       await page.updateComplete;
-      page.pluginId = "workspaces";
-      page.tabId = "workspaces";
-      await page.updateComplete;
 
-      currentWorkspaceLoad.resolve({ render: () => "current workspace view", stop: vi.fn() });
-      await waitForFast(() => expect(page.textContent).toContain("current workspace view"));
+      currentLogbookLoad.resolve({ render: () => "current Logbook view", stop: vi.fn() });
+      await waitForFast(() => expect(page.textContent).toContain("current Logbook view"));
 
-      firstWorkspaceLoad.resolve({ render: () => "stale workspace view", stop: vi.fn() });
+      firstLogbookLoad.resolve({ render: () => "stale Logbook view", stop: vi.fn() });
       await Promise.resolve();
       await page.updateComplete;
-      expect(page.textContent).not.toContain("stale workspace view");
-      expect(page.textContent).toContain("current workspace view");
-      logbookLoad.resolve({ render: () => "stale Logbook view", stop: vi.fn() });
+      expect(page.textContent).not.toContain("stale Logbook view");
+      expect(page.textContent).toContain("current Logbook view");
     } finally {
       page.remove();
     }
diff --git a/ui/src/pages/plugin/plugin-page.ts b/ui/src/pages/plugin/plugin-page.ts
index 9907ea3ea38..26bca91cc2d 100644
--- a/ui/src/pages/plugin/plugin-page.ts
+++ b/ui/src/pages/plugin/plugin-page.ts
@@ -72,13 +72,6 @@ const EXTERNAL_AUTH_PROBE_TIMEOUT_MS = 5_000;
 
 // Keyed by pluginId/tabId: tab ids are only unique within their plugin.
 const BUNDLED_TAB_VIEWS: Record<string, () => Promise<BundledPluginTabView>> = {
-  "workspaces/workspaces": async () => {
-    const [{ renderWorkspace }, { stopWorkspace }] = await Promise.all([
-      import("./workspace-view.ts"),
-      import("./workspace-controller.ts"),
-    ]);
-    return { render: renderWorkspace, stop: stopWorkspace };
-  },
   "logbook/logbook": async () => {
     const [{ renderLogbook }, { stopLogbookPolling }] = await Promise.all([
       import("./logbook-view.ts"),
@@ -552,8 +545,6 @@ export class PluginPage extends OpenClawLightDomContentsElement {
         return nothing;
       }
       const snapshot = context.gateway.snapshot;
-      // Config may be absent in unit harnesses; the Workspaces view defaults the
-      // embed policy to strict when `embed` is omitted.
       const config = context.config?.current;
       return this.bundledView.render({
         host: this.bundledViewHost,
diff --git a/ui/src/pages/plugin/workspace-controller.test.ts b/ui/src/pages/plugin/workspace-controller.test.ts
deleted file mode 100644
index 2e798af55c4..00000000000
--- a/ui/src/pages/plugin/workspace-controller.test.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { GatewayBrowserClient } from "../../api/gateway.ts";
-import { getWorkspaceState, subscribeToWorkspaceEvents } from "../../lib/workspace/index.ts";
-import { stopWorkspace } from "./workspace-controller.ts";
-
-describe("workspace controller", () => {
-  it("stops the live-update subscription for its host", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    const unsubscribe = vi.fn();
-    const client = {
-      request: vi.fn(),
-      addEventListener: vi.fn(() => unsubscribe),
-    } as unknown as GatewayBrowserClient;
-    subscribeToWorkspaceEvents(host, state, client);
-    stopWorkspace(host);
-    expect(unsubscribe).toHaveBeenCalledTimes(1);
-  });
-
-  it("is a no-op for a host that never subscribed", () => {
-    expect(() => stopWorkspace({})).not.toThrow();
-  });
-});
diff --git a/ui/src/pages/plugin/workspace-controller.ts b/ui/src/pages/plugin/workspace-controller.ts
deleted file mode 100644
index 1ec76c00d80..00000000000
--- a/ui/src/pages/plugin/workspace-controller.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-// Control UI controller for the Workspaces tab: thin lifecycle glue. All data and
-// mutation logic lives in `lib/workspace`; this module exposes only the `stop`
-// hook the bundled-view registry (`plugin-page.ts`) wires into tab-switch and
-// disconnect cleanup (matches logbook-controller's shape).
-
-import { stopWorkspace as stopWorkspaceLifecycle } from "../../lib/workspace/index.ts";
-import { stopWorkspaceView } from "./workspace-view.ts";
-
-/** Tears down the live-update subscription; wired into tab-switch + disconnect. */
-export function stopWorkspace(host: object): void {
-  stopWorkspaceLifecycle(host);
-  // Drop the view-owned menu-dismiss document listeners (#3) so a tab-switch or
-  // disconnect never leaves a stray global pointerdown/keydown handler.
-  stopWorkspaceView(host);
-}
diff --git a/ui/src/pages/plugin/workspace-view.test.ts b/ui/src/pages/plugin/workspace-view.test.ts
deleted file mode 100644
index 549a5f01cbb..00000000000
--- a/ui/src/pages/plugin/workspace-view.test.ts
+++ /dev/null
@@ -1,519 +0,0 @@
-import { render } from "lit";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GatewayBrowserClient } from "../../api/gateway.ts";
-import { getWorkspaceState } from "../../lib/workspace/index.ts";
-import { waitForFast } from "../../test-helpers/wait-for.ts";
-import { stopWorkspace } from "./workspace-controller.ts";
-import { renderWorkspace as renderWorkspaceView } from "./workspace-view.ts";
-
-function renderWorkspace(
-  props: Omit<Parameters<typeof renderWorkspaceView>[0], "onRequestUpdate">,
-) {
-  return renderWorkspaceView({ ...props, onRequestUpdate: () => undefined });
-}
-
-function renderView(host: object): HTMLElement {
-  const container = document.createElement("div");
-  // The view queries `.workspace-grid` on the host for grid metrics.
-  const el = container as unknown as object;
-  render(renderWorkspace({ host: el, client: null, connected: false }), container);
-  render(renderWorkspace({ host, client: null, connected: false }), container);
-  return container;
-}
-
-const doc = {
-  schemaVersion: 1,
-  workspaceVersion: 1,
-  tabs: [
-    {
-      slug: "main",
-      title: "Main",
-      hidden: false,
-      widgets: [
-        {
-          id: "w1",
-          kind: "builtin:markdown",
-          title: "Notes",
-          grid: { x: 0, y: 0, w: 6, h: 2 },
-          collapsed: false,
-          props: { markdown: "hello" },
-        },
-      ],
-    },
-    { slug: "hidden-one", title: "Hidden", hidden: true, widgets: [] },
-    { slug: "empty", title: "Empty", hidden: false, widgets: [] },
-  ],
-  widgetsRegistry: {},
-  prefs: { tabOrder: ["main", "empty", "hidden-one"] },
-};
-
-describe("renderWorkspace", () => {
-  afterEach(() => {
-    window.history.replaceState({}, "", "/");
-  });
-
-  it("shows the onboarding empty state with no tabs", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [],
-      widgetsRegistry: {},
-      prefs: { tabOrder: [] },
-    };
-    const container = renderView(host);
-    expect(container.querySelector('[data-test-id="workspace-empty"]')).not.toBeNull();
-  });
-
-  it("renders the tab strip with visible tabs and a hidden overflow", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "main";
-    const container = renderView(host);
-    const tabs = container.querySelectorAll('[data-test-id="workspace-tab"]');
-    expect(tabs.length).toBe(2); // main + empty (hidden-one is in overflow)
-    expect(container.querySelector(".workspace-tabs__hidden")).not.toBeNull();
-    // Active tab's widget grid renders.
-    expect(container.querySelector('[data-test-id="workspace-grid"]')).not.toBeNull();
-  });
-
-  it("renders the empty-tab hint for a tab with no widgets", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "empty";
-    const container = renderView(host);
-    expect(container.querySelector('[data-test-id="workspace-empty-tab"]')).not.toBeNull();
-  });
-
-  it("renders the first widget full bleed without grid chrome", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = structuredClone(doc);
-    state.workspace.tabs[0]!.layout = "full";
-    state.activeSlug = "main";
-    const container = renderView(host);
-    expect(container.querySelector('[data-test-id="workspace-fullbleed"]')).not.toBeNull();
-    expect(container.querySelector('[data-test-id="workspace-grid"]')).toBeNull();
-    expect(container.textContent).toContain("hello");
-  });
-
-  it("surfaces an action error toast", () => {
-    const host = {};
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "main";
-    state.actionError = "move failed";
-    const container = renderView(host);
-    expect(container.querySelector(".workspace__toast")?.textContent).toContain("move failed");
-  });
-
-  it("honors workspace deep links and updates them from tab navigation", () => {
-    window.history.replaceState({}, "", "/plugin?plugin=workspaces&id=workspaces&ws=empty");
-    const host = document.createElement("div");
-    document.body.append(host);
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "main";
-    const onPopState = vi.fn();
-    window.addEventListener("popstate", onPopState);
-
-    try {
-      render(renderWorkspace({ host, client: null, connected: false }), host);
-      expect(state.activeSlug).toBe("empty");
-      host
-        .querySelector<HTMLElement>("wa-tab-group")
-        ?.dispatchEvent(new CustomEvent("wa-tab-show", { detail: { name: "main" } }));
-      expect(new URLSearchParams(window.location.search).get("ws")).toBe("main");
-      expect(onPopState).toHaveBeenCalledOnce();
-    } finally {
-      window.removeEventListener("popstate", onPopState);
-      stopWorkspace(host);
-      host.remove();
-    }
-  });
-
-  it("cancels a removed deep link before the initial workspace finishes loading", async () => {
-    window.history.replaceState({}, "", "/plugin?plugin=workspaces&id=workspaces&ws=empty");
-    const host = document.createElement("div");
-    document.body.append(host);
-    let resolveWorkspace!: (value: unknown) => void;
-    const request = vi.fn(
-      () =>
-        new Promise((resolve) => {
-          resolveWorkspace = resolve;
-        }),
-    );
-    const client = {
-      request,
-      addEventListener: vi.fn(() => () => {}),
-    } as unknown as GatewayBrowserClient;
-    const state = getWorkspaceState(host);
-
-    try {
-      render(renderWorkspace({ host, client, connected: true }), host);
-      expect(request).toHaveBeenCalledOnce();
-
-      window.history.replaceState({}, "", "/plugin?plugin=workspaces&id=workspaces");
-      render(renderWorkspace({ host, client, connected: true }), host);
-
-      resolveWorkspace({ doc, workspaceVersion: doc.workspaceVersion });
-      await waitForFast(() => expect(state.loaded).toBe(true));
-      expect(state.activeSlug).toBe("main");
-    } finally {
-      stopWorkspace(host);
-      host.remove();
-    }
-  });
-
-  it("discards a stale binding result after the polling version advances", async () => {
-    vi.useFakeTimers();
-    const host = document.createElement("div");
-    document.body.append(host);
-    let resolveOld!: (value: unknown) => void;
-    let resolveFresh!: (value: unknown) => void;
-    const oldResult = new Promise((resolve) => {
-      resolveOld = resolve;
-    });
-    const freshResult = new Promise((resolve) => {
-      resolveFresh = resolve;
-    });
-    const request = vi.fn().mockReturnValueOnce(oldResult).mockReturnValueOnce(freshResult);
-    const client = {
-      request,
-      addEventListener: vi.fn(() => () => {}),
-    } as unknown as GatewayBrowserClient;
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.activeSlug = "main";
-    state.workspace = {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [
-        {
-          slug: "main",
-          title: "Main",
-          hidden: false,
-          widgets: [
-            {
-              id: "cost",
-              kind: "builtin:stat-card",
-              title: "Cost",
-              grid: { x: 0, y: 0, w: 4, h: 2 },
-              collapsed: false,
-              bindings: { value: { source: "rpc", method: "usage.cost" } },
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: {},
-      prefs: { tabOrder: ["main"] },
-    };
-
-    try {
-      render(renderWorkspace({ host, client, connected: true }), host);
-      expect(request).toHaveBeenCalledOnce();
-      await vi.advanceTimersByTimeAsync(60_000);
-      render(renderWorkspace({ host, client, connected: true }), host);
-      expect(request).toHaveBeenCalledTimes(2);
-
-      resolveFresh(2);
-      await freshResult;
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true }), host);
-        expect(host.querySelector(".workspace-stat__value")?.textContent).toBe("2");
-      });
-
-      resolveOld(1);
-      await oldResult;
-      await Promise.resolve();
-      render(renderWorkspace({ host, client, connected: true }), host);
-      expect(host.querySelector(".workspace-stat__value")?.textContent).toBe("2");
-    } finally {
-      stopWorkspace(host);
-      host.remove();
-      vi.useRealTimers();
-    }
-  });
-
-  it("refreshes agent status when the canonical session list advances", async () => {
-    const host = document.createElement("div");
-    document.body.append(host);
-    const state = getWorkspaceState(host);
-    let active = false;
-    const request = vi.fn(async (method: string) =>
-      method === "sessions.list"
-        ? { sessions: [{ key: "agent:main", hasActiveRun: active }] }
-        : { total: 42 },
-    );
-    const client = {
-      request,
-      addEventListener: vi.fn(() => () => undefined),
-    } as unknown as GatewayBrowserClient;
-    state.loaded = true;
-    state.activeSlug = "main";
-    state.workspace = {
-      schemaVersion: 1,
-      workspaceVersion: 1,
-      tabs: [
-        {
-          slug: "main",
-          title: "Main",
-          hidden: false,
-          widgets: [
-            {
-              id: "status",
-              kind: "builtin:agent-status",
-              title: "Agent status",
-              grid: { x: 0, y: 0, w: 6, h: 3 },
-              collapsed: false,
-              bindings: { value: { source: "rpc", method: "sessions.list" } },
-            },
-            {
-              id: "usage",
-              kind: "builtin:usage",
-              title: "Usage",
-              grid: { x: 6, y: 0, w: 6, h: 3 },
-              collapsed: false,
-              bindings: { value: { source: "rpc", method: "usage.status" } },
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: {},
-      prefs: { tabOrder: ["main"] },
-    };
-
-    try {
-      render(renderWorkspace({ host, client, connected: true }), host);
-      await waitForFast(() => expect(request).toHaveBeenCalledTimes(2));
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true }), host);
-        expect(
-          host.querySelector("[data-test-id='workspace-agent-status']")?.textContent,
-        ).toContain("Idle");
-      });
-
-      active = true;
-      render(renderWorkspace({ host, client, connected: true, sessionListRevision: 1 }), host);
-      await waitForFast(() => {
-        expect(request.mock.calls.filter(([method]) => method === "sessions.list")).toHaveLength(2);
-      });
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true, sessionListRevision: 1 }), host);
-        expect(
-          host.querySelector("[data-test-id='workspace-agent-status']")?.textContent,
-        ).toContain("Busy");
-      });
-      expect(request.mock.calls.filter(([method]) => method === "usage.status")).toHaveLength(1);
-    } finally {
-      stopWorkspace(host);
-      host.remove();
-    }
-  });
-
-  it("reloads a custom-widget frame after workspace changes and reconnects", async () => {
-    const host = document.createElement("div");
-    document.body.append(host);
-    const state = getWorkspaceState(host);
-    const workspace = (workspaceVersion: number) => ({
-      schemaVersion: 1,
-      workspaceVersion,
-      tabs: [
-        {
-          slug: "main",
-          title: "Main",
-          hidden: false,
-          widgets: [
-            {
-              id: "custom",
-              kind: "custom:revenue-chart",
-              title: "Revenue",
-              grid: { x: 0, y: 0, w: 6, h: 4 },
-              collapsed: false,
-            },
-          ],
-        },
-      ],
-      widgetsRegistry: { "revenue-chart": { status: "approved" as const } },
-      prefs: { tabOrder: ["main"] },
-    });
-    const request = vi
-      .fn()
-      .mockResolvedValueOnce({
-        frameToken: "1111111111111111111111111111111111111111111",
-        frameExpiresAt: Date.now() + 60 * 60 * 1000,
-        manifest: { entrypoint: "old.html", bindings: [], capabilities: ["prompt:send"] },
-      })
-      .mockResolvedValueOnce({
-        frameToken: "2222222222222222222222222222222222222222222",
-        frameExpiresAt: Date.now() + 60 * 60 * 1000,
-        manifest: { entrypoint: "new.html", bindings: [], capabilities: [] },
-      })
-      .mockResolvedValueOnce({
-        frameToken: "3333333333333333333333333333333333333333333",
-        frameExpiresAt: Date.now() + 60 * 60 * 1000,
-        manifest: { entrypoint: "new.html", bindings: [], capabilities: [] },
-      });
-    const client = {
-      request,
-      addEventListener: vi.fn(() => () => undefined),
-    } as unknown as GatewayBrowserClient;
-    state.loaded = true;
-    state.activeSlug = "main";
-    try {
-      state.workspace = workspace(1);
-      render(renderWorkspace({ host, client, connected: true }), host);
-      await waitForFast(() => expect(request).toHaveBeenCalledTimes(1));
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true }), host);
-        expect(host.querySelector("iframe")?.getAttribute("src")).toContain("old.html");
-      });
-
-      state.workspace = workspace(2);
-      render(renderWorkspace({ host, client, connected: true }), host);
-      await waitForFast(() => expect(request).toHaveBeenCalledTimes(2));
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true }), host);
-        expect(host.querySelector("iframe")?.getAttribute("src")).toContain("new.html");
-      });
-
-      render(renderWorkspace({ host, client, connected: false }), host);
-      render(renderWorkspace({ host, client, connected: true }), host);
-      await waitForFast(() => expect(request).toHaveBeenCalledTimes(3));
-      await waitForFast(() => {
-        render(renderWorkspace({ host, client, connected: true }), host);
-        expect(host.querySelector("iframe")?.getAttribute("src")).toContain(
-          "3333333333333333333333333333333333333333333",
-        );
-      });
-    } finally {
-      stopWorkspace(host);
-      host.remove();
-    }
-  });
-});
-
-describe("drag ghost (#4)", () => {
-  afterEach(() => {
-    window.history.replaceState({}, "", "/");
-  });
-
-  it("renders a snapped drop-target ghost while a drag is in flight", () => {
-    const host = document.createElement("div");
-    document.body.append(host);
-    const client = {
-      request: vi.fn(async () => ({})),
-      addEventListener: vi.fn(() => () => {}),
-    } as unknown as GatewayBrowserClient;
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "main";
-    try {
-      render(renderWorkspace({ host, client, connected: true }), host);
-      const grid = host.querySelector<HTMLElement>(".workspace-grid");
-      Object.defineProperty(grid, "clientWidth", { value: 720, configurable: true });
-      // No ghost before a drag begins.
-      expect(host.querySelector('[data-test-id="workspace-drag-ghost"]')).toBeNull();
-      const bar = host.querySelector<HTMLElement>(".workspace-widget__bar");
-      bar!.dispatchEvent(
-        new PointerEvent("pointerdown", { bubbles: true, button: 0, clientX: 10, clientY: 10 }),
-      );
-      render(renderWorkspace({ host, client, connected: true }), host);
-      // The ghost is present during the drag.
-      expect(host.querySelector('[data-test-id="workspace-drag-ghost"]')).not.toBeNull();
-      window.dispatchEvent(new PointerEvent("pointerup", { clientX: 10, clientY: 10 }));
-      render(renderWorkspace({ host, client, connected: true }), host);
-      // Ghost gone once the drag settles.
-      expect(host.querySelector('[data-test-id="workspace-drag-ghost"]')).toBeNull();
-    } finally {
-      stopWorkspace(host);
-      host.remove();
-    }
-  });
-});
-
-describe("mid-drag tab-switch cancellation", () => {
-  afterEach(() => {
-    window.history.replaceState({}, "", "/");
-  });
-
-  it("cancels an in-flight drag on stopWorkspace so a later pointerup is a no-op", () => {
-    // The host IS the render container so gridMetrics/pointer targets resolve.
-    const host = document.createElement("div");
-    document.body.append(host);
-    const request = vi.fn(async (..._args: unknown[]) => ({}));
-    const client = {
-      request,
-      addEventListener: vi.fn(() => () => {}),
-    } as unknown as GatewayBrowserClient;
-    const state = getWorkspaceState(host);
-    state.loaded = true;
-    state.workspace = doc;
-    state.activeSlug = "main";
-    render(renderWorkspace({ host, client, connected: true }), host);
-
-    // Grid clientWidth is 0 in jsdom; stub a real width so the drag begins.
-    const grid = host.querySelector<HTMLElement>(".workspace-grid");
-    expect(grid).not.toBeNull();
-    Object.defineProperty(grid, "clientWidth", { value: 720, configurable: true });
-
-    // Track window pointer listeners added during the drag.
-    const added = new Set<string>();
-    const originalAdd = window.addEventListener.bind(window);
-    const originalRemove = window.removeEventListener.bind(window);
-    const addSpy = vi
-      .spyOn(window, "addEventListener")
-      .mockImplementation((type: string, ...rest: unknown[]) => {
-        if (type === "pointermove" || type === "pointerup") {
-          added.add(type);
-        }
-        return (originalAdd as (t: string, ...r: unknown[]) => void)(type, ...rest);
-      });
-    const removeSpy = vi
-      .spyOn(window, "removeEventListener")
-      .mockImplementation((type: string, ...rest: unknown[]) => {
-        if (type === "pointermove" || type === "pointerup") {
-          added.delete(type);
-        }
-        return (originalRemove as (t: string, ...r: unknown[]) => void)(type, ...rest);
-      });
-
-    try {
-      const bar = host.querySelector<HTMLElement>(".workspace-widget__bar");
-      expect(bar).not.toBeNull();
-      bar!.dispatchEvent(
-        new PointerEvent("pointerdown", { bubbles: true, button: 0, clientX: 10, clientY: 10 }),
-      );
-      // The drag registered its window listeners.
-      expect(added.has("pointermove")).toBe(true);
-      expect(added.has("pointerup")).toBe(true);
-
-      // Operator switches tabs mid-drag → the bundled view's stop hook fires.
-      stopWorkspace(host);
-
-      // Listeners are gone…
-      expect(added.has("pointermove")).toBe(false);
-      expect(added.has("pointerup")).toBe(false);
-
-      // …and a late pointerup does not resolve a move against the stale tab/client.
-      window.dispatchEvent(new PointerEvent("pointerup", { clientX: 400, clientY: 200 }));
-      expect(request.mock.calls.some(([method]) => method === "workspaces.widget.move")).toBe(
-        false,
-      );
-    } finally {
-      addSpy.mockRestore();
-      removeSpy.mockRestore();
-      host.remove();
-    }
-  });
-});
diff --git a/ui/src/pages/plugin/workspace-view.ts b/ui/src/pages/plugin/workspace-view.ts
deleted file mode 100644
index e4addbe7eae..00000000000
--- a/ui/src/pages/plugin/workspace-view.ts
+++ /dev/null
@@ -1,1080 +0,0 @@
-// Control UI view renders the Workspaces bundled tab: tab strip, widget grid with
-// hand-rolled pointer drag/drop + resize, empty states. Pure render fns — the
-// controller owns lifecycle and `lib/workspace` owns data logic.
-
-import { html, nothing, type TemplateResult } from "lit";
-import type { GatewayBrowserClient } from "../../api/gateway.ts";
-import "../../components/modal-dialog.ts";
-import { icons } from "../../components/icons.ts";
-import "../../components/web-awesome.ts";
-import "../../components/web-awesome-tabs.ts";
-import {
-  loadWidgetManifestView,
-  type CustomWidgetHostContext,
-} from "../../components/workspace-custom-widget.ts";
-import {
-  renderWorkspaceWidgetBody,
-  renderWidgetCell,
-  type WorkspaceCustomWidgetContext,
-  type WorkspaceWidgetCellCallbacks,
-} from "../../components/workspace-widget-cell.ts";
-import { t } from "../../i18n/index.ts";
-import {
-  beginDrag,
-  collides,
-  WORKSPACE_GRID_GAP,
-  WORKSPACE_ROW_HEIGHT,
-  gridPlacementStyle,
-  gridRowCount,
-  nudgeRect,
-  resolveDrop,
-  updateDrag,
-  type WorkspaceDragState,
-} from "../../lib/workspace/grid.ts";
-import {
-  approveWidget,
-  cancelWorkspaceLoadIntent,
-  clearActiveDrag,
-  customWidgetName,
-  customWidgetStatus,
-  findTab,
-  getWorkspaceState,
-  hiddenTabs,
-  hideWidget,
-  loadWorkspace,
-  moveWidget,
-  moveWidgetToTab,
-  orderedTabs,
-  removeWidgetFromTab,
-  registerActiveDrag,
-  resolveBinding,
-  setActiveWorkspaceSlug,
-  setWidgetCollapsed,
-  startBindingPolling,
-  subscribeToWorkspaceEvents,
-  updateWidgetTitle,
-  visibleTabs,
-  type WorkspaceBindingResult,
-  type WorkspaceUiState,
-} from "../../lib/workspace/index.ts";
-import type {
-  WorkspaceBinding,
-  WorkspaceTab,
-  WorkspaceWidget,
-  WorkspaceDocument,
-  WidgetManifestView,
-} from "../../lib/workspace/types.ts";
-import { buildCustomWidgetApprovalsSource } from "../../lib/workspace/widgets/custom-widget-approvals.ts";
-import type { BuiltinWidgetContext } from "../../lib/workspace/widgets/index.ts";
-import type { PreviewViewport } from "../../lib/workspace/widgets/types.ts";
-import { getSafeLocalStorage } from "../../local-storage.ts";
-import "../../styles/workspace.css";
-import { pluginTabRefFromSearch } from "./route.ts";
-
-type WorkspaceProps = {
-  host: object;
-  client: GatewayBrowserClient | null;
-  connected: boolean;
-  /** Control UI embed policy for iframe-based builtins (defaults to strict). */
-  embed?: BuiltinWidgetContext["embed"];
-  onRequestUpdate: () => void;
-  /** Gateway HTTP base path for custom-widget iframe sources (L5). */
-  basePath?: string;
-  /** Session key for custom-widget prompt dispatch (L5). */
-  sessionKey?: string;
-  /** Advances when the shared session capability publishes a canonical list. */
-  sessionListRevision?: number;
-  /** Controls custom-widget decisions; reads remain available without this scope. */
-  canApproveWidgets?: boolean;
-};
-
-const DEFAULT_EMBED_CONTEXT: BuiltinWidgetContext["embed"] = {
-  embedSandboxMode: "strict",
-  allowExternalEmbedUrls: false,
-};
-
-// Per-host transient view state (menu, live drag) kept outside the data model so a
-// broadcast refetch never clobbers an open menu or an in-flight drag.
-type WorkspaceViewState = {
-  openMenuWidgetId: string | null;
-  drag: WorkspaceDragState | null;
-  /** Per-host preview viewport choices; intentionally not persisted in workspace data. */
-  previewViewports: Map<string, PreviewViewport>;
-  /** Last shared sessions.list revision folded into the binding cache. */
-  sessionListRevision: number | undefined;
-  sessionListRevisionSeen: boolean;
-  sessionBindingGeneration: number;
-  /** Resolved binding cache keyed by widgetId; refreshed when the doc changes. */
-  bindingResults: Map<string, WorkspaceBindingResult>;
-  bindingLoads: Set<string>;
-  bindingVersion: number;
-  /** Loaded custom-widget manifests keyed by widget name for one workspace version. */
-  manifestCache: Map<string, WidgetManifestView>;
-  manifestLoads: Set<string>;
-  manifestVersion: number;
-  manifestConnected: boolean;
-  manifestEpoch: number;
-  /**
-   * Monotonic data-refresh counter bumped by the per-widget polling timer.
-   * Folded into the binding cache key so a poll tick re-resolves data-widget
-   * bindings without a workspace-version change.
-   */
-  dataVersion: number;
-  /** Active themed dialog (#12) for edit-title / move-to-tab, or null. */
-  dialog: WorkspaceDialogState | null;
-  /** First-visit onboarding banner dismissed this session (#5); mirrors localStorage. */
-  onboardingDismissed: boolean;
-};
-
-/** localStorage flag so the first-visit onboarding banner (#5) stays dismissed across reloads. */
-const ONBOARDING_DISMISS_KEY = "openclaw:control-ui:workspace-onboarding-dismissed:v1";
-
-function isOnboardingDismissed(): boolean {
-  try {
-    return getSafeLocalStorage()?.getItem(ONBOARDING_DISMISS_KEY) === "1";
-  } catch {
-    return false;
-  }
-}
-
-function persistOnboardingDismissed(): void {
-  try {
-    getSafeLocalStorage()?.setItem(ONBOARDING_DISMISS_KEY, "1");
-  } catch {
-    // Best effort — dismissing the hint is not a product failure.
-  }
-}
-
-/** Themed-dialog state replacing the old window.prompt() flows (#12). */
-type WorkspaceDialogState =
-  | { kind: "editTitle"; slug: string; widgetId: string; title: string }
-  | { kind: "moveToTab"; slug: string; widgetId: string };
-
-const workspaceViewStates = new WeakMap<object, WorkspaceViewState>();
-
-// Per-host document dismiss listener for the open kebab menu (#3). Installed while
-// a menu is open so an outside pointerdown or Escape closes it; removed when the
-// menu closes or the view stops. The details-based hidden-tabs menu closes via its
-// own native outside-click/Escape once we drop `open` on the same signals.
-type MenuDismissBinding = {
-  onPointerDown: (event: PointerEvent) => void;
-  onKeyDown: (event: KeyboardEvent) => void;
-};
-const workspaceMenuDismiss = new WeakMap<object, MenuDismissBinding>();
-
-/** Remove the active menu-dismiss document listeners for `host`, if any. */
-function teardownMenuDismiss(host: object): void {
-  const binding = workspaceMenuDismiss.get(host);
-  if (!binding) {
-    return;
-  }
-  document.removeEventListener("pointerdown", binding.onPointerDown, true);
-  document.removeEventListener("keydown", binding.onKeyDown, true);
-  workspaceMenuDismiss.delete(host);
-}
-
-/**
- * Ensure the document-level dismiss listeners match whether a kebab menu is open.
- * When open, an outside pointerdown or Escape clears `openMenuWidgetId`; a click
- * inside the open menu/toggle is ignored so menu items still fire.
- */
-function syncMenuDismiss(
-  host: object,
-  viewState: WorkspaceViewState,
-  requestUpdate: () => void,
-): void {
-  const menuOpen = viewState.openMenuWidgetId !== null;
-  const active = workspaceMenuDismiss.has(host);
-  if (menuOpen === active) {
-    return;
-  }
-  if (!menuOpen) {
-    teardownMenuDismiss(host);
-    return;
-  }
-  const close = () => {
-    if (viewState.openMenuWidgetId === null) {
-      return;
-    }
-    viewState.openMenuWidgetId = null;
-    teardownMenuDismiss(host);
-    requestUpdate();
-  };
-  const onPointerDown = (event: PointerEvent) => {
-    const target = event.target;
-    if (
-      target instanceof Element &&
-      target.closest(".workspace-widget__menu, .workspace-widget__menu-toggle")
-    ) {
-      return;
-    }
-    close();
-  };
-  const onKeyDown = (event: KeyboardEvent) => {
-    if (event.key === "Escape") {
-      event.preventDefault();
-      close();
-    }
-  };
-  document.addEventListener("pointerdown", onPointerDown, true);
-  document.addEventListener("keydown", onKeyDown, true);
-  workspaceMenuDismiss.set(host, { onPointerDown, onKeyDown });
-}
-
-/** View-level teardown: drop any menu-dismiss listeners. Called from the controller's stop. */
-export function stopWorkspaceView(host: object): void {
-  teardownMenuDismiss(host);
-}
-
-function getViewState(host: object): WorkspaceViewState {
-  let state = workspaceViewStates.get(host);
-  if (!state) {
-    state = {
-      openMenuWidgetId: null,
-      drag: null,
-      previewViewports: new Map(),
-      sessionListRevision: undefined,
-      sessionListRevisionSeen: false,
-      sessionBindingGeneration: 0,
-      bindingResults: new Map(),
-      bindingLoads: new Set(),
-      bindingVersion: -1,
-      manifestCache: new Map(),
-      manifestLoads: new Set(),
-      manifestVersion: -1,
-      manifestConnected: false,
-      manifestEpoch: 0,
-      dataVersion: 0,
-      dialog: null,
-      onboardingDismissed: isOnboardingDismissed(),
-    };
-    workspaceViewStates.set(host, state);
-  }
-  return state;
-}
-
-/** Advance the data-refresh counter so the next render re-resolves bindings. */
-function bumpWorkspaceDataVersion(host: object): void {
-  getViewState(host).dataVersion += 1;
-}
-
-/** The workspace tab slug requested via the `?ws=` deep-link query param. */
-function requestedWorkspaceSlug(search: string): string | null {
-  const params = new URLSearchParams(search);
-  const ws = params.get("ws")?.trim();
-  return ws ? ws : null;
-}
-
-/** Deep-link to a workspace tab: update `?ws=` and drive the router via popstate. */
-function navigateToWorkspaceTab(slug: string): void {
-  const url = new URL(window.location.href);
-  const ref = pluginTabRefFromSearch(url.search);
-  url.searchParams.set("plugin", ref.pluginId);
-  url.searchParams.set("id", ref.id);
-  url.searchParams.set("ws", slug);
-  window.history.pushState({}, "", `${url.pathname}${url.search}${url.hash}`);
-  window.dispatchEvent(new PopStateEvent("popstate"));
-}
-
-/** Primary binding for a widget (first declared), if any. */
-function primaryBinding(widget: WorkspaceWidget): WorkspaceBinding | null {
-  const bindings = widget.bindings;
-  if (!bindings) {
-    return null;
-  }
-  const first = Object.values(bindings)[0];
-  return first ?? null;
-}
-
-function isCanonicalSessionBinding(binding: WorkspaceBinding | null): boolean {
-  return binding?.source === "rpc" && binding.method === "sessions.list";
-}
-
-function invalidateCanonicalSessionBindings(
-  viewState: WorkspaceViewState,
-  workspace: WorkspaceDocument | null,
-): void {
-  for (const tab of workspace?.tabs ?? []) {
-    for (const widget of tab.widgets) {
-      if (!isCanonicalSessionBinding(primaryBinding(widget))) {
-        continue;
-      }
-      viewState.bindingResults.delete(widget.id);
-      viewState.bindingLoads.delete(widget.id);
-    }
-  }
-}
-
-/**
- * Cache key mixing the workspace version with the data-refresh counter: a doc
- * change OR a poll tick both invalidate resolved bindings. Overflow-safe: only
- * equality is compared.
- */
-function bindingCacheKey(workspace: WorkspaceDocument, viewState: WorkspaceViewState): number {
-  return workspace.workspaceVersion * 1_000_003 + viewState.dataVersion;
-}
-
-/** Kick off binding resolution for widgets on the active tab; cache per version. */
-function ensureBindings(
-  viewState: WorkspaceViewState,
-  client: GatewayBrowserClient | null,
-  workspace: WorkspaceDocument,
-  tab: WorkspaceTab,
-  requestUpdate: (() => void) | null,
-): void {
-  const key = bindingCacheKey(workspace, viewState);
-  if (viewState.bindingVersion !== key) {
-    viewState.bindingResults.clear();
-    viewState.bindingLoads.clear();
-    viewState.bindingVersion = key;
-  }
-  for (const widget of tab.widgets) {
-    const binding = primaryBinding(widget);
-    if (
-      !binding ||
-      viewState.bindingResults.has(widget.id) ||
-      viewState.bindingLoads.has(widget.id)
-    ) {
-      continue;
-    }
-    viewState.bindingLoads.add(widget.id);
-    const sessionBindingGeneration = isCanonicalSessionBinding(binding)
-      ? viewState.sessionBindingGeneration
-      : undefined;
-    void resolveBinding(client, binding).then((result) => {
-      if (
-        viewState.bindingVersion !== key ||
-        (sessionBindingGeneration !== undefined &&
-          viewState.sessionBindingGeneration !== sessionBindingGeneration)
-      ) {
-        return;
-      }
-      viewState.bindingResults.set(widget.id, result);
-      viewState.bindingLoads.delete(widget.id);
-      requestUpdate?.();
-    });
-  }
-}
-
-function gridMetrics(host: object): { width: number } {
-  const grid =
-    host instanceof HTMLElement ? host.querySelector<HTMLElement>(".workspace-grid") : null;
-  return { width: grid?.clientWidth ?? 0 };
-}
-
-/**
- * First-visit onboarding banner (#5) teaching the two ways to add a tab: ask the
- * agent (primary) or the CLI command (secondary). Dismissible; the flag persists
- * in localStorage. The zero-tabs onboarding card is kept separately.
- */
-function renderOnboardingBanner(
-  viewState: WorkspaceViewState,
-  requestUpdate: () => void,
-): TemplateResult | typeof nothing {
-  if (viewState.onboardingDismissed) {
-    return nothing;
-  }
-  const dismiss = () => {
-    viewState.onboardingDismissed = true;
-    persistOnboardingDismissed();
-    requestUpdate();
-  };
-  return html`
-    <div class="workspace-onboarding" role="note" data-test-id="workspace-onboarding">
-      <span class="workspace-onboarding__icon" aria-hidden="true">${icons.spark}</span>
-      <div class="workspace-onboarding__body">
-        <div class="workspace-onboarding__title">${t("workspaces.onboarding.title")}</div>
-        <div class="workspace-onboarding__sub">${t("workspaces.onboarding.primary")}</div>
-        <div class="workspace-onboarding__sub">
-          ${t("workspaces.onboarding.secondary")}
-          <code class="workspace-onboarding__cmd">${t("workspaces.empty.onboardingCommand")}</code>
-        </div>
-      </div>
-      <button
-        class="workspace-onboarding__dismiss"
-        type="button"
-        data-test-id="workspace-onboarding-dismiss"
-        aria-label=${t("common.dismiss")}
-        @click=${dismiss}
-      >
-        ${icons.x}
-      </button>
-    </div>
-  `;
-}
-
-function renderTabStrip(state: WorkspaceUiState, workspace: WorkspaceDocument): TemplateResult {
-  const tabs = visibleTabs(workspace);
-  const hidden = hiddenTabs(workspace);
-  return html`
-    <wa-tab-group
-      class="workspace-tabs"
-      aria-label=${t("workspaces.tabs.label")}
-      .active=${state.activeSlug}
-      activation="auto"
-      without-scroll-controls
-      @wa-tab-show=${(event: CustomEvent<{ name: string }>) =>
-        navigateToWorkspaceTab(event.detail.name)}
-    >
-      ${tabs.map((tab) => {
-        return html`
-          <wa-tab
-            id=${`workspace-tab-${tab.slug}`}
-            class="workspace-tab"
-            panel=${tab.slug}
-            aria-controls="workspace-tab-panel"
-            data-test-id="workspace-tab"
-            data-ws=${tab.slug}
-          >
-            ${tab.icon && Object.hasOwn(icons, tab.icon)
-              ? html`<span class="workspace-tab__icon" aria-hidden="true"
-                  >${icons[tab.icon as keyof typeof icons]}</span
-                >`
-              : nothing}
-            <span class="workspace-tab__label">${tab.title}</span>
-          </wa-tab>
-        `;
-      })}
-      ${hidden.length > 0
-        ? html`
-            <wa-dropdown
-              slot="nav"
-              class="workspace-tabs__hidden"
-              placement="bottom-end"
-              @wa-select=${(event: CustomEvent<{ item: { value?: string } }>) => {
-                const slug = event.detail.item.value;
-                if (slug) {
-                  navigateToWorkspaceTab(slug);
-                }
-              }}
-            >
-              <button slot="trigger" class="workspace-tab workspace-tab--overflow" type="button">
-                <span class="workspace-tab__icon" aria-hidden="true">${icons.eyeOff}</span>
-                <span class="workspace-tab__label"
-                  >${t("workspaces.tabs.hidden", { count: String(hidden.length) })}</span
-                >
-              </button>
-              ${hidden.map(
-                (tab) => html`
-                  <wa-dropdown-item class="workspace-tabs__hidden-item" .value=${tab.slug}>
-                    ${tab.title}
-                  </wa-dropdown-item>
-                `,
-              )}
-            </wa-dropdown>
-          `
-        : nothing}
-    </wa-tab-group>
-  `;
-}
-
-/**
- * Load `widget.json` manifests for the APPROVED custom widgets on the active tab.
- * Only approved widgets ever build an iframe, so only they need a manifest; a
- * pending/rejected widget never fetches one. Workspace changes, reconnects, and
- * approaching server expiry clear the cache: capabilities are approval-scoped
- * and process-local, so they must never outlive either boundary.
- */
-function ensureManifests(
-  viewState: WorkspaceViewState,
-  props: WorkspaceProps,
-  workspace: WorkspaceDocument,
-  tab: WorkspaceTab,
-): void {
-  if (!props.connected || !props.client) {
-    return;
-  }
-  if (viewState.manifestVersion !== workspace.workspaceVersion) {
-    viewState.manifestCache.clear();
-    viewState.manifestLoads.clear();
-    viewState.manifestVersion = workspace.workspaceVersion;
-  }
-  const manifestVersion = viewState.manifestVersion;
-  const manifestEpoch = viewState.manifestEpoch;
-  for (const widget of tab.widgets) {
-    const name = customWidgetName(widget.kind);
-    const cached = name ? viewState.manifestCache.get(name) : undefined;
-    if (name && cached?.frameExpiresAt && cached.frameExpiresAt <= Date.now() + 60_000) {
-      viewState.manifestCache.delete(name);
-    }
-    if (
-      !name ||
-      customWidgetStatus(workspace, widget.kind) !== "approved" ||
-      viewState.manifestCache.has(name) ||
-      viewState.manifestLoads.has(name)
-    ) {
-      continue;
-    }
-    viewState.manifestLoads.add(name);
-    void loadWidgetManifestView(props.client, name).then((manifest) => {
-      // A fetch started for an older approval must not repopulate the cache after
-      // a workspace update invalidated it.
-      if (
-        viewState.manifestVersion !== manifestVersion ||
-        viewState.manifestEpoch !== manifestEpoch
-      ) {
-        return;
-      }
-      viewState.manifestLoads.delete(name);
-      if (manifest) {
-        viewState.manifestCache.set(name, manifest);
-        props.onRequestUpdate();
-      }
-    });
-  }
-}
-
-/** Builds the L5 custom-widget context for one `custom:<name>` widget, or null. */
-function buildCustomContext(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-  workspace: WorkspaceDocument,
-  widget: WorkspaceWidget,
-): WorkspaceCustomWidgetContext | null {
-  const name = customWidgetName(widget.kind);
-  if (!name) {
-    return null;
-  }
-  const host: CustomWidgetHostContext = {
-    client: props.client,
-    basePath: props.basePath ?? "",
-    sessionKey: props.sessionKey ?? "main",
-  };
-  const createdBy = workspace.widgetsRegistry[name]?.createdBy;
-  return {
-    status: customWidgetStatus(workspace, widget.kind),
-    ...(createdBy ? { createdBy } : {}),
-    manifest: viewState.manifestCache.get(name) ?? null,
-    host,
-    onApprove: () => void approveWidget(state, props.client, { name, decision: "approved" }),
-    onReject: () => void approveWidget(state, props.client, { name, decision: "rejected" }),
-  };
-}
-
-/** Shared ambient builtin state; full-bleed tabs must preserve every grid capability. */
-function buildBuiltinContext(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-  workspace: WorkspaceDocument,
-): BuiltinWidgetContext {
-  const decideCustomWidget = props.canApproveWidgets
-    ? (name: string, decision: "approved" | "rejected") => {
-        void approveWidget(state, props.client, { name, decision });
-      }
-    : undefined;
-  return {
-    basePath: props.basePath ?? "",
-    embed: props.embed ?? DEFAULT_EMBED_CONTEXT,
-    preview: {
-      getViewport: (widgetId, fallback) => viewState.previewViewports.get(widgetId) ?? fallback,
-      setViewport: (widgetId, viewport) => {
-        viewState.previewViewports.set(widgetId, viewport);
-        props.onRequestUpdate?.();
-      },
-    },
-    customWidgetApprovals: buildCustomWidgetApprovalsSource(
-      workspace,
-      state.pendingApprovalNames,
-      decideCustomWidget,
-    ),
-  };
-}
-
-function renderGrid(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-  workspace: WorkspaceDocument,
-  tab: WorkspaceTab,
-): TemplateResult {
-  ensureBindings(viewState, props.client, workspace, tab, props.onRequestUpdate ?? null);
-  ensureManifests(viewState, props, workspace, tab);
-  if (tab.widgets.length === 0) {
-    // #15: dashed placeholder card with an icon so an empty tab reads as an
-    // intentional drop zone.
-    return html`
-      <div class="workspace-empty workspace-empty--tab" data-test-id="workspace-empty-tab">
-        <span class="workspace-empty__icon" aria-hidden="true">${icons.plus}</span>
-        <div class="workspace-empty__title">${t("workspaces.empty.tabTitle")}</div>
-        <div class="workspace-empty__sub">${t("workspaces.empty.tabSubtitle")}</div>
-      </div>
-    `;
-  }
-  if (tab.layout === "full") {
-    return renderFullBleed(props, state, viewState, workspace, tab);
-  }
-  const callbacks = makeCallbacks(props, state, viewState, tab);
-  const builtinContext = buildBuiltinContext(props, state, viewState, workspace);
-  const rows = gridRowCount(tab.widgets);
-  const minHeight = rows * WORKSPACE_ROW_HEIGHT + Math.max(0, rows - 1) * WORKSPACE_GRID_GAP;
-  return html`
-    <div class="workspace-grid" style="min-height: ${minHeight}px" data-test-id="workspace-grid">
-      ${tab.widgets.map((widget) => {
-        const custom = buildCustomContext(props, state, viewState, workspace, widget);
-        return renderWidgetCell({
-          widget,
-          binding: viewState.bindingResults.get(widget.id) ?? null,
-          menuOpen: viewState.openMenuWidgetId === widget.id,
-          pending: state.pendingWidgetIds.has(widget.id),
-          dragging: viewState.drag?.widgetId === widget.id,
-          builtinContext,
-          callbacks,
-          ...(custom ? { custom } : {}),
-        });
-      })}
-      ${renderDragGhost(viewState, tab)}
-    </div>
-  `;
-}
-
-/** App-like tabs render their first widget through the same approval and sandbox path. */
-function renderFullBleed(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-  workspace: WorkspaceDocument,
-  tab: WorkspaceTab,
-): TemplateResult {
-  const widget = tab.widgets[0]!;
-  const callbacks = makeCallbacks(props, state, viewState, tab);
-  const builtinContext = buildBuiltinContext(props, state, viewState, workspace);
-  const custom = buildCustomContext(props, state, viewState, workspace, widget);
-  return html`<div
-    class="workspace-fullbleed"
-    data-test-id="workspace-fullbleed"
-    data-widget-id=${widget.id}
-  >
-    ${renderWorkspaceWidgetBody(
-      widget,
-      viewState.bindingResults.get(widget.id) ?? null,
-      builtinContext,
-      callbacks,
-      custom ?? undefined,
-    )}
-  </div>`;
-}
-
-/**
- * Snapped drop-target ghost for the active move/resize drag (#4). Placed in the
- * same grid slot the drop would land in so the target is obvious. An overlapping
- * (reject-bound) target reads distinctly via `--invalid`.
- */
-function renderDragGhost(
-  viewState: WorkspaceViewState,
-  tab: WorkspaceTab,
-): TemplateResult | typeof nothing {
-  const drag = viewState.drag;
-  if (!drag) {
-    return nothing;
-  }
-  const invalid = collides(drag.ghostRect, tab.widgets, drag.widgetId);
-  return html`
-    <div
-      class="workspace-ghost ${invalid ? "workspace-ghost--invalid" : ""}"
-      style=${gridPlacementStyle(drag.ghostRect)}
-      aria-hidden="true"
-      data-test-id="workspace-drag-ghost"
-    ></div>
-  `;
-}
-
-function makeCallbacks(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-  tab: WorkspaceTab,
-): WorkspaceWidgetCellCallbacks {
-  const requestUpdate = () => props.onRequestUpdate?.();
-  const commitDrag = (widget: WorkspaceWidget, event: PointerEvent, mode: "move" | "resize") => {
-    const metrics = gridMetrics(props.host);
-    if (metrics.width <= 0) {
-      return;
-    }
-    const drag = beginDrag({
-      widget,
-      mode,
-      clientX: event.clientX,
-      clientY: event.clientY,
-      metrics,
-    });
-    viewState.drag = drag;
-    const target = event.target as Element;
-    if (target.setPointerCapture) {
-      target.setPointerCapture(event.pointerId);
-    }
-    // Once cancelled (tab-switch/disconnect via stopWorkspace), the window
-    // listeners are removed and any late pointerup becomes a no-op so it cannot
-    // fire moveWidget against a stale tab/client.
-    let settled = false;
-    const teardown = () => {
-      window.removeEventListener("pointermove", onMove);
-      window.removeEventListener("pointerup", onUp);
-    };
-    const cancel = () => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      teardown();
-      viewState.drag = null;
-      requestUpdate();
-    };
-    const onMove = (moveEvent: PointerEvent) => {
-      updateDrag(drag, moveEvent.clientX, moveEvent.clientY);
-      requestUpdate();
-    };
-    const onUp = () => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      teardown();
-      clearActiveDrag(props.host);
-      const resolved = resolveDrop({
-        requested: drag.ghostRect,
-        widgets: tab.widgets,
-        widgetId: widget.id,
-      });
-      viewState.drag = null;
-      requestUpdate();
-      if (
-        resolved &&
-        (resolved.x !== widget.grid.x ||
-          resolved.y !== widget.grid.y ||
-          resolved.w !== widget.grid.w ||
-          resolved.h !== widget.grid.h)
-      ) {
-        void moveWidget(state, props.client, {
-          slug: tab.slug,
-          widgetId: widget.id,
-          grid: resolved,
-        });
-      }
-    };
-    window.addEventListener("pointermove", onMove);
-    window.addEventListener("pointerup", onUp);
-    registerActiveDrag(props.host, cancel);
-  };
-  return {
-    onToggleCollapse: (widget) =>
-      void setWidgetCollapsed(state, props.client, {
-        slug: tab.slug,
-        widgetId: widget.id,
-        collapsed: !widget.collapsed,
-      }),
-    onToggleMenu: (widget) => {
-      viewState.openMenuWidgetId = viewState.openMenuWidgetId === widget.id ? null : widget.id;
-      requestUpdate();
-    },
-    onCloseMenu: () => {
-      viewState.openMenuWidgetId = null;
-      requestUpdate();
-    },
-    onHide: (widget) => {
-      viewState.openMenuWidgetId = null;
-      // Hiding removes the widget from view and persists the hidden flag; distinct
-      // from remove, which deletes it from the document.
-      void hideWidget(state, props.client, { slug: tab.slug, widgetId: widget.id });
-    },
-    onRemove: (widget) => {
-      viewState.openMenuWidgetId = null;
-      viewState.previewViewports.delete(widget.id);
-      void removeWidgetFromTab(state, props.client, { slug: tab.slug, widgetId: widget.id });
-    },
-    onEditTitle: (widget) => {
-      viewState.openMenuWidgetId = null;
-      // #12: open the themed edit-title dialog instead of window.prompt().
-      viewState.dialog = {
-        kind: "editTitle",
-        slug: tab.slug,
-        widgetId: widget.id,
-        title: widget.title,
-      };
-      requestUpdate();
-    },
-    onMoveToTab: (widget) => {
-      viewState.openMenuWidgetId = null;
-      // #12: open the themed move-to-tab dialog (a select of existing tabs, not a
-      // free-text slug entry).
-      viewState.dialog = { kind: "moveToTab", slug: tab.slug, widgetId: widget.id };
-      requestUpdate();
-    },
-    onMovePointerDown: (widget, event) => {
-      if (event.button !== 0) {
-        return;
-      }
-      event.preventDefault();
-      commitDrag(widget, event, "move");
-    },
-    onResizePointerDown: (widget, event) => {
-      if (event.button !== 0) {
-        return;
-      }
-      event.preventDefault();
-      event.stopPropagation();
-      commitDrag(widget, event, "resize");
-    },
-    onKeyboardNudge: (widget, mode, direction) => {
-      const next = nudgeRect(widget.grid, mode, direction);
-      const resolved = resolveDrop({ requested: next, widgets: tab.widgets, widgetId: widget.id });
-      if (resolved) {
-        void moveWidget(state, props.client, {
-          slug: tab.slug,
-          widgetId: widget.id,
-          grid: resolved,
-        });
-      }
-    },
-  };
-}
-
-/**
- * Themed edit-title / move-to-tab dialog (#12), replacing window.prompt(). Reuses
- * the app's openclaw-modal-dialog (Escape/backdrop cancel, focus trap) and the
- * exec-approval card idiom. Move-to-tab offers a select of existing tabs.
- */
-function renderDialog(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-): TemplateResult | typeof nothing {
-  const dialog = viewState.dialog;
-  if (!dialog) {
-    return nothing;
-  }
-  const requestUpdate = () => props.onRequestUpdate?.();
-  const close = () => {
-    viewState.dialog = null;
-    requestUpdate();
-  };
-
-  if (dialog.kind === "editTitle") {
-    const title = t("workspaces.widget.editTitleTitle");
-    const submit = (event: Event) => {
-      event.preventDefault();
-      const input = (event.currentTarget as HTMLElement).querySelector<HTMLInputElement>(
-        "input[name='workspace-widget-title']",
-      );
-      const next = input?.value.trim() ?? "";
-      if (next && next !== dialog.title) {
-        void updateWidgetTitle(state, props.client, {
-          slug: dialog.slug,
-          widgetId: dialog.widgetId,
-          title: next,
-        });
-      }
-      close();
-    };
-    return html`
-      <openclaw-modal-dialog label=${title} @modal-cancel=${close}>
-        <form class="exec-approval-card" @submit=${submit}>
-          <div class="exec-approval-header">
-            <div class="exec-approval-title">${title}</div>
-          </div>
-          <input
-            class="workspace-dialog__input"
-            type="text"
-            name="workspace-widget-title"
-            data-test-id="workspace-edit-title-input"
-            .value=${dialog.title}
-            aria-label=${t("workspaces.widget.editTitleLabel")}
-            style="margin-top: 12px; width: 100%;"
-          />
-          <div class="exec-approval-actions">
-            <button class="btn btn--primary" type="submit">${t("common.save")}</button>
-            <button class="btn" type="button" @click=${close}>${t("common.cancel")}</button>
-          </div>
-        </form>
-      </openclaw-modal-dialog>
-    `;
-  }
-
-  const title = t("workspaces.widget.moveToTabTitle");
-  const targets = state.workspace
-    ? orderedTabs(state.workspace).filter((candidate) => candidate.slug !== dialog.slug)
-    : [];
-  const submit = (event: Event) => {
-    event.preventDefault();
-    const select = (event.currentTarget as HTMLElement).querySelector<HTMLSelectElement>(
-      "select[name='workspace-move-target']",
-    );
-    const toSlug = select?.value ?? "";
-    if (toSlug && toSlug !== dialog.slug) {
-      void moveWidgetToTab(state, props.client, {
-        fromSlug: dialog.slug,
-        toSlug,
-        widgetId: dialog.widgetId,
-      });
-    }
-    close();
-  };
-  return html`
-    <openclaw-modal-dialog label=${title} @modal-cancel=${close}>
-      <form class="exec-approval-card" @submit=${submit}>
-        <div class="exec-approval-header">
-          <div class="exec-approval-title">${title}</div>
-        </div>
-        ${targets.length === 0
-          ? html`<div class="exec-approval-sub" style="margin-top: 12px;">
-              ${t("workspaces.widget.moveToTabEmpty")}
-            </div>`
-          : html`<select
-              class="workspace-dialog__input"
-              name="workspace-move-target"
-              data-test-id="workspace-move-target"
-              aria-label=${title}
-              style="margin-top: 12px; width: 100%;"
-            >
-              ${targets.map(
-                (candidate) => html`<option value=${candidate.slug}>${candidate.title}</option>`,
-              )}
-            </select>`}
-        <div class="exec-approval-actions">
-          <button class="btn btn--primary" type="submit" ?disabled=${targets.length === 0}>
-            ${t("workspaces.widget.menu.moveToTab")}
-          </button>
-          <button class="btn" type="button" @click=${close}>${t("common.cancel")}</button>
-        </div>
-      </form>
-    </openclaw-modal-dialog>
-  `;
-}
-
-export function renderWorkspace(props: WorkspaceProps): TemplateResult {
-  const state = getWorkspaceState(props.host);
-  const viewState = getViewState(props.host);
-  const sessionListRevision = props.sessionListRevision;
-  if (viewState.sessionListRevisionSeen && sessionListRevision !== viewState.sessionListRevision) {
-    // The shared session capability already coalesced the canonical event refresh.
-    // Drop only sessions.list values; unrelated data widgets keep their caches.
-    viewState.sessionBindingGeneration += 1;
-    invalidateCanonicalSessionBindings(viewState, state.workspace);
-  }
-  viewState.sessionListRevision = sessionListRevision;
-  viewState.sessionListRevisionSeen = true;
-  state.requestUpdate = props.onRequestUpdate ?? null;
-  // Keep the outside-click / Escape dismiss listeners in sync with the open kebab
-  // menu (#3). Cheap no-op when the open state is unchanged.
-  syncMenuDismiss(props.host, viewState, () => props.onRequestUpdate?.());
-
-  const requestedSlug = requestedWorkspaceSlug(window.location.search);
-  const active = props.connected;
-  // Gateway restart revokes every in-memory frame capability without changing
-  // workspaceVersion. A disconnect/reconnect therefore starts a new cache epoch.
-  if (viewState.manifestConnected !== active) {
-    viewState.manifestConnected = active;
-    viewState.manifestEpoch += 1;
-    viewState.manifestCache.clear();
-    viewState.manifestLoads.clear();
-    viewState.manifestVersion = -1;
-  }
-  subscribeToWorkspaceEvents(props.host, state, active ? props.client : null);
-  // Per-widget data refresh: a visibility-gated timer bumps the data version so
-  // the next render re-resolves data-widget bindings. stopWorkspace clears it on
-  // tab-leave/disconnect (logbook's stop discipline — no orphan timers).
-  startBindingPolling(props.host, active ? props.client : null, () => {
-    bumpWorkspaceDataVersion(props.host);
-    props.onRequestUpdate?.();
-  });
-  if (active && !state.loaded && !state.loading && !state.error) {
-    void loadWorkspace(state, props.client, { requestedSlug });
-  }
-
-  // Deep-link: a changed `?ws=` re-points the active tab without a refetch.
-  if (!requestedSlug) {
-    cancelWorkspaceLoadIntent(state);
-  } else if (state.workspace) {
-    setActiveWorkspaceSlug(state, state.workspace, requestedSlug);
-  }
-
-  return html`
-    <section class="workspace" data-test-id="workspace">
-      ${state.actionError
-        ? html`<div class="callout danger workspace__toast" role="alert">${state.actionError}</div>`
-        : nothing}
-      ${renderBody(props, state, viewState)} ${renderDialog(props, state, viewState)}
-    </section>
-  `;
-}
-
-function renderBody(
-  props: WorkspaceProps,
-  state: WorkspaceUiState,
-  viewState: WorkspaceViewState,
-): TemplateResult {
-  if (state.error) {
-    return html`
-      <div class="card lazy-view-state" role="alert">
-        <div class="card-title">${t("workspaces.error.title")}</div>
-        <div class="card-sub">${t("workspaces.error.subtitle")}</div>
-        <details class="workspace-error-detail">
-          <summary>${t("workspaces.error.detailSummary")}</summary>
-          <div class="workspace-error-detail__text">${state.error}</div>
-        </details>
-        <button
-          class="btn btn--small"
-          type="button"
-          @click=${() =>
-            void loadWorkspace(state, props.client, {
-              requestedSlug: requestedWorkspaceSlug(window.location.search),
-            })}
-        >
-          ${t("common.reload")}
-        </button>
-      </div>
-    `;
-  }
-  const workspace = state.workspace;
-  if (!workspace) {
-    // #19: skeleton cards instead of a bare "Loading…" line.
-    return html`
-      <div class="workspace-skeleton" role="status" aria-label=${t("common.loading")}>
-        ${[0, 1, 2, 3, 4, 5].map(() => html`<div class="workspace-skeleton__card"></div>`)}
-      </div>
-    `;
-  }
-  if (workspace.tabs.length === 0) {
-    return html`
-      <div class="workspace-empty workspace-empty--onboarding" data-test-id="workspace-empty">
-        <div class="workspace-empty__title">${t("workspaces.empty.onboardingTitle")}</div>
-        <div class="workspace-empty__sub">${t("workspaces.empty.onboardingSubtitle")}</div>
-        <code class="workspace-empty__cmd">${t("workspaces.empty.onboardingCommand")}</code>
-      </div>
-    `;
-  }
-  const tab = findTab(workspace, state.activeSlug) ?? visibleTabs(workspace)[0];
-  if (!tab) {
-    return html`<div class="card lazy-view-state" role="status">
-      <div class="card-sub">${t("workspaces.empty.noVisibleTabs")}</div>
-    </div>`;
-  }
-  return html`
-    ${renderWorkspacesHeader(tab)}
-    ${renderOnboardingBanner(viewState, () => props.onRequestUpdate?.())}
-    ${renderTabStrip(state, workspace)}
-    <wa-tab-panel
-      id="workspace-tab-panel"
-      name=${tab.slug}
-      active
-      aria-labelledby=${`workspace-tab-${tab.slug}`}
-    >
-      ${renderGrid(props, state, viewState, workspace, tab)}
-    </wa-tab-panel>
-  `;
-}
-
-/**
- * Page-header treatment for the Workspaces view (#7): the active workspace tab as
- * the title, matching the app's .page-title header pattern
- * idiom used by the other top-level pages.
- */
-function renderWorkspacesHeader(tab: WorkspaceTab): TemplateResult {
-  return html`
-    <div class="workspace-page-header" data-test-id="workspace-page-header">
-      <div class="page-title">${tab.title}</div>
-    </div>
-  `;
-}
-/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/ui/src/styles/workspace.css b/ui/src/styles/workspace.css
deleted file mode 100644
index a7ddfd893f4..00000000000
--- a/ui/src/styles/workspace.css
+++ /dev/null
@@ -1,1043 +0,0 @@
-/* Workspaces bundled tab view (L3): tab strip, 12-column widget grid, cell chrome,
-   hand-rolled drag/resize affordances, provenance chip, error boundary. Uses the
-   shared Control UI theme tokens so agent-authored widgets and builtins match the
-   active palette (including the warm light theme). */
-
-.workspace {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  flex: 1;
-  min-height: 0;
-  padding-bottom: 16px;
-  --workspace-row-height: 56px;
-  --workspace-grid-gap: 12px;
-}
-
-.workspace__toast {
-  margin: 0;
-}
-
-/* #7: page-header treatment for the Workspaces view (title = active tab). */
-.workspace-page-header {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-}
-
-/* --- Tab strip ----------------------------------------------------------- */
-
-.workspace-tabs {
-  --track-width: 0;
-  --indicator-color: var(--accent);
-  display: block;
-  border-bottom: 1px solid var(--border);
-  padding-bottom: 8px;
-}
-
-.workspace-tabs::part(tabs) {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  flex-wrap: wrap;
-}
-
-.workspace-tabs::part(body) {
-  display: none;
-}
-
-.workspace-tab::part(base),
-button.workspace-tab {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  height: 32px;
-  padding: 0 12px;
-  border: 1px solid transparent;
-  border-radius: var(--radius-md);
-  background: transparent;
-  color: var(--text-muted, var(--text));
-  font: inherit;
-  cursor: pointer;
-  transition:
-    background 120ms var(--ease-out),
-    color 120ms var(--ease-out);
-}
-
-.workspace-tab:hover::part(base),
-button.workspace-tab:hover {
-  background: var(--bg-hover);
-  color: var(--text);
-}
-
-.workspace-tab[active]::part(base) {
-  background: color-mix(in srgb, var(--accent) 16%, transparent);
-  border-color: color-mix(in srgb, var(--accent) 40%, var(--border));
-  color: var(--text);
-}
-
-.workspace-tab__icon svg {
-  width: 15px;
-  height: 15px;
-}
-
-.workspace-tab__label {
-  white-space: nowrap;
-}
-
-.workspace-tabs__hidden {
-  position: relative;
-  margin-inline-start: auto;
-}
-
-.workspace-tab--overflow {
-  color: var(--text-muted, var(--text));
-  /* #6 nit: keep the "Hidden (N)" affordance a compact single-line chip — the
-     icon + count must never wrap to a second line. */
-  flex-wrap: nowrap;
-  white-space: nowrap;
-}
-
-.workspace-tab--overflow .workspace-tab__icon svg {
-  width: 15px;
-  height: 15px;
-}
-
-.workspace-tabs__hidden::part(menu) {
-  min-width: 160px;
-  padding: 4px;
-  background: var(--card);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-md);
-  box-shadow: var(--shadow-md);
-}
-
-.workspace-tabs__hidden-item {
-  color: var(--text);
-  font: inherit;
-}
-
-/* --- Grid ---------------------------------------------------------------- */
-
-.workspace-grid {
-  display: grid;
-  grid-template-columns: repeat(12, minmax(0, 1fr));
-  grid-auto-rows: var(--workspace-row-height);
-  gap: var(--workspace-grid-gap);
-  align-content: start;
-  flex: 1;
-  min-height: 0;
-}
-
-.workspace-fullbleed {
-  flex: 1;
-  min-width: 0;
-  min-height: 0;
-  overflow: auto;
-}
-
-.workspace-fullbleed > .workspace-widget__custom,
-.workspace-fullbleed > .workspace-embed__frame {
-  width: 100%;
-  height: 100%;
-  min-height: 480px;
-}
-
-/* --- Widget cell --------------------------------------------------------- */
-
-.workspace-widget {
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
-  min-height: 0;
-  position: relative;
-  background: var(--card);
-  border: 1px solid var(--border);
-  /* #14: match .card's larger corner radius. Note the kebab menu and resize
-     dog-ear are portaled/absolute layers OUTSIDE this box, so keeping the card
-     itself clip-free is what lets the menu extend past the card (#1). */
-  border-radius: var(--radius-lg);
-}
-
-/* #16: a collapsed cell shrinks to its header height instead of reserving its
-   full grid slot — the body/resize handle are unmounted, so span a single row. */
-.workspace-widget--collapsed {
-  grid-row: auto !important;
-}
-
-.workspace-widget--pending {
-  opacity: 0.7;
-}
-
-/* #4: snapped drop-target ghost rendered in the grid during a move/resize drag.
-   Accent-tinted outline marks a valid target; --invalid reads distinctly (muted
-   red) for an overlap-rejected drop. */
-.workspace-ghost {
-  pointer-events: none;
-  border-radius: var(--radius-lg);
-  border: 2px dashed color-mix(in srgb, var(--accent) 70%, transparent);
-  background: color-mix(in srgb, var(--accent) 12%, transparent);
-  z-index: 5;
-}
-
-.workspace-ghost--invalid {
-  border-color: color-mix(in srgb, var(--danger) 70%, transparent);
-  background: color-mix(in srgb, var(--danger) 12%, transparent);
-}
-
-.workspace-widget--dragging {
-  outline: 2px dashed color-mix(in srgb, var(--accent) 60%, transparent);
-  outline-offset: 1px;
-  z-index: 10;
-}
-
-.workspace-widget__bar {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 4px 6px 4px 4px;
-  border-bottom: 1px solid var(--border);
-  border-top-left-radius: var(--radius-lg);
-  border-top-right-radius: var(--radius-lg);
-  cursor: grab;
-  touch-action: none;
-  user-select: none;
-}
-
-.workspace-widget__bar:active {
-  cursor: grabbing;
-}
-
-.workspace-widget__collapse,
-.workspace-widget__menu-toggle {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  padding: 0;
-  border: none;
-  border-radius: var(--radius-sm);
-  background: transparent;
-  color: var(--text-muted, var(--text));
-  cursor: pointer;
-}
-
-.workspace-widget__collapse:hover,
-.workspace-widget__menu-toggle:hover {
-  background: var(--bg-hover);
-  color: var(--text);
-}
-
-/* #17: pressed/active cue while the kebab menu is open (aria-expanded=true). */
-.workspace-widget__menu-toggle[aria-expanded="true"] {
-  background: color-mix(in srgb, var(--accent) 16%, transparent);
-  color: var(--text);
-}
-
-.workspace-widget__collapse svg,
-.workspace-widget__menu-toggle svg {
-  width: 15px;
-  height: 15px;
-}
-
-.workspace-widget__title {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  /* #9: align to the app's .card-title token (15px / 600 / -0.02em). */
-  font-size: 15px;
-  font-weight: 600;
-  letter-spacing: -0.02em;
-  color: var(--text-strong, var(--text));
-}
-
-.workspace-widget__provenance {
-  display: inline-flex;
-  align-items: center;
-  padding: 1px 6px;
-  border-radius: var(--radius-full, 999px);
-  background: color-mix(in srgb, var(--accent) 18%, transparent);
-  color: var(--accent);
-  font-size: 0.68em;
-  font-weight: 700;
-  letter-spacing: 0.04em;
-}
-
-.workspace-widget__handle {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 20px;
-  height: 20px;
-  color: var(--text-dim, var(--text-muted, var(--text)));
-  cursor: grab;
-}
-
-.workspace-widget__handle svg {
-  width: 14px;
-  height: 14px;
-}
-
-.workspace-widget__menu {
-  z-index: 30;
-}
-
-.workspace-widget__menu::part(menu) {
-  min-width: 160px;
-  padding: 4px;
-  background: var(--card);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-md);
-  box-shadow: var(--shadow-md);
-}
-
-.workspace-widget__menu-item {
-  text-align: start;
-  color: var(--text);
-}
-
-.workspace-widget__menu-item--danger {
-  color: var(--danger);
-}
-
-.workspace-widget__body {
-  flex: 1;
-  min-height: 0;
-  /* #14: roomier body padding to match the .card idiom. */
-  padding: 14px 16px;
-  overflow: auto;
-  /* Clip body content to the card's rounded bottom corners now that the cell
-     itself no longer sets overflow:hidden (that would clip the kebab menu, #1). */
-  border-bottom-left-radius: var(--radius-lg);
-  border-bottom-right-radius: var(--radius-lg);
-  /* #10: ease the body in on expand instead of an instant unmount/mount. The
-     collapse direction is carried by the grid-row shrink (#16). */
-  animation: workspace-widget-expand 160ms var(--ease-out) both;
-}
-
-@keyframes workspace-widget-expand {
-  from {
-    opacity: 0;
-    transform: translateY(-4px);
-  }
-  to {
-    opacity: 1;
-    transform: none;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .workspace-widget__body {
-    animation: none;
-  }
-}
-
-.workspace-widget__resize {
-  position: absolute;
-  inset-inline-end: 0;
-  inset-block-end: 0;
-  width: 16px;
-  height: 16px;
-  cursor: nwse-resize;
-  touch-action: none;
-  background: linear-gradient(
-    135deg,
-    transparent 50%,
-    color-mix(in srgb, var(--border-strong) 80%, transparent) 50%
-  );
-  /* #2: reveal the resize dog-ear only on cell hover/focus-within (or while a
-     resize drag is active, see --dragging below). */
-  opacity: 0;
-  transition: opacity 120ms var(--ease-out);
-}
-
-.workspace-widget:hover .workspace-widget__resize,
-.workspace-widget:focus-within .workspace-widget__resize,
-.workspace-widget--dragging .workspace-widget__resize {
-  opacity: 1;
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .workspace-widget__resize {
-    transition: none;
-  }
-}
-
-.workspace-widget__placeholder {
-  color: var(--text-muted, var(--text));
-  font-size: 0.85em;
-}
-
-.workspace-widget__error {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
-  gap: 8px;
-  padding: 8px;
-  border-radius: var(--radius-sm);
-  background: var(--danger-subtle, color-mix(in srgb, var(--danger) 12%, transparent));
-  color: var(--text);
-}
-
-.workspace-widget__error-title {
-  font-weight: 600;
-  color: var(--danger);
-}
-
-.workspace-widget__error-humane {
-  font-size: 0.9em;
-  color: var(--text-muted, var(--text));
-}
-
-.workspace-widget__error-detail,
-.workspace-error-detail {
-  font-size: 0.82em;
-  color: var(--text-muted, var(--text));
-}
-
-.workspace-widget__error-detail summary,
-.workspace-error-detail summary {
-  cursor: pointer;
-  color: var(--text-muted, var(--text));
-}
-
-.workspace-widget__error-message {
-  margin-top: 4px;
-  font-size: 0.85em;
-  color: var(--text-muted, var(--text));
-  overflow-wrap: anywhere;
-}
-
-.workspace-error-detail__text {
-  margin-top: 4px;
-  overflow-wrap: anywhere;
-}
-
-/* --- Custom widget host (L5) --------------------------------------------- */
-
-.workspace-widget__custom {
-  display: flex;
-  min-height: 160px;
-  height: 100%;
-}
-
-.workspace-widget__frame {
-  display: block;
-  flex: 1;
-  width: 100%;
-  min-height: 160px;
-  border: 0;
-  border-radius: var(--radius-sm);
-  background: var(--card);
-}
-
-.workspace-widget__approval {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
-  gap: 8px;
-  padding: 8px;
-}
-
-.workspace-widget__approval-title {
-  font-weight: 600;
-  color: var(--text);
-}
-
-.workspace-widget__approval-sub {
-  font-size: 0.85em;
-  color: var(--text-muted, var(--muted));
-}
-
-.workspace-widget__approval-actions {
-  display: flex;
-  gap: 8px;
-}
-
-/* --- Builtin bodies ------------------------------------------------------ */
-
-.workspace-stat {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-}
-
-/* #9: align to the app's .stat-value / .stat-label tokens (components.css). */
-.workspace-stat__value {
-  font-size: 24px;
-  font-weight: 700;
-  letter-spacing: -0.03em;
-  line-height: 1.1;
-  color: var(--text);
-}
-
-.workspace-stat__label {
-  font-size: 12px;
-  font-weight: 500;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
-  color: var(--text-muted, var(--muted, var(--text)));
-}
-
-.workspace-markdown {
-  font-size: 0.9em;
-}
-
-/* Data-widget lists (sessions, cron, instances). */
-.workspace-list {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  font-size: 0.85em;
-}
-
-.workspace-list__row {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 4px 2px;
-  min-width: 0;
-}
-
-.workspace-list__row--disabled {
-  opacity: 0.55;
-}
-
-.workspace-list__link {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  flex: 1;
-  min-width: 0;
-  color: inherit;
-  text-decoration: none;
-  border-radius: var(--radius-sm);
-  padding: 2px 4px;
-}
-
-.workspace-list__link:hover {
-  background: var(--bg-hover);
-}
-
-.workspace-list__label {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  color: var(--text);
-}
-
-.workspace-list__meta {
-  color: var(--text-muted, var(--text));
-  font-size: 0.9em;
-  white-space: nowrap;
-}
-
-.workspace-custom-widget-approvals__row {
-  display: grid;
-  grid-template-columns: max-content minmax(0, 1fr) auto;
-  align-items: center;
-}
-
-.workspace-custom-widget-approvals__actions {
-  display: flex;
-  grid-column: 3;
-  grid-row: 1 / span 2;
-  gap: 6px;
-}
-
-.workspace-custom-widget-approvals__requested-by,
-.workspace-custom-widget-approvals__permission {
-  grid-column: 1 / 3;
-  grid-row: 2;
-  white-space: normal;
-}
-
-.workspace-custom-widget-approvals__permission {
-  grid-column: 1 / -1;
-  grid-row: 3;
-}
-
-/* Live-run / health status dot. */
-.workspace-dot {
-  flex: none;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  background: var(--text-dim, var(--text-muted, var(--text)));
-}
-
-.workspace-dot--live,
-.workspace-dot--ok {
-  background: var(--success, #22c55e);
-}
-
-.workspace-dot--live {
-  box-shadow: 0 0 0 3px color-mix(in srgb, var(--success, #22c55e) 30%, transparent);
-}
-
-.workspace-dot--warn {
-  background: var(--warning, #f59e0b);
-}
-
-/* Compact status badge (cron/activity last-run status). */
-.workspace-badge {
-  flex: none;
-  padding: 1px 6px;
-  border-radius: var(--radius-full, 999px);
-  font-size: 0.9em;
-  font-weight: 600;
-  text-transform: lowercase;
-}
-
-.workspace-badge--ok {
-  background: color-mix(in srgb, var(--success, #22c55e) 18%, transparent);
-  color: var(--success, #16a34a);
-}
-
-.workspace-badge--error {
-  background: color-mix(in srgb, var(--danger) 16%, transparent);
-  color: var(--danger);
-}
-
-.workspace-badge--muted {
-  background: var(--bg-muted);
-  color: var(--text-muted, var(--text));
-}
-
-/* Chart widget: dependency-free responsive SVG visuals. */
-.workspace-chart {
-  display: flex;
-  width: 100%;
-  height: 100%;
-  min-height: 40px;
-}
-
-.workspace-chart__svg {
-  display: block;
-  width: 100%;
-  height: 100%;
-}
-
-.workspace-chart__line {
-  stroke: var(--accent);
-  stroke-width: 1.5;
-  stroke-linecap: round;
-  stroke-linejoin: round;
-  vector-effect: non-scaling-stroke;
-}
-
-.workspace-chart__point {
-  fill: var(--accent);
-}
-
-.workspace-chart__area {
-  fill: color-mix(in srgb, var(--accent) 18%, transparent);
-}
-
-.workspace-chart__bars rect {
-  fill: var(--accent);
-}
-
-.workspace-chart__gauge-track,
-.workspace-chart__gauge-fill {
-  stroke-width: 3;
-  stroke-linecap: round;
-  vector-effect: non-scaling-stroke;
-}
-
-.workspace-chart__gauge-track {
-  stroke: var(--bg-muted);
-}
-
-.workspace-chart__gauge-fill {
-  stroke: var(--accent);
-}
-
-.workspace-chart__gauge-needle {
-  stroke: var(--text);
-  stroke-width: 1;
-  vector-effect: non-scaling-stroke;
-}
-
-/* Usage mini-summary. */
-.workspace-usage {
-  display: flex;
-  gap: 20px;
-}
-
-.workspace-usage__value {
-  font-size: 1.3em;
-  font-weight: 700;
-  color: var(--text);
-}
-
-.workspace-usage__label {
-  font-size: 0.78em;
-  color: var(--text-muted, var(--text));
-}
-
-/* Table widget. */
-.workspace-table {
-  font-size: 0.82em;
-}
-
-.workspace-table__grid {
-  width: 100%;
-  border-collapse: collapse;
-}
-
-.workspace-table__grid th,
-.workspace-table__grid td {
-  text-align: start;
-  padding: 4px 8px;
-  border-bottom: 1px solid var(--border);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  max-width: 220px;
-}
-
-.workspace-table__grid th {
-  color: var(--text-muted, var(--text));
-  font-weight: 600;
-}
-
-.workspace-table__footer {
-  margin-top: 6px;
-  color: var(--text-muted, var(--text));
-  font-size: 0.9em;
-}
-
-/* Activity feed. */
-.workspace-feed {
-  list-style: none;
-  margin: 0;
-  padding: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  font-size: 0.84em;
-}
-
-.workspace-feed__head {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  min-width: 0;
-}
-
-.workspace-feed__title {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  font-weight: 600;
-  color: var(--text);
-}
-
-.workspace-feed__time {
-  color: var(--text-muted, var(--text));
-  white-space: nowrap;
-}
-
-.workspace-feed__detail {
-  color: var(--text-muted, var(--text));
-  overflow-wrap: anywhere;
-}
-
-/* iframe-embed widget. */
-.workspace-embed__frame {
-  display: block;
-  width: 100%;
-  height: 100%;
-  min-height: 120px;
-  border: none;
-  border-radius: var(--radius-sm);
-  background: var(--bg-muted);
-}
-
-.workspace-preview {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  width: 100%;
-  height: 100%;
-  min-height: 0;
-}
-
-.workspace-preview__toolbar {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 8px;
-  flex-wrap: wrap;
-}
-
-.workspace-preview__viewports {
-  display: inline-flex;
-  gap: 4px;
-}
-
-.workspace-preview__viewport,
-.workspace-preview__reload {
-  padding: 2px 8px;
-  font-size: var(--font-size-xs, 12px);
-  color: var(--text-muted, var(--text));
-  background: var(--bg-muted);
-  border: 1px solid var(--border, var(--bg-muted));
-  border-radius: var(--radius-sm);
-  cursor: pointer;
-}
-
-.workspace-preview__viewport:hover,
-.workspace-preview__reload:hover,
-.workspace-preview__viewport[aria-pressed="true"] {
-  color: var(--text);
-  border-color: var(--accent);
-}
-
-.workspace-preview__viewport:focus-visible,
-.workspace-preview__reload:focus-visible {
-  outline: 2px solid var(--accent);
-  outline-offset: 2px;
-}
-
-.workspace-preview__frame-wrap {
-  flex: 1 1 auto;
-  display: flex;
-  justify-content: center;
-  min-height: 120px;
-}
-
-.workspace-preview__frame-wrap--tablet .workspace-preview__frame {
-  width: 768px;
-  max-width: 100%;
-}
-
-.workspace-preview__frame-wrap--mobile .workspace-preview__frame {
-  width: 375px;
-  max-width: 100%;
-}
-
-/* --- Responsive: single column below ~900px ------------------------------ */
-
-@media (max-width: 900px) {
-  .workspace-grid {
-    /* Collapse the 12-column grid to a single column so every widget stacks
-       full-width and reads on a narrow viewport. Explicit placements are
-       ignored because widgets flow into the single implicit column. */
-    grid-template-columns: minmax(0, 1fr);
-    grid-auto-rows: auto;
-  }
-
-  .workspace-grid > .workspace-widget {
-    grid-column: 1 / -1 !important;
-    grid-row: auto !important;
-    min-height: 160px;
-  }
-}
-
-/* --- Empty / onboarding states ------------------------------------------ */
-
-.workspace-empty {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 8px;
-  flex: 1;
-  min-height: 200px;
-  padding: 32px;
-  text-align: center;
-  color: var(--text-muted, var(--text));
-}
-
-.workspace-empty__title {
-  font-size: 1.05em;
-  font-weight: 600;
-  color: var(--text);
-}
-
-.workspace-empty__cmd {
-  margin-top: 4px;
-  padding: 4px 8px;
-  border-radius: var(--radius-sm);
-  background: var(--bg-muted);
-  font-family: var(--mono, monospace);
-  font-size: 0.85em;
-}
-
-/* #15: give the empty-tab state a dashed placeholder card with an icon so it
-   reads as an intentional drop zone, not a rendering gap. */
-.workspace-empty--tab {
-  gap: 10px;
-  border: 1px dashed var(--border-strong, var(--border));
-  border-radius: var(--radius-lg);
-  background: color-mix(in srgb, var(--card) 60%, transparent);
-}
-
-.workspace-empty__icon {
-  color: var(--text-dim, var(--text-muted, var(--text)));
-}
-
-.workspace-empty__icon svg {
-  width: 28px;
-  height: 28px;
-}
-
-/* #5: first-visit onboarding banner teaching the two ways to add a tab. Matches
-   the app's card/callout banner idiom (dismissible, localStorage-backed). */
-.workspace-onboarding {
-  display: flex;
-  align-items: flex-start;
-  gap: 12px;
-  padding: 14px 16px;
-  border: 1px solid color-mix(in srgb, var(--accent) 40%, var(--border));
-  border-radius: var(--radius-lg);
-  background: color-mix(in srgb, var(--accent) 8%, var(--card));
-}
-
-.workspace-onboarding__icon {
-  flex: none;
-  color: var(--accent);
-  margin-top: 1px;
-}
-
-.workspace-onboarding__icon svg {
-  width: 18px;
-  height: 18px;
-}
-
-.workspace-onboarding__body {
-  flex: 1;
-  min-width: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-}
-
-.workspace-onboarding__title {
-  font-weight: 600;
-  color: var(--text-strong, var(--text));
-}
-
-.workspace-onboarding__sub {
-  font-size: 0.9em;
-  color: var(--text-muted, var(--muted, var(--text)));
-}
-
-.workspace-onboarding__cmd {
-  margin-top: 2px;
-  padding: 2px 6px;
-  border-radius: var(--radius-sm);
-  background: var(--bg-muted);
-  font-family: var(--mono, monospace);
-  font-size: 0.82em;
-}
-
-.workspace-onboarding__dismiss {
-  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  padding: 0;
-  border: none;
-  border-radius: var(--radius-sm);
-  background: transparent;
-  color: var(--text-muted, var(--text));
-  cursor: pointer;
-}
-
-.workspace-onboarding__dismiss:hover {
-  background: var(--bg-hover);
-  color: var(--text);
-}
-
-.workspace-onboarding__dismiss svg {
-  width: 15px;
-  height: 15px;
-}
-
-/* #12: themed edit-title / move-to-tab dialog inputs (mirrors the .field idiom). */
-.workspace-dialog__input {
-  border: 1px solid var(--input, var(--border));
-  background: var(--card);
-  border-radius: var(--radius-md);
-  padding: 8px 12px;
-  color: var(--text);
-  outline: none;
-  box-shadow: inset 0 1px 0 var(--card-highlight, transparent);
-  transition:
-    border-color var(--duration-fast, 120ms) ease,
-    box-shadow var(--duration-fast, 120ms) ease;
-}
-
-.workspace-dialog__input:focus-visible {
-  border-color: var(--ring, var(--accent));
-  box-shadow: var(--focus-ring, 0 0 0 2px color-mix(in srgb, var(--accent) 40%, transparent));
-}
-
-select.workspace-dialog__input {
-  appearance: none;
-  cursor: pointer;
-}
-
-/* #19: skeleton loading cards instead of a bare "Loading…" line. */
-.workspace-skeleton {
-  display: grid;
-  grid-template-columns: repeat(12, minmax(0, 1fr));
-  gap: var(--workspace-grid-gap);
-  flex: 1;
-  align-content: start;
-}
-
-.workspace-skeleton__card {
-  grid-column: span 4;
-  min-height: 120px;
-  border: 1px solid var(--border);
-  border-radius: var(--radius-lg);
-  background: linear-gradient(
-    100deg,
-    var(--card) 30%,
-    color-mix(in srgb, var(--text) 6%, var(--card)) 50%,
-    var(--card) 70%
-  );
-  background-size: 200% 100%;
-  animation: workspace-skeleton-shimmer 1.4s ease-in-out infinite;
-}
-
-@keyframes workspace-skeleton-shimmer {
-  from {
-    background-position: 200% 0;
-  }
-  to {
-    background-position: -200% 0;
-  }
-}
-
-@media (max-width: 900px) {
-  .workspace-skeleton {
-    grid-template-columns: minmax(0, 1fr);
-  }
-
-  .workspace-skeleton__card {
-    grid-column: 1 / -1;
-  }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  .workspace-skeleton__card {
-    animation: none;
-  }
-}

From e7fe47d63fbc02ad122d474a035f53ae0b46b6e5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 10:58:22 +0100
Subject: [PATCH 16/76] fix(browser): allow one retry after transient failures
 (#110607)

* fix(browser): soften transient retry guidance

* style(browser): format retry hint test

* chore: keep release note in PR body
---
 .../client-fetch.attach-only.e2e.test.ts      |   2 +
 .../client-fetch.loopback-auth.test.ts        | 253 +++++++++++++++++-
 .../browser/src/browser/client-fetch.ts       | 113 ++++++--
 3 files changed, 334 insertions(+), 34 deletions(-)

diff --git a/extensions/browser/src/browser/client-fetch.attach-only.e2e.test.ts b/extensions/browser/src/browser/client-fetch.attach-only.e2e.test.ts
index 37360e0e3bf..e0aa3f91837 100644
--- a/extensions/browser/src/browser/client-fetch.attach-only.e2e.test.ts
+++ b/extensions/browser/src/browser/client-fetch.attach-only.e2e.test.ts
@@ -75,6 +75,8 @@ describe("browser client fetch attachOnly diagnostics", () => {
       const message = thrown instanceof Error ? thrown.message : String(thrown);
       expect(message).toContain("browser profile is external to OpenClaw");
       expect(message).toContain("Restarting the OpenClaw gateway will not launch it");
+      expect(message).toContain("Retry the browser tool once");
+      expect(message).toContain("If the same error persists");
       expect(message).not.toContain("Restart the OpenClaw gateway");
       expect(message).not.toContain("Do NOT retry the browser tool");
     } finally {
diff --git a/extensions/browser/src/browser/client-fetch.loopback-auth.test.ts b/extensions/browser/src/browser/client-fetch.loopback-auth.test.ts
index c08b0fb6618..ba61fe74877 100644
--- a/extensions/browser/src/browser/client-fetch.loopback-auth.test.ts
+++ b/extensions/browser/src/browser/client-fetch.loopback-auth.test.ts
@@ -226,11 +226,16 @@ describe("fetchBrowserJson loopback auth", () => {
     expect(headers.get("authorization")).toBeNull();
   });
 
-  it("preserves dispatcher timeout context without no-retry hint", async () => {
+  it("preserves dispatcher timeout context with retry-once hint", async () => {
     mocks.dispatch.mockRejectedValueOnce(new Error("Chrome CDP handshake timeout"));
 
     await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
-      contains: ["Chrome CDP handshake timeout", "Restart the OpenClaw gateway"],
+      contains: [
+        "Chrome CDP handshake timeout",
+        "Restart the OpenClaw gateway",
+        "Retry the browser tool once",
+        "If the same error persists",
+      ],
       omits: ["Can't reach the OpenClaw browser control service", "Do NOT retry the browser tool"],
     });
   });
@@ -267,6 +272,8 @@ describe("fetchBrowserJson loopback auth", () => {
           "Chrome CDP handshake timeout",
           "browser profile is external to OpenClaw",
           "Restarting the OpenClaw gateway will not launch it",
+          "Retry the browser tool once",
+          "If the same error persists",
         ],
         omits: ["Restart the OpenClaw gateway", "Do NOT retry the browser tool"],
       },
@@ -319,6 +326,8 @@ describe("fetchBrowserJson loopback auth", () => {
           "timed out",
           "browser profile is external to OpenClaw",
           "Restarting the OpenClaw gateway will not launch it",
+          "Retry the browser tool once",
+          "If the same error persists",
         ],
         omits: ["Restart the OpenClaw gateway", "Do NOT retry the browser tool"],
       },
@@ -342,7 +351,12 @@ describe("fetchBrowserJson loopback auth", () => {
     await expectThrownBrowserFetchError(
       () => fetchBrowserJson<{ ok: boolean }>("/tabs?profile=openclaw"),
       {
-        contains: ["Chrome CDP handshake timeout", "Restart the OpenClaw gateway"],
+        contains: [
+          "Chrome CDP handshake timeout",
+          "Restart the OpenClaw gateway",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["browser profile is external to OpenClaw", "Do NOT retry the browser tool"],
       },
     );
@@ -357,7 +371,12 @@ describe("fetchBrowserJson loopback auth", () => {
     await expectThrownBrowserFetchError(
       () => fetchBrowserJson<{ ok: boolean }>("/tabs?profile=manual"),
       {
-        contains: ["Chrome CDP handshake timeout", "Restart the OpenClaw gateway"],
+        contains: [
+          "Chrome CDP handshake timeout",
+          "Restart the OpenClaw gateway",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["browser profile is external to OpenClaw", "Do NOT retry the browser tool"],
       },
     );
@@ -380,7 +399,12 @@ describe("fetchBrowserJson loopback auth", () => {
     await expectThrownBrowserFetchError(
       () => fetchBrowserJson<{ ok: boolean }>("/tabs?profile=missing"),
       {
-        contains: ["Chrome CDP handshake timeout", "Restart the OpenClaw gateway"],
+        contains: [
+          "Chrome CDP handshake timeout",
+          "Restart the OpenClaw gateway",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["browser profile is external to OpenClaw", "Do NOT retry the browser tool"],
       },
     );
@@ -406,6 +430,8 @@ describe("fetchBrowserJson loopback auth", () => {
         "Chrome CDP handshake timeout",
         "browser profile is external to OpenClaw",
         "Restarting the OpenClaw gateway will not launch it",
+        "Retry the browser tool once",
+        "If the same error persists",
       ],
       omits: ["Restart the OpenClaw gateway", "Do NOT retry the browser tool"],
     });
@@ -449,6 +475,51 @@ describe("fetchBrowserJson loopback auth", () => {
     });
   });
 
+  it("keeps transient dispatcher connection resets retryable once", async () => {
+    mocks.dispatch.mockRejectedValueOnce(new Error("Chrome CDP connection reset"));
+
+    await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
+      contains: [
+        "Chrome CDP connection reset",
+        "Retry the browser tool once",
+        "If the same error persists",
+      ],
+      omits: ["Do NOT retry the browser tool"],
+    });
+  });
+
+  it("uses top-level reset codes to classify dispatcher failures as transient", async () => {
+    mocks.dispatch.mockRejectedValueOnce(
+      Object.assign(new Error("socket closed"), { code: "ECONNRESET" }),
+    );
+
+    await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
+      contains: ["socket closed", "Retry the browser tool once", "If the same error persists"],
+      omits: ["Do NOT retry the browser tool"],
+    });
+  });
+
+  it("keeps refusal causes non-retryable when the outer error mentions a timeout", async () => {
+    const refused = Object.assign(new Error("connect refused"), { code: "ECONNREFUSED" });
+    mocks.dispatch.mockRejectedValueOnce(
+      new Error("browser request timed out", { cause: refused }),
+    );
+
+    await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
+      contains: ["browser request timed out", "Do NOT retry the browser tool"],
+      omits: ["Retry the browser tool once"],
+    });
+  });
+
+  it("keeps disabled browser control failures non-retryable", async () => {
+    mocks.dispatch.mockRejectedValueOnce(new Error("browser control disabled"));
+
+    await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
+      contains: ["browser control disabled", "Do NOT retry the browser tool"],
+      omits: ["Retry the browser tool once"],
+    });
+  });
+
   it("preserves validated structured errors from dispatcher routes", async () => {
     mocks.dispatch.mockResolvedValueOnce({
       status: 409,
@@ -540,7 +611,115 @@ describe("fetchBrowserJson loopback auth", () => {
       () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
       {
         contains: ["internal error"],
-        omits: ["rate limit"],
+        omits: ["rate limit", "Retry the browser tool once", "Do NOT retry the browser tool"],
+      },
+    );
+  });
+
+  it("keeps transient HTTP error payloads retryable once", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: "Chrome CDP handshake timeout" }), {
+            status: 504,
+          }),
+      ),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
+      {
+        contains: [
+          "Chrome CDP handshake timeout",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
+        omits: ["Do NOT retry the browser tool"],
+      },
+    );
+  });
+
+  it.each([408, 504])("uses HTTP %i to classify generic payloads as transient", async (status) => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("request failed", { status })),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
+      {
+        contains: ["request failed", "Retry the browser tool once", "If the same error persists"],
+        omits: ["Do NOT retry the browser tool"],
+      },
+    );
+  });
+
+  it("does not mark client validation errors transient from timeout wording alone", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: "invalid timeout value" }), {
+            status: 400,
+          }),
+      ),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
+      {
+        contains: ["invalid timeout value"],
+        omits: ["Retry the browser tool once", "Do NOT retry the browser tool"],
+      },
+    );
+  });
+
+  it("keeps pre-annotated persistent payload hints mutually exclusive", async () => {
+    const persistentHint =
+      "Do NOT retry the browser tool — it will keep failing. Use an alternative approach or inform the user that the browser is currently unavailable.";
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: `browser request timed out. ${persistentHint}` }), {
+            status: 504,
+          }),
+      ),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
+      {
+        contains: ["browser request timed out", persistentHint],
+        omits: ["Retry the browser tool once"],
+      },
+    );
+  });
+
+  it("keeps transient dispatcher error payloads retryable once", async () => {
+    mocks.dispatch.mockResolvedValueOnce({
+      status: 500,
+      body: { error: "read ECONNRESET" },
+    });
+
+    await expectThrownBrowserFetchError(() => fetchBrowserJson<{ ok: boolean }>("/tabs"), {
+      contains: ["read ECONNRESET", "Retry the browser tool once", "If the same error persists"],
+      omits: ["Do NOT retry the browser tool"],
+    });
+  });
+
+  it("keeps authentication failures non-retryable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("Unauthorized", { status: 401 })),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://127.0.0.1:18888/"),
+      {
+        contains: ["Unauthorized", "Do NOT retry the browser tool"],
+        omits: ["Retry the browser tool once"],
       },
     );
   });
@@ -557,7 +736,7 @@ describe("fetchBrowserJson loopback auth", () => {
     });
   });
 
-  it("keeps absolute URL failures wrapped as reachability errors", async () => {
+  it("keeps transient absolute URL failures retryable once", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async () => {
@@ -570,13 +749,51 @@ describe("fetchBrowserJson loopback auth", () => {
       {
         contains: [
           "Can't reach the OpenClaw browser control service",
-          "Do NOT retry the browser tool",
+          "Retry the browser tool once",
+          "If the same error persists",
         ],
+        omits: ["Do NOT retry the browser tool"],
+      },
+    );
+  });
+
+  it("uses nested reset causes to classify generic fetch failures as transient", async () => {
+    const reset = Object.assign(new Error("socket closed"), { code: "ECONNRESET" });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("fetch failed", { cause: reset });
+      }),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://example.com/"),
+      {
+        contains: ["fetch failed", "Retry the browser tool once", "If the same error persists"],
+        omits: ["Do NOT retry the browser tool"],
       },
     );
   });
 
-  it("omits no-retry hint for absolute HTTP timeout failures", async () => {
+  it("uses nested refusal causes to keep unavailable services non-retryable", async () => {
+    const refused = Object.assign(new Error("connect refused"), { code: "ECONNREFUSED" });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("fetch failed", { cause: refused });
+      }),
+    );
+
+    await expectThrownBrowserFetchError(
+      () => fetchBrowserJson<{ ok: boolean }>("http://example.com/"),
+      {
+        contains: ["fetch failed", "Do NOT retry the browser tool"],
+        omits: ["Retry the browser tool once"],
+      },
+    );
+  });
+
+  it("uses retry-once hint for absolute HTTP timeout failures", async () => {
     vi.stubGlobal(
       "fetch",
       vi.fn(async () => {
@@ -587,7 +804,11 @@ describe("fetchBrowserJson loopback auth", () => {
     await expectThrownBrowserFetchError(
       () => fetchBrowserJson<{ ok: boolean }>("http://example.com/", { timeoutMs: 1234 }),
       {
-        contains: ["timed out after 1234ms"],
+        contains: [
+          "timed out after 1234ms",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["Do NOT retry the browser tool"],
       },
     );
@@ -604,7 +825,11 @@ describe("fetchBrowserJson loopback auth", () => {
     await expectThrownBrowserFetchError(
       () => fetchBrowserJson<{ ok: boolean }>("http://example.com/", { timeoutMs: Number.NaN }),
       {
-        contains: ["timed out after 5000ms"],
+        contains: [
+          "timed out after 5000ms",
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["NaNms", "Do NOT retry the browser tool"],
       },
     );
@@ -628,7 +853,11 @@ describe("fetchBrowserJson loopback auth", () => {
           timeoutMs: Number.MAX_SAFE_INTEGER,
         }),
       {
-        contains: [`timed out after ${MAX_TIMER_TIMEOUT_MS}ms`],
+        contains: [
+          `timed out after ${MAX_TIMER_TIMEOUT_MS}ms`,
+          "Retry the browser tool once",
+          "If the same error persists",
+        ],
         omits: ["Do NOT retry the browser tool"],
       },
     );
diff --git a/extensions/browser/src/browser/client-fetch.ts b/extensions/browser/src/browser/client-fetch.ts
index 9281df4ca9a..7101f0c951d 100644
--- a/extensions/browser/src/browser/client-fetch.ts
+++ b/extensions/browser/src/browser/client-fetch.ts
@@ -5,6 +5,7 @@
  * in-process dispatcher, adding loopback auth and operator-facing diagnostics.
  */
 import { parseBrowserHttpUrl } from "openclaw/plugin-sdk/browser-config";
+import { extractErrorCode, formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { resolveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
 import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
 import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
@@ -45,8 +46,10 @@ function browserServiceErrorFromPayload(
   status?: number,
 ): BrowserServiceError {
   const parsed = parseBrowserErrorPayload(value);
+  const message = parsed?.error ?? fallback;
+  const modelHint = resolveBrowserServiceModelHint(message, status);
   return new BrowserServiceError(
-    parsed?.error ?? fallback,
+    modelHint ? appendBrowserToolModelHint(message, modelHint) : message,
     parsed && "reason" in parsed ? parsed : undefined,
     status,
   );
@@ -126,9 +129,19 @@ function withLoopbackBrowserAuth(
   });
 }
 
-const BROWSER_TOOL_MODEL_HINT =
+const BROWSER_TOOL_PERSISTENT_MODEL_HINT =
   "Do NOT retry the browser tool — it will keep failing. " +
   "Use an alternative approach or inform the user that the browser is currently unavailable.";
+const BROWSER_TOOL_TRANSIENT_MODEL_HINT =
+  "This may be a transient browser error. Retry the browser tool once. " +
+  "If the same error persists, use an alternative approach or inform the user that the browser is currently unavailable.";
+
+// Retry history already lives in the model transcript. Keep this classifier stateless so one
+// session's transient failure cannot suppress browser retries in another session.
+const BROWSER_TRANSIENT_NETWORK_ERROR_RE =
+  /\b(?:ECONNRESET|ECONNABORTED|ENETRESET|ETIMEDOUT|EPIPE|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|UND_ERR_(?:CONNECT_TIMEOUT|HEADERS_TIMEOUT|BODY_TIMEOUT|SOCKET))\b|fetch failed|network error|other side closed|socket (?:hang up|terminated)|connection (?:reset|aborted|timed out)/i;
+const BROWSER_PERSISTENT_FAILURE_RE =
+  /\bECONNREFUSED\b|connection refused|browser control (?:is )?(?:disabled|not enabled)|invalid (?:auth|authentication|credentials|password|token)|authentication (?:failed|required)|unauthorized/i;
 
 const BROWSER_ERROR_BODY_LIMIT_BYTES = 16 * 1024;
 // `response/body` supports 5M characters; 32 MiB covers worst-case JSON escaping while staying bounded.
@@ -185,38 +198,87 @@ function normalizeErrorMessage(err: unknown): string {
   return String(err);
 }
 
-function appendBrowserToolModelHint(message: string): string {
-  if (message.includes(BROWSER_TOOL_MODEL_HINT)) {
-    return message;
-  }
-  return `${message} ${BROWSER_TOOL_MODEL_HINT}`;
+function appendBrowserToolModelHint(message: string, hint: string): string {
+  const messageWithoutHints = message
+    .replaceAll(BROWSER_TOOL_PERSISTENT_MODEL_HINT, "")
+    .replaceAll(BROWSER_TOOL_TRANSIENT_MODEL_HINT, "")
+    .trim();
+  return `${messageWithoutHints} ${hint}`;
 }
 
-type BrowserFetchFailureKind = "timeout" | "aborted" | "persistent";
+type BrowserFetchFailureKind = "timeout" | "aborted" | "transient-network" | "persistent";
 
 function resolveBrowserFetchTimeoutMs(timeoutMs: number | undefined): number {
   return resolveTimerTimeoutMs(timeoutMs, 5000);
 }
 
 function classifyBrowserFetchFailure(err: unknown): BrowserFetchFailureKind {
-  const msg = normalizeErrorMessage(err);
-  const msgLower = normalizeLowercaseStringOrEmpty(msg);
+  const directCode = extractErrorCode(err);
+  const formatted = formatErrorMessage(err);
+  const detail = directCode ? `${formatted} | ${directCode}` : formatted;
+  const detailLower = normalizeLowercaseStringOrEmpty(detail);
   const nameLower = err instanceof Error ? normalizeLowercaseStringOrEmpty(err.name) : "";
+  if (nameLower === "aborterror") {
+    return "aborted";
+  }
+  if (BROWSER_PERSISTENT_FAILURE_RE.test(detail)) {
+    return "persistent";
+  }
   const looksLikeTimeout =
-    nameLower.includes("timeout") || msgLower.includes("timed out") || msgLower.includes("timeout");
+    nameLower.includes("timeout") ||
+    detailLower.includes("timed out") ||
+    detailLower.includes("timeout");
   if (looksLikeTimeout) {
     return "timeout";
   }
+  if (BROWSER_TRANSIENT_NETWORK_ERROR_RE.test(detail)) {
+    return "transient-network";
+  }
   const looksLikeAbort =
-    nameLower === "aborterror" ||
-    msgLower.includes("aborterror") ||
-    msgLower.includes("aborted") ||
-    msgLower.includes("abort") ||
-    msgLower.includes("cancelled") ||
-    msgLower.includes("canceled");
+    detailLower.includes("aborterror") ||
+    detailLower.includes("aborted") ||
+    detailLower.includes("abort") ||
+    detailLower.includes("cancelled") ||
+    detailLower.includes("canceled");
   return looksLikeAbort ? "aborted" : "persistent";
 }
 
+function isPersistentBrowserServiceFailure(message: string, status: number | undefined): boolean {
+  return status === 401 || BROWSER_PERSISTENT_FAILURE_RE.test(message);
+}
+
+function resolveBrowserServiceModelHint(
+  message: string,
+  status: number | undefined,
+): string | undefined {
+  if (message.includes(BROWSER_TOOL_PERSISTENT_MODEL_HINT)) {
+    return BROWSER_TOOL_PERSISTENT_MODEL_HINT;
+  }
+  if (message.includes(BROWSER_TOOL_TRANSIENT_MODEL_HINT)) {
+    return BROWSER_TOOL_TRANSIENT_MODEL_HINT;
+  }
+  if (isPersistentBrowserServiceFailure(message, status)) {
+    return BROWSER_TOOL_PERSISTENT_MODEL_HINT;
+  }
+  if (status === 408 || status === 504) {
+    return BROWSER_TOOL_TRANSIENT_MODEL_HINT;
+  }
+  if (status === undefined || status < 500 || status > 599) {
+    return undefined;
+  }
+  const kind = classifyBrowserFetchFailure(new Error(message));
+  return kind === "timeout" || kind === "transient-network"
+    ? BROWSER_TOOL_TRANSIENT_MODEL_HINT
+    : undefined;
+}
+
+function resolveBrowserToolModelHint(kind: BrowserFetchFailureKind): string | undefined {
+  if (kind === "timeout" || kind === "transient-network") {
+    return BROWSER_TOOL_TRANSIENT_MODEL_HINT;
+  }
+  return kind === "persistent" ? BROWSER_TOOL_PERSISTENT_MODEL_HINT : undefined;
+}
+
 async function discardResponseBody(res: Response): Promise<void> {
   try {
     await res.body?.cancel();
@@ -230,8 +292,8 @@ function enhanceDispatcherPathError(url: string, err: unknown): Error {
   const kind = classifyBrowserFetchFailure(err);
   const ownership = resolveDispatcherBrowserControlOwnership(url);
   const operatorHint = resolveBrowserFetchOperatorHint(url, { ownership });
-  const suffix =
-    kind === "persistent" ? `${operatorHint} ${BROWSER_TOOL_MODEL_HINT}` : operatorHint;
+  const modelHint = resolveBrowserToolModelHint(kind);
+  const suffix = modelHint ? `${operatorHint} ${modelHint}` : operatorHint;
   const normalized = msg.endsWith(".") ? msg : `${msg}.`;
   return new Error(`${normalized} ${suffix}`, err instanceof Error ? { cause: err } : undefined);
 }
@@ -242,7 +304,7 @@ function enhanceBrowserFetchError(url: string, err: unknown, timeoutMs: number):
   const kind = classifyBrowserFetchFailure(err);
   if (kind === "timeout") {
     return new Error(
-      `Can't reach the OpenClaw browser control service (timed out after ${timeoutMs}ms). ${operatorHint}`,
+      `Can't reach the OpenClaw browser control service (timed out after ${timeoutMs}ms). ${operatorHint} ${BROWSER_TOOL_TRANSIENT_MODEL_HINT}`,
       err instanceof Error ? { cause: err } : undefined,
     );
   }
@@ -252,9 +314,16 @@ function enhanceBrowserFetchError(url: string, err: unknown, timeoutMs: number):
       err instanceof Error ? { cause: err } : undefined,
     );
   }
+  if (kind === "transient-network") {
+    return new Error(
+      `Can't reach the OpenClaw browser control service. ${operatorHint} (${msg}) ${BROWSER_TOOL_TRANSIENT_MODEL_HINT}`,
+      err instanceof Error ? { cause: err } : undefined,
+    );
+  }
   return new Error(
     appendBrowserToolModelHint(
       `Can't reach the OpenClaw browser control service. ${operatorHint} (${msg})`,
+      BROWSER_TOOL_PERSISTENT_MODEL_HINT,
     ),
     err instanceof Error ? { cause: err } : undefined,
   );
@@ -298,7 +367,7 @@ async function fetchHttpJson<T>(
         // Do not reflect upstream response text into the error surface (log/agent injection risk)
         await discardResponseBody(res);
         throw new BrowserServiceError(
-          `${resolveBrowserRateLimitMessage(url)} ${BROWSER_TOOL_MODEL_HINT}`,
+          `${resolveBrowserRateLimitMessage(url)} ${BROWSER_TOOL_PERSISTENT_MODEL_HINT}`,
         );
       }
       // Overflow cancels the stream and releases its reader lock before the guarded fetch below.
@@ -420,7 +489,7 @@ export async function fetchBrowserJson<T>(
       if (isRateLimitStatus(result.status)) {
         // Do not reflect upstream response text into the error surface (log/agent injection risk)
         throw new BrowserServiceError(
-          `${resolveBrowserRateLimitMessage(url)} ${BROWSER_TOOL_MODEL_HINT}`,
+          `${resolveBrowserRateLimitMessage(url)} ${BROWSER_TOOL_PERSISTENT_MODEL_HINT}`,
         );
       }
       throw browserServiceErrorFromPayload(result.body, `HTTP ${result.status}`, result.status);

From 7a7c158210bc578e438c174a84cf93d7f3cbb50f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:01:08 +0100
Subject: [PATCH 17/76] perf(ci): parallelize gateway watch artifact check
 (#110609)

---
 .github/workflows/ci.yml                | 63 ++++++++++++++-----------
 docs/ci.md                              |  2 +-
 test/scripts/ci-workflow-guards.test.ts | 15 ++++--
 3 files changed, 46 insertions(+), 34 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4b96b75211b..9b1eedd3607 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1137,6 +1137,7 @@ jobs:
         id: built_artifact_checks
         if: needs.preflight.outputs.run_checks == 'true' || needs.preflight.outputs.run_checks_node_core_dist == 'true' || needs.preflight.outputs.run_check_additional == 'true'
         env:
+          PARALLEL_GATEWAY_WATCH: ${{ runner.environment != 'github-hosted' && 'true' || 'false' }}
           RUN_CHANNELS: ${{ needs.preflight.outputs.run_checks }}
           RUN_CORE_SUPPORT_BOUNDARY: ${{ needs.preflight.outputs.run_checks_node_core_dist }}
           RUN_GATEWAY_WATCH: ${{ needs.preflight.outputs.run_check_additional }}
@@ -1164,6 +1165,29 @@ jobs:
             pids+=("$!")
           }
 
+          wait_checks() {
+            local index name log pid result
+            for index in "${!pids[@]}"; do
+              name="${names[$index]}"
+              log="${logs[$index]}"
+              pid="${pids[$index]}"
+
+              if wait "$pid"; then
+                result="success"
+              else
+                result="failure"
+              fi
+
+              echo "::group::${name} log"
+              cat "$log"
+              echo "::endgroup::"
+              results["$name"]="$result"
+            done
+            names=()
+            pids=()
+            logs=()
+          }
+
           if [ "$RUN_CHANNELS" = "true" ]; then
             start_check "channels" env \
               NODE_OPTIONS=--max-old-space-size=8192 \
@@ -1178,36 +1202,19 @@ jobs:
               node scripts/run-vitest.mjs run --config test/vitest/vitest.full-core-support-boundary.config.ts
           fi
 
-          for index in "${!pids[@]}"; do
-            name="${names[$index]}"
-            log="${logs[$index]}"
-            pid="${pids[$index]}"
-
-            if wait "$pid"; then
-              result="success"
-            else
-              result="failure"
-            fi
-
-            echo "::group::${name} log"
-            cat "$log"
-            echo "::endgroup::"
-            results["$name"]="$result"
-          done
+          if [ "$RUN_GATEWAY_WATCH" = "true" ] && [ "$PARALLEL_GATEWAY_WATCH" = "true" ]; then
+            start_check "gateway-watch" \
+              node scripts/check-gateway-watch-regression.mjs --skip-build
+          fi
 
-          if [ "$RUN_GATEWAY_WATCH" = "true" ]; then
-            log="${RUNNER_TEMP}/gateway-watch.log"
-            echo "starting gateway-watch: node scripts/check-gateway-watch-regression.mjs --skip-build"
-            if node scripts/check-gateway-watch-regression.mjs --skip-build >"$log" 2>&1; then
-              result="success"
-            else
-              result="failure"
-            fi
+          wait_checks
 
-            echo "::group::gateway-watch log"
-            cat "$log"
-            echo "::endgroup::"
-            results["gateway-watch"]="$result"
+          # Preserve the low-core hosted path; concurrent Vitest can otherwise
+          # starve the Gateway readiness deadline used by this regression gate.
+          if [ "$RUN_GATEWAY_WATCH" = "true" ] && [ "$PARALLEL_GATEWAY_WATCH" != "true" ]; then
+            start_check "gateway-watch" \
+              node scripts/check-gateway-watch-regression.mjs --skip-build
+            wait_checks
           fi
 
           for name in channels core-support-boundary gateway-watch; do
diff --git a/docs/ci.md b/docs/ci.md
index 69a2e81aa12..61d22c79667 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -121,7 +121,7 @@ The slowest Node test families are split or balanced so each job stays small wit
 - The build-artifact job also persists content-fingerprinted `build-all` step outputs. CI's self-built plugin SDK declarations hash the complete repository-owned TypeScript/JSON source graph, exclude installed and generated directories, and restore both flat declarations and package bridges after `tsdown` clears `dist`. Documentation, workflow, plugin, and other changes outside that graph can reuse the declaration snapshot; source changes rebuild it before the export gate runs.
 - Full declaration builds split `tsdown` into AI, workspace-package, and unified groups. Each group caches declarations only, then still rebuilds runtime JavaScript before restoring those declarations. Core or plugin changes therefore invalidate only the large unified graph, while workspace-package changes conservatively invalidate every dependent declaration group. Public full builds generally use an immutable Actions cache; coarse restore keys seed partial changes, per-group content fingerprints reject stale data, and GitHub's cache quota evicts old generations. The weekly Node 22 lane instead publishes a 14-day artifact after successful `main` runs and restores only artifacts whose immutable producer identity resolves to that workflow on `main`, avoiding quota churn without allowing PR code to write a shared cache. Private-QA declarations are never persisted in Actions caches because cache namespaces are not confidentiality boundaries.
 - `check-additional-*` stripes the supplemental boundary guard list (`scripts/run-additional-boundary-checks.mjs`) into one prompt-heavy shard (`check-additional-boundaries-a`, which includes the Codex prompt snapshot drift check) and one combined shard for the remaining stripes (`check-additional-boundaries-bcd`), each running independent guards concurrently and printing per-check timings. Package-boundary compile/canary work stays together, and runtime topology architecture runs separately from the gateway watch coverage embedded in `build-artifacts`.
-- Gateway watch, channel tests, and the core support-boundary shard run concurrently inside `build-artifacts` after `dist/` and `dist-runtime/` are already built.
+- On the 32-vCPU self-hosted build runner, Gateway watch, channel tests, and the core support-boundary shard start together inside `build-artifacts` after `dist/` and `dist-runtime/` are already built. GitHub-hosted fallback runs keep Gateway watch serial so low-core contention cannot consume its readiness deadline.
 
 Once admitted, canonical Linux CI permits up to 28 concurrent Node test jobs and
 12 for the smaller fast/check lanes; Windows and Android stay at two because
diff --git a/test/scripts/ci-workflow-guards.test.ts b/test/scripts/ci-workflow-guards.test.ts
index bf27e4f1954..73d32bf1612 100644
--- a/test/scripts/ci-workflow-guards.test.ts
+++ b/test/scripts/ci-workflow-guards.test.ts
@@ -4087,7 +4087,7 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
     expect(saveStep.with.key).toContain("dist-build-v2-");
   });
 
-  it("runs gateway watch after parallel built artifact checks", () => {
+  it("parallelizes gateway watch only on the large self-hosted build runner", () => {
     const workflow = readCiWorkflow();
     const buildArtifactSteps = workflow.jobs["build-artifacts"].steps;
     const builtArtifactChecks = buildArtifactSteps.find(
@@ -4095,15 +4095,20 @@ printf '%s\n' "\${CURL_SUCCESS_IP:-203.0.113.7}"
     );
     const run = builtArtifactChecks.run;
 
+    expect(builtArtifactChecks.env.PARALLEL_GATEWAY_WATCH).toBe(
+      "${{ runner.environment != 'github-hosted' && 'true' || 'false' }}",
+    );
     expect(run).toContain('start_check "channels"');
     expect(run).toContain('start_check "core-support-boundary"');
-    expect(run).not.toContain('start_check "gateway-watch"');
-    expect(run.indexOf('for index in "${!pids[@]}"')).toBeLessThan(
-      run.indexOf('if [ "$RUN_GATEWAY_WATCH" = "true" ]; then'),
+    expect(run).toContain('start_check "gateway-watch"');
+    expect(run).toContain(
+      'if [ "$RUN_GATEWAY_WATCH" = "true" ] && [ "$PARALLEL_GATEWAY_WATCH" = "true" ]; then',
     );
     expect(run).toContain(
-      'node scripts/check-gateway-watch-regression.mjs --skip-build >"$log" 2>&1',
+      'if [ "$RUN_GATEWAY_WATCH" = "true" ] && [ "$PARALLEL_GATEWAY_WATCH" != "true" ]; then',
     );
+    expect(run).toContain("wait_checks()");
+    expect(run.match(/wait_checks$/gmu)).toHaveLength(2);
   });
 
   it("keeps docs i18n CI on the workflow-owned patched Go toolchain", () => {

From 8c95ec95ca50532d01d02affd150b691b0f178f4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:02:38 +0100
Subject: [PATCH 18/76] fix(ui): show sidebar connection state only on
 sustained disconnect (#110567)

---
 ui/src/components/app-sidebar.ts              | 60 +++++++++++++++----
 ui/src/components/sidebar-agent-card.ts       | 21 ++++---
 ui/src/styles/layout.css                      | 28 ++++-----
 .../test-helpers/app-sidebar-cases/basics.ts  | 41 ++++++++++++-
 ui/src/test-helpers/app-sidebar.ts            |  1 +
 5 files changed, 112 insertions(+), 39 deletions(-)

diff --git a/ui/src/components/app-sidebar.ts b/ui/src/components/app-sidebar.ts
index eeea929fbd1..d0c387b1911 100644
--- a/ui/src/components/app-sidebar.ts
+++ b/ui/src/components/app-sidebar.ts
@@ -1,4 +1,4 @@
-import { html, nothing } from "lit";
+import { html, nothing, type PropertyValues } from "lit";
 import { state } from "lit/decorators.js";
 import type { NavigationRouteId } from "../app-navigation.ts";
 import { pathForRoute } from "../app-route-paths.ts";
@@ -34,9 +34,13 @@ import {
 const PALETTE_SHORTCUT = /Mac|iP(hone|ad|od)/i.test(globalThis.navigator?.platform ?? "")
   ? "⌘K"
   : "Ctrl K";
+const OFFLINE_INDICATOR_DELAY_MS = 2_000;
 
 class AppSidebar extends AppSidebarSessionListElement {
   @state() private logoVisit: LobsterLogoVisitDetail | null = null;
+  @state() private debouncedDisconnected = false;
+
+  private offlineIndicatorTimer: ReturnType<typeof globalThis.setTimeout> | null = null;
 
   constructor() {
     super();
@@ -44,6 +48,38 @@ class AppSidebar extends AppSidebarSessionListElement {
     this.addEventListener(LOBSTER_LOGO_VISIT_EVENT, this.handleLogoVisit as EventListener);
   }
 
+  override connectedCallback() {
+    super.connectedCallback();
+    this.syncOfflineIndicator();
+  }
+
+  override disconnectedCallback() {
+    this.syncOfflineIndicator(false);
+    super.disconnectedCallback();
+  }
+
+  protected override willUpdate(changed: PropertyValues<this>) {
+    if (changed.has("connected")) {
+      this.syncOfflineIndicator();
+    }
+  }
+
+  private syncOfflineIndicator(schedule = !this.connected) {
+    if (this.offlineIndicatorTimer !== null) {
+      globalThis.clearTimeout(this.offlineIndicatorTimer);
+      this.offlineIndicatorTimer = null;
+    }
+    this.debouncedDisconnected = false;
+    if (!schedule) {
+      return;
+    }
+    // Both sidebar signals share one grace window so brief transport blips stay quiet.
+    this.offlineIndicatorTimer = globalThis.setTimeout(() => {
+      this.offlineIndicatorTimer = null;
+      this.debouncedDisconnected = true;
+    }, OFFLINE_INDICATOR_DELAY_MS);
+  }
+
   private readonly handleLogoVisit = (event: Event) => {
     const detail = (event as CustomEvent<LobsterLogoVisitDetail>).detail;
     // A lookless visit is a logo scare: the brand mark hides (the img gets
@@ -99,7 +135,7 @@ class AppSidebar extends AppSidebarSessionListElement {
           .agentName=${cardName}
           .avatarUrl=${cardAgent ? resolveAgentAvatarUrl(cardAgent) : null}
           .avatarText=${cardAvatarText}
-          .connected=${this.connected}
+          .offline=${this.debouncedDisconnected}
           .statusLabel=${gatewayStatus}
           .subtitle=${this.agentChipSubtitle(cardAgentId)}
           .menuOpen=${this.agentMenuPosition !== null}
@@ -209,15 +245,17 @@ class AppSidebar extends AppSidebarSessionListElement {
           .gatewayVersion=${this.gatewayVersion}
           .onNavigate=${(routeId: "about") => this.onNavigate?.(routeId)}
         ></openclaw-sidebar-build-chip>
-        <span
-          class="sidebar-footer-bar__status ${this.connected
-            ? "sidebar-connection-status--online"
-            : "sidebar-connection-status--offline"}"
-          role="img"
-          aria-live="polite"
-          aria-label=${gatewayStatus}
-          title=${gatewayStatus}
-        ></span>
+        ${this.debouncedDisconnected
+          ? html`<span
+              class="sidebar-footer-bar__status"
+              role="status"
+              aria-live="polite"
+              title=${gatewayStatus}
+              ><span class="sidebar-footer-bar__status-dot" aria-hidden="true"></span>${t(
+                "common.offline",
+              )}</span
+            >`
+          : nothing}
         <openclaw-tooltip .content=${t("nav.settings")}>
           <button
             type="button"
diff --git a/ui/src/components/sidebar-agent-card.ts b/ui/src/components/sidebar-agent-card.ts
index c07abb6bc78..f8afc22ce93 100644
--- a/ui/src/components/sidebar-agent-card.ts
+++ b/ui/src/components/sidebar-agent-card.ts
@@ -12,7 +12,7 @@ class SidebarAgentCard extends OpenClawLightDomContentsElement {
   @property({ attribute: false }) agentName = "";
   @property({ attribute: false }) avatarUrl: string | null = null;
   @property({ attribute: false }) avatarText = "";
-  @property({ attribute: false }) connected = false;
+  @property({ attribute: false }) offline = false;
   @property({ attribute: false }) statusLabel = "";
   @property({ attribute: false }) subtitle = "";
   @property({ attribute: false }) menuOpen = false;
@@ -33,7 +33,7 @@ class SidebarAgentCard extends OpenClawLightDomContentsElement {
           class="sidebar-agent-card__main"
           aria-haspopup="menu"
           aria-expanded=${String(this.menuOpen)}
-          aria-label="${this.agentName} · ${menuLabel}"
+          aria-label="${this.agentName} · ${menuLabel} · ${this.statusLabel}"
           @click=${(event: MouseEvent) => this.onToggleMenu?.(event.currentTarget as HTMLElement)}
         >
           <span class="sidebar-agent-card__avatar">
@@ -48,15 +48,14 @@ class SidebarAgentCard extends OpenClawLightDomContentsElement {
               : html`<span class="sidebar-agent-card__avatar-text" aria-hidden="true"
                   >${this.avatarText}</span
                 >`}
-            <span
-              class="sidebar-agent-card__presence ${this.connected
-                ? "sidebar-connection-status--online"
-                : "sidebar-connection-status--offline"}"
-              role="img"
-              aria-live="polite"
-              aria-label=${this.statusLabel}
-              title=${this.statusLabel}
-            ></span>
+            ${this.offline
+              ? html`<span
+                  class="sidebar-agent-card__presence"
+                  role="img"
+                  aria-label=${this.statusLabel}
+                  title=${this.statusLabel}
+                ></span>`
+              : nothing}
           </span>
           <span class="sidebar-agent-card__text">
             <span class="sidebar-agent-card__name">
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index 3b751c27eaf..b976dc66f60 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -2339,7 +2339,6 @@ wa-dropdown.sidebar-session-sort-menu::part(menu) {
   object-fit: cover;
 }
 
-/* Presence fuses connection state into the identity: no separate online dot. */
 .sidebar-agent-card__presence {
   position: absolute;
   right: -1px;
@@ -2348,13 +2347,6 @@ wa-dropdown.sidebar-session-sort-menu::part(menu) {
   height: 10px;
   border-radius: var(--radius-full);
   border: 2px solid var(--sidebar-bg);
-}
-
-.sidebar-agent-card__presence.sidebar-connection-status--online {
-  background: var(--ok);
-}
-
-.sidebar-agent-card__presence.sidebar-connection-status--offline {
   background: var(--danger);
 }
 
@@ -2485,17 +2477,23 @@ wa-dropdown.sidebar-session-sort-menu::part(menu) {
 }
 
 .sidebar-footer-bar__status {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
   flex: none;
-  width: 8px;
-  height: 8px;
+  padding: 3px 7px;
   border-radius: var(--radius-full);
+  background: color-mix(in srgb, var(--danger) 12%, transparent);
+  color: var(--danger);
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 1;
 }
 
-.sidebar-footer-bar__status.sidebar-connection-status--online {
-  background: var(--ok);
-}
-
-.sidebar-footer-bar__status.sidebar-connection-status--offline {
+.sidebar-footer-bar__status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: var(--radius-full);
   background: var(--danger);
 }
 
diff --git a/ui/src/test-helpers/app-sidebar-cases/basics.ts b/ui/src/test-helpers/app-sidebar-cases/basics.ts
index 011bcc5d5ea..479e5e1d7a8 100644
--- a/ui/src/test-helpers/app-sidebar-cases/basics.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/basics.ts
@@ -146,15 +146,52 @@ describe("AppSidebar agent chip", () => {
     expect(onNavigate).not.toHaveBeenCalledWith("config");
   });
 
-  it("shows offline in the chip subtitle when disconnected", async () => {
+  it("shows connection exceptions only after a sustained disconnect", async () => {
+    vi.useFakeTimers();
     const gateway = createGateway({} as GatewayBrowserClient);
     const { sidebar } = await mountSidebar(gateway, createSessions("main", ["agent:main:main"]));
-    sidebar.connected = false;
+    const presence = () => sidebar.querySelector(".sidebar-agent-card__presence");
+    const offlinePill = () => sidebar.querySelector(".sidebar-footer-bar__status");
+    const expectQuiet = () => {
+      expect(presence()).toBeNull();
+      expect(offlinePill()).toBeNull();
+    };
+    sidebar.connected = true;
     await sidebar.updateComplete;
 
+    expectQuiet();
+    expect(
+      sidebar.querySelector(".sidebar-agent-card__main")?.getAttribute("aria-label"),
+    ).toContain("Online");
+
+    sidebar.connected = false;
+    await sidebar.updateComplete;
     expect(sidebar.querySelector(".sidebar-agent-card__subtitle")?.textContent?.trim()).toBe(
       "Offline",
     );
+    await vi.advanceTimersByTimeAsync(1_999);
+    expectQuiet();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await sidebar.updateComplete;
+    const pill = offlinePill();
+    expect(pill?.textContent?.trim()).toBe("Offline");
+    expect(pill?.getAttribute("aria-live")).toBe("polite");
+    expect(pill?.getAttribute("title")).toContain("Offline");
+    expect(pill?.querySelector(".sidebar-footer-bar__status-dot")).not.toBeNull();
+    expect(presence()).not.toBeNull();
+
+    sidebar.connected = true;
+    await sidebar.updateComplete;
+    expectQuiet();
+
+    sidebar.connected = false;
+    await sidebar.updateComplete;
+    await vi.advanceTimersByTimeAsync(1_000);
+    sidebar.connected = true;
+    await sidebar.updateComplete;
+    await vi.advanceTimersByTimeAsync(2_000);
+    expectQuiet();
   });
 
   it("shows a working subtitle while the agent has an active run", async () => {
diff --git a/ui/src/test-helpers/app-sidebar.ts b/ui/src/test-helpers/app-sidebar.ts
index e4d14ac4d77..7838f002180 100644
--- a/ui/src/test-helpers/app-sidebar.ts
+++ b/ui/src/test-helpers/app-sidebar.ts
@@ -351,6 +351,7 @@ export function setupSidebarTest() {
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     document.body.replaceChildren();
     if (originalLocalStorage) {
       Object.defineProperty(globalThis, "localStorage", originalLocalStorage);

From b3650b70125a5fcac3cbb81f94a966df5e2085e0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:05:09 +0100
Subject: [PATCH 19/76] fix(tui): exit reliably after quit (#110595)

---
 src/tui/gateway-chat.test.ts      | 28 +++++++++++++++++++++++++++
 src/tui/gateway-chat.ts           |  4 +++-
 src/tui/tui-pty-local.e2e.test.ts |  8 ++++----
 src/tui/tui.test.ts               | 32 ++++++++++++++++++++++++-------
 4 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/src/tui/gateway-chat.test.ts b/src/tui/gateway-chat.test.ts
index 193d4d2c116..e600d656c65 100644
--- a/src/tui/gateway-chat.test.ts
+++ b/src/tui/gateway-chat.test.ts
@@ -653,6 +653,34 @@ describe("GatewayChatClient", () => {
     vi.useRealTimers();
   });
 
+  it("waits for gateway transport teardown on stop", async () => {
+    const client = new GatewayChatClient({
+      url: "ws://127.0.0.1:18789",
+      token: "test-token",
+      allowInsecureLocalOperatorUi: true,
+    });
+    let finishStop: (() => void) | undefined;
+    const stopAndWait = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finishStop = resolve;
+        }),
+    );
+    (client as unknown as { client: { stopAndWait: typeof stopAndWait } }).client.stopAndWait =
+      stopAndWait;
+
+    let stopped = false;
+    const stopPromise = client.stop().then(() => {
+      stopped = true;
+    });
+
+    expect(stopAndWait).toHaveBeenCalledOnce();
+    expect(stopped).toBe(false);
+    finishStop?.();
+    await stopPromise;
+    expect(stopped).toBe(true);
+  });
+
   it("identifies the TUI as a tui client and skips device identity on insecure local ui paths", async () => {
     const constructedOptions: Array<Record<string, unknown>> = [];
 
diff --git a/src/tui/gateway-chat.ts b/src/tui/gateway-chat.ts
index fb9ad04c34c..d850359c814 100644
--- a/src/tui/gateway-chat.ts
+++ b/src/tui/gateway-chat.ts
@@ -220,7 +220,9 @@ export class GatewayChatClient implements TuiBackend {
   }
 
   stop() {
-    this.client.stop();
+    // Keep TUI teardown ordered after the transport closes. Otherwise the
+    // late close callback can re-arm UI timers after shutdown cleared them.
+    return this.client.stopAndWait();
   }
 
   async subscribeSessionEvents() {
diff --git a/src/tui/tui-pty-local.e2e.test.ts b/src/tui/tui-pty-local.e2e.test.ts
index 2a0f57aa65b..46de5c0240d 100644
--- a/src/tui/tui-pty-local.e2e.test.ts
+++ b/src/tui/tui-pty-local.e2e.test.ts
@@ -701,7 +701,7 @@ async function startSharedGatewayFixture(): Promise<SharedGatewayFixture> {
     const fixtureMockModel = mockModel;
     const fixtureControlClient = controlClient;
     const cleanup = createIdempotentCleanup(async () => {
-      fixtureControlClient.stop();
+      await fixtureControlClient.stop();
       try {
         await fixtureGateway.cleanup();
       } finally {
@@ -719,7 +719,7 @@ async function startSharedGatewayFixture(): Promise<SharedGatewayFixture> {
       cleanup,
     };
   } catch (error) {
-    controlClient?.stop();
+    await controlClient?.stop();
     try {
       await gateway?.cleanup();
     } finally {
@@ -1033,7 +1033,7 @@ describe("TUI PTY real backends", () => {
           await fixture.run.write("/exit\r", { delay: false });
           expect((await fixture.run.waitForExit()).exitCode).toBe(0);
         } finally {
-          eventProbe?.stop();
+          await eventProbe?.stop();
           await fixture.cleanup();
         }
       },
@@ -1357,7 +1357,7 @@ describe("TUI PTY real backends", () => {
         await fixture.run.write("/exit\r", { delay: false });
         expect((await fixture.run.waitForExit()).exitCode).toBe(0);
       } finally {
-        queueClient.stop();
+        await queueClient.stop();
         await fixture.cleanup();
       }
     },
diff --git a/src/tui/tui.test.ts b/src/tui/tui.test.ts
index d6b04205c3c..1861a6921ae 100644
--- a/src/tui/tui.test.ts
+++ b/src/tui/tui.test.ts
@@ -1,6 +1,6 @@
 // Covers core TUI state transitions and backend event rendering.
 import { EventEmitter } from "node:events";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { MAX_TIMER_TIMEOUT_MS } from "../infra/parse-finite-number.js";
 import { MALFORMED_STREAMING_FRAGMENT_ERROR_MESSAGE } from "../shared/assistant-error-format.js";
@@ -426,6 +426,10 @@ describe("resolveTuiCtrlCAction", () => {
 });
 
 describe("TUI shutdown safety", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   it("drains terminal input before stopping the TUI", async () => {
     const calls: string[] = [];
     const drainInput = vi.fn(async () => {
@@ -543,12 +547,10 @@ describe("TUI shutdown safety", () => {
     expect(finish).toHaveBeenCalledTimes(1);
   });
 
-  it("schedules a process-exit guard after standalone TUI return", () => {
-    let callback: (() => void) | undefined;
+  it("does not keep a clean standalone TUI alive for the watchdog deadline", () => {
     const unref = vi.fn();
-    const setTimeoutFn = vi.fn((fn: () => void, ms: number) => {
-      callback = fn;
-      expect(ms).toBe(2000);
+    const setTimeoutFn = vi.fn((_callback: () => void, delayMs: number) => {
+      expect(delayMs).toBe(2000);
       return { unref };
     });
     const exit = vi.fn();
@@ -558,9 +560,25 @@ describe("TUI shutdown safety", () => {
 
     expect(setTimeoutFn).toHaveBeenCalledOnce();
     expect(unref).toHaveBeenCalledOnce();
-    callback?.();
+    expect(writeStderr).not.toHaveBeenCalled();
+    expect(exit).not.toHaveBeenCalled();
+  });
+
+  it("forces standalone TUI exit on deadline while another handle lingers", async () => {
+    vi.useFakeTimers();
+    const lingeringHandle = setInterval(() => {}, 60_000);
+    const exit = vi.fn();
+    const writeStderr = vi.fn();
+
+    const timer = scheduleProcessExitAfterTuiReturn({ exit, writeStderr });
+
+    expect((timer as NodeJS.Timeout).hasRef()).toBe(false);
+    await vi.advanceTimersByTimeAsync(1999);
+    expect(exit).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
     expect(writeStderr).toHaveBeenCalledWith("openclaw tui forcing process exit after return\n");
     expect(exit).toHaveBeenCalledWith(0);
+    clearInterval(lingeringHandle);
   });
 });
 

From bf20509c467bf6a3b20cd5281630f9d63c10754d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:06:32 +0100
Subject: [PATCH 20/76] fix: prevent TUI PTY tests from aborting after
 completion (#110610)

* test(tui): await PTY teardown before worker exit

* test(tui): avoid unbound PTY mock assertion
---
 src/tui/tui-pty-harness.e2e.test.ts  |  6 ++--
 src/tui/tui-pty-local.e2e.test.ts    |  4 +--
 src/tui/tui-pty-test-support.test.ts | 52 ++++++++++++++++++++++++++++
 src/tui/tui-pty-test-support.ts      | 42 +++++++++++++++-------
 4 files changed, 87 insertions(+), 17 deletions(-)
 create mode 100644 src/tui/tui-pty-test-support.test.ts

diff --git a/src/tui/tui-pty-harness.e2e.test.ts b/src/tui/tui-pty-harness.e2e.test.ts
index ace2dd1c01a..f97c1420d01 100644
--- a/src/tui/tui-pty-harness.e2e.test.ts
+++ b/src/tui/tui-pty-harness.e2e.test.ts
@@ -513,7 +513,7 @@ async function startTuiFixture(opts: { env?: NodeJS.ProcessEnv } = {}) {
     waitForLogEntry: async (predicate: (entry: FixtureLogEntry) => boolean, timeoutMs?: number) =>
       await waitForFixtureLogEntry(logPath, predicate, timeoutMs),
     cleanup: async () => {
-      run.dispose();
+      await run.dispose();
       await rm(tempDir, { recursive: true, force: true });
     },
   };
@@ -561,12 +561,12 @@ describe.sequential("TUI PTY harness", () => {
 
   afterAll(async () => {
     for (const run of activeRuns.splice(0)) {
-      run.dispose();
+      await run.dispose();
     }
     for (const started of [fixture, compactFooterFixture, slowStartupFixture]) {
       await (started as Awaited<ReturnType<typeof startTuiFixture>> | undefined)?.cleanup();
     }
-  });
+  }, STARTUP_TEST_TIMEOUT_MS);
 
   it("renders local ready on startup", () => {
     expect(fixture.run.output()).toContain("local ready");
diff --git a/src/tui/tui-pty-local.e2e.test.ts b/src/tui/tui-pty-local.e2e.test.ts
index 46de5c0240d..10977921365 100644
--- a/src/tui/tui-pty-local.e2e.test.ts
+++ b/src/tui/tui-pty-local.e2e.test.ts
@@ -571,7 +571,7 @@ async function startLocalModeTui(
   });
 
   const cleanup = createIdempotentCleanup(async () => {
-    run.dispose();
+    await run.dispose();
     await mockModel.stop();
     await rm(tempDir, { recursive: true, force: true });
   });
@@ -776,7 +776,7 @@ async function startGatewayModeTui(
   });
   const cleanup = createIdempotentCleanup(async () => {
     shared.mockModel.releaseFirstResponse(scenario.modelId);
-    run.dispose();
+    await run.dispose();
     for (const key of sessionKeys) {
       await shared.controlClient.abortChat({ sessionKey: key });
     }
diff --git a/src/tui/tui-pty-test-support.test.ts b/src/tui/tui-pty-test-support.test.ts
new file mode 100644
index 00000000000..1da873c20e8
--- /dev/null
+++ b/src/tui/tui-pty-test-support.test.ts
@@ -0,0 +1,52 @@
+import type { IPty } from "@lydell/node-pty";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const nodePtyMocks = vi.hoisted(() => ({
+  spawn: vi.fn(),
+}));
+
+vi.mock("@lydell/node-pty", () => ({
+  spawn: nodePtyMocks.spawn,
+}));
+
+import { startPty } from "./tui-pty-test-support.js";
+
+describe("TUI PTY test support", () => {
+  beforeEach(() => {
+    nodePtyMocks.spawn.mockReset();
+  });
+
+  it("waits for PTY exit before completing idempotent disposal", async () => {
+    const order: string[] = [];
+    let exitListener: ((event: { exitCode: number; signal?: number }) => void) | undefined;
+    const kill = vi.fn(() => order.push("kill"));
+    const pty = {
+      kill,
+      onData: vi.fn(() => ({ dispose: () => order.push("data-dispose") })),
+      onExit: vi.fn((listener: typeof exitListener) => {
+        exitListener = listener;
+        return { dispose: () => order.push("exit-dispose") };
+      }),
+      write: vi.fn(),
+    } as unknown as IPty;
+    nodePtyMocks.spawn.mockReturnValue(pty);
+
+    const run = startPty("node", [], {
+      cwd: process.cwd(),
+      env: {},
+      exitTimeoutMs: 1_000,
+      outputTimeoutMs: 1_000,
+    });
+
+    const disposal = run.dispose();
+    expect(run.dispose()).toBe(disposal);
+    expect(order).toEqual(["data-dispose", "kill"]);
+
+    order.push("exit");
+    exitListener?.({ exitCode: 0 });
+    await disposal;
+
+    expect(order).toEqual(["data-dispose", "kill", "exit", "exit-dispose"]);
+    expect(kill).toHaveBeenCalledWith("SIGTERM");
+  });
+});
diff --git a/src/tui/tui-pty-test-support.ts b/src/tui/tui-pty-test-support.ts
index fb63e14d681..3f323570347 100644
--- a/src/tui/tui-pty-test-support.ts
+++ b/src/tui/tui-pty-test-support.ts
@@ -13,9 +13,11 @@ export type PtyRun = {
   write: (data: string, opts?: { delay?: boolean }) => Promise<void>;
   waitForOutput: (needle: string, timeoutMs?: number) => Promise<string>;
   waitForExit: (timeoutMs?: number) => Promise<PtyExitEvent>;
-  dispose: () => void;
+  dispose: () => Promise<void>;
 };
 
+const PTY_EXIT_SETTLE_MS = 25;
+
 /** Polls until a reader returns a value or the timeout expires. */
 export function waitFor<T>(params: {
   timeoutMs: number;
@@ -116,14 +118,23 @@ export function startPty(
     },
   });
 
-  pty.onData((data) => {
+  const dataSubscription = pty.onData((data) => {
     output += data;
     mirrorPtyOutput(data);
   });
-  pty.onExit((event) => {
+  const exitSubscription = pty.onExit((event) => {
     exitEvent = event;
   });
 
+  const waitForExit = async (timeoutMs = opts.exitTimeoutMs) =>
+    await waitFor({
+      timeoutMs,
+      read: () => exitEvent,
+      onTimeout: () => new Error(`timed out waiting for PTY exit\n${output}`),
+    });
+
+  let disposePromise: Promise<void> | undefined;
+
   const run: PtyRun = {
     output: () => output,
     write: async (data, writeOpts) => await writePtyInput(pty, data, writeOpts),
@@ -143,16 +154,23 @@ export function startPty(
         },
         onTimeout: () => new Error(`timed out waiting for ${JSON.stringify(needle)}\n${output}`),
       }),
-    waitForExit: async (timeoutMs = opts.exitTimeoutMs) =>
-      await waitFor({
-        timeoutMs,
-        read: () => exitEvent,
-        onTimeout: () => new Error(`timed out waiting for PTY exit\n${output}`),
-      }),
+    waitForExit,
     dispose: () => {
-      if (!exitEvent) {
-        pty.kill("SIGTERM");
-      }
+      disposePromise ??= (async () => {
+        dataSubscription.dispose();
+        try {
+          if (!exitEvent) {
+            pty.kill("SIGTERM");
+          }
+          await waitForExit();
+          // node-pty releases its native exit callback after onExit returns.
+          // Give that release a turn before Vitest tears down the worker.
+          await sleep(PTY_EXIT_SETTLE_MS);
+        } finally {
+          exitSubscription.dispose();
+        }
+      })();
+      return disposePromise;
     },
   };
   opts.activeRuns?.push(run);

From fab3cdf1d8e2e716e006d6840ba34bcb1d347c4a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:09:21 +0100
Subject: [PATCH 21/76] refactor(gateway): simplify lifecycle mutation
 contracts (#110583)

* refactor(gateway): simplify lifecycle mutation contracts

* refactor(cli): unexport internal emitDaemonActionMessage
---
 src/cli/daemon-cli.coverage.test.ts           |  2 +-
 src/cli/daemon-cli/launchd-recovery.ts        | 12 ++--
 src/cli/daemon-cli/lifecycle-audit.ts         | 10 +--
 src/cli/daemon-cli/lifecycle-core.test.ts     | 61 +++++++++++++------
 src/cli/daemon-cli/lifecycle-core.ts          | 49 +++++++--------
 src/cli/daemon-cli/lifecycle.ts               |  6 ++
 src/cli/daemon-cli/response.ts                |  2 +-
 src/cli/daemon-cli/start-repair.ts            | 24 ++++++--
 .../test-helpers/lifecycle-core-harness.ts    |  2 +-
 src/cli/gateway-cli/run.ts                    |  5 +-
 src/cli/ports.ts                              | 12 +---
 src/daemon/launchd-restart-handoff.test.ts    |  4 +-
 src/daemon/launchd-restart-handoff.ts         |  4 --
 src/daemon/launchd.test.ts                    |  2 +-
 src/daemon/launchd.ts                         | 33 ++++------
 src/daemon/restart-logs.ts                    |  4 +-
 src/daemon/schtasks.stop.test.ts              |  2 +-
 src/daemon/schtasks.ts                        | 45 ++++++--------
 src/daemon/service-mutation.ts                | 14 +++++
 src/daemon/service-types.ts                   | 41 +++++++++++--
 src/daemon/service.test-helpers.ts            |  2 +-
 src/daemon/service.test.ts                    | 22 +++++++
 src/daemon/service.ts                         |  7 ++-
 src/daemon/systemd.test.ts                    |  2 +-
 src/daemon/systemd.ts                         | 19 +++---
 25 files changed, 230 insertions(+), 156 deletions(-)
 create mode 100644 src/daemon/service-mutation.ts

diff --git a/src/cli/daemon-cli.coverage.test.ts b/src/cli/daemon-cli.coverage.test.ts
index ffeb05047cd..e2d800bf583 100644
--- a/src/cli/daemon-cli.coverage.test.ts
+++ b/src/cli/daemon-cli.coverage.test.ts
@@ -14,7 +14,7 @@ const resolveGatewayProgramArguments = vi.fn(async (_opts?: unknown) => ({
 const serviceInstall = vi.fn().mockResolvedValue(undefined);
 const serviceStage = vi.fn().mockResolvedValue(undefined);
 const serviceUninstall = vi.fn().mockResolvedValue(undefined);
-const serviceStart = vi.fn().mockResolvedValue({ outcome: "completed" });
+const serviceStart = vi.fn().mockResolvedValue(undefined);
 const serviceStop = vi.fn().mockResolvedValue(undefined);
 const serviceRestart = vi.fn().mockResolvedValue({ outcome: "completed" });
 const serviceIsLoaded = vi.fn().mockResolvedValue(false);
diff --git a/src/cli/daemon-cli/launchd-recovery.ts b/src/cli/daemon-cli/launchd-recovery.ts
index bd0a24b1cc5..e9e028c5971 100644
--- a/src/cli/daemon-cli/launchd-recovery.ts
+++ b/src/cli/daemon-cli/launchd-recovery.ts
@@ -10,17 +10,19 @@ const LAUNCH_AGENT_RECOVERY_MESSAGE =
 
 type LaunchAgentRecoveryAction = "started" | "restarted";
 
-type LaunchAgentRecoveryResult = {
-  result: LaunchAgentRecoveryAction;
+type LaunchAgentRecoveryResult<TResult extends LaunchAgentRecoveryAction> = {
+  result: TResult;
   loaded: true;
   message: string;
 };
 
 /** Re-bootstrap an installed but unloaded LaunchAgent after a daemon start/restart command. */
-export async function recoverInstalledLaunchAgent(params: {
-  result: LaunchAgentRecoveryAction;
+export async function recoverInstalledLaunchAgent<
+  TResult extends LaunchAgentRecoveryAction,
+>(params: {
+  result: TResult;
   env?: Record<string, string | undefined>;
-}): Promise<LaunchAgentRecoveryResult | null> {
+}): Promise<LaunchAgentRecoveryResult<TResult> | null> {
   if (process.platform !== "darwin") {
     return null;
   }
diff --git a/src/cli/daemon-cli/lifecycle-audit.ts b/src/cli/daemon-cli/lifecycle-audit.ts
index c4ee77a5578..3b904cfb58d 100644
--- a/src/cli/daemon-cli/lifecycle-audit.ts
+++ b/src/cli/daemon-cli/lifecycle-audit.ts
@@ -2,8 +2,10 @@ import {
   appendGatewayLifecycleAuditLog,
   type GatewayLifecycleAuditSource,
 } from "../../daemon/restart-logs.js";
+import { createGatewayLifecycleMutationReporter } from "../../daemon/service-mutation.js";
 /** Gateway lifecycle audit helpers shared by managed and unmanaged CLI paths. */
 import type { GatewayLifecycleMutation } from "../../daemon/service-types.js";
+import type { GatewayLifecycleMutationMode } from "../../daemon/service-types.js";
 import { isTerminalInteractive } from "../terminal-interactivity.js";
 
 type GatewayLifecycleAction = "start" | "stop" | "restart";
@@ -11,7 +13,7 @@ type GatewayLifecycleAction = "start" | "stop" | "restart";
 export function appendGatewayLifecycleAudit(params: {
   action: GatewayLifecycleAction;
   source: GatewayLifecycleAuditSource;
-  mode: string;
+  mode: GatewayLifecycleMutationMode;
   pid?: number;
   env?: NodeJS.ProcessEnv;
 }): void {
@@ -29,15 +31,15 @@ export function createGatewayLifecycleMutationAudit(params: {
   source?: GatewayLifecycleAuditSource;
   env?: NodeJS.ProcessEnv;
 }): (mutation: GatewayLifecycleMutation) => void {
-  return (mutation) => {
+  const reportMutation = createGatewayLifecycleMutationReporter((mutation) => {
     appendGatewayLifecycleAudit({
       action: params.action,
       source: params.source ?? "cli",
       mode: mutation.mode,
-      ...(mutation.pid === undefined ? {} : { pid: mutation.pid }),
       ...(params.env === undefined ? {} : { env: params.env }),
     });
-  };
+  });
+  return (mutation) => reportMutation(mutation.mode);
 }
 
 export function createServiceLifecycleMutationAudit(params: {
diff --git a/src/cli/daemon-cli/lifecycle-core.test.ts b/src/cli/daemon-cli/lifecycle-core.test.ts
index 36d42b17026..861d6079b37 100644
--- a/src/cli/daemon-cli/lifecycle-core.test.ts
+++ b/src/cli/daemon-cli/lifecycle-core.test.ts
@@ -580,8 +580,8 @@ describe("runServiceRestart token drift", () => {
     expect(clearGatewayRestartIntentSync).toHaveBeenCalledOnce();
   });
 
-  it("emits scheduled when service start is deferred", async () => {
-    service.start.mockResolvedValue({ outcome: "scheduled" });
+  it("reports an already-running gateway without starting it", async () => {
+    service.readRuntime.mockResolvedValue({ status: "running", pid: 4242 });
 
     await runServiceStart({
       serviceNoun: "Gateway",
@@ -590,36 +590,61 @@ describe("runServiceRestart token drift", () => {
       opts: { json: true },
     });
 
-    expect(service.isLoaded).toHaveBeenCalled();
-    const payload = readJsonLog<{ result?: string; message?: string }>();
-    expect(payload.result).toBe("scheduled");
-    expect(payload.message).toBe("restart scheduled, gateway will restart momentarily");
+    const payload = readJsonLog<{ ok?: boolean; result?: string; message?: string }>();
+    expect(payload).toMatchObject({
+      ok: true,
+      result: "already-running",
+      message: "Gateway service already running (pid 4242).",
+    });
+    expect(service.start).not.toHaveBeenCalled();
+    expect(appendGatewayLifecycleAudit).not.toHaveBeenCalled();
   });
 
-  it("reports an already-running gateway without starting it", async () => {
+  it("warns in json when an already-running gateway definition needs repair", async () => {
     service.readRuntime.mockResolvedValue({ status: "running", pid: 4242 });
+    service.readCommand.mockResolvedValue({
+      programArguments: ["openclaw", "gateway", "run"],
+      environment: { OPENCLAW_SERVICE_VERSION: "2026.4.24" },
+    });
+
+    await runServiceStart(createServiceRunArgs());
+
+    const payload = readJsonLog<{ result?: string; warnings?: string[] }>();
+    expect(payload.result).toBe("already-running");
+    expect(payload.warnings).toEqual([
+      expect.stringMatching(
+        /^Gateway service already running, but its installed service definition needs repair: service was installed by OpenClaw 2026\.4\.24, current CLI is .+; run `openclaw gateway restart` to apply\.$/,
+      ),
+    ]);
+    expect(service.start).not.toHaveBeenCalled();
+  });
+
+  it("prints one warning line when an already-running gateway definition needs repair", async () => {
+    service.readRuntime.mockResolvedValue({ status: "running", pid: 4242 });
+    service.readCommand.mockResolvedValue({
+      programArguments: ["openclaw", "gateway", "run"],
+      environment: { OPENCLAW_SERVICE_VERSION: "2026.4.24" },
+    });
 
     await runServiceStart({
       serviceNoun: "Gateway",
       service,
       renderStartHints: () => [],
-      opts: { json: true },
     });
 
-    const payload = readJsonLog<{ ok?: boolean; result?: string; message?: string }>();
-    expect(payload).toMatchObject({
-      ok: true,
-      result: "already-running",
-      message: "Gateway service already running (pid 4242).",
-    });
+    const repairWarnings = runtimeLogs.filter((line) =>
+      line.startsWith(
+        "Gateway service already running, but its installed service definition needs repair:",
+      ),
+    );
+    expect(repairWarnings).toHaveLength(1);
+    expect(repairWarnings[0]).toContain("run `openclaw gateway restart` to apply.");
     expect(service.start).not.toHaveBeenCalled();
-    expect(appendGatewayLifecycleAudit).not.toHaveBeenCalled();
   });
 
   it("audits a service start that actually mutates the gateway", async () => {
     service.start.mockImplementationOnce(async (args?: GatewayServiceControlArgs) => {
       args?.onMutation?.({ mode: "kickstart" });
-      return { outcome: "completed" };
     });
 
     await runServiceStart(createServiceRunArgs());
@@ -634,7 +659,7 @@ describe("runServiceRestart token drift", () => {
   it("audits direct managed restart mutations", async () => {
     service.readRuntime.mockResolvedValue({ status: "running", pid: 4242 });
     service.restart.mockImplementationOnce(async (args?: GatewayServiceControlArgs) => {
-      args?.onMutation?.({ mode: "kickstart", pid: 4242 });
+      args?.onMutation?.({ mode: "kickstart" });
       return { outcome: "completed" };
     });
 
@@ -644,7 +669,6 @@ describe("runServiceRestart token drift", () => {
       action: "restart",
       source: "cli",
       mode: "kickstart",
-      pid: 4242,
     });
   });
 
@@ -671,7 +695,6 @@ describe("runServiceRestart token drift", () => {
       args?.warn?.(
         "Existing generated LaunchAgent env wrapper contains custom behavior and will be overwritten.",
       );
-      return { outcome: "completed" };
     });
 
     await runServiceStart({
diff --git a/src/cli/daemon-cli/lifecycle-core.ts b/src/cli/daemon-cli/lifecycle-core.ts
index 1bac74299e9..c559fba547c 100644
--- a/src/cli/daemon-cli/lifecycle-core.ts
+++ b/src/cli/daemon-cli/lifecycle-core.ts
@@ -32,7 +32,6 @@ import { getConfigActionPreflightFailure } from "./lifecycle-config-preflight.js
 import {
   buildDaemonServiceSnapshot,
   createDaemonActionContext,
-  emitDaemonActionMessage,
   emitDaemonAlreadyRunning,
   emitDaemonScheduledRestart,
 } from "./response.js";
@@ -54,8 +53,8 @@ type RestartPostCheckContext = {
   fail: (message: string, hints?: string[]) => void;
 };
 
-type ServiceRecoveryResult = {
-  result: "started" | "stopped" | "restarted";
+type ServiceRecoveryResult<TResult extends "started" | "stopped" | "restarted"> = {
+  result: TResult;
   message?: string;
   warnings?: string[];
   loaded?: boolean;
@@ -198,8 +197,10 @@ export async function runServiceStart(params: {
   service: GatewayService;
   renderStartHints: () => string[];
   opts?: DaemonLifecycleOptions;
-  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult | null>;
-  repairLoadedService?: (ctx: ServiceStartRepairContext) => Promise<ServiceRecoveryResult | null>;
+  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult<"started"> | null>;
+  repairLoadedService?: (
+    ctx: ServiceStartRepairContext,
+  ) => Promise<ServiceRecoveryResult<"started"> | null>;
   expectedPort?: number;
 }) {
   const json = Boolean(params.opts?.json);
@@ -276,6 +277,15 @@ export async function runServiceStart(params: {
       return;
     }
     if (startResult.outcome === "already-running") {
+      if (startResult.issues.length > 0) {
+        const warning = `${params.serviceNoun} service already running, but its installed service definition needs repair: ${startResult.issues
+          .map((issue) => issue.message)
+          .join("; ")}; run \`openclaw gateway restart\` to apply.`;
+        warnings.push(warning);
+        if (!json) {
+          defaultRuntime.log(warning);
+        }
+      }
       emitDaemonAlreadyRunning({
         serviceNoun: params.serviceNoun,
         service: params.service,
@@ -286,23 +296,6 @@ export async function runServiceStart(params: {
       });
       return;
     }
-    if (startResult.outcome === "scheduled") {
-      const restartStatus = describeGatewayServiceRestart(params.serviceNoun, {
-        outcome: "scheduled",
-      });
-      emitDaemonActionMessage({
-        json,
-        emit,
-        payload: {
-          ok: true,
-          result: "scheduled",
-          message: restartStatus.message,
-          service: buildDaemonServiceSnapshot(params.service, startResult.state.loaded),
-          warnings: warnings.length ? warnings : undefined,
-        },
-      });
-      return;
-    }
     if (startResult.outcome === "repair-required") {
       try {
         const handled = await params.repairLoadedService?.({
@@ -359,7 +352,7 @@ export async function runServiceStop(params: {
   serviceNoun: string;
   service: GatewayService;
   opts?: DaemonLifecycleOptions;
-  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult | null>;
+  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult<"stopped"> | null>;
   stopWhenNotLoaded?: boolean;
 }) {
   const json = Boolean(params.opts?.json);
@@ -466,9 +459,11 @@ export async function runServiceRestart(params: {
   opts?: DaemonLifecycleOptions;
   checkTokenDrift?: boolean;
   expectedPort?: number;
-  repairLoadedService?: (ctx: ServiceStartRepairContext) => Promise<ServiceRecoveryResult | null>;
+  repairLoadedService?: (
+    ctx: ServiceStartRepairContext,
+  ) => Promise<ServiceRecoveryResult<"restarted"> | null>;
   postRestartCheck?: (ctx: RestartPostCheckContext) => Promise<GatewayServiceRestartResult | void>;
-  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult | null>;
+  onNotLoaded?: (ctx: ServiceRecoveryContext) => Promise<ServiceRecoveryResult<"restarted"> | null>;
 }): Promise<boolean> {
   const json = Boolean(params.opts?.json);
   const { stdout, warnings, emit, fail } = createDaemonActionContext({ action: "restart", json });
@@ -478,8 +473,8 @@ export async function runServiceRestart(params: {
     serviceNoun: params.serviceNoun,
     action: "restart",
   });
-  let handledRecovery: ServiceRecoveryResult | null = null;
-  let handledRepair: ServiceRecoveryResult | null = null;
+  let handledRecovery: ServiceRecoveryResult<"restarted"> | null = null;
+  let handledRepair: ServiceRecoveryResult<"restarted"> | null = null;
   let recoveredLoadedState: boolean | null = null;
   let wroteRestartIntent = false;
   const prepareGatewayRestartIntent = async () => {
diff --git a/src/cli/daemon-cli/lifecycle.ts b/src/cli/daemon-cli/lifecycle.ts
index 4b15b163fe7..def0fdfd9b6 100644
--- a/src/cli/daemon-cli/lifecycle.ts
+++ b/src/cli/daemon-cli/lifecycle.ts
@@ -167,6 +167,12 @@ function resolveVerifiedGatewayListenerPids(port: number): number[] {
   );
 }
 
+async function handleSystemScopeSystemdGateway(
+  action: "stop",
+): Promise<{ result: "stopped"; message: string } | null>;
+async function handleSystemScopeSystemdGateway(
+  action: "restart",
+): Promise<{ result: "restarted"; message: string } | null>;
 async function handleSystemScopeSystemdGateway(
   action: "stop" | "restart",
 ): Promise<{ result: "stopped" | "restarted"; message: string } | null> {
diff --git a/src/cli/daemon-cli/response.ts b/src/cli/daemon-cli/response.ts
index 641090bf5e3..71164e2727d 100644
--- a/src/cli/daemon-cli/response.ts
+++ b/src/cli/daemon-cli/response.ts
@@ -100,7 +100,7 @@ export function buildDaemonServiceSnapshot(service: GatewayService, loaded: bool
 type DaemonEmit = (payload: Omit<DaemonActionResponse, "action">) => void;
 
 /** Emit a lifecycle result and mirror its message to text output. */
-export function emitDaemonActionMessage(params: {
+function emitDaemonActionMessage(params: {
   json: boolean;
   emit: DaemonEmit;
   payload: Omit<DaemonActionResponse, "action">;
diff --git a/src/cli/daemon-cli/start-repair.ts b/src/cli/daemon-cli/start-repair.ts
index 357d2b55795..da181c436ad 100644
--- a/src/cli/daemon-cli/start-repair.ts
+++ b/src/cli/daemon-cli/start-repair.ts
@@ -16,9 +16,7 @@ import { parseTcpPort, parseTcpPortFromArgs } from "../../infra/tcp-port.js";
 import { defaultRuntime } from "../../runtime.js";
 import { mergeInstallInvocationEnv } from "./install.js";
 
-/** Repair a loaded but stale Gateway service definition and report the start result. */
-export async function repairLoadedGatewayServiceForStart(params: {
-  action?: "restart" | "start";
+type GatewayServiceRepairParams = {
   service: GatewayService;
   port?: number;
   state: GatewayServiceState;
@@ -26,7 +24,25 @@ export async function repairLoadedGatewayServiceForStart(params: {
   json: boolean;
   stdout: NodeJS.WritableStream;
   warn?: (message: string) => void;
-}): Promise<{
+};
+
+type GatewayServiceRepairResult<TResult extends "restarted" | "started"> = {
+  result: TResult;
+  message: string;
+  warnings?: string[];
+  loaded: boolean;
+};
+
+/** Repair a loaded but stale Gateway service definition and report the start result. */
+export function repairLoadedGatewayServiceForStart(
+  params: GatewayServiceRepairParams & { action: "restart" },
+): Promise<GatewayServiceRepairResult<"restarted">>;
+export function repairLoadedGatewayServiceForStart(
+  params: GatewayServiceRepairParams & { action?: "start" },
+): Promise<GatewayServiceRepairResult<"started">>;
+export async function repairLoadedGatewayServiceForStart(
+  params: GatewayServiceRepairParams & { action?: "restart" | "start" },
+): Promise<{
   result: "restarted" | "started";
   message: string;
   warnings?: string[];
diff --git a/src/cli/daemon-cli/test-helpers/lifecycle-core-harness.ts b/src/cli/daemon-cli/test-helpers/lifecycle-core-harness.ts
index ba9a86bce6e..f587f44c94d 100644
--- a/src/cli/daemon-cli/test-helpers/lifecycle-core-harness.ts
+++ b/src/cli/daemon-cli/test-helpers/lifecycle-core-harness.ts
@@ -56,7 +56,7 @@ export function resetLifecycleServiceMocks() {
   service.readRuntime.mockResolvedValue({ status: "stopped" });
   service.stop.mockResolvedValue(undefined);
   service.uninstall.mockResolvedValue(undefined);
-  service.start.mockResolvedValue({ outcome: "completed" });
+  service.start.mockResolvedValue(undefined);
   service.restart.mockResolvedValue({ outcome: "completed" });
 }
 
diff --git a/src/cli/gateway-cli/run.ts b/src/cli/gateway-cli/run.ts
index dcb0d19f72b..d8804b749a6 100644
--- a/src/cli/gateway-cli/run.ts
+++ b/src/cli/gateway-cli/run.ts
@@ -839,6 +839,7 @@ async function runGatewayCommandOnce(opts: GatewayRunOpts, hooks: GatewayRunRunt
     }
   }
   if (opts.force) {
+    const interactive = isTerminalInteractive();
     const describeNonInteractiveGatewayOwner = () => {
       const gatewayPids = findVerifiedGatewayListenerPidsOnPortSync(port);
       if (gatewayPids.length === 0) {
@@ -846,7 +847,7 @@ async function runGatewayCommandOnce(opts: GatewayRunOpts, hooks: GatewayRunRunt
       }
       return `${NON_INTERACTIVE_GATEWAY_RUN_FORCE_MESSAGE} Existing gateway listener pid${gatewayPids.length === 1 ? "" : "s"}: ${formatGatewayPidList(gatewayPids)}.`;
     };
-    if (!isTerminalInteractive()) {
+    if (!interactive) {
       const refusal = describeNonInteractiveGatewayOwner();
       if (refusal) {
         defaultRuntime.error(refusal);
@@ -860,7 +861,7 @@ async function runGatewayCommandOnce(opts: GatewayRunOpts, hooks: GatewayRunRunt
         timeoutMs: 2000,
         intervalMs: 100,
         sigtermTimeoutMs: 700,
-        ...(isTerminalInteractive()
+        ...(interactive
           ? {}
           : {
               beforeSignal: () => {
diff --git a/src/cli/ports.ts b/src/cli/ports.ts
index 89924ad0ddf..2306c59d60e 100644
--- a/src/cli/ports.ts
+++ b/src/cli/ports.ts
@@ -284,17 +284,7 @@ export function forceFreePort(
   opts: { beforeSignal?: BeforePortSignal } = {},
 ): PortProcess[] {
   const listeners = listPortListeners(port);
-  for (const proc of listeners) {
-    try {
-      opts.beforeSignal?.({ port, pid: proc.pid, signal: "SIGTERM" });
-      process.kill(proc.pid, "SIGTERM");
-    } catch (err) {
-      throw new Error(
-        `failed to kill pid ${proc.pid}${proc.command ? ` (${proc.command})` : ""}: ${String(err)}`,
-        { cause: err },
-      );
-    }
-  }
+  killPids(port, listeners, "SIGTERM", opts.beforeSignal);
   return listeners;
 }
 
diff --git a/src/daemon/launchd-restart-handoff.test.ts b/src/daemon/launchd-restart-handoff.test.ts
index 8a57effb393..56d1856d198 100644
--- a/src/daemon/launchd-restart-handoff.test.ts
+++ b/src/daemon/launchd-restart-handoff.test.ts
@@ -138,7 +138,6 @@ describe("scheduleDetachedLaunchdRestartHandoff", () => {
     expect(args[0]).toBe("-c");
     expect(args[2]).toBe("openclaw-launchd-restart-handoff");
     expect(args[6]).toBe("9876");
-    expect(args[7]).toBe("ai.openclaw.gateway");
     expect(args[1]).toContain('while kill -0 "$wait_pid" >/dev/null 2>&1; do');
     expect(args[1]).toContain("exec >>'/Users/test/.openclaw/logs/gateway-restart.log' 2>&1");
     expect(args[1]).toContain("openclaw restart attempt source=handoff mode=kickstart");
@@ -153,7 +152,7 @@ describe("scheduleDetachedLaunchdRestartHandoff", () => {
     expect(unrefMock).toHaveBeenCalledTimes(1);
   });
 
-  it("passes the plain label separately for start-after-exit mode", () => {
+  it("uses the service target for start-after-exit mode", () => {
     spawnMock.mockReturnValue({ pid: 4242, unref: unrefMock });
 
     scheduleDetachedLaunchdRestartHandoff({
@@ -165,7 +164,6 @@ describe("scheduleDetachedLaunchdRestartHandoff", () => {
     });
 
     const [, args] = requireSpawnCall();
-    expect(args[7]).toBe("ai.openclaw.gateway");
     expect(args[1]).toContain('if launchctl print "$service_target" >/dev/null 2>&1; then');
     expect(args[1]).toContain("reason=launchd-auto-reload");
     expect(args[1]).toContain("print_retry_count=$((print_retry_count - 1))");
diff --git a/src/daemon/launchd-restart-handoff.ts b/src/daemon/launchd-restart-handoff.ts
index 491ef3d72d8..98d6f1a18f7 100644
--- a/src/daemon/launchd-restart-handoff.ts
+++ b/src/daemon/launchd-restart-handoff.ts
@@ -17,7 +17,6 @@ type LaunchdRestartHandoffResult = Result<number | undefined, string>;
 
 type LaunchdRestartTarget = {
   domain: string;
-  label: string;
   plistPath: string;
   serviceTarget: string;
 };
@@ -92,7 +91,6 @@ function resolveLaunchdRestartTarget(
   const plistPath = path.join(home, "Library", "LaunchAgents", `${label}.plist`);
   return {
     domain,
-    label,
     plistPath,
     serviceTarget: `${domain}/${label}`,
   };
@@ -105,7 +103,6 @@ function buildLaunchdRestartScript(
   // The detached shell waits for the caller before touching launchd so the
   // current gateway process can exit cleanly after scheduling the handoff.
   const waitForCallerPid = `wait_pid="$4"
-label="$5"
 ${renderPosixRestartLogSetup(restartLogEnv)}
 printf '[%s] openclaw restart attempt source=handoff mode=${mode} target=%s pid=%s interactive=0\\n' "$(date -u +%FT%TZ)" "$service_target" "$wait_pid" >&2
 if [ -n "$wait_pid" ] && [ "$wait_pid" -gt 1 ] 2>/dev/null; then
@@ -268,7 +265,6 @@ export function scheduleDetachedLaunchdRestartHandoff(params: {
         target.domain,
         target.plistPath,
         String(waitForPid),
-        target.label,
       ],
       {
         detached: true,
diff --git a/src/daemon/launchd.test.ts b/src/daemon/launchd.test.ts
index 69c866b8dca..f5a5938f819 100644
--- a/src/daemon/launchd.test.ts
+++ b/src/daemon/launchd.test.ts
@@ -2014,7 +2014,7 @@ describe("launchd install", () => {
         stdout: { write } as unknown as NodeJS.WritableStream,
         onMutation,
       }),
-    ).resolves.toEqual({ outcome: "completed" });
+    ).resolves.toBeUndefined();
 
     const domain = typeof process.getuid === "function" ? `gui/${process.getuid()}` : "gui/501";
     const serviceId = `${domain}/ai.openclaw.gateway`;
diff --git a/src/daemon/launchd.ts b/src/daemon/launchd.ts
index f6655e2d8b0..0209226c14b 100644
--- a/src/daemon/launchd.ts
+++ b/src/daemon/launchd.ts
@@ -33,6 +33,7 @@ import { formatLine, toPosixPath, writeFormattedLines } from "./output.js";
 import { resolveGatewayStateDir, resolveHomeDir } from "./paths.js";
 import { resolveGatewaySupervisorLogPaths } from "./restart-logs.js";
 import { parseKeyValueOutput } from "./runtime-parse.js";
+import { createGatewayLifecycleMutationReporter } from "./service-mutation.js";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import type {
   GatewayServiceCommandConfig,
@@ -995,6 +996,7 @@ export async function stopLaunchAgent({
   const domain = resolveGuiDomain();
   const label = resolveLaunchAgentLabel({ env: serviceEnv });
   const serviceTarget = `${domain}/${label}`;
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
 
   if (
     isCurrentProcessLaunchdServiceLabel(label, process.env, { allowConfiguredLabelFallback: false })
@@ -1012,7 +1014,7 @@ export async function stopLaunchAgent({
     if (bootout.code !== 0 && !isLaunchctlNotLoaded(bootout)) {
       throw new Error(`launchctl bootout failed: ${formatLaunchctlResultDetail(bootout)}`);
     }
-    onMutation?.({ mode: "bootout" });
+    reportMutation("bootout");
     await assertGatewayPortReleasedAfterStop(serviceEnv);
     stdout.write(`${formatLine("Stopped LaunchAgent", serviceTarget)}\n`);
     return;
@@ -1026,13 +1028,13 @@ export async function stopLaunchAgent({
       serviceTarget,
       stdout,
       warning: `launchctl disable failed; used bootout fallback and left service unloaded: ${formatLaunchctlResultDetail(disableResult)}`,
-      onMutation: () => onMutation?.({ mode: "disable-bootout" }),
+      onMutation: () => reportMutation("disable-bootout"),
     });
     await assertGatewayPortReleasedAfterStop(serviceEnv);
     stdout.write(`${formatLine("Stopped LaunchAgent (degraded)", serviceTarget)}\n`);
     return;
   }
-  onMutation?.({ mode: "disable" });
+  reportMutation("disable");
 
   // `launchctl stop` targets the plain label (not the fully-qualified service target).
   const stop = await execLaunchctl(["stop", label]);
@@ -1041,14 +1043,14 @@ export async function stopLaunchAgent({
       serviceTarget,
       stdout,
       warning: `launchctl stop failed; used bootout fallback and left service unloaded: ${formatLaunchctlResultDetail(stop)}`,
-      onMutation: () => onMutation?.({ mode: "disable-bootout" }),
+      onMutation: () => reportMutation("disable-bootout"),
     });
     await assertGatewayPortReleasedAfterStop(serviceEnv);
     stdout.write(`${formatLine("Stopped LaunchAgent (degraded)", serviceTarget)}\n`);
     return;
   }
 
-  onMutation?.({ mode: "disable-stop" });
+  reportMutation("disable-stop");
 
   const stopState = await waitForLaunchAgentStopped(serviceTarget);
   if (stopState.state !== "stopped" && stopState.state !== "not-loaded") {
@@ -1060,7 +1062,7 @@ export async function stopLaunchAgent({
       serviceTarget,
       stdout,
       warning,
-      onMutation: () => onMutation?.({ mode: "disable-bootout" }),
+      onMutation: () => reportMutation("disable-bootout"),
     });
     await assertGatewayPortReleasedAfterStop(serviceEnv);
     stdout.write(`${formatLine("Stopped LaunchAgent (degraded)", serviceTarget)}\n`);
@@ -1255,29 +1257,17 @@ async function ensureLaunchAgentLoadedAfterFailure(params: {
   }
 }
 
-function createLaunchAgentMutationReporter(
-  onMutation: GatewayServiceControlArgs["onMutation"],
-): (mode: string) => void {
-  return (mode) => {
-    try {
-      onMutation?.({ mode });
-    } catch {
-      // Audit observers are diagnostic; never interrupt service control.
-    }
-  };
-}
-
 export async function startLaunchAgent({
   stdout,
   env,
   onMutation,
-}: GatewayServiceControlArgs): Promise<GatewayServiceRestartResult> {
+}: GatewayServiceControlArgs): Promise<void> {
   const serviceEnv = env ?? (process.env as GatewayServiceEnv);
   const domain = resolveGuiDomain();
   const label = resolveLaunchAgentLabel({ env: serviceEnv });
   const plistPath = resolveLaunchAgentPlistPath(serviceEnv);
   const serviceTarget = `${domain}/${label}`;
-  const reportMutation = createLaunchAgentMutationReporter(onMutation);
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
 
   // Enable is an independent mutation; audit it even if the later launch fails.
   const enable = await execLaunchctl(["enable", serviceTarget]);
@@ -1303,7 +1293,6 @@ export async function startLaunchAgent({
   }
 
   writeLaunchAgentActionLine(stdout, "Started LaunchAgent", serviceTarget);
-  return { outcome: "completed" };
 }
 
 export async function restartLaunchAgent({
@@ -1317,7 +1306,7 @@ export async function restartLaunchAgent({
   const label = resolveLaunchAgentLabel({ env: serviceEnv });
   const plistPath = resolveLaunchAgentPlistPath(serviceEnv);
   const serviceTarget = `${domain}/${label}`;
-  const reportMutation = createLaunchAgentMutationReporter(onMutation);
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
 
   // Restart requests issued from inside the managed gateway process tree need a
   // detached handoff. A direct `kickstart -k` would terminate the caller before
diff --git a/src/daemon/restart-logs.ts b/src/daemon/restart-logs.ts
index aad8dfd7f11..c7dadba85b3 100644
--- a/src/daemon/restart-logs.ts
+++ b/src/daemon/restart-logs.ts
@@ -4,7 +4,7 @@ import path from "node:path";
 import { quoteCmdScriptArg } from "./cmd-argv.js";
 import { resolveGatewayProfileSuffix } from "./constants.js";
 import { resolveGatewayStateDir, resolveHomeDir } from "./paths.js";
-import type { GatewayServiceEnv } from "./service-types.js";
+import type { GatewayLifecycleMutationMode, GatewayServiceEnv } from "./service-types.js";
 
 const GATEWAY_RESTART_LOG_FILENAME = "gateway-restart.log";
 
@@ -13,7 +13,7 @@ export type GatewayLifecycleAuditSource = "cli" | "safe-rpc" | "supervisor" | "h
 type GatewayLifecycleAuditEntry = {
   action: "start" | "stop" | "restart";
   source: GatewayLifecycleAuditSource;
-  mode: string;
+  mode: GatewayLifecycleMutationMode;
   pid?: number;
   interactive: boolean;
 };
diff --git a/src/daemon/schtasks.stop.test.ts b/src/daemon/schtasks.stop.test.ts
index 7ac6a36aff0..b8a353c1d84 100644
--- a/src/daemon/schtasks.stop.test.ts
+++ b/src/daemon/schtasks.stop.test.ts
@@ -377,7 +377,7 @@ describe("Scheduled Task stop/restart cleanup", () => {
           stdout: { write } as unknown as NodeJS.WritableStream,
           onMutation,
         }),
-      ).resolves.toEqual({ outcome: "completed" });
+      ).resolves.toBeUndefined();
 
       expect(schtasksCalls).toContainEqual(["/Run", "/TN", "OpenClaw Gateway"]);
       expect(onMutation).toHaveBeenCalledWith({ mode: "schtasks-start" });
diff --git a/src/daemon/schtasks.ts b/src/daemon/schtasks.ts
index b531b1d651f..cd820b2485e 100644
--- a/src/daemon/schtasks.ts
+++ b/src/daemon/schtasks.ts
@@ -32,6 +32,7 @@ import { formatLine, writeFormattedLines } from "./output.js";
 import { resolveGatewayTaskScriptPath } from "./paths.js";
 import { parseKeyValueOutput } from "./runtime-parse.js";
 import { execSchtasks } from "./schtasks-exec.js";
+import { createGatewayLifecycleMutationReporter } from "./service-mutation.js";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import type {
   GatewayServiceCommandConfig,
@@ -1207,11 +1208,10 @@ async function startStartupEntry(
   env: GatewayServiceEnv,
   stdout: NodeJS.WritableStream,
   onMutation?: () => void,
-): Promise<GatewayServiceRestartResult> {
+): Promise<void> {
   await launchFallbackTaskScript(env);
   onMutation?.();
   stdout.write(`${formatLine("Started Windows login item", resolveTaskName(env))}\n`);
-  return { outcome: "completed" };
 }
 
 const CALLER_OWNED_SERVICE_IDENTITY_KEYS = [
@@ -1879,22 +1879,19 @@ export async function stopScheduledTask({
   onMutation,
 }: GatewayServiceControlArgs): Promise<void> {
   const effectiveEnv = env ?? (process.env as GatewayServiceEnv);
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   try {
     await assertSchtasksAvailable();
   } catch (err) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
-      await stopStartupEntry(effectiveEnv, stdout, () =>
-        onMutation?.({ mode: "startup-entry-stop" }),
-      );
+      await stopStartupEntry(effectiveEnv, stdout, () => reportMutation("startup-entry-stop"));
       return;
     }
     throw err;
   }
   if (!(await isRegisteredScheduledTask(effectiveEnv))) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
-      await stopStartupEntry(effectiveEnv, stdout, () =>
-        onMutation?.({ mode: "startup-entry-stop" }),
-      );
+      await stopStartupEntry(effectiveEnv, stdout, () => reportMutation("startup-entry-stop"));
       return;
     }
   }
@@ -1903,7 +1900,7 @@ export async function stopScheduledTask({
   if (res.code !== 0 && !isTaskNotRunning(res)) {
     throw new Error(`schtasks end failed: ${res.stderr || res.stdout}`.trim());
   }
-  onMutation?.({ mode: "schtasks-stop" });
+  reportMutation("schtasks-stop");
   const manageGatewayPort = shouldManageGatewayListenerPort(effectiveEnv);
   const stopPort = manageGatewayPort ? await resolveScheduledTaskPort(effectiveEnv) : null;
   if (manageGatewayPort) {
@@ -1929,30 +1926,22 @@ export async function startScheduledTask({
   stdout,
   env,
   onMutation,
-}: GatewayServiceControlArgs): Promise<GatewayServiceRestartResult> {
+}: GatewayServiceControlArgs): Promise<void> {
   const effectiveEnv = env ?? (process.env as GatewayServiceEnv);
-  const reportMutation = (mode: string) => {
-    try {
-      onMutation?.({ mode });
-    } catch {
-      // Audit observers are diagnostic; never interrupt service control.
-    }
-  };
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   try {
     await assertSchtasksAvailable();
   } catch (err) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
-      return await startStartupEntry(effectiveEnv, stdout, () =>
-        reportMutation("startup-entry-start"),
-      );
+      await startStartupEntry(effectiveEnv, stdout, () => reportMutation("startup-entry-start"));
+      return;
     }
     throw err;
   }
   if (!(await isRegisteredScheduledTask(effectiveEnv))) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
-      return await startStartupEntry(effectiveEnv, stdout, () =>
-        reportMutation("startup-entry-start"),
-      );
+      await startStartupEntry(effectiveEnv, stdout, () => reportMutation("startup-entry-start"));
+      return;
     }
   }
   const taskName = resolveTaskName(effectiveEnv);
@@ -1963,7 +1952,6 @@ export async function startScheduledTask({
     onMutation: () => reportMutation("schtasks-start"),
   });
   stdout.write(`${formatLine("Started Scheduled Task", taskName)}\n`);
-  return { outcome: "completed" };
 }
 
 async function restartRegisteredScheduledTask(params: {
@@ -2054,12 +2042,13 @@ export async function restartScheduledTask({
   onMutation,
 }: GatewayServiceControlArgs): Promise<GatewayServiceRestartResult> {
   const effectiveEnv = env ?? (process.env as GatewayServiceEnv);
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   try {
     await assertSchtasksAvailable();
   } catch (err) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
       const result = await restartStartupEntry(effectiveEnv, stdout, (kind) =>
-        onMutation?.({ mode: kind === "stop" ? "startup-entry-stop" : "startup-entry-restart" }),
+        reportMutation(kind === "stop" ? "startup-entry-stop" : "startup-entry-restart"),
       );
       return result;
     }
@@ -2068,7 +2057,7 @@ export async function restartScheduledTask({
   if (!(await isRegisteredScheduledTask(effectiveEnv))) {
     if (await isStartupEntryInstalled(effectiveEnv)) {
       const result = await restartStartupEntry(effectiveEnv, stdout, (kind) =>
-        onMutation?.({ mode: kind === "stop" ? "startup-entry-stop" : "startup-entry-restart" }),
+        reportMutation(kind === "stop" ? "startup-entry-stop" : "startup-entry-restart"),
       );
       return result;
     }
@@ -2077,8 +2066,8 @@ export async function restartScheduledTask({
     env: effectiveEnv,
     stdout,
     mode: { kind: "standard" },
-    onEndMutation: () => onMutation?.({ mode: "schtasks-end" }),
-    onRunMutation: () => onMutation?.({ mode: "schtasks-restart" }),
+    onEndMutation: () => reportMutation("schtasks-end"),
+    onRunMutation: () => reportMutation("schtasks-restart"),
   });
   return result;
 }
diff --git a/src/daemon/service-mutation.ts b/src/daemon/service-mutation.ts
new file mode 100644
index 00000000000..0523b283c71
--- /dev/null
+++ b/src/daemon/service-mutation.ts
@@ -0,0 +1,14 @@
+import type { GatewayLifecycleMutationMode, GatewayServiceControlArgs } from "./service-types.js";
+
+/** Isolate diagnostic observers from authoritative service-control mutations. */
+export function createGatewayLifecycleMutationReporter(
+  onMutation: GatewayServiceControlArgs["onMutation"],
+): (mode: GatewayLifecycleMutationMode) => void {
+  return (mode) => {
+    try {
+      onMutation?.({ mode });
+    } catch {
+      // Audit observers are diagnostic; never interrupt service control.
+    }
+  };
+}
diff --git a/src/daemon/service-types.ts b/src/daemon/service-types.ts
index b94d6e89db6..c81155ed948 100644
--- a/src/daemon/service-types.ts
+++ b/src/daemon/service-types.ts
@@ -34,9 +34,39 @@ export type GatewayServiceControlArgs = {
   onMutation?: (mutation: GatewayLifecycleMutation) => void;
 };
 
+export type GatewayLifecycleMutationMode =
+  | "enable"
+  | "bootstrap"
+  | "kickstart"
+  | "bootout"
+  | "disable"
+  | "disable-stop"
+  | "disable-bootout"
+  | "handoff-kickstart"
+  | "handoff-reload"
+  | "systemctl-start"
+  | "systemctl-stop"
+  | "systemctl-restart"
+  | "startup-entry-start"
+  | "startup-entry-stop"
+  | "startup-entry-restart"
+  | "schtasks-start"
+  | "schtasks-stop"
+  | "schtasks-end"
+  | "schtasks-restart"
+  | "sigterm"
+  | "sigusr1"
+  | "rpc"
+  | "launchd-bootstrap"
+  | "service-repair"
+  | "scheduled"
+  | "deferred"
+  | "coalesced"
+  | "reload"
+  | "start-after-exit";
+
 export type GatewayLifecycleMutation = {
-  mode: string;
-  pid?: number;
+  mode: GatewayLifecycleMutationMode;
 };
 
 export type GatewayServiceRestartResult = { outcome: "completed" } | { outcome: "scheduled" };
@@ -80,9 +110,12 @@ export type GatewayServiceStartRepairIssue = {
 };
 
 export type GatewayServiceStartResult =
-  | { outcome: "already-running"; state: GatewayServiceState }
+  | {
+      outcome: "already-running";
+      state: GatewayServiceState;
+      issues: GatewayServiceStartRepairIssue[];
+    }
   | { outcome: "started"; state: GatewayServiceState }
-  | { outcome: "scheduled"; state: GatewayServiceState }
   | { outcome: "missing-install"; state: GatewayServiceState }
   | {
       outcome: "repair-required";
diff --git a/src/daemon/service.test-helpers.ts b/src/daemon/service.test-helpers.ts
index 8fb0239fa58..73f0bb6cded 100644
--- a/src/daemon/service.test-helpers.ts
+++ b/src/daemon/service.test-helpers.ts
@@ -11,7 +11,7 @@ export function createMockGatewayService(overrides: Partial<GatewayService> = {}
     stage: vi.fn(async () => {}),
     install: vi.fn(async () => {}),
     uninstall: vi.fn(async () => {}),
-    start: vi.fn(async () => ({ outcome: "completed" as const })),
+    start: vi.fn(async () => {}),
     stop: vi.fn(async () => {}),
     restart: vi.fn(async () => ({ outcome: "completed" as const })),
     isLoaded: vi.fn(async () => false),
diff --git a/src/daemon/service.test.ts b/src/daemon/service.test.ts
index 19bfcaffcc4..f2d20f8a005 100644
--- a/src/daemon/service.test.ts
+++ b/src/daemon/service.test.ts
@@ -248,6 +248,28 @@ describe("startGatewayService", () => {
     expect(service.start).not.toHaveBeenCalled();
   });
 
+  it("returns repair drift with an already-running service", async () => {
+    const service = createService({
+      readCommand: vi.fn(async () => ({
+        programArguments: ["openclaw", "gateway", "run"],
+        environment: { OPENCLAW_SERVICE_VERSION: "2026.4.24" },
+      })),
+      isLoaded: vi.fn(async () => true),
+      readRuntime: vi.fn(async () => ({ status: "running", pid: 4242 })),
+    });
+
+    const result = await startGatewayService(service, {
+      env: {},
+      stdout: process.stdout,
+    });
+
+    expect(result.outcome).toBe("already-running");
+    if (result.outcome === "already-running") {
+      expect(result.issues).toEqual([expect.objectContaining({ code: "version-mismatch" })]);
+    }
+    expect(service.start).not.toHaveBeenCalled();
+  });
+
   it("requests repair before start when the loaded service version is stale", async () => {
     const service = createService({
       readCommand: vi.fn(async () => ({
diff --git a/src/daemon/service.ts b/src/daemon/service.ts
index b1d2ff4f8e0..b13d7eb324a 100644
--- a/src/daemon/service.ts
+++ b/src/daemon/service.ts
@@ -79,7 +79,7 @@ export type GatewayService = {
   stage: (args: GatewayServiceStageArgs) => Promise<void>;
   install: (args: GatewayServiceInstallArgs) => Promise<void>;
   uninstall: (args: GatewayServiceManageArgs) => Promise<void>;
-  start: (args: GatewayServiceControlArgs) => Promise<GatewayServiceRestartResult>;
+  start: (args: GatewayServiceControlArgs) => Promise<void>;
   stop: (args: GatewayServiceControlArgs) => Promise<void>;
   restart: (args: GatewayServiceControlArgs) => Promise<GatewayServiceRestartResult>;
   isLoaded: (args: GatewayServiceEnvArgs) => Promise<boolean>;
@@ -222,6 +222,7 @@ export async function startGatewayService(
     return {
       outcome: "already-running",
       state,
+      issues: repairIssues,
     };
   }
 
@@ -234,10 +235,10 @@ export async function startGatewayService(
   }
 
   try {
-    const startResult = await service.start({ ...args, env: state.env });
+    await service.start({ ...args, env: state.env });
     const nextState = await readGatewayServiceState(service, { env: state.env });
     return {
-      outcome: startResult.outcome === "scheduled" ? "scheduled" : "started",
+      outcome: "started",
       state: nextState,
     };
   } catch (err) {
diff --git a/src/daemon/systemd.test.ts b/src/daemon/systemd.test.ts
index 7c3c9b190a4..8b99f17f132 100644
--- a/src/daemon/systemd.test.ts
+++ b/src/daemon/systemd.test.ts
@@ -2191,7 +2191,7 @@ describe("systemd service control", () => {
         env: {},
         onMutation,
       }),
-    ).resolves.toEqual({ outcome: "completed" });
+    ).resolves.toBeUndefined();
 
     expect(onMutation).toHaveBeenCalledWith({ mode: "systemctl-start" });
     expect(
diff --git a/src/daemon/systemd.ts b/src/daemon/systemd.ts
index a5d5473af26..e08d96a931f 100644
--- a/src/daemon/systemd.ts
+++ b/src/daemon/systemd.ts
@@ -33,6 +33,7 @@ import {
   isEnvironmentFileOnlySource,
   readManagedServiceEnvKeysFromEnvironment,
 } from "./service-managed-env.js";
+import { createGatewayLifecycleMutationReporter } from "./service-mutation.js";
 import type { GatewayServiceRuntime } from "./service-runtime.js";
 import type {
   GatewayServiceCommandConfig,
@@ -1386,21 +1387,15 @@ export async function startSystemdService({
   stdout,
   env,
   onMutation,
-}: GatewayServiceControlArgs): Promise<GatewayServiceRestartResult> {
+}: GatewayServiceControlArgs): Promise<void> {
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   await runSystemdServiceAction({
     stdout,
     env,
     action: "start",
     label: "Started systemd service",
-    onMutation: () => {
-      try {
-        onMutation?.({ mode: "systemctl-start" });
-      } catch {
-        // Audit observers are diagnostic; never interrupt service control.
-      }
-    },
+    onMutation: () => reportMutation("systemctl-start"),
   });
-  return { outcome: "completed" };
 }
 
 export async function stopSystemdService({
@@ -1408,12 +1403,13 @@ export async function stopSystemdService({
   env,
   onMutation,
 }: GatewayServiceControlArgs): Promise<void> {
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   await runSystemdServiceAction({
     stdout,
     env,
     action: "stop",
     label: "Stopped systemd service",
-    onMutation: () => onMutation?.({ mode: "systemctl-stop" }),
+    onMutation: () => reportMutation("systemctl-stop"),
   });
 }
 
@@ -1422,12 +1418,13 @@ export async function restartSystemdService({
   env,
   onMutation,
 }: GatewayServiceControlArgs): Promise<GatewayServiceRestartResult> {
+  const reportMutation = createGatewayLifecycleMutationReporter(onMutation);
   await runSystemdServiceAction({
     stdout,
     env,
     action: "restart",
     label: "Restarted systemd service",
-    onMutation: () => onMutation?.({ mode: "systemctl-restart" }),
+    onMutation: () => reportMutation("systemctl-restart"),
   });
   return { outcome: "completed" };
 }

From 21bd5a49c3a4ee63d2ca216340683805895128f5 Mon Sep 17 00:00:00 2001
From: snowzlmbot <snowzlmbot@gmail.com>
Date: Sat, 18 Jul 2026 18:09:33 +0800
Subject: [PATCH 22/76] fix(chat): preserve explicit current-source sends in
 Control UI history (#106073)

* fix(gateway): retain explicit source replies in history

Co-authored-by: snowzlmbot <293528334+snowzlmbot@users.noreply.github.com>

* test(infra): update source reply mirror mock

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: snowzlmbot <293528334+snowzlmbot@users.noreply.github.com>
---
 ...ed-agent-message-tool-source-reply.test.ts |  46 ++++++
 ...mbedded-agent-message-tool-source-reply.ts |   8 +-
 src/gateway/chat-display-projection.ts        |  65 +++++++-
 src/gateway/server-methods/send.ts            |   2 +
 .../server.chat.gateway-server-chat.test.ts   | 119 +++++++++++++++
 .../message-action-runner.core-send.test.ts   | 140 +++++++++++++++++-
 ...sage-action-runner.plugin-dispatch.test.ts |   2 +
 src/infra/outbound/message-action-runner.ts   |  82 +++++++++-
 src/infra/outbound/source-reply-mirror.ts     |  64 +++++++-
 9 files changed, 511 insertions(+), 17 deletions(-)

diff --git a/src/agents/embedded-agent-message-tool-source-reply.test.ts b/src/agents/embedded-agent-message-tool-source-reply.test.ts
index 2dcc8bcf0e0..1a5a749f213 100644
--- a/src/agents/embedded-agent-message-tool-source-reply.test.ts
+++ b/src/agents/embedded-agent-message-tool-source-reply.test.ts
@@ -383,4 +383,50 @@ describe("isDeliveredMessageToolOnlySourceReplyResult", () => {
       }),
     ).toBe(false);
   });
+
+  it("accepts explicit sends with a structured current-source marker", () => {
+    expect(
+      isDeliveredMessageToolOnlySourceReplyResult({
+        sourceReplyDeliveryMode: "message_tool_only",
+        toolName: "message",
+        args: {
+          action: "send",
+          channel: "telegram",
+          target: "8455538490",
+          message: "reply",
+        },
+        result: {
+          content: [{ type: "text", text: '{"ok":true}' }],
+          details: {
+            ok: true,
+            messageId: "telegram-242",
+            sourceReplyRoute: "current-source",
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("does not trust current-source markers echoed in result text", () => {
+    expect(
+      isDeliveredMessageToolOnlySourceReplyResult({
+        sourceReplyDeliveryMode: "message_tool_only",
+        toolName: "message",
+        args: {
+          action: "send",
+          target: "elsewhere",
+          message: "reply",
+        },
+        result: {
+          content: [
+            {
+              type: "text",
+              text: '{"ok":true,"sourceReplyRoute":"current-source"}',
+            },
+          ],
+          details: { ok: true, messageId: "remote-242" },
+        },
+      }),
+    ).toBe(false);
+  });
 });
diff --git a/src/agents/embedded-agent-message-tool-source-reply.ts b/src/agents/embedded-agent-message-tool-source-reply.ts
index a05a23aeaf4..cece28b1564 100644
--- a/src/agents/embedded-agent-message-tool-source-reply.ts
+++ b/src/agents/embedded-agent-message-tool-source-reply.ts
@@ -37,6 +37,10 @@ function asRecord(value: unknown): Record<string, unknown> {
     : {};
 }
 
+function resultConfirmsCurrentSourceRoute(value: unknown): boolean {
+  return asRecord(asRecord(value).details).sourceReplyRoute === "current-source";
+}
+
 function hasStringValue(value: unknown): boolean {
   return typeof value === "string" && value.trim().length > 0;
 }
@@ -563,7 +567,9 @@ export function isDeliveredMessageToolOnlySourceReplyResult(params: {
   if (!isMessageToolSendActionName(args.action) && !sourceRouteReplyAction) {
     return false;
   }
-  if (hasExplicitMessageRoute(args) && params.allowExplicitSourceRoute !== true) {
+  const hasConfirmedExplicitSourceRoute =
+    params.allowExplicitSourceRoute === true || resultConfirmsCurrentSourceRoute(params.result);
+  if (hasExplicitMessageRoute(args) && !hasConfirmedExplicitSourceRoute) {
     return false;
   }
   return isDeliveredMessagingToolResult(params);
diff --git a/src/gateway/chat-display-projection.ts b/src/gateway/chat-display-projection.ts
index 21ebfa6bb5a..62bcbe38206 100644
--- a/src/gateway/chat-display-projection.ts
+++ b/src/gateway/chat-display-projection.ts
@@ -53,6 +53,7 @@ type ChatDisplayProjectionResult = {
 type PendingMessageToolVisibleReply = {
   toolCallId?: string;
   text: string;
+  requiresSourceRouteConfirmation: boolean;
   anchor: Record<string, unknown>;
   completionAnchor?: Record<string, unknown>;
   deliveryMirrorAnchor?: Record<string, unknown>;
@@ -996,15 +997,17 @@ function extractMessageToolVisibleReplies(
     if (isDryRunMessageToolRecord(args)) {
       continue;
     }
-    if (hasExplicitMessageToolRoute(args)) {
-      continue;
-    }
+    const requiresSourceRouteConfirmation = hasExplicitMessageToolRoute(args);
     const text = readMessageToolVisibleText(args);
     if (!text?.trim()) {
       continue;
     }
     const toolCallId = readToolBlockCallId(record);
-    replies.push({ ...(toolCallId ? { toolCallId } : {}), text });
+    replies.push({
+      ...(toolCallId ? { toolCallId } : {}),
+      text,
+      requiresSourceRouteConfirmation,
+    });
   }
   return replies;
 }
@@ -1099,6 +1102,40 @@ function hasDryRunToolResultValue(value: unknown): boolean {
   });
 }
 
+function hasSuppressedToolResultValue(value: unknown): boolean {
+  const record = readMaybeJsonRecord(value);
+  if (record) {
+    const messageId = normalizeOptionalString(record.messageId)?.toLowerCase();
+    const status = (
+      normalizeOptionalString(record.deliveryStatus) ??
+      normalizeOptionalString(record.delivery_status) ??
+      normalizeOptionalString(record.status)
+    )?.toLowerCase();
+    if (
+      record.delivered === false ||
+      messageId === "skipped" ||
+      messageId === "suppressed" ||
+      status === "skipped" ||
+      status === "suppressed"
+    ) {
+      return true;
+    }
+  }
+  if (!Array.isArray(value)) {
+    return false;
+  }
+  return value.some((block) => {
+    if (hasSuppressedToolResultValue(block)) {
+      return true;
+    }
+    const blockRecord = readRecord(block);
+    return (
+      hasSuppressedToolResultValue(blockRecord?.text) ||
+      hasSuppressedToolResultValue(blockRecord?.content)
+    );
+  });
+}
+
 function isSuccessfulMessageToolResult(
   message: Record<string, unknown>,
   pending: PendingMessageToolVisibleReply,
@@ -1112,10 +1149,17 @@ function isSuccessfulMessageToolResult(
     return false;
   }
   const resultCallId = readMessageToolResultCallId(message);
+  const hasConfirmedSourceRoute =
+    !pending.requiresSourceRouteConfirmation ||
+    readRecord(message.details)?.sourceReplyRoute === "current-source";
   if (pending.toolCallId) {
-    return resultCallId === pending.toolCallId && isSuccessfulMessageToolResultPayload(message);
+    return (
+      resultCallId === pending.toolCallId &&
+      isSuccessfulMessageToolResultPayload(message) &&
+      hasConfirmedSourceRoute
+    );
   }
-  return isSuccessfulMessageToolResultPayload(message);
+  return isSuccessfulMessageToolResultPayload(message) && hasConfirmedSourceRoute;
 }
 
 function isSuccessfulMessageToolResultPayload(message: Record<string, unknown>): boolean {
@@ -1130,6 +1174,15 @@ function isSuccessfulMessageToolResultPayload(message: Record<string, unknown>):
   ) {
     return false;
   }
+  if (
+    hasSuppressedToolResultValue(message.details) ||
+    hasSuppressedToolResultValue(message.result) ||
+    hasSuppressedToolResultValue(message.output) ||
+    hasSuppressedToolResultValue(message.content) ||
+    hasSuppressedToolResultValue(message.text)
+  ) {
+    return false;
+  }
   const ok =
     readToolResultOkValue(message.result) ??
     readToolResultOkValue(message.output) ??
diff --git a/src/gateway/server-methods/send.ts b/src/gateway/server-methods/send.ts
index d407170be31..bf705419069 100644
--- a/src/gateway/server-methods/send.ts
+++ b/src/gateway/server-methods/send.ts
@@ -558,6 +558,8 @@ export const sendHandlers: GatewayRequestHandlers = {
           channel,
           actionParams: request.params,
           cfg,
+          accountId,
+          currentAccountId: trustedContext.requesterAccountId,
           sessionKey,
           sessionId: trustedContext.sessionId,
           agentId,
diff --git a/src/gateway/server.chat.gateway-server-chat.test.ts b/src/gateway/server.chat.gateway-server-chat.test.ts
index 691c1590bbb..13e1bad2d12 100644
--- a/src/gateway/server.chat.gateway-server-chat.test.ts
+++ b/src/gateway/server.chat.gateway-server-chat.test.ts
@@ -1396,6 +1396,125 @@ describe("gateway server chat", () => {
     ).toBe(false);
   });
 
+  test("chat.history keeps confirmed current-source sends before a later final", async () => {
+    const sourceReply = "Visible reply delivered to Telegram.";
+    const laterFinal = "A later run produced this different final.";
+    const historyMessages = await loadChatHistoryWithMessages([
+      {
+        role: "user",
+        content: [{ type: "text", text: "reply in this Telegram chat" }],
+        timestamp: 1,
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "call-message-current-source",
+            name: "message",
+            arguments: {
+              action: "send",
+              channel: "telegram",
+              target: "8455538490",
+              message: sourceReply,
+            },
+          },
+        ],
+        timestamp: 2,
+      },
+      {
+        role: "toolResult",
+        toolName: "message",
+        toolCallId: "call-message-current-source",
+        content: { ok: true, messageId: "24269", chatId: "8455538490" },
+        details: {
+          ok: true,
+          messageId: "24269",
+          chatId: "8455538490",
+          sourceReplyRoute: "current-source",
+        },
+        timestamp: 3,
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "NO_REPLY" }],
+        timestamp: 4,
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: "continue" }],
+        timestamp: 5,
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: laterFinal }],
+        timestamp: 6,
+      },
+    ]);
+
+    expect(collectHistoryTextValues(historyMessages)).toEqual([
+      "reply in this Telegram chat",
+      sourceReply,
+      "continue",
+      laterFinal,
+    ]);
+    expect(historyMessages).toContainEqual(
+      expect.objectContaining({
+        role: "assistant",
+        content: [{ type: "text", text: sourceReply }],
+        openclawMessageToolMirror: expect.objectContaining({
+          toolCallId: "call-message-current-source",
+        }),
+      }),
+    );
+  });
+
+  test("chat.history does not mirror suppressed current-source sends", async () => {
+    const historyMessages = await loadChatHistoryWithMessages([
+      {
+        role: "user",
+        content: [{ type: "text", text: "reply here" }],
+        timestamp: 1,
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "toolCall",
+            id: "call-message-suppressed-current-source",
+            name: "message",
+            arguments: {
+              action: "send",
+              target: "8455538490",
+              message: "Must not appear",
+            },
+          },
+        ],
+        timestamp: 2,
+      },
+      {
+        role: "toolResult",
+        toolName: "message",
+        toolCallId: "call-message-suppressed-current-source",
+        content: { ok: true, messageId: "suppressed" },
+        details: {
+          ok: true,
+          messageId: "suppressed",
+          deliveryStatus: "suppressed",
+          sourceReplyRoute: "current-source",
+        },
+        timestamp: 3,
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: "NO_REPLY" }],
+        timestamp: 4,
+      },
+    ]);
+
+    expect(collectHistoryTextValues(historyMessages)).toEqual(["reply here"]);
+  });
+
   test("chat.history does not mirror message tool sends from unmatched results", async () => {
     const historyMessages = await loadChatHistoryWithMessages([
       {
diff --git a/src/infra/outbound/message-action-runner.core-send.test.ts b/src/infra/outbound/message-action-runner.core-send.test.ts
index b81a30d747c..dab0c16d8c2 100644
--- a/src/infra/outbound/message-action-runner.core-send.test.ts
+++ b/src/infra/outbound/message-action-runner.core-send.test.ts
@@ -37,7 +37,7 @@ const slackConfig = {
   },
 } as OpenClawConfig;
 
-function registerSlackTextPlugin() {
+function registerSlackTextPlugin(accountIds: string[] = ["default"]) {
   const sendText = vi.fn().mockResolvedValue({
     channel: "slack",
     messageId: "m1",
@@ -57,7 +57,7 @@ function registerSlackTextPlugin() {
             },
           }),
           config: {
-            listAccountIds: () => ["default"],
+            listAccountIds: () => accountIds,
             resolveAccount: () => ({ enabled: true }),
             isConfigured: () => true,
           },
@@ -570,6 +570,142 @@ describe("runMessageAction core send routing", () => {
     expect(result.to).toBe("channel:C123");
   });
 
+  it("marks explicit sends to the trusted current source conversation", async () => {
+    registerSlackTextPlugin();
+
+    const result = await runMessageAction({
+      cfg: slackConfig,
+      action: "send",
+      params: {
+        channel: "slack",
+        target: "channel:C123",
+        message: "visible source reply",
+      },
+      toolContext: {
+        currentChannelProvider: "slack",
+        currentChannelId: "channel:C123",
+      },
+      messageActionAuthorization: {
+        requesterAccountId: "default",
+        toolContext: {
+          currentChannelProvider: "slack",
+          currentChannelId: "channel:C123",
+          currentSourceTurnId: "source-turn-1",
+        },
+      },
+      sessionKey: "agent:main:slack:channel:C123",
+      defaultAccountId: "default",
+      sourceReplyDeliveryMode: "message_tool_only",
+      dryRun: false,
+    });
+
+    expect(result.kind).toBe("send");
+    expect(result.payload).toMatchObject({ sourceReplyRoute: "current-source" });
+  });
+
+  it("does not trust ambient routing when the authorized source differs", async () => {
+    registerSlackTextPlugin();
+
+    const result = await runMessageAction({
+      cfg: slackConfig,
+      action: "send",
+      params: {
+        channel: "slack",
+        target: "channel:C123",
+        message: "not the authorized source",
+      },
+      toolContext: {
+        currentChannelProvider: "slack",
+        currentChannelId: "channel:C123",
+      },
+      messageActionAuthorization: {
+        requesterAccountId: "default",
+        toolContext: {
+          currentChannelProvider: "slack",
+          currentChannelId: "channel:C999",
+          currentSourceTurnId: "source-turn-1",
+        },
+      },
+      sessionKey: "agent:main:slack:channel:C123",
+      defaultAccountId: "default",
+      sourceReplyDeliveryMode: "message_tool_only",
+      dryRun: false,
+    });
+
+    expect(result.kind).toBe("send");
+    expect((result.payload as { sourceReplyRoute?: unknown }).sourceReplyRoute).toBeUndefined();
+  });
+
+  it("does not mark same-target sends through another account", async () => {
+    registerSlackTextPlugin(["default", "other"]);
+
+    const result = await runMessageAction({
+      cfg: slackConfig,
+      action: "send",
+      params: {
+        channel: "slack",
+        accountId: "other",
+        target: "channel:C123",
+        message: "cross-account reply",
+      },
+      toolContext: {
+        currentChannelProvider: "slack",
+        currentChannelId: "channel:C123",
+      },
+      messageActionAuthorization: {
+        requesterAccountId: "default",
+        toolContext: {
+          currentChannelProvider: "slack",
+          currentChannelId: "channel:C123",
+          currentSourceTurnId: "source-turn-1",
+        },
+      },
+      sessionKey: "agent:main:slack:channel:C123",
+      defaultAccountId: "default",
+      sourceReplyDeliveryMode: "message_tool_only",
+      dryRun: false,
+    });
+
+    expect(result.kind).toBe("send");
+    expect((result.payload as { sourceReplyRoute?: unknown }).sourceReplyRoute).toBeUndefined();
+  });
+
+  it("does not mark same-target sends to another thread", async () => {
+    registerSlackTextPlugin();
+
+    const result = await runMessageAction({
+      cfg: slackConfig,
+      action: "send",
+      params: {
+        channel: "slack",
+        target: "channel:C123",
+        threadId: "other-thread",
+        message: "thread-only reply",
+      },
+      toolContext: {
+        currentChannelProvider: "slack",
+        currentChannelId: "channel:C123",
+        currentThreadTs: "source-thread",
+      },
+      messageActionAuthorization: {
+        requesterAccountId: "default",
+        toolContext: {
+          currentChannelProvider: "slack",
+          currentChannelId: "channel:C123",
+          currentThreadTs: "source-thread",
+          currentSourceTurnId: "source-turn-1",
+        },
+      },
+      sessionKey: "agent:main:slack:channel:C123:thread:source-thread",
+      defaultAccountId: "default",
+      sourceReplyDeliveryMode: "message_tool_only",
+      dryRun: false,
+    });
+
+    expect(result.kind).toBe("send");
+    expect((result.payload as { sourceReplyRoute?: unknown }).sourceReplyRoute).toBeUndefined();
+  });
+
   it("preserves required delivery when message-tool-only sends target another conversation", async () => {
     const sendText = registerSlackTextPlugin();
 
diff --git a/src/infra/outbound/message-action-runner.plugin-dispatch.test.ts b/src/infra/outbound/message-action-runner.plugin-dispatch.test.ts
index 52cdd56bbac..5f53191fd13 100644
--- a/src/infra/outbound/message-action-runner.plugin-dispatch.test.ts
+++ b/src/infra/outbound/message-action-runner.plugin-dispatch.test.ts
@@ -105,6 +105,7 @@ const mocks = vi.hoisted(() => ({
   prepareOutboundMirrorRoute: vi.fn(),
   beginTerminalSourceReplyDelivery: vi.fn(),
   cancelTerminalSourceReplyDelivery: vi.fn(),
+  isDeliveredCurrentSourceReply: vi.fn(() => false),
   reconcileTerminalSourceReplyDelivery: vi.fn(),
 }));
 
@@ -130,6 +131,7 @@ vi.mock("./message.gateway.runtime.js", () => ({
 vi.mock("./source-reply-mirror.js", () => ({
   beginTerminalSourceReplyDelivery: mocks.beginTerminalSourceReplyDelivery,
   cancelTerminalSourceReplyDelivery: mocks.cancelTerminalSourceReplyDelivery,
+  isDeliveredCurrentSourceReply: mocks.isDeliveredCurrentSourceReply,
   reconcileTerminalSourceReplyDelivery: mocks.reconcileTerminalSourceReplyDelivery,
 }));
 
diff --git a/src/infra/outbound/message-action-runner.ts b/src/infra/outbound/message-action-runner.ts
index b4b3bb955a9..9ab79c293e9 100644
--- a/src/infra/outbound/message-action-runner.ts
+++ b/src/infra/outbound/message-action-runner.ts
@@ -114,6 +114,7 @@ import { ensureOutboundSessionEntry, resolveOutboundSessionRoute } from "./outbo
 import {
   beginTerminalSourceReplyDelivery,
   cancelTerminalSourceReplyDelivery,
+  isDeliveredCurrentSourceReply,
   reconcileTerminalSourceReplyDelivery,
 } from "./source-reply-mirror.js";
 import { normalizeTargetForProvider } from "./target-normalization.js";
@@ -257,6 +258,63 @@ export function getToolResult(
   return "toolResult" in result ? result.toolResult : undefined;
 }
 
+function asResultRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function markDeliveredCurrentSourceReply<T extends MessageActionRunResult>(
+  result: T,
+  params: {
+    cfg: OpenClawConfig;
+    actionParams: Record<string, unknown>;
+    channel: ChannelId;
+    accountId?: string | null;
+    input: RunMessageActionParams;
+    agentId?: string;
+    replyToIsExplicit: boolean;
+  },
+): T {
+  if (result.kind !== "send" || params.input.sourceReplyDeliveryMode !== "message_tool_only") {
+    return result;
+  }
+  const authorization = params.input.messageActionAuthorization;
+  if (
+    !authorization?.toolContext ||
+    !isDeliveredCurrentSourceReply({
+      action: "send",
+      channel: params.channel,
+      actionParams: params.actionParams,
+      cfg: params.cfg,
+      accountId: params.accountId,
+      currentAccountId: authorization.requesterAccountId ?? params.input.defaultAccountId,
+      sessionKey: params.input.sessionKey,
+      sessionId: params.input.sessionId,
+      agentId: params.agentId,
+      toolContext: authorization.toolContext,
+      deliveredPayload: result.payload,
+      replyToIsExplicit: params.replyToIsExplicit,
+    })
+  ) {
+    return result;
+  }
+  const payload = asResultRecord(result.payload);
+  const details = asResultRecord(result.toolResult?.details);
+  return {
+    ...result,
+    payload: payload ? { ...payload, sourceReplyRoute: "current-source" } : result.payload,
+    ...(result.toolResult
+      ? {
+          toolResult: {
+            ...result.toolResult,
+            details: { ...details, sourceReplyRoute: "current-source" },
+          },
+        }
+      : {}),
+  } as T;
+}
+
 function resolveGatewayActionOptions(gateway?: MessageActionRunnerGateway) {
   return resolveOutboundMessageGatewayOptions(gateway);
 }
@@ -825,6 +883,9 @@ async function runGatewayPluginMessageActionOrNull(params: {
     channel: params.channel,
     actionParams: params.params,
     cfg: params.cfg,
+    accountId: params.accountId,
+    currentAccountId:
+      params.input.messageActionAuthorization?.requesterAccountId ?? params.input.defaultAccountId,
     sessionKey: params.input.sessionKey,
     sessionId: params.input.sessionId,
     agentId: params.agentId,
@@ -1421,7 +1482,15 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
         }),
       });
   if (gatewayPluginAction) {
-    return gatewayPluginAction;
+    return markDeliveredCurrentSourceReply(gatewayPluginAction, {
+      cfg,
+      actionParams: params,
+      channel,
+      accountId,
+      input,
+      agentId,
+      replyToIsExplicit,
+    });
   }
 
   const useCorePresentationDelivery = Boolean(
@@ -1510,7 +1579,7 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
     threadId: resolvedThreadId ?? undefined,
   });
 
-  return {
+  const result: MessageActionRunResult = {
     kind: "send",
     channel,
     action,
@@ -1522,6 +1591,15 @@ async function handleSendAction(ctx: ResolvedActionContext): Promise<MessageActi
     sendResult: send.sendResult,
     dryRun,
   };
+  return markDeliveredCurrentSourceReply(result, {
+    cfg,
+    actionParams: params,
+    channel,
+    accountId,
+    input,
+    agentId,
+    replyToIsExplicit,
+  });
 }
 
 async function handlePollAction(ctx: ResolvedActionContext): Promise<MessageActionRunResult> {
diff --git a/src/infra/outbound/source-reply-mirror.ts b/src/infra/outbound/source-reply-mirror.ts
index c63ab64fb92..1859171963e 100644
--- a/src/infra/outbound/source-reply-mirror.ts
+++ b/src/infra/outbound/source-reply-mirror.ts
@@ -18,7 +18,7 @@ import {
   type RestartRecoveryTerminalDeliveryScope,
 } from "../../config/sessions/restart-recovery-receipt.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
-import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
 import { readTrimmedStringAlias } from "../../utils/string-readers.js";
 import { createOutboundPayloadPlan, projectOutboundPayloadPlanForMirror } from "./payloads.js";
 
@@ -27,6 +27,8 @@ type SourceReplyTranscriptMirrorParams = {
   channel: string;
   actionParams: Record<string, unknown>;
   cfg: OpenClawConfig;
+  accountId?: string | null;
+  currentAccountId?: string | null;
   sessionKey?: string;
   sessionId?: string;
   agentId?: string;
@@ -35,6 +37,7 @@ type SourceReplyTranscriptMirrorParams = {
   sourceReplyFinal?: boolean;
   toolCallId?: string;
   deliveredPayload?: unknown;
+  replyToIsExplicit?: boolean;
 };
 
 type MirrorableSourceReplyTranscriptParams = SourceReplyTranscriptMirrorParams & {
@@ -102,6 +105,14 @@ function resolveSourceReplyThreadPlacement(
   if (params.actionParams.topLevel === true) {
     return currentThreadId ? "mismatch" : "match";
   }
+  if (
+    params.channel === "slack" &&
+    params.replyToIsExplicit === true &&
+    !currentThreadId &&
+    normalizeOptionalString(params.actionParams.replyTo)
+  ) {
+    return "mismatch";
+  }
   for (const key of ["threadId", "messageThreadId"] as const) {
     if (!Object.hasOwn(params.actionParams, key)) {
       continue;
@@ -133,20 +144,44 @@ function resolveThreadedSourceTarget(
   );
 }
 
-function hasExplicitDeliveryFailure(payload: unknown): boolean {
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+function hasExplicitDeliveryFailure(payload: unknown, depth = 0): boolean {
+  if (!payload || typeof payload !== "object" || depth > 4) {
     return false;
   }
+  if (Array.isArray(payload)) {
+    return payload.some((value) => hasExplicitDeliveryFailure(value, depth + 1));
+  }
   const record = payload as Record<string, unknown>;
-  if (record.ok === false) {
+  if (record.ok === false || record.delivered === false || record.dryRun === true) {
+    return true;
+  }
+  const messageId = normalizeOptionalLowercaseString(record.messageId);
+  if (messageId === "skipped" || messageId === "suppressed") {
     return true;
   }
   const status = normalizeOptionalLowercaseString(record.status);
-  if (status === "failed" || status === "error") {
+  if (
+    status === "failed" ||
+    status === "error" ||
+    status === "skipped" ||
+    status === "suppressed" ||
+    status === "dry_run"
+  ) {
     return true;
   }
   const deliveryStatus = normalizeOptionalLowercaseString(record.deliveryStatus);
-  return deliveryStatus === "failed" || deliveryStatus === "error";
+  if (
+    deliveryStatus === "failed" ||
+    deliveryStatus === "error" ||
+    deliveryStatus === "skipped" ||
+    deliveryStatus === "suppressed" ||
+    deliveryStatus === "dry_run"
+  ) {
+    return true;
+  }
+  return ["details", "payload", "result", "results", "sendResult", "toolResult"].some((key) =>
+    hasExplicitDeliveryFailure(record[key], depth + 1),
+  );
 }
 
 function resolveCurrentSourceTurnId(
@@ -269,6 +304,16 @@ function isCurrentSourceConversation(
   if (!toolContext) {
     return false;
   }
+  const accountId = normalizeOptionalString(params.accountId);
+  if (accountId) {
+    const currentAccountId = normalizeOptionalString(params.currentAccountId);
+    if (
+      !currentAccountId ||
+      normalizeAccountId(accountId) !== normalizeAccountId(currentAccountId)
+    ) {
+      return false;
+    }
+  }
   const currentChannel = normalizeOptionalLowercaseString(toolContext.currentChannelProvider);
   if (!currentChannel || currentChannel !== normalizeOptionalLowercaseString(params.channel)) {
     return false;
@@ -318,6 +363,13 @@ function isExactCurrentSourceConversation(
   );
 }
 
+/** Confirms that a successful send reached the exact trusted source conversation. */
+export function isDeliveredCurrentSourceReply(params: SourceReplyTranscriptMirrorParams): boolean {
+  return (
+    !hasExplicitDeliveryFailure(params.deliveredPayload) && isExactCurrentSourceConversation(params)
+  );
+}
+
 /** Mirrors successful outbound source replies into the owning session transcript. */
 export async function mirrorDeliveredSourceReplyToTranscript(
   params: SourceReplyTranscriptMirrorParams,

From 04d7462806a9cb7d0d5e3487d59504c93f5e55cf Mon Sep 17 00:00:00 2001
From: mushuiyu886 <yang.haoyu@xydigit.com>
Date: Sat, 18 Jul 2026 18:10:39 +0800
Subject: [PATCH 23/76] fix(plugin-sdk): attached send results report the
 configured channel (#110069)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(plugin-sdk): keep attached channel authoritative

* refactor(plugin-sdk): simplify channel attachment

Co-authored-by: 杨浩宇0668001029 <yang.haoyu@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/plugin-sdk/channel-send-result.test.ts | 18 ++++++++++++++++++
 src/plugin-sdk/channel-send-result.ts      |  2 +-
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/plugin-sdk/channel-send-result.test.ts b/src/plugin-sdk/channel-send-result.test.ts
index f58c588c9fa..19ca5541c85 100644
--- a/src/plugin-sdk/channel-send-result.test.ts
+++ b/src/plugin-sdk/channel-send-result.test.ts
@@ -36,6 +36,24 @@ describe("attachChannelToResult(s)", () => {
       { channel: "signal", messageId: "m2", timestamp: 2 },
     ]);
   });
+
+  it("keeps the explicitly attached channel authoritative", () => {
+    const providerResult = {
+      channel: "stale-provider-channel",
+      messageId: "m1",
+    };
+
+    expect(attachChannelToResult("configured-channel", providerResult)).toEqual({
+      channel: "configured-channel",
+      messageId: "m1",
+    });
+    expect(attachChannelToResults("configured-channel", [providerResult])).toEqual([
+      {
+        channel: "configured-channel",
+        messageId: "m1",
+      },
+    ]);
+  });
 });
 
 describe("buildChannelSendResult", () => {
diff --git a/src/plugin-sdk/channel-send-result.ts b/src/plugin-sdk/channel-send-result.ts
index 01929966477..315aaef3a35 100644
--- a/src/plugin-sdk/channel-send-result.ts
+++ b/src/plugin-sdk/channel-send-result.ts
@@ -28,8 +28,8 @@ export function attachChannelToResult<T extends object>(
   result: T,
 ) {
   return {
-    channel,
     ...result,
+    channel,
   };
 }
 

From 42e6972d354dbdd6edfc435d5585fa453a59579e Mon Sep 17 00:00:00 2001
From: mushuiyu886 <yang.haoyu@xydigit.com>
Date: Sat, 18 Jul 2026 18:14:05 +0800
Subject: [PATCH 24/76] fix(opencode): Zen GPT-5.6 models are missing from
 discovery (#110405)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(opencode): add Zen GPT-5.6 models

* test(opencode): narrow GPT-5.6 policy fixture

* fix(opencode): align GPT-5.6 thinking levels

Co-authored-by: 杨浩宇0668001029 <yang.haoyu@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 extensions/opencode/index.test.ts             | 110 +++++++++++++++++-
 extensions/opencode/index.ts                  |   4 +-
 extensions/opencode/provider-catalog.ts       |  45 +++++++
 .../opencode/provider-policy-api.test.ts      |  19 +++
 extensions/opencode/provider-policy-api.ts    |  25 +++-
 5 files changed, 197 insertions(+), 6 deletions(-)

diff --git a/extensions/opencode/index.test.ts b/extensions/opencode/index.test.ts
index b71cf969fd5..b8561dd4122 100644
--- a/extensions/opencode/index.test.ts
+++ b/extensions/opencode/index.test.ts
@@ -97,6 +97,9 @@ describe("opencode provider plugin", () => {
       "gemini-3.5-flash",
       "gemini-3.1-pro",
       "gemini-3-flash",
+      "gpt-5.6-sol",
+      "gpt-5.6-terra",
+      "gpt-5.6-luna",
       "gpt-5.5",
       "gpt-5.5-pro",
       "gpt-5.4",
@@ -169,6 +172,39 @@ describe("opencode provider plugin", () => {
       api: "openai-responses",
       baseUrl: "https://opencode.ai/zen/v1",
     });
+    expect(requireMapEntry(models, "gpt-5.6-luna")).toMatchObject({
+      name: "GPT-5.6 Luna",
+      api: "openai-responses",
+      baseUrl: "https://opencode.ai/zen/v1",
+      input: ["text", "image"],
+      contextWindow: 1_050_000,
+      maxTokens: 128_000,
+      cost: {
+        input: 1,
+        output: 6,
+        cacheRead: 0.1,
+        cacheWrite: 1.25,
+        tieredPricing: [
+          { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 1.25, range: [0, 272_000] },
+          { input: 2, output: 9, cacheRead: 0.2, cacheWrite: 2.5, range: [272_000] },
+        ],
+      },
+      compat: {
+        supportedReasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
+      },
+    });
+    expect(requireMapEntry(models, "gpt-5.6-terra")).toMatchObject({
+      name: "GPT-5.6 Terra",
+      contextWindow: 1_050_000,
+      maxTokens: 128_000,
+      cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125 },
+    });
+    expect(requireMapEntry(models, "gpt-5.6-sol")).toMatchObject({
+      name: "GPT-5.6 Sol",
+      contextWindow: 1_050_000,
+      maxTokens: 128_000,
+      cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25 },
+    });
     expect(requireMapEntry(models, "gemini-3.5-flash")).toMatchObject({
       api: "google-generative-ai",
       baseUrl: "https://opencode.ai/zen/v1",
@@ -330,6 +366,57 @@ describe("opencode provider plugin", () => {
       ["claude-opus-4-5", { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 }],
       ["claude-opus-4-1", { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 }],
       ["claude-sonnet-5", { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 }],
+      [
+        "gpt-5.6-luna",
+        {
+          input: 1,
+          output: 6,
+          cacheRead: 0.1,
+          cacheWrite: 1.25,
+          tieredPricing: [
+            { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 1.25, range: [0, 272_000] },
+            { input: 2, output: 9, cacheRead: 0.2, cacheWrite: 2.5, range: [272_000] },
+          ],
+        },
+      ],
+      [
+        "gpt-5.6-terra",
+        {
+          input: 2.5,
+          output: 15,
+          cacheRead: 0.25,
+          cacheWrite: 3.125,
+          tieredPricing: [
+            {
+              input: 2.5,
+              output: 15,
+              cacheRead: 0.25,
+              cacheWrite: 3.125,
+              range: [0, 272_000],
+            },
+            {
+              input: 5,
+              output: 22.5,
+              cacheRead: 0.5,
+              cacheWrite: 6.25,
+              range: [272_000],
+            },
+          ],
+        },
+      ],
+      [
+        "gpt-5.6-sol",
+        {
+          input: 5,
+          output: 30,
+          cacheRead: 0.5,
+          cacheWrite: 6.25,
+          tieredPricing: [
+            { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25, range: [0, 272_000] },
+            { input: 10, output: 45, cacheRead: 1, cacheWrite: 12.5, range: [272_000] },
+          ],
+        },
+      ],
       ["gpt-5.4-mini", { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 }],
       ["glm-5.2", { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 }],
       ["hy3-free", { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }],
@@ -372,7 +459,7 @@ describe("opencode provider plugin", () => {
       throw new Error("expected OpenCode Zen static provider");
     }
 
-    expect(result.provider.models).toHaveLength(52);
+    expect(result.provider.models).toHaveLength(55);
     expect(result.provider.models.map((model) => model.id)).toContain("claude-opus-4-8");
     expect(result.provider.models.map((model) => model.id)).toContain("claude-sonnet-5");
     expect(result.provider.models.map((model) => model.id)).toContain("glm-5.2");
@@ -381,6 +468,7 @@ describe("opencode provider plugin", () => {
     expect(result.provider.models.map((model) => model.id)).toContain("kimi-k2.7-code");
     expect(result.provider.models.map((model) => model.id)).toContain("minimax-m2.7");
     expect(result.provider.models.map((model) => model.id)).toContain("minimax-m3");
+    expect(result.provider.models.map((model) => model.id)).toContain("gpt-5.6-luna");
     expect(result.provider.models.find((model) => model.id === "minimax-m2.7")).toMatchObject({
       api: "openai-completions",
       baseUrl: "https://opencode.ai/zen/v1",
@@ -395,8 +483,9 @@ describe("opencode provider plugin", () => {
       throw new Error("expected registered OpenCode Zen static provider");
     }
 
-    expect(result.provider.models).toHaveLength(52);
+    expect(result.provider.models).toHaveLength(55);
     expect(result.provider.models.map((model) => model.id)).toContain("claude-sonnet-5");
+    expect(result.provider.models.map((model) => model.id)).toContain("gpt-5.6-sol");
     expect(result.provider.models.map((model) => model.id)).toContain("minimax-m3");
     expect(result.provider.models.find((model) => model.id === "grok-4.5")).toMatchObject({
       api: "openai-completions",
@@ -616,7 +705,7 @@ describe("opencode provider plugin", () => {
     });
   });
 
-  it("exposes Anthropic thinking levels for proxied Claude models", async () => {
+  it("exposes provider-owned thinking levels for proxied models", async () => {
     const { providers } = await registerProviderPlugin({
       plugin,
       id: "opencode",
@@ -655,5 +744,20 @@ describe("opencode provider plugin", () => {
     expect(sonnet46LevelIds).toContain("adaptive");
     expect(sonnet46LevelIds).not.toContain("xhigh");
     expect(sonnet46LevelIds).not.toContain("max");
+
+    const gpt56Profile = resolveThinkingProfile({
+      provider: "opencode",
+      modelId: "gpt-5.6-luna",
+      api: "openai-responses",
+      reasoning: true,
+      compat: {
+        supportedReasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
+      },
+    });
+    const gpt56LevelIds = gpt56Profile?.levels.map((level) => level.id) ?? [];
+    expect(gpt56Profile?.defaultLevel).toBe("medium");
+    expect(gpt56LevelIds).not.toContain("minimal");
+    expect(gpt56LevelIds).toContain("xhigh");
+    expect(gpt56LevelIds).toContain("max");
   });
 });
diff --git a/extensions/opencode/index.ts b/extensions/opencode/index.ts
index a4e36042670..0f1bc0e2959 100644
--- a/extensions/opencode/index.ts
+++ b/extensions/opencode/index.ts
@@ -4,7 +4,6 @@ import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-aut
 import {
   buildProviderReplayFamilyHooks,
   matchesExactOrPrefix,
-  resolveClaudeThinkingProfile,
 } from "openclaw/plugin-sdk/provider-model-shared";
 import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { applyOpencodeZenConfig, OPENCODE_ZEN_DEFAULT_MODEL } from "./api.js";
@@ -16,6 +15,7 @@ import {
   normalizeOpencodeZenBaseUrl,
   resolveOpencodeZenModel,
 } from "./provider-catalog.js";
+import { resolveThinkingProfile as resolveOpencodeThinkingProfile } from "./provider-policy-api.js";
 import { registerOpenCodeSessionCatalog } from "./session-catalog-plugin.js";
 
 const PROVIDER_ID = "opencode";
@@ -151,7 +151,7 @@ export default definePluginEntry({
       augmentModelCatalog: () => listOpencodeZenModelCatalogEntries(),
       ...buildProviderReplayFamilyHooks({ family: "passthrough-gemini" }),
       isModernModelRef: ({ modelId }) => isModernOpencodeModel(modelId),
-      resolveThinkingProfile: ({ modelId }) => resolveClaudeThinkingProfile(modelId),
+      resolveThinkingProfile: resolveOpencodeThinkingProfile,
     });
     api.registerMediaUnderstandingProvider(opencodeMediaUnderstandingProvider);
     registerOpenCodeSessionCatalog(api);
diff --git a/extensions/opencode/provider-catalog.ts b/extensions/opencode/provider-catalog.ts
index f10eee6ed2a..b895bf734c1 100644
--- a/extensions/opencode/provider-catalog.ts
+++ b/extensions/opencode/provider-catalog.ts
@@ -30,6 +30,9 @@ const FREE_COST: ModelDefinitionConfig["cost"] = {
 // Zen publishes route-specific limits that differ from the family defaults below.
 const MODEL_LIMITS: Record<string, { contextWindow: number; maxTokens: number }> = {
   "claude-sonnet-5": { contextWindow: 1_000_000, maxTokens: 128_000 },
+  "gpt-5.6-luna": { contextWindow: 1_050_000, maxTokens: 128_000 },
+  "gpt-5.6-sol": { contextWindow: 1_050_000, maxTokens: 128_000 },
+  "gpt-5.6-terra": { contextWindow: 1_050_000, maxTokens: 128_000 },
   "glm-5.2": { contextWindow: 1_000_000, maxTokens: 131_072 },
   "grok-4.5": { contextWindow: 500_000, maxTokens: 500_000 },
   "hy3-free": { contextWindow: 256_000, maxTokens: 64_000 },
@@ -89,6 +92,36 @@ const MODEL_COSTS: Record<string, ModelDefinitionConfig["cost"]> = {
     ],
   },
   "gemini-3.5-flash": { input: 1.5, output: 9, cacheRead: 0.15, cacheWrite: 0 },
+  "gpt-5.6-luna": {
+    input: 1,
+    output: 6,
+    cacheRead: 0.1,
+    cacheWrite: 1.25,
+    tieredPricing: [
+      { input: 1, output: 6, cacheRead: 0.1, cacheWrite: 1.25, range: [0, 272_000] },
+      { input: 2, output: 9, cacheRead: 0.2, cacheWrite: 2.5, range: [272_000] },
+    ],
+  },
+  "gpt-5.6-sol": {
+    input: 5,
+    output: 30,
+    cacheRead: 0.5,
+    cacheWrite: 6.25,
+    tieredPricing: [
+      { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 6.25, range: [0, 272_000] },
+      { input: 10, output: 45, cacheRead: 1, cacheWrite: 12.5, range: [272_000] },
+    ],
+  },
+  "gpt-5.6-terra": {
+    input: 2.5,
+    output: 15,
+    cacheRead: 0.25,
+    cacheWrite: 3.125,
+    tieredPricing: [
+      { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 3.125, range: [0, 272_000] },
+      { input: 5, output: 22.5, cacheRead: 0.5, cacheWrite: 6.25, range: [272_000] },
+    ],
+  },
   "glm-5": { input: 1, output: 3.2, cacheRead: 0.2, cacheWrite: 0 },
   "glm-5.1": { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
   "glm-5.2": { input: 1.4, output: 4.4, cacheRead: 0.26, cacheWrite: 0 },
@@ -171,6 +204,9 @@ const MODEL_NAMES: Record<string, string> = {
   "gemini-3-flash": "Gemini 3 Flash",
   "gemini-3.1-pro": "Gemini 3.1 Pro",
   "gemini-3.5-flash": "Gemini 3.5 Flash",
+  "gpt-5.6-luna": "GPT-5.6 Luna",
+  "gpt-5.6-sol": "GPT-5.6 Sol",
+  "gpt-5.6-terra": "GPT-5.6 Terra",
   "glm-5": "GLM-5",
   "glm-5.1": "GLM-5.1",
   "glm-5.2": "GLM-5.2",
@@ -207,6 +243,9 @@ const MODEL_NAMES: Record<string, string> = {
   "qwen3.6-plus": "Qwen3.6 Plus",
 };
 
+const GPT_56_MODEL_IDS = new Set(["gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra"]);
+const GPT_56_REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"];
+
 type OpencodeZenModelDefinition = ModelDefinitionConfig & {
   provider: typeof PROVIDER_ID;
   api: NonNullable<ModelDefinitionConfig["api"]>;
@@ -343,6 +382,9 @@ function buildOpencodeZenModel(modelId: string): OpencodeZenModelDefinition {
     compat: {
       supportsUsageInStreaming: true,
       supportsReasoningEffort: true,
+      ...(GPT_56_MODEL_IDS.has(normalizedModelId)
+        ? { supportedReasoningEfforts: GPT_56_REASONING_EFFORTS }
+        : {}),
       maxTokensField: "max_tokens",
     },
   }) as OpencodeZenModelDefinition;
@@ -363,6 +405,9 @@ const OPENCODE_ZEN_MODELS = [
   "gemini-3.5-flash",
   "gemini-3.1-pro",
   "gemini-3-flash",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
   "gpt-5.5",
   "gpt-5.5-pro",
   "gpt-5.4",
diff --git a/extensions/opencode/provider-policy-api.test.ts b/extensions/opencode/provider-policy-api.test.ts
index 99b086e1124..c45dbcd1826 100644
--- a/extensions/opencode/provider-policy-api.test.ts
+++ b/extensions/opencode/provider-policy-api.test.ts
@@ -42,4 +42,23 @@ describe("opencode provider policy public artifact", () => {
       defaultLevel: "adaptive",
     });
   });
+
+  it("exposes the full GPT-5.6 reasoning profile", () => {
+    expect(
+      resolveThinkingProfile({
+        provider: "opencode",
+        modelId: "gpt-5.6-luna",
+      }),
+    ).toEqual({
+      levels: [
+        { id: "off" },
+        { id: "low" },
+        { id: "medium" },
+        { id: "high" },
+        { id: "xhigh" },
+        { id: "max" },
+      ],
+      defaultLevel: "medium",
+    });
+  });
 });
diff --git a/extensions/opencode/provider-policy-api.ts b/extensions/opencode/provider-policy-api.ts
index 72fe0de8344..4262e4e61bf 100644
--- a/extensions/opencode/provider-policy-api.ts
+++ b/extensions/opencode/provider-policy-api.ts
@@ -1,6 +1,29 @@
 // Opencode API module exposes the plugin public contract.
+import type {
+  ProviderDefaultThinkingPolicyContext,
+  ProviderThinkingProfile,
+} from "openclaw/plugin-sdk/plugin-entry";
 import { resolveClaudeThinkingProfile } from "openclaw/plugin-sdk/provider-model-shared";
 
-export function resolveThinkingProfile(params: { provider?: string; modelId: string }) {
+const GPT_56_THINKING_PROFILE = {
+  levels: [
+    { id: "off" },
+    { id: "low" },
+    { id: "medium" },
+    { id: "high" },
+    { id: "xhigh" },
+    { id: "max" },
+  ],
+  defaultLevel: "medium",
+} as const satisfies ProviderThinkingProfile;
+
+function isGpt56Model(modelId: string): boolean {
+  return /^gpt-5\.6(?:-|$)/u.test(modelId.trim().toLowerCase());
+}
+
+export function resolveThinkingProfile(params: ProviderDefaultThinkingPolicyContext) {
+  if (isGpt56Model(params.modelId)) {
+    return GPT_56_THINKING_PROFILE;
+  }
   return resolveClaudeThinkingProfile(params.modelId);
 }

From 52d49a69b2f8b723dfd18d44870c8796fda02440 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:14:41 +0100
Subject: [PATCH 25/76] fix(plugin-sdk): refresh config schema API baseline
 (#110614)

---
 docs/.generated/plugin-sdk-api-baseline.sha256 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 7626ccb571a..646b8d4c3c0 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -94,7 +94,7 @@ d340686cf814326b5a554a32cc5ca324a9e1254a933c4d9d8d1ada5ac7109a10  module/command
 a821f9cc4e6f9339399d99e73f58c3b00baf139aa9d85c22d73c89d8be5702d2  module/config-contracts
 20f3f8042de53e4eee61b64de9102c8c202b9299e6a29235647a4729f70145f2  module/config-mutation
 316949815affe623ac63951a5db580527f02663576dffa084f02768f612c0c1c  module/config-runtime
-2efea5ed295e37932c69f907b8e197ef237d757c1e9accd3d3809c3696428a55  module/config-schema
+a7d72564e1766cc51fafcba150e32cac267afb2fc8c92ffce4095a1bb5152030  module/config-schema
 bfe6eec12f45bc2fda6df28699681b22dfd819a2261aabe8e0c789a20a017058  module/config-types
 42d15153981cfe3adc1d5f91621434c56f07a9bd48c15ce34742f72dd040c142  module/context-visibility-runtime
 03636897fb99cb73e4d8620c8a0e0d72b4d52fc32bf94f525af2aa88c489c6c2  module/conversation-binding-runtime

From cb785ed95b3694323bf6f7c33c333b14d6be4696 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:19:08 +0100
Subject: [PATCH 26/76] feat(ui): syntax-highlight the channel health snapshot
 on the channels settings page (#110613)

---
 ui/src/components/markdown.ts | 5 +++++
 ui/src/pages/channels/view.ts | 7 +++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/ui/src/components/markdown.ts b/ui/src/components/markdown.ts
index 05b72e8cd76..ef530ab6e61 100644
--- a/ui/src/components/markdown.ts
+++ b/ui/src/components/markdown.ts
@@ -840,6 +840,11 @@ function highlightCode(text: string, lang: string): string {
   return escapeHtml(text);
 }
 
+/** Highlight a JSON/JSON5 snippet; output is escaped hljs markup safe for unsafeHTML in a code block. */
+export function highlightJsonHtml(text: string): string {
+  return highlightCode(text, "json");
+}
+
 function codeClassAttribute(lang: string, highlighted: string): string {
   const classes = [
     highlighted.includes("hljs-") ? "hljs" : "",
diff --git a/ui/src/pages/channels/view.ts b/ui/src/pages/channels/view.ts
index 01d4a35c90b..eab774802ce 100644
--- a/ui/src/pages/channels/view.ts
+++ b/ui/src/pages/channels/view.ts
@@ -1,6 +1,7 @@
 // Channels hub: connected-channel rows, add-a-channel gallery, setup wizard,
 // and a per-channel detail overlay with the full config form.
 import { html, nothing } from "lit";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import "../../styles/channels.css";
 import type {
   ChannelAccountSnapshot,
@@ -16,6 +17,7 @@ import type {
   WhatsAppStatus,
 } from "../../api/types.ts";
 import { icons } from "../../components/icons.ts";
+import { highlightJsonHtml } from "../../components/markdown.ts";
 import "../../components/openclaw-mascot.ts";
 import {
   renderSettingsEmpty,
@@ -108,8 +110,9 @@ export function renderChannels(props: ChannelsProps) {
         html`
           <div class="settings-row settings-row--stacked">
             <pre class="code-block">
-${props.snapshot ? JSON.stringify(props.snapshot, null, 2) : t("channels.health.noSnapshotYet")}
-            </pre>
+${props.snapshot
+                ? unsafeHTML(highlightJsonHtml(JSON.stringify(props.snapshot, null, 2)))
+                : t("channels.health.noSnapshotYet")}</pre>
           </div>
         `,
       )}

From 21c3438dedbe708ce9d88d160976c357a5e72360 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:19:34 +0100
Subject: [PATCH 27/76] feat(ui): merge voice and video talk into one button
 with in-call camera toggle (#110576)

* feat(ui): merge voice and video talk into one button with in-call camera toggle

* fix(ui): avoid stale TS narrowing on talk status re-check in camera toggle
---
 ui/src/e2e/chat-composer-redesign.e2e.test.ts |   3 +
 ui/src/i18n/locales/en.ts                     |   6 +-
 ui/src/pages/chat/chat-composer.test.ts       |  25 +++
 ui/src/pages/chat/chat-pane.ts                |   8 +-
 ui/src/pages/chat/chat-realtime.test.ts       | 113 ++++++++++++-
 ui/src/pages/chat/chat-realtime.ts            |  77 ++++++++-
 ui/src/pages/chat/chat-state.ts               |   3 +
 ui/src/pages/chat/chat-view.test.ts           |  34 ++--
 ui/src/pages/chat/chat-view.ts                |  10 +-
 ui/src/pages/chat/components/chat-composer.ts |  66 +++++---
 .../realtime-talk-google-live-video.test.ts   |  89 +++++++---
 .../pages/chat/realtime-talk-google-live.ts   | 110 +++++++++---
 ui/src/pages/chat/realtime-talk-input.test.ts |  70 +++-----
 ui/src/pages/chat/realtime-talk-input.ts      |  40 ++---
 ui/src/pages/chat/realtime-talk-shared.ts     |   3 +-
 .../chat/realtime-talk-webrtc-video.test.ts   | 156 ++++++++++++++----
 .../pages/chat/realtime-talk-webrtc.test.ts   |   2 -
 ui/src/pages/chat/realtime-talk-webrtc.ts     |  98 +++++++++--
 ui/src/pages/chat/realtime-talk.test.ts       | 131 ++++++++++++++-
 ui/src/pages/chat/realtime-talk.ts            |  55 +++++-
 20 files changed, 864 insertions(+), 235 deletions(-)

diff --git a/ui/src/e2e/chat-composer-redesign.e2e.test.ts b/ui/src/e2e/chat-composer-redesign.e2e.test.ts
index 10f7879fcd6..09ac3cc03dc 100644
--- a/ui/src/e2e/chat-composer-redesign.e2e.test.ts
+++ b/ui/src/e2e/chat-composer-redesign.e2e.test.ts
@@ -142,6 +142,9 @@ describeControlUiE2e("Control UI chat composer redesign", () => {
       await expect.poll(() => attach.isVisible()).toBe(true);
       await expect.poll(() => camera.isVisible()).toBe(false);
       await expect.poll(() => voice.isVisible()).toBe(true);
+      await expect
+        .poll(() => page.getByRole("button", { name: "Start video talk" }).count())
+        .toBe(0);
       await expect
         .poll(() =>
           attach.evaluate((node) => node.closest(".agent-chat__composer-input-row") != null),
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 9ee2c5d456e..100bbccb321 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -3731,10 +3731,11 @@ export const en: TranslationMap = {
         limitHours: "{hours}-hour limit",
       },
       takePhoto: "Take photo",
+      cameraAccessFailed: "Unable to access the camera.",
       cameraBusy: "The camera is busy or unavailable to the browser.",
       cameraNoneFound: "No camera was found.",
       cameraPermissionBlocked:
-        "Camera access is blocked. Allow camera and microphone access in browser site settings.",
+        "Camera access is blocked. Allow camera access in browser site settings.",
       cameraPreview: "Camera preview",
       dismissVoiceInputError: "Dismiss voice input error",
       microphoneAccessFailed: "Unable to access microphone inputs.",
@@ -3751,10 +3752,11 @@ export const en: TranslationMap = {
       selectedMicrophoneUnavailable:
         "The selected microphone is unavailable. Choose another input or System default.",
       startVoiceInput: "Start voice input",
-      startVideoTalk: "Start video talk",
       stillListening: "Still listening",
       stopVoiceInput: "Stop voice input",
       systemDefaultMicrophone: "System default",
+      turnCameraOff: "Turn camera off",
+      turnCameraOn: "Turn camera on",
       voiceTranscript: "Voice transcript",
     },
     selectors: {
diff --git a/ui/src/pages/chat/chat-composer.test.ts b/ui/src/pages/chat/chat-composer.test.ts
index e63d53bf3a0..1e032132aad 100644
--- a/ui/src/pages/chat/chat-composer.test.ts
+++ b/ui/src/pages/chat/chat-composer.test.ts
@@ -86,6 +86,7 @@ describe("renderChatComposer controls", () => {
     let view = renderComposer({ onToggleRealtimeTalk });
     button(view.container, t("chat.composer.startVoiceInput")).click();
     expect(onToggleRealtimeTalk).toHaveBeenCalledOnce();
+    expect(view.container.querySelector('[aria-label="Start video talk"]')).toBeNull();
 
     const onSend = vi.fn();
     view = renderComposer({ draft: "Send this", onSend });
@@ -123,6 +124,30 @@ describe("renderChatComposer controls", () => {
     expect(button(view.container, t("chat.runControls.sendMessage")).disabled).toBe(false);
   });
 
+  it("offers camera only inside a video-capable active talk session", () => {
+    const onToggleRealtimeCamera = vi.fn();
+    const { container } = renderComposer({
+      onToggleRealtimeTalk: vi.fn(),
+      onToggleRealtimeCamera,
+      realtimeTalkActive: true,
+      realtimeTalkStatus: "listening",
+      realtimeTalkVideoCapable: true,
+    });
+
+    button(container, t("chat.composer.turnCameraOn")).click();
+    expect(onToggleRealtimeCamera).toHaveBeenCalledOnce();
+    expect(container.querySelector('[aria-label="Start video talk"]')).toBeNull();
+
+    const failed = renderComposer({
+      onToggleRealtimeTalk: vi.fn(),
+      onToggleRealtimeCamera,
+      realtimeTalkActive: true,
+      realtimeTalkStatus: "error",
+      realtimeTalkVideoCapable: true,
+    });
+    expect(button(failed.container, t("chat.composer.turnCameraOn")).disabled).toBe(true);
+  });
+
   it("sends attachment-only drafts instead of starting voice", () => {
     const onSend = vi.fn();
     const onToggleRealtimeTalk = vi.fn();
diff --git a/ui/src/pages/chat/chat-pane.ts b/ui/src/pages/chat/chat-pane.ts
index fc1b9037f83..faaef120675 100644
--- a/ui/src/pages/chat/chat-pane.ts
+++ b/ui/src/pages/chat/chat-pane.ts
@@ -1861,6 +1861,9 @@ class ChatPane extends OpenClawLightDomElement {
       state.realtimeTalkSession = null;
       state.realtimeTalkActive = false;
       state.realtimeTalkVideoStream = null;
+      state.realtimeTalkVideoCapable = false;
+      state.realtimeTalkVideoPending = false;
+      state.realtimeTalkCameraError = false;
       state.realtimeTalkStatus = "idle";
       state.realtimeTalkInputLevel.set(0);
       state.resetToolStream();
@@ -2334,6 +2337,9 @@ class ChatPane extends OpenClawLightDomElement {
       realtimeTalkInputLevel: state.realtimeTalkInputLevel,
       realtimeTalkConversation: state.realtimeTalkConversation,
       realtimeTalkVideoStream: state.realtimeTalkVideoStream,
+      realtimeTalkVideoCapable: state.realtimeTalkVideoCapable,
+      realtimeTalkVideoPending: state.realtimeTalkVideoPending,
+      realtimeTalkCameraError: state.realtimeTalkCameraError,
       connected: state.connected,
       canSend: catalogKey ? this.catalogSession?.canContinue === true : !selectedSessionArchived,
       disabledReason: catalogDisabledReason ?? disabledReason,
@@ -2451,7 +2457,7 @@ class ChatPane extends OpenClawLightDomElement {
         this.context.navigate("sessions", { search: `?${search.toString()}` });
       },
       onToggleRealtimeTalk: () => void state.toggleRealtimeTalk(),
-      onToggleRealtimeVideo: () => void state.toggleRealtimeTalk({ video: true }),
+      onToggleRealtimeCamera: () => void state.toggleRealtimeTalkCamera(),
       onDismissError: () => {
         dismissChatError(state as never);
         state.requestUpdate?.();
diff --git a/ui/src/pages/chat/chat-realtime.test.ts b/ui/src/pages/chat/chat-realtime.test.ts
index 8d377f776c0..aa9e2e31605 100644
--- a/ui/src/pages/chat/chat-realtime.test.ts
+++ b/ui/src/pages/chat/chat-realtime.test.ts
@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
 import { loadSettings, saveSettings } from "../../app/settings.ts";
+import { createStorageMock } from "../../test-helpers/storage.ts";
 import {
   attachChatRealtimeActions,
   createInitialChatRealtimeState,
@@ -11,8 +12,8 @@ import { RealtimeTalkSession } from "./realtime-talk.ts";
 
 type InspectableRealtimeTalkSession = {
   callbacks: RealtimeTalkCallbacks;
-  options: { provider?: string; transport?: string; capabilities?: string[] };
-  localOptions: { inputDeviceId?: string; videoEnabled?: boolean };
+  options: { provider?: string; transport?: string };
+  localOptions: { inputDeviceId?: string };
 };
 
 function inspectSession(state: ChatRealtimeState): InspectableRealtimeTalkSession {
@@ -44,8 +45,7 @@ describe("chat realtime actions", () => {
   let startSpy: MockInstance<RealtimeTalkSession["start"]>;
 
   beforeEach(() => {
-    vi.stubGlobal("localStorage", window.localStorage);
-    localStorage.clear();
+    vi.stubGlobal("localStorage", createStorageMock());
     startSpy = vi.spyOn(RealtimeTalkSession.prototype, "start").mockResolvedValue(undefined);
     vi.spyOn(RealtimeTalkSession.prototype, "stop").mockImplementation(() => undefined);
   });
@@ -67,22 +67,117 @@ describe("chat realtime actions", () => {
     expect(startSpy).toHaveBeenCalledOnce();
   });
 
-  it("launches video talk through the configured provider and owns the preview stream", async () => {
+  it("enables camera only after a video-capable voice session starts", async () => {
     const state = createState();
+    const setVideoEnabled = vi
+      .spyOn(RealtimeTalkSession.prototype, "setVideoEnabled")
+      .mockResolvedValue(undefined);
 
-    await state.toggleRealtimeTalk({ video: true });
+    await state.toggleRealtimeTalk();
     const session = inspectSession(state);
     const stream = {} as MediaStream;
+    session.callbacks.onVideoCapability?.(true);
+    await state.toggleRealtimeTalkCamera();
     session.callbacks.onVideoStream?.(stream);
 
     expect(session.options.provider).toBeUndefined();
     expect(session.options.transport).toBeUndefined();
-    expect(session.options.capabilities).toEqual(["camera-frame"]);
-    expect(session.localOptions.videoEnabled).toBe(true);
+    expect(setVideoEnabled).toHaveBeenCalledWith(true);
     expect(state.realtimeTalkVideoStream).toBe(stream);
 
+    await state.toggleRealtimeTalkCamera();
+    expect(setVideoEnabled).toHaveBeenLastCalledWith(false);
+    session.callbacks.onVideoStream?.(null);
+    expect(state.realtimeTalkVideoStream).toBeNull();
+  });
+
+  it("keeps voice active and surfaces a non-fatal camera error", async () => {
+    const state = createState();
+    vi.spyOn(RealtimeTalkSession.prototype, "setVideoEnabled").mockRejectedValue(
+      new Error("Camera access is blocked"),
+    );
+
+    await state.toggleRealtimeTalk();
+    const session = inspectSession(state);
+    session.callbacks.onVideoCapability?.(true);
+    session.callbacks.onStatus?.("listening");
+    await state.toggleRealtimeTalkCamera();
+
+    expect(state.realtimeTalkSession).not.toBeNull();
+    expect(state.realtimeTalkActive).toBe(true);
+    expect(state.realtimeTalkStatus).toBe("listening");
+    expect(state.realtimeTalkVideoStream).toBeNull();
+    expect(state.realtimeTalkDetail).toBe("Camera access is blocked");
+    expect(state.realtimeTalkCameraError).toBe(true);
+  });
+
+  it("keeps the connection error when camera toggle is requested after failure", async () => {
+    const state = createState();
+    const setVideoEnabled = vi
+      .spyOn(RealtimeTalkSession.prototype, "setVideoEnabled")
+      .mockResolvedValue(undefined);
+
     await state.toggleRealtimeTalk();
+    const session = inspectSession(state);
+    session.callbacks.onVideoCapability?.(true);
+    session.callbacks.onStatus?.("error", "Realtime connection closed");
+    await state.toggleRealtimeTalkCamera();
+
+    expect(setVideoEnabled).not.toHaveBeenCalled();
+    expect(state.realtimeTalkDetail).toBe("Realtime connection closed");
+    expect(state.realtimeTalkCameraError).toBe(false);
+  });
+
+  it("keeps a connection error authoritative over an in-flight camera rejection", async () => {
+    const state = createState();
+    let rejectCamera: (error: Error) => void = () => undefined;
+    vi.spyOn(RealtimeTalkSession.prototype, "setVideoEnabled").mockImplementation(
+      () =>
+        new Promise<void>((_resolve, reject) => {
+          rejectCamera = reject;
+        }),
+    );
+
+    await state.toggleRealtimeTalk();
+    const session = inspectSession(state);
+    session.callbacks.onVideoCapability?.(true);
+    session.callbacks.onStatus?.("listening");
+    const toggling = state.toggleRealtimeTalkCamera();
+    session.callbacks.onStatus?.("error", "Realtime connection closed");
+    rejectCamera(new Error("Camera access is blocked"));
+    await toggling;
+
+    expect(state.realtimeTalkDetail).toBe("Realtime connection closed");
+    expect(state.realtimeTalkCameraError).toBe(false);
+  });
+
+  it("releases a camera stream that arrives after a connection error", async () => {
+    const state = createState();
+    let resolveCamera: () => void = () => undefined;
+    const setVideoEnabled = vi
+      .spyOn(RealtimeTalkSession.prototype, "setVideoEnabled")
+      .mockImplementation((enabled) =>
+        enabled
+          ? new Promise<void>((resolve) => {
+              resolveCamera = resolve;
+            })
+          : Promise.resolve(),
+      );
+
+    await state.toggleRealtimeTalk();
+    const session = inspectSession(state);
+    session.callbacks.onVideoCapability?.(true);
+    session.callbacks.onStatus?.("listening");
+    const toggling = state.toggleRealtimeTalkCamera();
+    session.callbacks.onStatus?.("error", "Realtime connection closed");
+    session.callbacks.onVideoStream?.({} as MediaStream);
+    resolveCamera();
+    await toggling;
+
+    expect(setVideoEnabled).toHaveBeenLastCalledWith(false);
     expect(state.realtimeTalkVideoStream).toBeNull();
+    expect(state.realtimeTalkDetail).toBe("Realtime connection closed");
+    expect(state.realtimeTalkCameraError).toBe(false);
   });
 
   it("re-reads the persisted microphone on every launch instead of caching it", async () => {
@@ -100,7 +195,7 @@ describe("chat realtime actions", () => {
   });
 
   it("keeps a microphone picked while storage is blocked for the next launch", async () => {
-    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+    vi.spyOn(localStorage, "setItem").mockImplementation(() => {
       throw new DOMException("blocked", "SecurityError");
     });
     saveSettings({ ...loadSettings(), realtimeTalkInputDeviceId: "usb-mic" });
diff --git a/ui/src/pages/chat/chat-realtime.ts b/ui/src/pages/chat/chat-realtime.ts
index 7badec5b004..54354f31862 100644
--- a/ui/src/pages/chat/chat-realtime.ts
+++ b/ui/src/pages/chat/chat-realtime.ts
@@ -22,11 +22,15 @@ export type ChatRealtimeState = {
   realtimeTalkInputLevel: RealtimeTalkLevelSignal;
   realtimeTalkConversation: RealtimeTalkConversationEntry[];
   realtimeTalkVideoStream: MediaStream | null;
+  realtimeTalkVideoCapable: boolean;
+  realtimeTalkVideoPending: boolean;
+  realtimeTalkCameraError: boolean;
   realtimeTalkSession: RealtimeTalkSession | null;
   realtimeTalkConversationState: RealtimeTalkConversationState;
   requestUpdate: () => void;
   resetRealtimeTalkConversation: () => void;
-  toggleRealtimeTalk: (options?: { video?: boolean }) => Promise<void>;
+  toggleRealtimeTalk: () => Promise<void>;
+  toggleRealtimeTalkCamera: () => Promise<void>;
 };
 
 export function createInitialChatRealtimeState() {
@@ -37,6 +41,9 @@ export function createInitialChatRealtimeState() {
     realtimeTalkInputLevel: new RealtimeTalkLevelSignal(),
     realtimeTalkConversation: [],
     realtimeTalkVideoStream: null,
+    realtimeTalkVideoCapable: false,
+    realtimeTalkVideoPending: false,
+    realtimeTalkCameraError: false,
     realtimeTalkSession: null,
     realtimeTalkConversationState: createRealtimeTalkConversationState(),
   };
@@ -58,6 +65,9 @@ export function dismissRealtimeTalkError(state: ChatRealtimeState) {
   state.realtimeTalkDetail = null;
   state.realtimeTalkInputLevel.set(0);
   state.realtimeTalkVideoStream = null;
+  state.realtimeTalkVideoCapable = false;
+  state.realtimeTalkVideoPending = false;
+  state.realtimeTalkCameraError = false;
   state.resetRealtimeTalkConversation();
 }
 
@@ -65,7 +75,7 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
   state.resetRealtimeTalkConversation = () => {
     resetChatRealtimeConversation(state);
   };
-  state.toggleRealtimeTalk = async (options = {}) => {
+  state.toggleRealtimeTalk = async () => {
     if (state.realtimeTalkSession) {
       state.realtimeTalkSession.stop();
       state.realtimeTalkSession = null;
@@ -74,6 +84,9 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
       state.realtimeTalkDetail = null;
       state.realtimeTalkInputLevel.set(0);
       state.realtimeTalkVideoStream = null;
+      state.realtimeTalkVideoCapable = false;
+      state.realtimeTalkVideoPending = false;
+      state.realtimeTalkCameraError = false;
       state.resetRealtimeTalkConversation();
       state.requestUpdate();
       return;
@@ -90,6 +103,9 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
     state.realtimeTalkActive = true;
     state.realtimeTalkStatus = "connecting";
     state.realtimeTalkDetail = null;
+    state.realtimeTalkVideoCapable = false;
+    state.realtimeTalkVideoPending = false;
+    state.realtimeTalkCameraError = false;
     state.realtimeTalkInputLevel.set(0);
     state.resetRealtimeTalkConversation();
     const session = new RealtimeTalkSession(
@@ -102,12 +118,20 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
           }
           state.realtimeTalkStatus = status;
           state.realtimeTalkDetail = detail ?? null;
+          state.realtimeTalkCameraError = false;
           state.realtimeTalkActive = status !== "idle";
           if (status === "idle" || status === "error") {
             state.realtimeTalkInputLevel.set(0);
           }
           state.requestUpdate();
         },
+        onVideoCapability: (capable) => {
+          if (state.realtimeTalkSession !== session) {
+            return;
+          }
+          state.realtimeTalkVideoCapable = capable;
+          state.requestUpdate();
+        },
         onInputLevel: (level) => {
           if (state.realtimeTalkSession !== session) {
             return;
@@ -129,12 +153,20 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
           if (state.realtimeTalkSession !== session) {
             return;
           }
+          if (stream && state.realtimeTalkStatus === "error") {
+            void session.setVideoEnabled(false).catch(() => undefined);
+            return;
+          }
           state.realtimeTalkVideoStream = stream;
+          if (stream) {
+            state.realtimeTalkDetail = null;
+            state.realtimeTalkCameraError = false;
+          }
           state.requestUpdate();
         },
       },
-      options.video ? { capabilities: ["camera-frame"] } : {},
-      { inputDeviceId, videoEnabled: options.video },
+      {},
+      { inputDeviceId },
     );
     state.realtimeTalkSession = session;
     try {
@@ -150,7 +182,44 @@ export function attachChatRealtimeActions(state: ChatRealtimeState) {
       state.realtimeTalkDetail = error instanceof Error ? error.message : String(error);
       state.realtimeTalkInputLevel.set(0);
       state.realtimeTalkVideoStream = null;
+      state.realtimeTalkVideoCapable = false;
+      state.realtimeTalkVideoPending = false;
+      state.realtimeTalkCameraError = false;
       state.requestUpdate();
     }
   };
+  // Reads through a call so TS does not keep the early-guard narrowing across the
+  // await below; the status can legitimately become "error" while acquiring the camera.
+  const talkStatusIsError = () => state.realtimeTalkStatus === "error";
+  state.toggleRealtimeTalkCamera = async () => {
+    const session = state.realtimeTalkSession;
+    if (
+      !session ||
+      !state.realtimeTalkVideoCapable ||
+      state.realtimeTalkVideoPending ||
+      talkStatusIsError()
+    ) {
+      return;
+    }
+    const enabled = state.realtimeTalkVideoStream === null;
+    state.realtimeTalkVideoPending = true;
+    state.realtimeTalkCameraError = false;
+    state.realtimeTalkDetail = null;
+    state.requestUpdate();
+    try {
+      await session.setVideoEnabled(enabled);
+    } catch (error) {
+      if (state.realtimeTalkSession !== session || talkStatusIsError()) {
+        return;
+      }
+      state.realtimeTalkVideoStream = null;
+      state.realtimeTalkDetail = error instanceof Error ? error.message : String(error);
+      state.realtimeTalkCameraError = true;
+    } finally {
+      if (state.realtimeTalkSession === session) {
+        state.realtimeTalkVideoPending = false;
+        state.requestUpdate();
+      }
+    }
+  };
 }
diff --git a/ui/src/pages/chat/chat-state.ts b/ui/src/pages/chat/chat-state.ts
index a0b2daeab82..09bbbaeea44 100644
--- a/ui/src/pages/chat/chat-state.ts
+++ b/ui/src/pages/chat/chat-state.ts
@@ -1966,6 +1966,9 @@ export class ChatStateController<TState extends ChatPageHost> implements Reactiv
     if (state) {
       state.realtimeTalkSession = null;
       state.realtimeTalkVideoStream = null;
+      state.realtimeTalkVideoCapable = false;
+      state.realtimeTalkVideoPending = false;
+      state.realtimeTalkCameraError = false;
       state.resetToolStream?.();
     }
   }
diff --git a/ui/src/pages/chat/chat-view.test.ts b/ui/src/pages/chat/chat-view.test.ts
index dcdf8ca8c88..719d7aca2b5 100644
--- a/ui/src/pages/chat/chat-view.test.ts
+++ b/ui/src/pages/chat/chat-view.test.ts
@@ -646,7 +646,7 @@ function createChatProps(
     onSend: () => undefined,
     onCompact: () => undefined,
     onToggleRealtimeTalk: () => undefined,
-    onToggleRealtimeVideo: () => undefined,
+    onToggleRealtimeCamera: () => undefined,
     onDismissError: () => undefined,
     onAbort: () => undefined,
     onQueueRemove: () => undefined,
@@ -2158,23 +2158,37 @@ describe("chat voice controls", () => {
     await i18n.setLocale("en");
   });
 
-  it("keeps voice input visible without a second dictation control", () => {
+  it("shows one mic button for starting realtime talk", () => {
     const container = renderChatView();
 
     requireElement(container, '[aria-label="Start voice input"]', "voice input button");
-    requireElement(container, '[aria-label="Start video talk"]', "video talk button");
+    expect(container.querySelector('[aria-label="Start video talk"]')).toBeNull();
     expect(container.querySelector('[aria-label="Voice input"]')).toBeNull();
   });
 
-  it("starts Video Talk separately and renders the live camera preview", () => {
-    const onToggleRealtimeVideo = vi.fn();
+  it("toggles camera inside a video-capable voice session and renders the preview", () => {
+    const onToggleRealtimeCamera = vi.fn();
     const stream = {} as MediaStream;
-    const container = renderChatView({
-      onToggleRealtimeVideo,
-      realtimeTalkVideoStream: stream,
+    let container = renderChatView({
+      realtimeTalkActive: true,
+      realtimeTalkStatus: "listening",
+      realtimeTalkVideoCapable: true,
+      onToggleRealtimeCamera,
     });
 
-    requireElement(container, '[aria-label="Start video talk"]', "video talk button").dispatchEvent(
+    requireElement(container, '[aria-label="Turn camera on"]', "camera on button").dispatchEvent(
+      new MouseEvent("click", { bubbles: true }),
+    );
+    expect(onToggleRealtimeCamera).toHaveBeenCalledOnce();
+
+    container = renderChatView({
+      realtimeTalkActive: true,
+      realtimeTalkStatus: "listening",
+      realtimeTalkVideoCapable: true,
+      realtimeTalkVideoStream: stream,
+      onToggleRealtimeCamera,
+    });
+    requireElement(container, '[aria-label="Turn camera off"]', "camera off button").dispatchEvent(
       new MouseEvent("click", { bubbles: true }),
     );
     const preview = requireElement(
@@ -2183,7 +2197,7 @@ describe("chat voice controls", () => {
       "camera preview",
     ) as HTMLVideoElement;
 
-    expect(onToggleRealtimeVideo).toHaveBeenCalledOnce();
+    expect(onToggleRealtimeCamera).toHaveBeenCalledTimes(2);
     expect(preview.srcObject).toBe(stream);
     expect(preview.autoplay).toBe(true);
     expect(preview.muted).toBe(true);
diff --git a/ui/src/pages/chat/chat-view.ts b/ui/src/pages/chat/chat-view.ts
index f11fccb99c5..ba5e77b7bad 100644
--- a/ui/src/pages/chat/chat-view.ts
+++ b/ui/src/pages/chat/chat-view.ts
@@ -106,6 +106,9 @@ export type ChatProps = {
   realtimeTalkInputLevel?: RealtimeTalkLevelSignal;
   realtimeTalkConversation?: RealtimeTalkConversationEntry[];
   realtimeTalkVideoStream?: MediaStream | null;
+  realtimeTalkVideoCapable?: boolean;
+  realtimeTalkVideoPending?: boolean;
+  realtimeTalkCameraError?: boolean;
   connected: boolean;
   canSend: boolean;
   disabledReason: string | null;
@@ -154,7 +157,7 @@ export type ChatProps = {
   onCompact?: () => void | Promise<void>;
   onOpenSessionCheckpoints?: () => void | Promise<void>;
   onToggleRealtimeTalk?: () => void;
-  onToggleRealtimeVideo?: () => void;
+  onToggleRealtimeCamera?: () => void;
   onDismissError?: () => void;
   onDismissRealtimeTalkError?: () => void;
   onAbort?: () => void;
@@ -352,6 +355,9 @@ export function renderChat(props: ChatProps) {
     realtimeTalkInputLevel: props.realtimeTalkInputLevel,
     realtimeTalkConversation: props.realtimeTalkConversation,
     realtimeTalkVideoStream: props.realtimeTalkVideoStream,
+    realtimeTalkVideoCapable: props.realtimeTalkVideoCapable,
+    realtimeTalkVideoPending: props.realtimeTalkVideoPending,
+    realtimeTalkCameraError: props.realtimeTalkCameraError,
     composerControls: props.composerControls,
     getDraft: props.getDraft,
     onDraftChange: props.onDraftChange,
@@ -361,7 +367,7 @@ export function renderChat(props: ChatProps) {
     onSend: props.onSend,
     onCompact: props.onCompact,
     onToggleRealtimeTalk: props.onToggleRealtimeTalk,
-    onToggleRealtimeVideo: props.onToggleRealtimeVideo,
+    onToggleRealtimeCamera: props.onToggleRealtimeCamera,
     onDismissRealtimeTalkError: props.onDismissRealtimeTalkError,
     onAbort: props.onAbort,
     onQueueRemove: props.onQueueRemove,
diff --git a/ui/src/pages/chat/components/chat-composer.ts b/ui/src/pages/chat/components/chat-composer.ts
index 06c9b332ca6..9a960c2c6f6 100644
--- a/ui/src/pages/chat/components/chat-composer.ts
+++ b/ui/src/pages/chat/components/chat-composer.ts
@@ -113,6 +113,9 @@ type ChatComposerProps = {
   realtimeTalkInputLevel?: RealtimeTalkLevelSignal;
   realtimeTalkConversation?: RealtimeTalkConversationEntry[];
   realtimeTalkVideoStream?: MediaStream | null;
+  realtimeTalkVideoCapable?: boolean;
+  realtimeTalkVideoPending?: boolean;
+  realtimeTalkCameraError?: boolean;
   composerControls?: TemplateResult | typeof nothing;
   getDraft?: () => string;
   onDraftChange: (next: string) => void;
@@ -122,7 +125,7 @@ type ChatComposerProps = {
   onSend: () => void;
   onCompact?: () => void | Promise<void>;
   onToggleRealtimeTalk?: () => void;
-  onToggleRealtimeVideo?: () => void;
+  onToggleRealtimeCamera?: () => void;
   onDismissRealtimeTalkError?: () => void;
   onAbort?: () => void;
   onQueueRemove: (id: string) => void;
@@ -1721,13 +1724,16 @@ type ChatRunControlsProps = {
   voiceStatus?: RealtimeTalkStatus;
   voiceDetail?: string | null;
   voiceInputLevel?: RealtimeTalkLevelSignal;
+  voiceVideoCapable?: boolean;
+  voiceVideoEnabled?: boolean;
+  voiceVideoPending?: boolean;
   onAbort?: () => void;
   onExport: () => void;
   onNewSession: () => void;
   onSend: () => void;
   onStoreDraft: (draft: string) => void;
   onToggleVoice?: () => void;
-  onToggleVideo?: () => void;
+  onToggleCamera?: () => void;
   showPrimary?: boolean;
   showSecondary?: boolean;
 };
@@ -1809,6 +1815,34 @@ function renderChatPrimaryActions(props: ChatRunControlsProps) {
                   >${voiceStatusLabel(props.voiceStatus, props.voiceDetail)}</span
                 >
               `}
+          ${props.voiceVideoCapable && props.onToggleCamera
+            ? html`
+                <openclaw-tooltip
+                  .content=${props.voiceVideoEnabled
+                    ? t("chat.composer.turnCameraOff")
+                    : t("chat.composer.turnCameraOn")}
+                >
+                  <button
+                    class="chat-send-btn chat-send-btn--voice"
+                    @click=${props.onToggleCamera}
+                    ?disabled=${props.voiceVideoPending ||
+                    props.voiceStatus === "connecting" ||
+                    props.voiceStatus === "error"}
+                    aria-label=${props.voiceVideoEnabled
+                      ? t("chat.composer.turnCameraOff")
+                      : t("chat.composer.turnCameraOn")}
+                    aria-pressed=${props.voiceVideoEnabled ? "true" : "false"}
+                  >
+                    ${icons.camera}
+                    <span class="agent-chat__control-label"
+                      >${props.voiceVideoEnabled
+                        ? t("chat.composer.turnCameraOff")
+                        : t("chat.composer.turnCameraOn")}</span
+                    >
+                  </button>
+                </openclaw-tooltip>
+              `
+            : nothing}
           ${abortAction}
         `
       : props.canAbort
@@ -1875,23 +1909,6 @@ function renderChatPrimaryActions(props: ChatRunControlsProps) {
                   >
                 </button>
               </openclaw-tooltip>
-              ${props.onToggleVideo
-                ? html`
-                    <openclaw-tooltip .content=${t("chat.composer.startVideoTalk")}>
-                      <button
-                        class="chat-send-btn chat-send-btn--voice"
-                        @click=${props.onToggleVideo}
-                        ?disabled=${!props.connected || props.sending || props.isBusy}
-                        aria-label=${t("chat.composer.startVideoTalk")}
-                      >
-                        ${icons.camera}
-                        <span class="agent-chat__control-label"
-                          >${t("chat.composer.startVideoTalk")}</span
-                        >
-                      </button>
-                    </openclaw-tooltip>
-                  `
-                : nothing}
             `}
   `;
 }
@@ -2271,13 +2288,16 @@ export function renderChatComposer(props: ChatComposerProps) {
     voiceStatus: props.realtimeTalkStatus,
     voiceDetail: props.realtimeTalkDetail,
     voiceInputLevel: props.realtimeTalkInputLevel,
+    voiceVideoCapable: props.realtimeTalkVideoCapable,
+    voiceVideoEnabled: Boolean(props.realtimeTalkVideoStream),
+    voiceVideoPending: props.realtimeTalkVideoPending,
     onAbort: props.onAbort,
     onExport: () => exportMarkdown(props),
     onNewSession: props.onNewSession,
     onSend: handleSend,
     onStoreDraft: () => {},
     onToggleVoice: props.onToggleRealtimeTalk ? handleVoicePrimaryAction : undefined,
-    onToggleVideo: props.onToggleRealtimeVideo,
+    onToggleCamera: props.onToggleRealtimeCamera,
   };
   const slashMenuVisible = props.connected && canCompose && isSlashMenuVisible(state);
   const activeSlashMenuOptionId = getActiveSlashMenuOptionId(state, props.paneId);
@@ -2367,9 +2387,11 @@ export function renderChatComposer(props: ChatComposerProps) {
 
         ${renderChatAttachmentInputs({ ...props, disabled: !canCompose })}
         ${renderChatVoiceError({
-          status: props.realtimeTalkStatus,
+          status: props.realtimeTalkCameraError ? "error" : props.realtimeTalkStatus,
           detail: props.realtimeTalkDetail,
-          onDismissError: props.onDismissRealtimeTalkError,
+          onDismissError: props.realtimeTalkCameraError
+            ? undefined
+            : props.onDismissRealtimeTalkError,
         })}
         ${props.realtimeTalkVideoStream
           ? html`
diff --git a/ui/src/pages/chat/realtime-talk-google-live-video.test.ts b/ui/src/pages/chat/realtime-talk-google-live-video.test.ts
index 0794e6a8cf8..e28c33a50fe 100644
--- a/ui/src/pages/chat/realtime-talk-google-live-video.test.ts
+++ b/ui/src/pages/chat/realtime-talk-google-live-video.test.ts
@@ -79,7 +79,6 @@ function createTransport(callbacks: RealtimeTalkCallbacks) {
       callbacks,
       client: { request: vi.fn(), addEventListener: vi.fn() } as never,
       sessionKey: "main",
-      videoEnabled: true,
     },
   );
 }
@@ -102,12 +101,12 @@ describe("Google Live Video Talk", () => {
     const audioStop = vi.fn();
     const videoStop = vi.fn();
     const audioTrack = { stop: audioStop } as unknown as MediaStreamTrack;
-    const videoTrack = {
+    const videoTrack = Object.assign(new EventTarget(), {
       stop: videoStop,
       readyState: "live",
       enabled: true,
       muted: false,
-    } as unknown as MediaStreamTrack;
+    }) as unknown as MediaStreamTrack;
     const audio = {
       getAudioTracks: () => [audioTrack],
       getTracks: () => [audioTrack],
@@ -116,21 +115,8 @@ describe("Google Live Video Talk", () => {
       getVideoTracks: () => [videoTrack],
       getTracks: () => [videoTrack],
     } as unknown as MediaStream;
-    class TestMediaStream {
-      constructor(readonly tracks: MediaStreamTrack[]) {}
-      getAudioTracks() {
-        return [audioTrack];
-      }
-      getVideoTracks() {
-        return [videoTrack];
-      }
-      getTracks() {
-        return this.tracks;
-      }
-    }
     const getUserMedia = vi.fn().mockResolvedValueOnce(audio).mockResolvedValueOnce(camera);
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
-    vi.stubGlobal("MediaStream", TestMediaStream);
 
     const originalCreateElement = document.createElement.bind(document);
     vi.spyOn(document, "createElement").mockImplementation((tagName: string) => {
@@ -156,6 +142,9 @@ describe("Google Live Video Talk", () => {
     const transport = createTransport({ onStatus, onVideoStream });
 
     await transport.start();
+    expect(getUserMedia).toHaveBeenCalledOnce();
+    expect(onVideoStream).not.toHaveBeenCalled();
+    await transport.setVideoEnabled(true);
     const ws = FakeGoogleLiveWebSocket.instance;
     if (!ws) {
       throw new Error("missing Google Live WebSocket");
@@ -201,7 +190,7 @@ describe("Google Live Video Talk", () => {
       },
     });
     expect(getUserMedia).toHaveBeenNthCalledWith(2, { video: true });
-    expect(onVideoStream).toHaveBeenCalledWith(expect.any(TestMediaStream));
+    expect(onVideoStream).toHaveBeenCalledWith(camera);
     expect(onStatus).toHaveBeenCalledWith("listening");
 
     const countVideoMessages = () =>
@@ -212,9 +201,9 @@ describe("Google Live Video Talk", () => {
     await vi.advanceTimersByTimeAsync(1);
     expect(countVideoMessages()).toBe(2);
 
-    (videoTrack as { readyState: MediaStreamTrackState }).readyState = "ended";
-    await vi.advanceTimersByTimeAsync(1_000);
-    expect(countVideoMessages()).toBe(2);
+    await transport.setVideoEnabled(false);
+    expect(videoStop).toHaveBeenCalledOnce();
+    expect(audioStop).not.toHaveBeenCalled();
     ws.emitMessage({
       toolCall: {
         functionCalls: [
@@ -231,8 +220,7 @@ describe("Google Live Video Talk", () => {
             name: REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME,
             response: {
               ok: false,
-              cameraStreamActive: false,
-              error: "Camera stream is unavailable",
+              error: "camera is off",
             },
           },
         ],
@@ -248,6 +236,54 @@ describe("Google Live Video Talk", () => {
     expect(videoStop).toHaveBeenCalledOnce();
   });
 
+  it("clears ended camera state and reacquires on the next enable", async () => {
+    const audioTrack = { stop: vi.fn() } as unknown as MediaStreamTrack;
+    const firstVideoTrack = Object.assign(new EventTarget(), {
+      stop: vi.fn(),
+      readyState: "live",
+      enabled: true,
+      muted: false,
+    }) as unknown as MediaStreamTrack;
+    const secondVideoTrack = Object.assign(new EventTarget(), {
+      stop: vi.fn(),
+      readyState: "live",
+      enabled: true,
+      muted: false,
+    }) as unknown as MediaStreamTrack;
+    const audio = {
+      getAudioTracks: () => [audioTrack],
+      getTracks: () => [audioTrack],
+    } as unknown as MediaStream;
+    const firstCamera = {
+      getVideoTracks: () => [firstVideoTrack],
+      getTracks: () => [firstVideoTrack],
+    } as unknown as MediaStream;
+    const secondCamera = {
+      getVideoTracks: () => [secondVideoTrack],
+      getTracks: () => [secondVideoTrack],
+    } as unknown as MediaStream;
+    const getUserMedia = vi
+      .fn()
+      .mockResolvedValueOnce(audio)
+      .mockResolvedValueOnce(firstCamera)
+      .mockResolvedValueOnce(secondCamera);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+    vi.spyOn(HTMLMediaElement.prototype, "play").mockResolvedValue(undefined);
+    const onVideoStream = vi.fn();
+    const transport = createTransport({ onVideoStream });
+
+    await transport.start();
+    await transport.setVideoEnabled(true);
+    firstVideoTrack.dispatchEvent(new Event("ended"));
+
+    expect(onVideoStream).toHaveBeenLastCalledWith(null);
+    await transport.setVideoEnabled(true);
+    expect(getUserMedia).toHaveBeenNthCalledWith(3, { video: true });
+    expect(onVideoStream).toHaveBeenLastCalledWith(secondCamera);
+
+    transport.stop();
+  });
+
   it("releases acquired media when stopped during the camera prompt", async () => {
     const audioStop = vi.fn();
     const videoStop = vi.fn();
@@ -267,14 +303,15 @@ describe("Google Live Video Talk", () => {
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
     const transport = createTransport({});
 
-    const start = transport.start();
-    await Promise.resolve();
+    await transport.start();
+    const enabling = transport.setVideoEnabled(true);
+    await vi.waitFor(() => expect(getUserMedia).toHaveBeenCalledTimes(2));
     transport.stop();
     resolveCamera(camera);
-    await start;
+    await enabling;
 
     expect(audioStop).toHaveBeenCalledOnce();
     expect(videoStop).toHaveBeenCalledOnce();
-    expect(FakeGoogleLiveWebSocket.instance).toBeUndefined();
+    expect(FakeGoogleLiveWebSocket.instance?.readyState).toBe(3);
   });
 });
diff --git a/ui/src/pages/chat/realtime-talk-google-live.ts b/ui/src/pages/chat/realtime-talk-google-live.ts
index 0eff349085e..9e96c1be18e 100644
--- a/ui/src/pages/chat/realtime-talk-google-live.ts
+++ b/ui/src/pages/chat/realtime-talk-google-live.ts
@@ -8,7 +8,7 @@ import {
   RealtimeTalkPcmInputPump,
   RealtimeTalkPcmOutputQueue,
 } from "./realtime-talk-audio.ts";
-import { openRealtimeTalkInput } from "./realtime-talk-input.ts";
+import { openRealtimeTalkCamera, openRealtimeTalkInput } from "./realtime-talk-input.ts";
 import type { RealtimeTalkJsonPcmWebSocketSessionResult } from "./realtime-talk-shared.ts";
 import {
   REALTIME_VOICE_AGENT_CONSULT_TOOL_NAME,
@@ -106,6 +106,7 @@ function buildGoogleLiveUrl(session: RealtimeTalkJsonPcmWebSocketSessionResult):
 export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
   private ws: WebSocket | null = null;
   private media: MediaStream | null = null;
+  private cameraMedia: MediaStream | null = null;
   private captureVideo: HTMLVideoElement | null = null;
   private inputContext: AudioContext | null = null;
   private outputContext: AudioContext | null = null;
@@ -113,6 +114,9 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
   private readonly inputPump = new RealtimeTalkPcmInputPump();
   private closed = false;
   private mediaSetupController: AbortController | null = null;
+  private cameraSetupController: AbortController | null = null;
+  private readonly handleCameraTrackEnded = () => this.releaseCamera();
+  private setupComplete = false;
   private videoFramesActive = false;
   private hasSentVideoFrame = false;
   private videoFrameTimer: ReturnType<typeof globalThis.setTimeout> | null = null;
@@ -143,7 +147,6 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
     let media: MediaStream;
     try {
       media = await openRealtimeTalkInput(this.ctx.inputDeviceId, {
-        video: this.ctx.videoEnabled,
         signal: mediaSetupController.signal,
       });
     } catch (error) {
@@ -161,16 +164,6 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
       return;
     }
     this.media = media;
-    if (this.ctx.videoEnabled) {
-      const captureVideo = document.createElement("video");
-      captureVideo.autoplay = true;
-      captureVideo.muted = true;
-      captureVideo.playsInline = true;
-      captureVideo.srcObject = media;
-      this.captureVideo = captureVideo;
-      this.ctx.callbacks.onVideoStream?.(media);
-      void captureVideo.play().catch(() => undefined);
-    }
     this.inputContext = new AudioContext({ sampleRate: this.session.audio.inputSampleRateHz });
     this.outputContext = new AudioContext({ sampleRate: this.session.audio.outputSampleRateHz });
     if (this.ctx.callbacks.onInputLevel) {
@@ -201,6 +194,57 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
     });
   }
 
+  async setVideoEnabled(enabled: boolean): Promise<void> {
+    if (!enabled) {
+      this.releaseCamera();
+      return;
+    }
+    if (this.closed) {
+      throw new Error("Realtime Talk session is closed");
+    }
+    if (this.cameraMedia?.getVideoTracks().some((track) => track.readyState === "live")) {
+      return;
+    }
+    this.cameraSetupController?.abort();
+    const controller = new AbortController();
+    this.cameraSetupController = controller;
+    let camera: MediaStream;
+    try {
+      camera = await openRealtimeTalkCamera(controller.signal);
+    } catch (error) {
+      if (this.closed || controller.signal.aborted) {
+        return;
+      }
+      throw error;
+    } finally {
+      if (this.cameraSetupController === controller) {
+        this.cameraSetupController = null;
+      }
+    }
+    if (this.closed || controller.signal.aborted) {
+      camera.getTracks().forEach((track) => track.stop());
+      return;
+    }
+    this.cameraMedia = camera;
+    // External track loss clears preview state so the next toggle reacquires the camera.
+    camera
+      .getVideoTracks()
+      .forEach((track) =>
+        track.addEventListener("ended", this.handleCameraTrackEnded, { once: true }),
+      );
+    const captureVideo = document.createElement("video");
+    captureVideo.autoplay = true;
+    captureVideo.muted = true;
+    captureVideo.playsInline = true;
+    captureVideo.srcObject = camera;
+    this.captureVideo = captureVideo;
+    this.ctx.callbacks.onVideoStream?.(camera);
+    void captureVideo.play().catch(() => undefined);
+    if (this.setupComplete) {
+      this.startVideoFrames();
+    }
+  }
+
   stop(): void {
     if (!this.closed) {
       this.emitTalkEvent({ type: "session.closed", final: true });
@@ -208,7 +252,9 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
     this.closed = true;
     this.mediaSetupController?.abort();
     this.mediaSetupController = null;
-    this.stopVideoFrames();
+    this.cameraSetupController?.abort();
+    this.cameraSetupController = null;
+    this.setupComplete = false;
     for (const controller of this.consultAbortControllers) {
       controller.abort();
     }
@@ -219,11 +265,7 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
     this.inputMeter = null;
     this.media?.getTracks().forEach((track) => track.stop());
     this.media = null;
-    if (this.captureVideo) {
-      this.captureVideo.srcObject = null;
-      this.captureVideo = null;
-    }
-    this.ctx.callbacks.onVideoStream?.(null);
+    this.releaseCamera();
     this.stopOutput();
     void this.inputContext?.close();
     this.inputContext = null;
@@ -275,6 +317,7 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
       return;
     }
     if (message.setupComplete) {
+      this.setupComplete = true;
       this.ctx.callbacks.onStatus?.("listening");
       this.emitTalkEvent({ type: "session.ready" });
       this.startVideoFrames();
@@ -395,11 +438,10 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
     }
     if (name === REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME) {
       const active = this.videoFramesActive && this.hasSentVideoFrame && this.isCameraTrackUsable();
-      this.submitToolResult(callId, {
-        ok: active,
-        cameraStreamActive: active,
-        ...(!active ? { error: "Camera stream is unavailable" } : {}),
-      });
+      this.submitToolResult(
+        callId,
+        active ? { ok: true, cameraStreamActive: true } : { ok: false, error: "camera is off" },
+      );
       this.emitTalkEvent({
         type: active ? "tool.result" : "tool.error",
         callId,
@@ -488,7 +530,7 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
   }
 
   private startVideoFrames(): void {
-    if (!this.ctx.videoEnabled || !this.captureVideo || this.videoFramesActive || this.closed) {
+    if (!this.captureVideo || this.videoFramesActive || this.closed) {
       return;
     }
     this.videoFramesActive = true;
@@ -547,17 +589,33 @@ export class GoogleLiveRealtimeTalkTransport implements RealtimeTalkTransport {
   }
 
   private hasLiveCameraTrack(): boolean {
-    return this.media?.getVideoTracks().some((track) => track.readyState === "live") === true;
+    return this.cameraMedia?.getVideoTracks().some((track) => track.readyState === "live") === true;
   }
 
   private isCameraTrackUsable(): boolean {
     return (
-      this.media
+      this.cameraMedia
         ?.getVideoTracks()
         .some((track) => track.readyState === "live" && track.enabled && !track.muted) === true
     );
   }
 
+  private releaseCamera(): void {
+    this.cameraSetupController?.abort();
+    this.cameraSetupController = null;
+    this.stopVideoFrames();
+    this.cameraMedia?.getVideoTracks().forEach((track) => {
+      track.removeEventListener("ended", this.handleCameraTrackEnded);
+      track.stop();
+    });
+    this.cameraMedia = null;
+    if (this.captureVideo) {
+      this.captureVideo.srcObject = null;
+      this.captureVideo = null;
+    }
+    this.ctx.callbacks.onVideoStream?.(null);
+  }
+
   private sendControlSpeechMessage(message: string): void {
     this.stopOutput();
     if (!isGemini31LiveModel(this.session.model)) {
diff --git a/ui/src/pages/chat/realtime-talk-input.test.ts b/ui/src/pages/chat/realtime-talk-input.test.ts
index 935dfe44220..2de499bed59 100644
--- a/ui/src/pages/chat/realtime-talk-input.test.ts
+++ b/ui/src/pages/chat/realtime-talk-input.test.ts
@@ -1,6 +1,10 @@
 // @vitest-environment node
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { discoverRealtimeTalkInputs, openRealtimeTalkInput } from "./realtime-talk-input.ts";
+import {
+  discoverRealtimeTalkInputs,
+  openRealtimeTalkCamera,
+  openRealtimeTalkInput,
+} from "./realtime-talk-input.ts";
 
 function mediaDevice(kind: MediaDeviceKind, deviceId: string, label: string): MediaDeviceInfo {
   return { kind, deviceId, label, groupId: "", toJSON: () => ({}) } as MediaDeviceInfo;
@@ -115,23 +119,14 @@ describe("realtime Talk microphone inputs", () => {
     });
   });
 
-  it("acquires camera separately so video errors do not mask microphone errors", async () => {
-    const audioTrack = {} as MediaStreamTrack;
-    const videoTrack = {} as MediaStreamTrack;
-    const audio = {
-      getAudioTracks: () => [audioTrack],
-      getTracks: () => [audioTrack],
-    } as unknown as MediaStream;
-    const camera = { getVideoTracks: () => [videoTrack] } as unknown as MediaStream;
-    class TestMediaStream {
-      constructor(readonly tracks: MediaStreamTrack[]) {}
-    }
+  it("acquires camera separately so camera errors cannot stop microphone input", async () => {
+    const audio = { getTracks: () => [] } as unknown as MediaStream;
+    const camera = { getTracks: () => [] } as unknown as MediaStream;
     const getUserMedia = vi.fn().mockResolvedValueOnce(audio).mockResolvedValueOnce(camera);
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
-    vi.stubGlobal("MediaStream", TestMediaStream);
 
-    const combined = await openRealtimeTalkInput("usb-mic", { video: true });
-    expect(combined).toBeInstanceOf(TestMediaStream);
+    await expect(openRealtimeTalkInput("usb-mic")).resolves.toBe(audio);
+    await expect(openRealtimeTalkCamera()).resolves.toBe(camera);
     expect(getUserMedia).toHaveBeenNthCalledWith(1, {
       audio: {
         autoGainControl: true,
@@ -141,65 +136,38 @@ describe("realtime Talk microphone inputs", () => {
       },
     });
     expect(getUserMedia).toHaveBeenNthCalledWith(2, { video: true });
-    expect((combined as unknown as TestMediaStream).tracks).toEqual([audioTrack, videoTrack]);
   });
 
   it("reports camera permission denial with actionable guidance", async () => {
-    const stop = vi.fn();
-    const audio = { getTracks: () => [{ stop }] } as unknown as MediaStream;
-    const getUserMedia = vi
-      .fn()
-      .mockResolvedValueOnce(audio)
-      .mockRejectedValueOnce(new DOMException("denied", "NotAllowedError"));
+    const getUserMedia = vi.fn().mockRejectedValue(new DOMException("denied", "NotAllowedError"));
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
 
-    await expect(openRealtimeTalkInput(undefined, { video: true })).rejects.toThrow(
-      "Camera access is blocked",
-    );
-    expect(stop).toHaveBeenCalledOnce();
+    await expect(openRealtimeTalkCamera()).rejects.toThrow("Camera access is blocked");
   });
 
-  it("reports a missing camera when an exact microphone is selected", async () => {
-    const stop = vi.fn();
-    const audio = { getTracks: () => [{ stop }] } as unknown as MediaStream;
-    const getUserMedia = vi
-      .fn()
-      .mockResolvedValueOnce(audio)
-      .mockRejectedValueOnce(new DOMException("missing", "NotFoundError"));
+  it("reports a missing camera", async () => {
+    const getUserMedia = vi.fn().mockRejectedValue(new DOMException("missing", "NotFoundError"));
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
 
-    await expect(openRealtimeTalkInput("usb-mic", { video: true })).rejects.toThrow(
-      "No camera was found",
-    );
-    expect(stop).toHaveBeenCalledOnce();
+    await expect(openRealtimeTalkCamera()).rejects.toThrow("No camera was found");
   });
 
-  it("releases partial media when video acquisition is cancelled", async () => {
-    const audioStop = vi.fn();
+  it("releases camera media when acquisition is cancelled", async () => {
     const videoStop = vi.fn();
-    const audio = {
-      getAudioTracks: () => [{} as MediaStreamTrack],
-      getTracks: () => [{ stop: audioStop }],
-    } as unknown as MediaStream;
     const camera = {
-      getVideoTracks: () => [{} as MediaStreamTrack],
       getTracks: () => [{ stop: videoStop }],
     } as unknown as MediaStream;
     let resolveCamera: (stream: MediaStream) => void = () => undefined;
     const cameraPending = new Promise<MediaStream>((resolve) => {
       resolveCamera = resolve;
     });
-    const getUserMedia = vi.fn().mockResolvedValueOnce(audio).mockReturnValueOnce(cameraPending);
+    const getUserMedia = vi.fn().mockReturnValue(cameraPending);
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
     const controller = new AbortController();
 
-    const opening = openRealtimeTalkInput(undefined, {
-      video: true,
-      signal: controller.signal,
-    });
-    await vi.waitFor(() => expect(getUserMedia).toHaveBeenCalledTimes(2));
+    const opening = openRealtimeTalkCamera(controller.signal);
+    await vi.waitFor(() => expect(getUserMedia).toHaveBeenCalledOnce());
     controller.abort();
-    expect(audioStop).toHaveBeenCalledOnce();
     resolveCamera(camera);
 
     await expect(opening).rejects.toMatchObject({ name: "AbortError" });
diff --git a/ui/src/pages/chat/realtime-talk-input.ts b/ui/src/pages/chat/realtime-talk-input.ts
index 8e95e7e4fe4..3186ef9733d 100644
--- a/ui/src/pages/chat/realtime-talk-input.ts
+++ b/ui/src/pages/chat/realtime-talk-input.ts
@@ -105,7 +105,7 @@ function realtimeTalkAbortReason(signal: AbortSignal): Error {
 
 export async function openRealtimeTalkInput(
   inputDeviceId: string | undefined,
-  options: { video?: boolean; signal?: AbortSignal } = {},
+  options: { signal?: AbortSignal } = {},
 ): Promise<MediaStream> {
   const devices = globalThis.navigator?.mediaDevices;
   if (!devices?.getUserMedia) {
@@ -130,31 +130,25 @@ export async function openRealtimeTalkInput(
     audio.getTracks().forEach((track) => track.stop());
     throw realtimeTalkAbortReason(options.signal);
   }
-  if (!options.video) {
-    return audio;
-  }
+  return audio;
+}
 
-  let audioStopped = false;
-  const stopAudio = () => {
-    if (audioStopped) {
-      return;
-    }
-    audioStopped = true;
-    audio.getTracks().forEach((track) => track.stop());
-  };
-  options.signal?.addEventListener("abort", stopAudio, { once: true });
-  let camera: MediaStream | undefined;
+export async function openRealtimeTalkCamera(signal?: AbortSignal): Promise<MediaStream> {
+  const devices = globalThis.navigator?.mediaDevices;
+  if (!devices?.getUserMedia) {
+    throw new Error(t("chat.composer.cameraAccessFailed"));
+  }
+  let camera: MediaStream;
   try {
     camera = await devices.getUserMedia({ video: true });
-    if (options.signal?.aborted) {
-      throw realtimeTalkAbortReason(options.signal);
+    if (signal?.aborted) {
+      camera.getTracks().forEach((track) => track.stop());
+      throw realtimeTalkAbortReason(signal);
     }
-    return new MediaStream([...audio.getAudioTracks(), ...camera.getVideoTracks()]);
+    return camera;
   } catch (error) {
-    camera?.getTracks().forEach((track) => track.stop());
-    stopAudio();
-    if (options.signal?.aborted) {
-      throw realtimeTalkAbortReason(options.signal);
+    if (signal?.aborted) {
+      throw realtimeTalkAbortReason(signal);
     }
     if (error instanceof DOMException && error.name === "NotAllowedError") {
       throw new Error(t("chat.composer.cameraPermissionBlocked"), { cause: error });
@@ -165,8 +159,6 @@ export async function openRealtimeTalkInput(
     if (error instanceof DOMException && error.name === "NotReadableError") {
       throw new Error(t("chat.composer.cameraBusy"), { cause: error });
     }
-    throw error;
-  } finally {
-    options.signal?.removeEventListener("abort", stopAudio);
+    throw new Error(t("chat.composer.cameraAccessFailed"), { cause: error });
   }
 }
diff --git a/ui/src/pages/chat/realtime-talk-shared.ts b/ui/src/pages/chat/realtime-talk-shared.ts
index f202f3b8d97..41cb390827c 100644
--- a/ui/src/pages/chat/realtime-talk-shared.ts
+++ b/ui/src/pages/chat/realtime-talk-shared.ts
@@ -16,6 +16,7 @@ export type RealtimeTalkEvent = TalkEvent;
 
 export type RealtimeTalkCallbacks = {
   onStatus?: (status: RealtimeTalkStatus, detail?: string) => void;
+  onVideoCapability?: (capable: boolean) => void;
   onInputLevel?: (level: number) => void;
   onTranscript?: (entry: { role: "user" | "assistant"; text: string; final: boolean }) => void;
   onTalkEvent?: (event: RealtimeTalkEvent) => void;
@@ -101,6 +102,7 @@ export type RealtimeTalkSessionResult =
 export type RealtimeTalkTransport = {
   start(): Promise<void>;
   stop(): void;
+  setVideoEnabled?: (enabled: boolean) => Promise<void>;
 };
 
 export type RealtimeTalkTransportContext = {
@@ -108,7 +110,6 @@ export type RealtimeTalkTransportContext = {
   sessionKey: string;
   callbacks: RealtimeTalkCallbacks;
   inputDeviceId?: string;
-  videoEnabled?: boolean;
   consultThinkingLevel?: string;
   consultFastMode?: boolean;
 };
diff --git a/ui/src/pages/chat/realtime-talk-webrtc-video.test.ts b/ui/src/pages/chat/realtime-talk-webrtc-video.test.ts
index ea2aafdc163..aee6e0fd60c 100644
--- a/ui/src/pages/chat/realtime-talk-webrtc-video.test.ts
+++ b/ui/src/pages/chat/realtime-talk-webrtc-video.test.ts
@@ -67,33 +67,24 @@ describe("OpenAI Realtime Video Talk", () => {
     vi.restoreAllMocks();
   });
 
-  it("keeps camera local, bounds the frame event, and releases both tracks", async () => {
+  it("starts audio-only, toggles local camera, and reports camera-off tool calls", async () => {
     const audioStop = vi.fn();
     const videoStop = vi.fn();
     const audioTrack = { stop: audioStop } as unknown as MediaStreamTrack;
-    const videoTrack = { stop: videoStop } as unknown as MediaStreamTrack;
+    const videoTrack = Object.assign(new EventTarget(), {
+      stop: videoStop,
+      readyState: "live",
+    }) as unknown as MediaStreamTrack;
     const audio = {
       getAudioTracks: () => [audioTrack],
       getTracks: () => [audioTrack],
     } as unknown as MediaStream;
     const camera = {
       getVideoTracks: () => [videoTrack],
+      getTracks: () => [videoTrack],
     } as unknown as MediaStream;
-    class TestMediaStream {
-      constructor(readonly tracks: MediaStreamTrack[]) {}
-      getAudioTracks() {
-        return [audioTrack];
-      }
-      getVideoTracks() {
-        return [videoTrack];
-      }
-      getTracks() {
-        return this.tracks;
-      }
-    }
     const getUserMedia = vi.fn().mockResolvedValueOnce(audio).mockResolvedValueOnce(camera);
     vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
-    vi.stubGlobal("MediaStream", TestMediaStream);
 
     const originalCreateElement = document.createElement.bind(document);
     let videoReadyState: number = HTMLMediaElement.HAVE_METADATA;
@@ -129,13 +120,17 @@ describe("OpenAI Realtime Video Talk", () => {
         client: {} as never,
         sessionKey: "main",
         callbacks: { onStatus, onTalkEvent, onVideoStream },
-        videoEnabled: true,
       },
     );
 
     await transport.start();
     const peer = FakePeerConnection.instance;
-    const combined = onVideoStream.mock.calls[0]?.[0] as MediaStream;
+    expect(getUserMedia).toHaveBeenCalledOnce();
+    expect(peer?.addTrack).toHaveBeenCalledWith(audioTrack, audio);
+    expect(onVideoStream).not.toHaveBeenCalled();
+
+    await transport.setVideoEnabled(true);
+    expect(onVideoStream).toHaveBeenCalledWith(camera);
     peer?.channel.dispatchEvent(
       new MessageEvent("message", {
         data: JSON.stringify({
@@ -184,24 +179,129 @@ describe("OpenAI Realtime Video Talk", () => {
     });
     expect(getUserMedia).toHaveBeenNthCalledWith(2, { video: true });
     expect(peer?.addTrack).toHaveBeenCalledOnce();
-    expect(peer?.addTrack).toHaveBeenCalledWith(audioTrack, combined);
-    expect(combined).toBeInstanceOf(TestMediaStream);
-    expect(onVideoStream).toHaveBeenCalledWith(combined);
     expect(drawImage).toHaveBeenCalledTimes(2);
     expect(onTalkEvent.mock.calls.map(([event]) => event.type)).toContain("tool.result");
     for (const [payload] of peer?.channel.send.mock.calls ?? []) {
       expect(new TextEncoder().encode(String(payload)).length).toBeLessThanOrEqual(512);
     }
 
-    peer!.connectionState = "failed";
-    peer!.dispatchEvent(new Event("connectionstatechange"));
-    expect(onStatus).toHaveBeenLastCalledWith("error", "Realtime connection closed");
+    await transport.setVideoEnabled(false);
     expect(onVideoStream).toHaveBeenLastCalledWith(null);
-    expect(audioStop).toHaveBeenCalledOnce();
     expect(videoStop).toHaveBeenCalledOnce();
+    expect(audioStop).not.toHaveBeenCalled();
+
+    peer?.channel.dispatchEvent(
+      new MessageEvent("message", {
+        data: JSON.stringify({
+          type: "response.function_call_arguments.done",
+          item_id: "item-camera-off",
+          call_id: "call-camera-off",
+          name: REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME,
+          arguments: "{}",
+        }),
+      }),
+    );
+    await vi.waitFor(() =>
+      expect(sentRealtimeEvents()).toContainEqual({
+        type: "conversation.item.create",
+        item: {
+          type: "function_call_output",
+          call_id: "call-camera-off",
+          output: JSON.stringify({ ok: false, error: "camera is off" }),
+        },
+      }),
+    );
+    expect(onStatus).not.toHaveBeenCalledWith("error", expect.anything());
+
+    transport.stop();
+    expect(audioStop).toHaveBeenCalledOnce();
   });
 
-  it("releases the microphone when stopped during the camera prompt", async () => {
+  it("clears ended camera state and reacquires on the next enable", async () => {
+    const audioTrack = { stop: vi.fn() } as unknown as MediaStreamTrack;
+    const firstVideoTrack = Object.assign(new EventTarget(), {
+      stop: vi.fn(),
+      readyState: "live",
+    }) as unknown as MediaStreamTrack;
+    const secondVideoTrack = Object.assign(new EventTarget(), {
+      stop: vi.fn(),
+      readyState: "live",
+    }) as unknown as MediaStreamTrack;
+    const audio = {
+      getAudioTracks: () => [audioTrack],
+      getTracks: () => [audioTrack],
+    } as unknown as MediaStream;
+    const firstCamera = {
+      getVideoTracks: () => [firstVideoTrack],
+      getTracks: () => [firstVideoTrack],
+    } as unknown as MediaStream;
+    const secondCamera = {
+      getVideoTracks: () => [secondVideoTrack],
+      getTracks: () => [secondVideoTrack],
+    } as unknown as MediaStream;
+    const getUserMedia = vi
+      .fn()
+      .mockResolvedValueOnce(audio)
+      .mockResolvedValueOnce(firstCamera)
+      .mockResolvedValueOnce(secondCamera);
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+    vi.spyOn(HTMLMediaElement.prototype, "play").mockResolvedValue(undefined);
+    const onVideoStream = vi.fn();
+    const transport = new WebRtcSdpRealtimeTalkTransport(
+      { provider: "openai", transport: "webrtc", clientSecret: "test-client-secret" },
+      {
+        client: {} as never,
+        sessionKey: "main",
+        callbacks: { onVideoStream },
+      },
+    );
+
+    await transport.start();
+    await transport.setVideoEnabled(true);
+    firstVideoTrack.dispatchEvent(new Event("ended"));
+
+    expect(onVideoStream).toHaveBeenLastCalledWith(null);
+    await transport.setVideoEnabled(true);
+    expect(getUserMedia).toHaveBeenNthCalledWith(3, { video: true });
+    expect(onVideoStream).toHaveBeenLastCalledWith(secondCamera);
+
+    transport.stop();
+  });
+
+  it("keeps voice alive when lazy camera acquisition fails", async () => {
+    const audioStop = vi.fn();
+    const audioTrack = { stop: audioStop } as unknown as MediaStreamTrack;
+    const audio = {
+      getAudioTracks: () => [audioTrack],
+      getTracks: () => [audioTrack],
+    } as unknown as MediaStream;
+    const getUserMedia = vi
+      .fn()
+      .mockResolvedValueOnce(audio)
+      .mockRejectedValueOnce(new DOMException("denied", "NotAllowedError"));
+    vi.stubGlobal("navigator", { mediaDevices: { getUserMedia } });
+    const onStatus = vi.fn();
+    const onVideoStream = vi.fn();
+    const transport = new WebRtcSdpRealtimeTalkTransport(
+      { provider: "openai", transport: "webrtc", clientSecret: "test-client-secret" },
+      {
+        client: {} as never,
+        sessionKey: "main",
+        callbacks: { onStatus, onVideoStream },
+      },
+    );
+
+    await transport.start();
+    await expect(transport.setVideoEnabled(true)).rejects.toThrow("Camera access is blocked");
+
+    expect(audioStop).not.toHaveBeenCalled();
+    expect(onVideoStream).not.toHaveBeenCalled();
+    expect(onStatus).not.toHaveBeenCalledWith("error", expect.anything());
+    transport.stop();
+    expect(audioStop).toHaveBeenCalledOnce();
+  });
+
+  it("releases acquired media when stopped during the camera prompt", async () => {
     const audioStop = vi.fn();
     const videoStop = vi.fn();
     const audio = {
@@ -228,17 +328,17 @@ describe("OpenAI Realtime Video Talk", () => {
         client: {} as never,
         sessionKey: "main",
         callbacks: {},
-        videoEnabled: true,
       },
     );
 
-    const starting = transport.start();
+    await transport.start();
+    const enabling = transport.setVideoEnabled(true);
     await vi.waitFor(() => expect(getUserMedia).toHaveBeenCalledTimes(2));
     transport.stop();
     expect(audioStop).toHaveBeenCalledOnce();
     resolveCamera(camera);
 
-    await expect(starting).resolves.toBeUndefined();
+    await expect(enabling).resolves.toBeUndefined();
     expect(videoStop).toHaveBeenCalledOnce();
   });
 });
diff --git a/ui/src/pages/chat/realtime-talk-webrtc.test.ts b/ui/src/pages/chat/realtime-talk-webrtc.test.ts
index 1cb4f67d40a..2d8eb51532b 100644
--- a/ui/src/pages/chat/realtime-talk-webrtc.test.ts
+++ b/ui/src/pages/chat/realtime-talk-webrtc.test.ts
@@ -84,7 +84,6 @@ function createOpenAiTransport(
   client: Record<string, unknown> = {},
   callbacks: Record<string, unknown> = {},
   inputDeviceId?: string,
-  videoEnabled?: boolean,
 ): WebRtcSdpRealtimeTalkTransport {
   return new WebRtcSdpRealtimeTalkTransport(
     {
@@ -97,7 +96,6 @@ function createOpenAiTransport(
       sessionKey: "main",
       callbacks: callbacks as never,
       inputDeviceId,
-      videoEnabled,
     },
   );
 }
diff --git a/ui/src/pages/chat/realtime-talk-webrtc.ts b/ui/src/pages/chat/realtime-talk-webrtc.ts
index a79fd949db3..40c4c2ff355 100644
--- a/ui/src/pages/chat/realtime-talk-webrtc.ts
+++ b/ui/src/pages/chat/realtime-talk-webrtc.ts
@@ -1,7 +1,7 @@
 // Control UI chat module implements realtime talk webrtc behavior.
 import { REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME } from "../../../../src/talk/describe-view-tool.js";
 import { RealtimeTalkMediaStreamMeter } from "./realtime-talk-audio.ts";
-import { openRealtimeTalkInput } from "./realtime-talk-input.ts";
+import { openRealtimeTalkCamera, openRealtimeTalkInput } from "./realtime-talk-input.ts";
 import type { RealtimeTalkWebRtcSdpSessionResult } from "./realtime-talk-shared.ts";
 import {
   REALTIME_VOICE_AGENT_CONSULT_TOOL_NAME,
@@ -53,6 +53,7 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
   private peer: RTCPeerConnection | null = null;
   private channel: RTCDataChannel | null = null;
   private media: MediaStream | null = null;
+  private cameraMedia: MediaStream | null = null;
   private audio: HTMLAudioElement | null = null;
   private captureVideo: HTMLVideoElement | null = null;
   private inputMeter: RealtimeTalkMediaStreamMeter | null = null;
@@ -63,6 +64,8 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
   private toolBuffers = new Map<string, ToolBuffer>();
   private pendingOfferRequest: PendingOfferRequest | null = null;
   private mediaSetupController: AbortController | null = null;
+  private cameraSetupController: AbortController | null = null;
+  private readonly handleCameraTrackEnded = () => this.releaseCamera();
   private readonly consultAbortControllers = new Set<AbortController>();
   private readonly emitTalkEvent: ReturnType<typeof createRealtimeTalkEventEmitter>;
 
@@ -98,7 +101,6 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
       media = await this.awaitSetupStep(
         peer,
         openRealtimeTalkInput(this.ctx.inputDeviceId, {
-          video: this.ctx.videoEnabled,
           signal: mediaSetupController.signal,
         }),
       );
@@ -115,16 +117,6 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
       return;
     }
     this.media = media;
-    if (this.ctx.videoEnabled) {
-      const captureVideo = document.createElement("video");
-      captureVideo.autoplay = true;
-      captureVideo.muted = true;
-      captureVideo.playsInline = true;
-      captureVideo.srcObject = media;
-      this.captureVideo = captureVideo;
-      this.ctx.callbacks.onVideoStream?.(media);
-      void captureVideo.play().catch(() => undefined);
-    }
     if (this.ctx.callbacks.onInputLevel) {
       this.inputMeter = new RealtimeTalkMediaStreamMeter(this.ctx.callbacks.onInputLevel);
       this.inputMeter.start(media);
@@ -184,6 +176,54 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
     );
   }
 
+  async setVideoEnabled(enabled: boolean): Promise<void> {
+    if (!enabled) {
+      this.releaseCamera();
+      return;
+    }
+    if (this.closed) {
+      throw new Error("Realtime Talk session is closed");
+    }
+    if (this.cameraMedia?.getVideoTracks().some((track) => track.readyState === "live")) {
+      return;
+    }
+    this.cameraSetupController?.abort();
+    const controller = new AbortController();
+    this.cameraSetupController = controller;
+    let camera: MediaStream;
+    try {
+      camera = await openRealtimeTalkCamera(controller.signal);
+    } catch (error) {
+      if (this.closed || controller.signal.aborted) {
+        return;
+      }
+      throw error;
+    } finally {
+      if (this.cameraSetupController === controller) {
+        this.cameraSetupController = null;
+      }
+    }
+    if (this.closed || controller.signal.aborted) {
+      camera.getTracks().forEach((track) => track.stop());
+      return;
+    }
+    this.cameraMedia = camera;
+    // External track loss clears preview state so the next toggle reacquires the camera.
+    camera
+      .getVideoTracks()
+      .forEach((track) =>
+        track.addEventListener("ended", this.handleCameraTrackEnded, { once: true }),
+      );
+    const captureVideo = document.createElement("video");
+    captureVideo.autoplay = true;
+    captureVideo.muted = true;
+    captureVideo.playsInline = true;
+    captureVideo.srcObject = camera;
+    this.captureVideo = captureVideo;
+    this.ctx.callbacks.onVideoStream?.(camera);
+    void captureVideo.play().catch(() => undefined);
+  }
+
   private async readOfferAnswer(
     peer: RTCPeerConnection,
     offer: RTCSessionDescriptionInit,
@@ -286,6 +326,8 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
     this.closed = true;
     this.mediaSetupController?.abort();
     this.mediaSetupController = null;
+    this.cameraSetupController?.abort();
+    this.cameraSetupController = null;
     this.abortOfferRequest();
     this.channel?.close();
     this.channel = null;
@@ -293,11 +335,7 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
     this.peer = null;
     this.media?.getTracks().forEach((track) => track.stop());
     this.media = null;
-    if (this.captureVideo) {
-      this.captureVideo.srcObject = null;
-      this.captureVideo = null;
-    }
-    this.ctx.callbacks.onVideoStream?.(null);
+    this.releaseCamera();
     this.inputMeter?.stop();
     this.inputMeter = null;
     this.audio?.remove();
@@ -526,6 +564,17 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
       itemId,
       payload: { name: REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME },
     });
+    if (!this.cameraMedia?.getVideoTracks().some((track) => track.readyState === "live")) {
+      this.submitToolResult(callId, { ok: false, error: "camera is off" });
+      this.emitTalkEvent({
+        type: "tool.error",
+        callId,
+        itemId,
+        final: true,
+        payload: { name: REALTIME_VOICE_DESCRIBE_VIEW_TOOL_NAME, message: "camera is off" },
+      });
+      return;
+    }
     try {
       const frame = await captureRealtimeTalkVideoFrame(
         this.captureVideo,
@@ -566,6 +615,21 @@ export class WebRtcSdpRealtimeTalkTransport implements RealtimeTalkTransport {
     this.requestResponseCreate();
   }
 
+  private releaseCamera(): void {
+    this.cameraSetupController?.abort();
+    this.cameraSetupController = null;
+    this.cameraMedia?.getVideoTracks().forEach((track) => {
+      track.removeEventListener("ended", this.handleCameraTrackEnded);
+      track.stop();
+    });
+    this.cameraMedia = null;
+    if (this.captureVideo) {
+      this.captureVideo.srcObject = null;
+      this.captureVideo = null;
+    }
+    this.ctx.callbacks.onVideoStream?.(null);
+  }
+
   private reportToolResultSubmissionError(error: unknown): void {
     if (this.closed) {
       return;
diff --git a/ui/src/pages/chat/realtime-talk.test.ts b/ui/src/pages/chat/realtime-talk.test.ts
index c936cef3bc4..108aaf6819b 100644
--- a/ui/src/pages/chat/realtime-talk.test.ts
+++ b/ui/src/pages/chat/realtime-talk.test.ts
@@ -8,6 +8,8 @@ const {
   relayStop,
   webRtcStart,
   webRtcStop,
+  googleSetVideoEnabled,
+  webRtcSetVideoEnabled,
   googleCtor,
   relayCtor,
   webRtcCtor,
@@ -18,14 +20,16 @@ const {
   relayStop: vi.fn(),
   webRtcStart: vi.fn(async () => undefined),
   webRtcStop: vi.fn(),
+  googleSetVideoEnabled: vi.fn(async () => undefined),
+  webRtcSetVideoEnabled: vi.fn(async () => undefined),
   googleCtor: vi.fn(function () {
-    return { start: googleStart, stop: googleStop };
+    return { start: googleStart, stop: googleStop, setVideoEnabled: googleSetVideoEnabled };
   }),
   relayCtor: vi.fn(function () {
     return { start: relayStart, stop: relayStop };
   }),
   webRtcCtor: vi.fn(function () {
-    return { start: webRtcStart, stop: webRtcStop };
+    return { start: webRtcStart, stop: webRtcStop, setVideoEnabled: webRtcSetVideoEnabled };
   }),
 }));
 
@@ -51,6 +55,8 @@ describe("RealtimeTalkSession", () => {
     relayStop.mockClear();
     webRtcStart.mockClear();
     webRtcStop.mockClear();
+    googleSetVideoEnabled.mockClear();
+    webRtcSetVideoEnabled.mockClear();
     googleCtor.mockClear();
     relayCtor.mockClear();
     webRtcCtor.mockClear();
@@ -199,6 +205,62 @@ describe("RealtimeTalkSession", () => {
     expect(relayStart).toHaveBeenCalledTimes(1);
   });
 
+  it("strips browser capabilities and hides camera when falling back to Gateway relay", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "talk.catalog") {
+        return {
+          realtime: {
+            activeProvider: "openai",
+            providers: [{ id: "openai", label: "OpenAI", supportsVideoFrames: true }],
+          },
+        };
+      }
+      if (method === "talk.client.create") {
+        throw new Error("browser session unavailable");
+      }
+      if (method === "talk.session.create") {
+        return {
+          provider: "openai",
+          transport: "gateway-relay",
+          relaySessionId: "relay-1",
+          audio: {
+            inputEncoding: "pcm16",
+            inputSampleRateHz: 24000,
+            outputEncoding: "pcm16",
+            outputSampleRateHz: 24000,
+          },
+        };
+      }
+      throw new Error(`Unexpected request: ${method}`);
+    });
+    const onVideoCapability = vi.fn();
+    const session = new RealtimeTalkSession(
+      { request } as never,
+      "main",
+      { onVideoCapability },
+      { provider: "openai", transport: "gateway-relay" },
+    );
+
+    await session.start();
+
+    expect(request).toHaveBeenNthCalledWith(2, "talk.client.create", {
+      sessionKey: "main",
+      provider: "openai",
+      transport: "gateway-relay",
+      capabilities: ["camera-frame"],
+    });
+    expect(request).toHaveBeenNthCalledWith(3, "talk.session.create", {
+      sessionKey: "main",
+      provider: "openai",
+      transport: "gateway-relay",
+      mode: "realtime",
+      brain: "agent-consult",
+    });
+    expect(onVideoCapability).toHaveBeenCalledOnce();
+    expect(onVideoCapability).toHaveBeenCalledWith(false);
+    expect(relayCtor).toHaveBeenCalledTimes(1);
+  });
+
   it("starts the WebRTC transport for canonical WebRTC sessions", async () => {
     const request = vi.fn(async () => ({
       provider: "openai",
@@ -259,6 +321,71 @@ describe("RealtimeTalkSession", () => {
     );
   });
 
+  it("requests camera-frame for the active video-capable provider without enabling camera", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "talk.catalog") {
+        return {
+          realtime: {
+            activeProvider: "openai",
+            providers: [{ id: "openai", label: "OpenAI", supportsVideoFrames: true }],
+          },
+        };
+      }
+      return {
+        provider: "openai",
+        transport: "webrtc",
+        clientSecret: "secret",
+      };
+    });
+    const onVideoCapability = vi.fn();
+    const session = new RealtimeTalkSession({ request } as never, "main", {
+      onVideoCapability,
+    });
+
+    await session.start();
+
+    expect(request).toHaveBeenNthCalledWith(1, "talk.catalog", {});
+    expect(request).toHaveBeenNthCalledWith(2, "talk.client.create", {
+      sessionKey: "main",
+      capabilities: ["camera-frame"],
+    });
+    expect(onVideoCapability).toHaveBeenCalledWith(true);
+    expect(webRtcCtor).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.not.objectContaining({ videoEnabled: expect.anything() }),
+    );
+
+    await session.setVideoEnabled(true);
+    expect(webRtcSetVideoEnabled).toHaveBeenCalledWith(true);
+  });
+
+  it("does not request camera-frame for a provider without video-frame support", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "talk.catalog") {
+        return {
+          realtime: {
+            activeProvider: "openai",
+            providers: [{ id: "openai", label: "OpenAI", supportsVideoFrames: false }],
+          },
+        };
+      }
+      return {
+        provider: "openai",
+        transport: "webrtc",
+        clientSecret: "secret",
+      };
+    });
+    const onVideoCapability = vi.fn();
+    const session = new RealtimeTalkSession({ request } as never, "main", {
+      onVideoCapability,
+    });
+
+    await session.start();
+
+    expect(request).toHaveBeenNthCalledWith(2, "talk.client.create", { sessionKey: "main" });
+    expect(onVideoCapability).toHaveBeenCalledWith(false);
+  });
+
   it("does not fall back to Gateway relay when config selects a client transport", async () => {
     const clientError = new Error("browser session unavailable");
     const request = vi.fn(async (method: string) => {
diff --git a/ui/src/pages/chat/realtime-talk.ts b/ui/src/pages/chat/realtime-talk.ts
index 1cde137f07d..d897071950a 100644
--- a/ui/src/pages/chat/realtime-talk.ts
+++ b/ui/src/pages/chat/realtime-talk.ts
@@ -1,4 +1,5 @@
 // Control UI chat module implements realtime talk behavior.
+import type { TalkCatalogResult } from "@openclaw/gateway-protocol";
 import { normalizeTalkTransport } from "../../../../src/talk/talk-session-controller.js";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
 import { GatewayRelayRealtimeTalkTransport } from "./realtime-talk-gateway-relay.ts";
@@ -26,12 +27,10 @@ type RealtimeTalkLaunchOptions = {
   silenceDurationMs?: number;
   prefixPaddingMs?: number;
   reasoningEffort?: string;
-  capabilities?: Array<"camera-frame">;
 };
 
 type RealtimeTalkLocalOptions = {
   inputDeviceId?: string;
-  videoEnabled?: boolean;
 };
 
 type RealtimeTalkLaunchTransport = NonNullable<RealtimeTalkLaunchOptions["transport"]>;
@@ -114,7 +113,13 @@ export class RealtimeTalkSession {
   async start(): Promise<void> {
     this.closed = false;
     this.callbacks.onStatus?.("connecting");
-    const session = await this.createSession();
+    const providerVideoCapable = await this.resolveVideoCapability();
+    if (this.closed) {
+      return;
+    }
+    const session = await this.createSession(
+      providerVideoCapable ? { ...this.options, capabilities: ["camera-frame"] } : this.options,
+    );
     if (this.closed) {
       return;
     }
@@ -123,24 +128,49 @@ export class RealtimeTalkSession {
       sessionKey: this.sessionKey,
       callbacks: this.callbacks,
       inputDeviceId: this.localOptions.inputDeviceId,
-      videoEnabled: this.localOptions.videoEnabled,
       consultThinkingLevel: session.consultThinkingLevel,
       consultFastMode: session.consultFastMode,
     });
+    this.callbacks.onVideoCapability?.(
+      providerVideoCapable && typeof this.transport.setVideoEnabled === "function",
+    );
     await this.transport.start();
   }
 
-  private async createSession(): Promise<RealtimeTalkSessionResult> {
+  private async resolveVideoCapability(): Promise<boolean> {
+    if (!this.callbacks.onVideoCapability) {
+      return false;
+    }
+    try {
+      const catalog = await this.client.request<TalkCatalogResult>("talk.catalog", {});
+      const selectedProvider = this.options.provider ?? catalog.realtime.activeProvider;
+      if (!selectedProvider) {
+        return false;
+      }
+      return (
+        catalog.realtime.providers.find(
+          (provider) =>
+            provider.id === selectedProvider || provider.aliases?.includes(selectedProvider),
+        )?.supportsVideoFrames === true
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  private async createSession(
+    options: RealtimeTalkLaunchOptions & { capabilities?: Array<"camera-frame"> },
+  ): Promise<RealtimeTalkSessionResult> {
     try {
       return await this.client.request<RealtimeTalkSessionResult>(
         "talk.client.create",
         compactLaunchParams({
           sessionKey: this.sessionKey,
-          ...this.options,
+          ...options,
         }),
       );
     } catch (error) {
-      let transport = this.options.transport;
+      let transport = options.transport;
       if (!transport) {
         let result: RealtimeTalkConfigResult;
         try {
@@ -162,12 +192,14 @@ export class RealtimeTalkSession {
       if (transport && transport !== "gateway-relay") {
         throw error;
       }
+      const gatewayOptions = { ...options };
+      delete gatewayOptions.capabilities;
       try {
         return await this.client.request<RealtimeTalkSessionResult>(
           "talk.session.create",
           compactLaunchParams({
             sessionKey: this.sessionKey,
-            ...this.options,
+            ...gatewayOptions,
             mode: "realtime",
             transport: transport ?? "gateway-relay",
             brain: "agent-consult",
@@ -185,4 +217,11 @@ export class RealtimeTalkSession {
     this.transport?.stop();
     this.transport = null;
   }
+
+  async setVideoEnabled(enabled: boolean): Promise<void> {
+    if (this.closed || !this.transport?.setVideoEnabled) {
+      throw new Error("Camera is unavailable for this realtime session");
+    }
+    await this.transport.setVideoEnabled(enabled);
+  }
 }

From 2e21d53c84ec88433dac587bb97f2796e63b20ca Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 18:22:30 +0800
Subject: [PATCH 28/76] fix(plugins): bound plugin manifest metadata file reads
 (#110036)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(plugins): bound plugin manifest metadata file reads

* fix(plugins): use correct Error type check in oversized manifest catch

readRegularFileSync throws a plain Error (not RangeError) when the file
exceeds maxBytes. Change the catch-block type check from RangeError to
Error to properly detect oversized plugin manifests and emit the
subsystem warning.

* test(plugins): exercise valid oversized manifests

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/plugins/manifest-metadata-scan.test.ts | 51 ++++++++++++++++++++++
 src/plugins/manifest-metadata-scan.ts      | 21 ++++++++-
 2 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/src/plugins/manifest-metadata-scan.test.ts b/src/plugins/manifest-metadata-scan.test.ts
index 8d2de7b8d39..fe5f883e1f2 100644
--- a/src/plugins/manifest-metadata-scan.test.ts
+++ b/src/plugins/manifest-metadata-scan.test.ts
@@ -126,4 +126,55 @@ describe("listOpenClawPluginManifestMetadata", () => {
       origin: "global",
     });
   });
+
+  it("skips oversized plugin manifests to prevent OOM during metadata scan", () => {
+    const root = createTempRoot();
+    const home = path.join(root, "home");
+
+    const goodPluginDir = path.join(home, ".openclaw", "extensions", "good-plugin");
+    writeJson(path.join(goodPluginDir, "openclaw.plugin.json"), { id: "good-plugin" });
+
+    const oversizedDir = path.join(home, ".openclaw", "extensions", "big-plugin");
+    const oversizedPath = path.join(oversizedDir, "openclaw.plugin.json");
+    fs.mkdirSync(oversizedDir, { recursive: true });
+    fs.writeFileSync(
+      oversizedPath,
+      JSON.stringify({ id: "big-plugin", pad: "x".repeat(256 * 1024) }),
+      "utf8",
+    );
+    expect(fs.statSync(oversizedPath).size).toBeGreaterThan(256 * 1024);
+
+    const records = listOpenClawPluginManifestMetadata({
+      OPENCLAW_HOME: home,
+      OPENCLAW_BUNDLED_PLUGINS_DIR: path.join(root, "empty-bundled"),
+    });
+
+    // "good-plugin" is present; "big-plugin" is skipped due to oversized manifest.
+    expect(records.find((record) => record.manifest.id === "good-plugin")).toBeTruthy();
+    expect(records.find((record) => record.manifest.id === "big-plugin")).toBeUndefined();
+  });
+
+  it("accepts plugin manifests at the exact byte limit", () => {
+    const root = createTempRoot();
+    const home = path.join(root, "home");
+
+    const exactDir = path.join(home, ".openclaw", "extensions", "exact-plugin");
+    fs.mkdirSync(exactDir, { recursive: true });
+
+    // Write a compact JSON manifest padded to exactly the byte limit.
+    const exactPath = path.join(exactDir, "openclaw.plugin.json");
+    const exactManifest = { id: "exact-plugin", pad: "" };
+    const compactJson = JSON.stringify(exactManifest);
+    const requiredPadding = 256 * 1024 - Buffer.byteLength(compactJson, "utf8");
+    exactManifest.pad = "x".repeat(requiredPadding);
+    fs.writeFileSync(exactPath, JSON.stringify(exactManifest), "utf8");
+    expect(Buffer.byteLength(fs.readFileSync(exactPath), "utf8")).toBe(256 * 1024);
+
+    const records = listOpenClawPluginManifestMetadata({
+      OPENCLAW_HOME: home,
+      OPENCLAW_BUNDLED_PLUGINS_DIR: path.join(root, "empty-bundled"),
+    });
+
+    expect(records.find((record) => record.manifest.id === "exact-plugin")).toBeTruthy();
+  });
 });
diff --git a/src/plugins/manifest-metadata-scan.ts b/src/plugins/manifest-metadata-scan.ts
index 5788e8498d1..d3cf430095c 100644
--- a/src/plugins/manifest-metadata-scan.ts
+++ b/src/plugins/manifest-metadata-scan.ts
@@ -6,10 +6,18 @@ import { normalizeOptionalString as normalizeTrimmedString } from "@openclaw/nor
 import { resolveStateDir } from "../config/paths.js";
 import { resolveHomeRelativePath } from "../infra/home-dir.js";
 import { resolveOpenClawPackageRootSync } from "../infra/openclaw-root.js";
+import { readRegularFileSync } from "../infra/regular-file.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { parseJsonWithJson5Fallback } from "../utils/parse-json-compat.js";
 import { resolveBundledPluginsDir } from "./bundled-dir.js";
 import { readPersistedInstalledPluginIndexSync } from "./installed-plugin-index-store.js";
 
+// Plugin manifest files are small metadata descriptors. Bound reads to prevent
+// a corrupted or hostile manifest from exhausting memory during metadata scan.
+const PLUGIN_MANIFEST_METADATA_MAX_BYTES = 256 * 1024;
+
+const log = createSubsystemLogger("plugins/manifest-metadata-scan");
+
 type PluginManifestMetadataRecord = {
   pluginDir: string;
   manifest: Record<string, unknown>;
@@ -56,9 +64,18 @@ function listChildPluginDirs(
 
 function readJsonObject(filePath: string): Record<string, unknown> | undefined {
   try {
-    const parsed = parseJsonWithJson5Fallback(fs.readFileSync(filePath, "utf8"));
+    const { buffer } = readRegularFileSync({
+      filePath,
+      maxBytes: PLUGIN_MANIFEST_METADATA_MAX_BYTES,
+    });
+    const parsed = parseJsonWithJson5Fallback(buffer.toString("utf-8"));
     return isRecord(parsed) ? parsed : undefined;
-  } catch {
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("exceeds")) {
+      log.warn(
+        `Ignoring oversized plugin manifest at ${filePath}: file exceeds the ${PLUGIN_MANIFEST_METADATA_MAX_BYTES}-byte limit`,
+      );
+    }
     return undefined;
   }
 }

From 16bd13d2547c434a68e26e1b2de9f876a9af4e95 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:25:52 +0100
Subject: [PATCH 29/76] fix(plugin-sdk): refresh channel send API baseline
 (#110620)

---
 docs/.generated/plugin-sdk-api-baseline.sha256 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 646b8d4c3c0..001cb093102 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -71,7 +71,7 @@ bba5540be7cf9613a163663decdb2affe2af9bbd3ad7914989ab186f9c2abec1  module/channel
 54cdfc60ea96f55453fdccdb1241d8c988aeafe033b9e0cea0f3ecaa13d2e08a  module/channel-secret-basic-runtime
 c78711a2466fca83ae2e68725e61e3a1a4e7dd25abce74d30a943c1be364f704  module/channel-secret-runtime
 96e38ca99edb7d39839a7675939d5b8c199f8625502cae15e66b4bc7885922a7  module/channel-secret-tts-runtime
-3bb07813120d0d73248991cb4a753434eec0fb8a1ec247ec9f4bb00ef8d1b199  module/channel-send-result
+7c90157a95bc0523fc66b1f78ce140f7ec7dbf809dfa3a480244efc01f972754  module/channel-send-result
 e705b97daac4fbd7f6aeb2e515b1cdaa1db342684644eaef8197767b2595826e  module/channel-setup
 47719805c7a1d2623dcecafad50abb6cc674262b250e1f0d7020a79ad41cfd42  module/channel-status
 a4918b82b795f086ae71acb43e2b725fda01f6c8bf2333c155a52581bd4cf8aa  module/channel-streaming

From e22c2dfaaa890d1d689f894a46c6cc0a4339d301 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 18:27:40 +0800
Subject: [PATCH 30/76] fix(gateway): bound BOOT.md file read size (#101776)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(gateway): bound BOOT.md file read size

* fix(gateway): treat non-regular BOOT.md as empty/missing and add coverage

* fix(gateway): preserve non-size BOOT.md failures while bounding oversized reads

* fix(gateway): preserve readable BOOT.md symlink behavior

* fix(gateway): treat dangling BOOT.md symlink as missing

* fix(gateway): report oversized BOOT files

* fix(gateway): preserve missing BOOT race behavior

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/gateway/boot.test.ts | 75 +++++++++++++++++++++++++++++++++++++++-
 src/gateway/boot.ts      | 26 ++++++++++----
 2 files changed, 94 insertions(+), 7 deletions(-)

diff --git a/src/gateway/boot.test.ts b/src/gateway/boot.test.ts
index bb4a5d2a4d8..6eb9ca43e01 100644
--- a/src/gateway/boot.test.ts
+++ b/src/gateway/boot.test.ts
@@ -170,7 +170,41 @@ describe("runBootOnce", () => {
     });
   });
 
-  it("returns failed when BOOT.md cannot be read", async () => {
+  it("skips when BOOT.md disappears after path resolution", async () => {
+    await withBootWorkspace({ bootContent: "Say hello." }, async (workspaceDir) => {
+      const bootPath = path.join(workspaceDir, "BOOT.md");
+      const realpath = vi.spyOn(fs, "realpath");
+      realpath.mockImplementationOnce(async (inputPath) => {
+        realpath.mockRestore();
+        const resolvedPath = await fs.realpath(inputPath);
+        await fs.rm(resolvedPath);
+        return resolvedPath;
+      });
+
+      await expect(runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+        status: "skipped",
+        reason: "missing",
+      });
+      expect(agentCommand).not.toHaveBeenCalled();
+      await expect(fs.access(bootPath)).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("returns failed when BOOT.md exceeds the safe read size limit", async () => {
+    await withBootWorkspace({ bootContent: "" }, async (workspaceDir) => {
+      const bootPath = path.join(workspaceDir, "BOOT.md");
+      const oversized = Buffer.alloc(16 * 1024 * 1024 + 1, "x");
+      await fs.writeFile(bootPath, oversized);
+      const result = await runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir });
+      expect(result.status).toBe("failed");
+      if (result.status === "failed") {
+        expect(result.reason).toContain("File exceeds 16777216 bytes");
+      }
+      expect(agentCommand).not.toHaveBeenCalled();
+    });
+  });
+
+  it("returns failed when BOOT.md is not a regular file", async () => {
     await withBootWorkspace({ bootAsDirectory: true }, async (workspaceDir) => {
       const result = await runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir });
       expect(result.status).toBe("failed");
@@ -180,6 +214,45 @@ describe("runBootOnce", () => {
       expect(agentCommand).not.toHaveBeenCalled();
     });
   });
+
+  it("runs agent command when BOOT.md is a symlink to a regular file", async () => {
+    if (process.platform === "win32") {
+      // Symlink support in unit tests is not guaranteed on Windows CI runners.
+      return;
+    }
+    await withBootWorkspace({ bootContent: "" }, async (workspaceDir) => {
+      const bootPath = path.join(workspaceDir, "BOOT.md");
+      const targetPath = path.join(workspaceDir, "REAL_BOOT.md");
+      await fs.writeFile(targetPath, "Say hello.", "utf-8");
+      await fs.rm(bootPath, { force: true });
+      await fs.symlink(targetPath, bootPath);
+      agentCommand.mockResolvedValue(undefined);
+      await expect(runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+        status: "ran",
+      });
+      expect(agentCommand).toHaveBeenCalledTimes(1);
+      const call = requireAgentCall();
+      expect(call.message).toContain("Say hello.");
+    });
+  });
+
+  it("skips when BOOT.md is a dangling symlink", async () => {
+    if (process.platform === "win32") {
+      // Symlink support in unit tests is not guaranteed on Windows CI runners.
+      return;
+    }
+    await withBootWorkspace({ bootContent: "" }, async (workspaceDir) => {
+      const bootPath = path.join(workspaceDir, "BOOT.md");
+      const targetPath = path.join(workspaceDir, "MISSING_BOOT.md");
+      await fs.rm(bootPath, { force: true });
+      await fs.symlink(targetPath, bootPath);
+      await expect(runBootOnce({ cfg: {}, deps: makeDeps(), workspaceDir })).resolves.toEqual({
+        status: "skipped",
+        reason: "missing",
+      });
+      expect(agentCommand).not.toHaveBeenCalled();
+    });
+  });
   it.each([
     { title: "empty", content: "   \n", reason: "empty" as const },
     { title: "whitespace-only", content: "\n\t ", reason: "empty" as const },
diff --git a/src/gateway/boot.ts b/src/gateway/boot.ts
index 9436e63a872..448bfcebe4b 100644
--- a/src/gateway/boot.ts
+++ b/src/gateway/boot.ts
@@ -21,6 +21,7 @@ import { resolveStorePath } from "../config/sessions/paths.js";
 import { preserveTemporarySessionMapping } from "../config/sessions/session-accessor.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { formatErrorMessage } from "../infra/errors.js";
+import { readRegularFile } from "../infra/regular-file.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { type RuntimeEnv, defaultRuntime } from "../runtime.js";
 import { clearBootEchoContextForSession, setBootEchoContextForSession } from "./boot-echo-guard.js";
@@ -72,17 +73,24 @@ function resolveBootSessionKey(sessionKey: string): string {
   return `agent:${agentId}:boot`;
 }
 
+const MAX_BOOT_FILE_BYTES = 16 * 1024 * 1024;
+
 async function loadBootFile(
   workspaceDir: string,
 ): Promise<{ content?: string; status: "ok" | "missing" | "empty" }> {
   const bootPath = path.join(workspaceDir, BOOT_FILENAME);
+
+  // Resolve symlinks so BOOT.md can be a readable symlink to a regular file
+  // while keeping directory/permission/size-limit failures surfaced to the
+  // operator. ENOENT from either resolution or the bounded open keeps the
+  // established readFile contract: treat disappearance as missing.
+  let buffer: Buffer;
   try {
-    const content = await fs.readFile(bootPath, "utf-8");
-    const trimmed = content.trim();
-    if (!trimmed) {
-      return { status: "empty" };
-    }
-    return { status: "ok", content: trimmed };
+    const resolvedPath = await fs.realpath(bootPath);
+    ({ buffer } = await readRegularFile({
+      filePath: resolvedPath,
+      maxBytes: MAX_BOOT_FILE_BYTES,
+    }));
   } catch (err) {
     const anyErr = err as { code?: string };
     if (anyErr.code === "ENOENT") {
@@ -90,6 +98,12 @@ async function loadBootFile(
     }
     throw err;
   }
+  const content = buffer.toString("utf-8");
+  const trimmed = content.trim();
+  if (!trimmed) {
+    return { status: "empty" };
+  }
+  return { status: "ok", content: trimmed };
 }
 
 export async function runBootOnce(params: {

From adff355caf2cbd791579f1339c3370adc9d6ef77 Mon Sep 17 00:00:00 2001
From: mushuiyu886 <yang.haoyu@xydigit.com>
Date: Sat, 18 Jul 2026 18:30:13 +0800
Subject: [PATCH 31/76] fix(plugin-sdk): failed raw channel sends report
 success (#109906)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(plugin-sdk): reject failed raw channel sends

* fix(plugin-sdk): preserve raw result helper compatibility

* test(plugin-sdk): cover raw send fallback errors

Co-authored-by: 杨浩宇0668001029 <yang.haoyu@xydigit.com>

* fix(security): bound skill-file audit read via safe reader (restore removed fs dependency) (#110589)

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/plugin-sdk/channel-send-result.test.ts | 46 ++++++++++------------
 src/plugin-sdk/channel-send-result.ts      | 14 ++++++-
 2 files changed, 32 insertions(+), 28 deletions(-)

diff --git a/src/plugin-sdk/channel-send-result.test.ts b/src/plugin-sdk/channel-send-result.test.ts
index 19ca5541c85..2cf3ba8770a 100644
--- a/src/plugin-sdk/channel-send-result.test.ts
+++ b/src/plugin-sdk/channel-send-result.test.ts
@@ -131,38 +131,32 @@ describe("createAttachedChannelResultAdapter", () => {
 });
 
 describe("createRawChannelSendResultAdapter", () => {
-  it("normalizes raw send results through adapter methods", async () => {
+  it("normalizes successes and rejects provider failures", async () => {
     const adapter = createRawChannelSendResultAdapter({
       channel: "zalo",
       sendText: async () => ({ ok: true, messageId: "m1" }),
       sendMedia: async () => ({ ok: false, error: "boom" }),
     });
 
-    const sendCases = [
-      {
-        name: "sendText",
-        run: () => adapter.sendText!({ cfg: {} as never, to: "x", text: "hi" }),
-        expected: {
-          channel: "zalo",
-          ok: true,
-          messageId: "m1",
-          error: undefined,
-        },
-      },
-      {
-        name: "sendMedia",
-        run: () => adapter.sendMedia!({ cfg: {} as never, to: "x", text: "hi" }),
-        expected: {
-          channel: "zalo",
-          ok: false,
-          messageId: "",
-          error: new Error("boom"),
-        },
-      },
-    ];
+    await expect(adapter.sendText!({ cfg: {} as never, to: "x", text: "hi" })).resolves.toEqual({
+      channel: "zalo",
+      ok: true,
+      messageId: "m1",
+      error: undefined,
+    });
+    await expect(adapter.sendMedia!({ cfg: {} as never, to: "x", text: "hi" })).rejects.toThrow(
+      "boom",
+    );
+  });
 
-    for (const testCase of sendCases) {
-      await expect(testCase.run()).resolves.toEqual(testCase.expected);
-    }
+  it("uses a channel-specific error when a failed result has no message", async () => {
+    const adapter = createRawChannelSendResultAdapter({
+      channel: "legacy-test",
+      sendText: async () => ({ ok: false }),
+    });
+
+    await expect(adapter.sendText!({ cfg: {} as never, to: "x", text: "hi" })).rejects.toThrow(
+      "Channel send failed for legacy-test",
+    );
   });
 });
diff --git a/src/plugin-sdk/channel-send-result.ts b/src/plugin-sdk/channel-send-result.ts
index 315aaef3a35..b705c6be870 100644
--- a/src/plugin-sdk/channel-send-result.ts
+++ b/src/plugin-sdk/channel-send-result.ts
@@ -88,6 +88,16 @@ export function createAttachedChannelResultAdapter(params: {
   };
 }
 
+function buildRawChannelAdapterResult(
+  channel: string,
+  result: ChannelSendRawResult,
+): OutboundDeliveryResult {
+  if (!result.ok) {
+    throw new Error(result.error?.trim() || `Channel send failed for ${channel}`);
+  }
+  return buildChannelSendResult(channel, result);
+}
+
 /** Wraps legacy raw text/media send methods and normalizes their results. */
 export function createRawChannelSendResultAdapter(params: {
   /** Channel id attached to every normalized legacy send result. */
@@ -99,10 +109,10 @@ export function createRawChannelSendResultAdapter(params: {
 }): Pick<ChannelOutboundAdapter, "sendText" | "sendMedia"> {
   return {
     sendText: params.sendText
-      ? async (ctx) => buildChannelSendResult(params.channel, await params.sendText!(ctx))
+      ? async (ctx) => buildRawChannelAdapterResult(params.channel, await params.sendText!(ctx))
       : undefined,
     sendMedia: params.sendMedia
-      ? async (ctx) => buildChannelSendResult(params.channel, await params.sendMedia!(ctx))
+      ? async (ctx) => buildRawChannelAdapterResult(params.channel, await params.sendMedia!(ctx))
       : undefined,
   };
 }

From cc920838bc3d857cba373acc0deb2d0b9e21e4ba Mon Sep 17 00:00:00 2001
From: "Chris M." <chris.mish@gmail.com>
Date: Sat, 18 Jul 2026 03:33:57 -0700
Subject: [PATCH 32/76] fix(android): recover Wear requests from stale phone
 routes (#110423)

* fix(android): harden Wear phone routing

* fix(android): preserve proven Wear phone routes

Co-authored-by: Chris Mish <chrism@promethean-dynamic.com>

* fix(android): guard Wear discovery invalidation

Co-authored-by: Chris Mish <chrism@promethean-dynamic.com>

---------

Co-authored-by: Chris Mish <chrism@promethean-dynamic.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 .../java/ai/openclaw/wear/WearProxyClient.kt  | 196 ++++++---
 .../openclaw/wear/WearProxyListenerService.kt |  18 +-
 .../ai/openclaw/wear/WearProxyClientTest.kt   | 371 ++++++++++++++++++
 3 files changed, 523 insertions(+), 62 deletions(-)

diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyClient.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyClient.kt
index a9aa798eba5..fd7eea770af 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyClient.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyClient.kt
@@ -12,7 +12,6 @@ import com.google.android.gms.wearable.CapabilityClient
 import com.google.android.gms.wearable.Wearable
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CompletableDeferred
-import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.currentCoroutineContext
 import kotlinx.coroutines.ensureActive
@@ -21,13 +20,12 @@ import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
-import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.withTimeoutOrNull
 import kotlinx.serialization.json.JsonElement
 import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.buildJsonObject
 import java.util.UUID
 import java.util.concurrent.ConcurrentHashMap
-import java.util.concurrent.atomic.AtomicReference
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 
@@ -77,10 +75,9 @@ internal class WearProxyClient private constructor(
   private val transport: WearMessageTransport,
 ) : WearRpcRequester {
   private val pending = ConcurrentHashMap<String, PendingWearRequest>()
-  private val selectedPhoneNodeId = AtomicReference<String?>()
   private val preferredPhoneLock = Any()
-  private var preferredPhoneKnown = false
-  private var preferredPhoneNodeId: String? = null
+  private var preferredPhoneGeneration = 0L
+  private var registeredPhone: PreferredPhoneRegistration? = null
   private val inboundMutex = Mutex()
   private val mutableEvents =
     MutableSharedFlow<WearInboundEvent>(
@@ -98,31 +95,49 @@ internal class WearProxyClient private constructor(
     params: JsonObject,
     expectedNodeId: String?,
     requirePreferredNode: Boolean,
-  ): WearRpcResult =
-    try {
-      withTimeout(REQUEST_TIMEOUT_MS) {
-        requestBeforeDeadline(method, params, expectedNodeId, requirePreferredNode)
+  ): WearRpcResult {
+    var attemptedPreferredPhone: PreferredPhoneRegistration? = null
+    val result =
+      withTimeoutOrNull(REQUEST_TIMEOUT_MS) {
+        requestBeforeDeadline(method, params, expectedNodeId, requirePreferredNode) { registration ->
+          attemptedPreferredPhone = registration
+        }
       }
-    } catch (_: TimeoutCancellationException) {
-      throw WearProxyException("timeout", "Paired phone did not respond")
-    }
+    if (result != null) return result
+
+    // MessageClient success only proves the request was queued. A silent phone
+    // must be rediscovered just like a node that rejected the send outright.
+    invalidatePreferredPhone(attemptedPreferredPhone)
+    throw WearProxyException("timeout", "Paired phone did not respond")
+  }
 
   private suspend fun requestBeforeDeadline(
     method: WearRpcMethod,
     params: JsonObject,
     expectedNodeId: String?,
     requirePreferredNode: Boolean,
+    recordPreferredPhoneAttempt: (PreferredPhoneRegistration?) -> Unit,
   ): WearRpcResult {
     // Stateful RPCs stay on the phone that supplied their session/transcript.
     // Rediscovery here could route a shared session key to a different phone.
-    val requiredPreferredNodeId = if (requirePreferredNode) resolvePreferredPhoneNode() else null
-    val nodeId = expectedNodeId ?: requiredPreferredNodeId ?: resolvePreferredPhoneNode()
-    if (requirePreferredNode && expectedNodeId != null && requiredPreferredNodeId != expectedNodeId) {
+    val preferredPhone =
+      when {
+        requirePreferredNode || expectedNodeId == null -> resolvePreferredPhone()
+        else -> preferredPhoneRegistration(expectedNodeId)
+      }
+    val nodeId = expectedNodeId ?: checkNotNull(preferredPhone).nodeId
+    if (requirePreferredNode && expectedNodeId != null && preferredPhone?.nodeId != expectedNodeId) {
       throw WearProxyException("phone_changed", "Preferred phone changed during request")
     }
+    recordPreferredPhoneAttempt(preferredPhone?.takeIf { it.nodeId == nodeId })
     val requestId = UUID.randomUUID().toString()
     val response = CompletableDeferred<WearMessage.Response>()
-    val pendingRequest = PendingWearRequest(nodeId = nodeId, response = response)
+    val pendingRequest =
+      PendingWearRequest(
+        nodeId = nodeId,
+        response = response,
+        preferredPhone = preferredPhone?.takeIf { it.nodeId == nodeId },
+      )
     check(pending.putIfAbsent(requestId, pendingRequest) == null)
     return try {
       try {
@@ -136,14 +151,16 @@ internal class WearProxyClient private constructor(
         )
       } catch (_: CancellationException) {
         currentCoroutineContext().ensureActive()
+        invalidatePreferredPhone(preferredPhone?.takeIf { it.nodeId == nodeId })
         throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
       } catch (_: Throwable) {
+        invalidatePreferredPhone(preferredPhone?.takeIf { it.nodeId == nodeId })
         throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
       }
       val envelope = response.await()
       if (
         (expectedNodeId == null || requirePreferredNode || method.requiresPreferredSnapshotSource()) &&
-        selectedPhoneNodeId.get() != nodeId
+        currentPreferredPhone()?.nodeId != nodeId
       ) {
         throw WearProxyException("phone_changed", "Preferred phone changed during request")
       }
@@ -175,8 +192,12 @@ internal class WearProxyClient private constructor(
         path == WearProtocol.RESPONSE_PATH && message is WearMessage.Response -> {
           pending[message.requestId]
             ?.takeIf { it.nodeId == sourceNodeId }
-            ?.response
-            ?.complete(message)
+            ?.let { request ->
+              // Correlation is the reachability proof. Advance the registration
+              // before a concurrently expiring request can invalidate it.
+              confirmPreferredPhoneResponse(request.preferredPhone)
+              request.response.complete(message)
+            }
           null
         }
         path == WearProtocol.EVENT_PATH && message is WearMessage.Event -> {
@@ -209,15 +230,12 @@ internal class WearProxyClient private constructor(
     } ?: throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
 
   private suspend fun acceptEventSource(sourceNodeId: String): Boolean {
-    val snapshot = preferredPhoneSnapshot()
-    if (snapshot.known) {
-      val preferred = snapshot.nodeId
-      selectedPhoneNodeId.set(preferred)
-      return preferred == sourceNodeId
+    val preferredPhone = currentPreferredPhone()
+    if (preferredPhone != null) {
+      return preferredPhone.nodeId == sourceNodeId
     }
-    if (selectedPhoneNodeId.get() == sourceNodeId) return true
     return try {
-      resolvePreferredPhoneNode() == sourceNodeId
+      resolvePreferredPhone().nodeId == sourceNodeId
     } catch (err: CancellationException) {
       throw err
     } catch (_: WearProxyException) {
@@ -225,49 +243,97 @@ internal class WearProxyClient private constructor(
     }
   }
 
-  /** Capability callbacks invalidate cached routing before another old-phone event is accepted. */
-  fun updatePreferredPhoneNodeId(nodeId: String?) {
+  /** A unique directly connected phone becomes the preferred routing source immediately. */
+  fun updatePreferredPhoneNodeId(nodeId: String) {
     val changed =
       synchronized(preferredPhoneLock) {
-        val changed = !preferredPhoneKnown || preferredPhoneNodeId != nodeId
-        preferredPhoneKnown = true
-        preferredPhoneNodeId = nodeId
+        val changed = registeredPhone?.nodeId != nodeId
+        preferredPhoneGeneration += 1
+        registeredPhone = PreferredPhoneRegistration(nodeId, preferredPhoneGeneration)
         changed
       }
-    selectedPhoneNodeId.set(nodeId)
     if (changed) mutablePreferredPhoneChanges.tryEmit(nodeId)
   }
 
-  private suspend fun resolvePreferredPhoneNode(): String {
-    preferredPhoneSnapshot().takeIf(PreferredPhoneSnapshot::known)?.let { snapshot ->
-      return snapshot.nodeId ?: throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
-    }
+  /** Capability callbacks are not reachability-filtered, so ambiguous results force fresh discovery. */
+  fun invalidatePreferredPhoneNode() {
+    val changed =
+      synchronized(preferredPhoneLock) {
+        val changed = registeredPhone != null
+        preferredPhoneGeneration += 1
+        registeredPhone = null
+        changed
+      }
+    if (changed) mutablePreferredPhoneChanges.tryEmit(null)
+  }
+
+  private suspend fun resolvePreferredPhone(): PreferredPhoneRegistration {
+    // Capability callbacks can invalidate the route while discovery suspends.
+    // Only a result from the same generation may repopulate it.
+    val discoveryGeneration =
+      synchronized(preferredPhoneLock) {
+        registeredPhone?.let { return it }
+        preferredPhoneGeneration
+      }
     val resolved = resolvePhoneNode()
-    val selected =
+    return synchronized(preferredPhoneLock) {
+      registeredPhone ?: if (preferredPhoneGeneration == discoveryGeneration) {
+        preferredPhoneGeneration += 1
+        PreferredPhoneRegistration(resolved, preferredPhoneGeneration).also { registeredPhone = it }
+      } else {
+        null
+      }
+    } ?: throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
+  }
+
+  private fun currentPreferredPhone(): PreferredPhoneRegistration? =
+    synchronized(preferredPhoneLock) {
+      registeredPhone
+    }
+
+  private fun preferredPhoneRegistration(nodeId: String): PreferredPhoneRegistration? =
+    synchronized(preferredPhoneLock) {
+      registeredPhone?.takeIf { it.nodeId == nodeId }
+    }
+
+  private fun invalidatePreferredPhone(registration: PreferredPhoneRegistration?) {
+    if (registration == null) return
+    val invalidated =
       synchronized(preferredPhoneLock) {
-        if (!preferredPhoneKnown) {
-          preferredPhoneKnown = true
-          preferredPhoneNodeId = resolved
+        if (registeredPhone == registration) {
+          // A capability callback can refresh the same node while an older request
+          // is failing. Clear only the registration that owned this transport attempt.
+          preferredPhoneGeneration += 1
+          registeredPhone = null
+          true
+        } else {
+          false
         }
-        preferredPhoneNodeId
-      } ?: throw WearProxyException("phone_unavailable", "Paired phone is unavailable")
-    selectedPhoneNodeId.set(selected)
-    return selected
+      }
+    if (invalidated) mutablePreferredPhoneChanges.tryEmit(null)
   }
 
-  private fun preferredPhoneSnapshot(): PreferredPhoneSnapshot =
+  private fun confirmPreferredPhoneResponse(registration: PreferredPhoneRegistration?) {
+    if (registration == null) return
     synchronized(preferredPhoneLock) {
-      PreferredPhoneSnapshot(known = preferredPhoneKnown, nodeId = preferredPhoneNodeId)
+      if (registeredPhone == registration) {
+        // Any correlated response proves this registration is reachable. Advance
+        // it so an older parallel request cannot clear it on a later timeout.
+        preferredPhoneGeneration += 1
+        registeredPhone = registration.copy(generation = preferredPhoneGeneration)
+      }
     }
+  }
 
-  private data class PreferredPhoneSnapshot(
-    val known: Boolean,
-    val nodeId: String?,
+  private data class PreferredPhoneRegistration(
+    val nodeId: String,
+    val generation: Long,
   )
 
   private data class PendingWearRequest(
     val nodeId: String,
     val response: CompletableDeferred<WearMessage.Response>,
+    val preferredPhone: PreferredPhoneRegistration?,
   )
 
   companion object {
@@ -281,13 +347,13 @@ internal class WearProxyClient private constructor(
       return WearProxyClient(
         nodeResolver =
           WearNodeResolver {
-            capabilityClient
-              .getCapability(WearProtocol.PHONE_CAPABILITY, CapabilityClient.FILTER_REACHABLE)
-              .await()
-              .nodes
-              .sortedWith(compareByDescending<com.google.android.gms.wearable.Node> { it.isNearby }.thenBy { it.id })
-              .firstOrNull()
-              ?.id
+            selectReachablePhoneNodeId(
+              capabilityClient
+                .getCapability(WearProtocol.PHONE_CAPABILITY, CapabilityClient.FILTER_REACHABLE)
+                .await()
+                .nodes
+                .map { node -> WearReachablePhoneNode(id = node.id, isNearby = node.isNearby) },
+            )
           },
         transport =
           WearMessageTransport { nodeId, path, data ->
@@ -303,6 +369,22 @@ internal class WearProxyClient private constructor(
   }
 }
 
+internal data class WearReachablePhoneNode(
+  val id: String,
+  val isNearby: Boolean,
+)
+
+internal fun selectReachablePhoneNodeId(nodes: Collection<WearReachablePhoneNode>): String? {
+  val distinctNodes = nodes.distinctBy(WearReachablePhoneNode::id)
+  val nearbyNodes = distinctNodes.filter(WearReachablePhoneNode::isNearby)
+  return when {
+    nearbyNodes.size == 1 -> nearbyNodes.single().id
+    nearbyNodes.isNotEmpty() -> null
+    distinctNodes.size == 1 -> distinctNodes.single().id
+    else -> null
+  }
+}
+
 private fun WearRpcMethod.requiresPreferredSnapshotSource(): Boolean = this == WearRpcMethod.ProxyStatus || this == WearRpcMethod.SessionsList || this == WearRpcMethod.ChatHistory
 
 internal enum class WearSequenceDecision {
diff --git a/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyListenerService.kt b/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyListenerService.kt
index efe10c706e1..2933b9c3e29 100644
--- a/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyListenerService.kt
+++ b/apps/android/wear/src/main/java/ai/openclaw/wear/WearProxyListenerService.kt
@@ -11,11 +11,19 @@ class WearProxyListenerService : WearableListenerService() {
   override fun onCapabilityChanged(capabilityInfo: CapabilityInfo) {
     if (capabilityInfo.name != WearProtocol.PHONE_CAPABILITY) return
     val preferredNodeId =
-      capabilityInfo.nodes
-        .sortedWith(compareByDescending<com.google.android.gms.wearable.Node> { it.isNearby }.thenBy { it.id })
-        .firstOrNull()
-        ?.id
-    (application as? WearApplication)?.proxyClient?.updatePreferredPhoneNodeId(preferredNodeId)
+      selectReachablePhoneNodeId(
+        capabilityInfo.nodes.map { node ->
+          WearReachablePhoneNode(id = node.id, isNearby = node.isNearby)
+        },
+      )
+    val proxyClient = (application as? WearApplication)?.proxyClient ?: return
+    if (preferredNodeId == null) {
+      // Capability callbacks contain reachable nodes. Multiple routes remain
+      // ambiguous, so force the next request through fresh discovery.
+      proxyClient.invalidatePreferredPhoneNode()
+    } else {
+      proxyClient.updatePreferredPhoneNodeId(preferredNodeId)
+    }
   }
 
   override fun onMessageReceived(messageEvent: MessageEvent) {
diff --git a/apps/android/wear/src/test/java/ai/openclaw/wear/WearProxyClientTest.kt b/apps/android/wear/src/test/java/ai/openclaw/wear/WearProxyClientTest.kt
index a23bc75f006..0dd00c0941b 100644
--- a/apps/android/wear/src/test/java/ai/openclaw/wear/WearProxyClientTest.kt
+++ b/apps/android/wear/src/test/java/ai/openclaw/wear/WearProxyClientTest.kt
@@ -8,13 +8,16 @@ import ai.openclaw.wear.shared.WearProtocolCodec
 import ai.openclaw.wear.shared.WearProxyCapability
 import ai.openclaw.wear.shared.WearRpcMethod
 import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CompletableDeferred
 import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitCancellation
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.test.advanceUntilIdle
 import kotlinx.coroutines.test.runCurrent
 import kotlinx.coroutines.test.runTest
+import kotlinx.coroutines.withTimeout
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonObject
 import kotlinx.serialization.json.jsonObject
@@ -346,6 +349,374 @@ class WearProxyClientTest {
       assertEquals("phone_unavailable", (failure as WearProxyException).code)
     }
 
+  @Test
+  fun shorterCallerTimeoutPropagatesWithoutInvalidatingPhone() =
+    runTest {
+      var discoveries = 0
+      var respond = false
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "resolver-phone"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              if (!respond) awaitCancellation()
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              client.handleMessage(
+                sourceNodeId = nodeId,
+                path = WearProtocol.RESPONSE_PATH,
+                data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+              )
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-current")
+
+      val failure =
+        runCatching {
+          withTimeout(1_000L) {
+            client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+          }
+        }.exceptionOrNull()
+      respond = true
+
+      assertTrue(failure is TimeoutCancellationException)
+      assertEquals("phone-current", client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null).sourceNodeId)
+      assertEquals(0, discoveries)
+    }
+
+  @Test
+  fun sendFailureInvalidatesCachedPhoneAndRediscoversNextRequest() =
+    runTest {
+      var resolvedNode = "phone-old"
+      var discoveries = 0
+      var sends = 0
+      val sentNodes = mutableListOf<String>()
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              resolvedNode
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sends += 1
+              sentNodes += nodeId
+              if (sends == 1) error("stale node")
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              client.handleMessage(
+                sourceNodeId = nodeId,
+                path = WearProtocol.RESPONSE_PATH,
+                data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+              )
+            },
+        )
+
+      val first = runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) }.exceptionOrNull()
+      resolvedNode = "phone-new"
+      val second = client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+
+      assertEquals("phone_unavailable", (first as WearProxyException).code)
+      assertEquals("phone-new", second.sourceNodeId)
+      assertEquals(2, discoveries)
+      assertEquals(listOf("phone-old", "phone-new"), sentNodes)
+    }
+
+  @Test
+  fun responseTimeoutInvalidatesCachedPhoneAndRediscoversNextRequest() =
+    runTest {
+      var resolvedNode = "phone-old"
+      var discoveries = 0
+      var sends = 0
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              resolvedNode
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sends += 1
+              if (sends > 1) {
+                val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+                client.handleMessage(
+                  sourceNodeId = nodeId,
+                  path = WearProtocol.RESPONSE_PATH,
+                  data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+                )
+              }
+            },
+        )
+
+      val first = runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) }.exceptionOrNull()
+      resolvedNode = "phone-new"
+      val second = client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+
+      assertEquals("timeout", (first as WearProxyException).code)
+      assertEquals("phone-new", second.sourceNodeId)
+      assertEquals(2, discoveries)
+    }
+
+  @Test
+  fun staleSendFailureDoesNotInvalidateNewerSamePhoneGeneration() =
+    runTest {
+      var discoveries = 0
+      var sends = 0
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "resolver-phone"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sends += 1
+              if (sends == 1) {
+                client.updatePreferredPhoneNodeId(nodeId)
+                error("stale send")
+              }
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              client.handleMessage(
+                sourceNodeId = nodeId,
+                path = WearProtocol.RESPONSE_PATH,
+                data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+              )
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-current")
+
+      val first = runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) }.exceptionOrNull()
+      val second = client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+
+      assertEquals("phone_unavailable", (first as WearProxyException).code)
+      assertEquals("phone-current", second.sourceNodeId)
+      assertEquals(0, discoveries)
+    }
+
+  @Test
+  fun staleResponseTimeoutDoesNotInvalidateNewerSamePhoneGeneration() =
+    runTest {
+      var discoveries = 0
+      var sends = 0
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "resolver-phone"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sends += 1
+              if (sends == 1) {
+                client.updatePreferredPhoneNodeId(nodeId)
+              } else {
+                val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+                client.handleMessage(
+                  sourceNodeId = nodeId,
+                  path = WearProtocol.RESPONSE_PATH,
+                  data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+                )
+              }
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-current")
+
+      val first = runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) }.exceptionOrNull()
+      val second = client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+
+      assertEquals("timeout", (first as WearProxyException).code)
+      assertEquals("phone-current", second.sourceNodeId)
+      assertEquals(0, discoveries)
+    }
+
+  @Test
+  fun successfulParallelResponseProtectsPhoneFromOlderTimeout() =
+    runTest {
+      var discoveries = 0
+      var sends = 0
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "resolver-phone"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sends += 1
+              if (sends > 1) {
+                val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+                client.handleMessage(
+                  sourceNodeId = nodeId,
+                  path = WearProtocol.RESPONSE_PATH,
+                  data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+                )
+              }
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-current")
+
+      val older = async { runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) } }
+      runCurrent()
+      val newer = async { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) }
+      runCurrent()
+
+      assertEquals("phone-current", newer.await().sourceNodeId)
+      assertEquals("timeout", (older.await().exceptionOrNull() as WearProxyException).code)
+      assertEquals("phone-current", client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null).sourceNodeId)
+      assertEquals(0, discoveries)
+    }
+
+  @Test
+  fun correlatedResponseProtectsPhoneBeforeRequesterResumes() =
+    runTest {
+      var discoveries = 0
+      var respond = false
+      val requests = mutableListOf<WearMessage.Request>()
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "resolver-phone"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              requests += request
+              if (respond) {
+                client.handleMessage(
+                  sourceNodeId = nodeId,
+                  path = WearProtocol.RESPONSE_PATH,
+                  data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+                )
+              }
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-current")
+
+      val older = async { runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) } }
+      val newer = async { runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) } }
+      runCurrent()
+      assertEquals(2, requests.size)
+
+      client.handleMessage(
+        sourceNodeId = "phone-current",
+        path = WearProtocol.RESPONSE_PATH,
+        data = WearProtocolCodec.encode(WearMessage.Response(requestId = requests[1].requestId, ok = true)),
+      )
+      newer.cancel()
+      advanceUntilIdle()
+
+      assertTrue(newer.isCancelled)
+      assertEquals("timeout", (older.await().exceptionOrNull() as WearProxyException).code)
+      respond = true
+      assertEquals("phone-current", client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null).sourceNodeId)
+      assertEquals(0, discoveries)
+    }
+
+  @Test
+  fun ambiguousCapabilityCallbackForcesReachableRediscovery() =
+    runTest {
+      var discoveries = 0
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              discoveries += 1
+              "phone-reachable"
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              client.handleMessage(
+                sourceNodeId = nodeId,
+                path = WearProtocol.RESPONSE_PATH,
+                data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+              )
+            },
+        )
+      client.updatePreferredPhoneNodeId("phone-stale")
+
+      client.invalidatePreferredPhoneNode()
+      val result = client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null)
+
+      assertEquals("phone-reachable", result.sourceNodeId)
+      assertEquals(1, discoveries)
+    }
+
+  @Test
+  fun inFlightDiscoveryCannotRestoreInvalidatedPhone() =
+    runTest {
+      val discoveryStarted = CompletableDeferred<Unit>()
+      val releaseDiscovery = CompletableDeferred<Unit>()
+      var resolvedNode = "phone-old"
+      var discoveries = 0
+      val sentNodes = mutableListOf<String>()
+      lateinit var client: WearProxyClient
+      client =
+        WearProxyClient.createForTests(
+          nodeResolver =
+            WearNodeResolver {
+              val result = resolvedNode
+              discoveries += 1
+              if (discoveries == 1) {
+                discoveryStarted.complete(Unit)
+                releaseDiscovery.await()
+              }
+              result
+            },
+          transport =
+            WearMessageTransport { nodeId, _, data ->
+              sentNodes += nodeId
+              val request = (WearProtocolCodec.decode(data) as WearDecodeResult.Success).message as WearMessage.Request
+              client.handleMessage(
+                sourceNodeId = nodeId,
+                path = WearProtocol.RESPONSE_PATH,
+                data = WearProtocolCodec.encode(WearMessage.Response(requestId = request.requestId, ok = true)),
+              )
+            },
+        )
+
+      val first = async { runCatching { client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null) } }
+      discoveryStarted.await()
+      client.invalidatePreferredPhoneNode()
+      resolvedNode = "phone-new"
+      releaseDiscovery.complete(Unit)
+
+      assertEquals("phone_unavailable", (first.await().exceptionOrNull() as WearProxyException).code)
+      assertEquals("phone-new", client.request(WearRpcMethod.ProxyStatus, buildJsonObject {}, null).sourceNodeId)
+      assertEquals(2, discoveries)
+      assertEquals(listOf("phone-new"), sentNodes)
+    }
+
+  @Test
+  fun reachablePhoneSelectionPrefersOneNearbyNodeAndRejectsAmbiguity() {
+    val nearby = WearReachablePhoneNode(id = "phone-nearby", isNearby = true)
+    val nearbyTwo = WearReachablePhoneNode(id = "phone-nearby-2", isNearby = true)
+    val cloud = WearReachablePhoneNode(id = "phone-cloud", isNearby = false)
+    val cloudTwo = WearReachablePhoneNode(id = "phone-cloud-2", isNearby = false)
+
+    assertEquals("phone-nearby", selectReachablePhoneNodeId(listOf(cloud, nearby)))
+    assertEquals("phone-cloud", selectReachablePhoneNodeId(listOf(cloud)))
+    assertEquals(null, selectReachablePhoneNodeId(listOf(nearby, nearbyTwo, cloud)))
+    assertEquals(null, selectReachablePhoneNodeId(listOf(cloud, cloudTwo)))
+  }
+
   @Test
   fun eventGapAndResetRequireCanonicalRefresh() {
     val tracker = WearEventSequenceTracker()

From 5360c75de23be2e53dc9c70d8da81c6f0580cef5 Mon Sep 17 00:00:00 2001
From: mushuiyu886 <yang.haoyu@xydigit.com>
Date: Sat, 18 Jul 2026 18:34:21 +0800
Subject: [PATCH 33/76] fix(tui): stop Codex login lookup hanging the terminal
 (#109452)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(tui): bound Codex CLI lookup

* fix(tui): bound Codex CLI lookup asynchronously

Co-authored-by: 杨浩宇0668001029 <yang.haoyu@xydigit.com>

* style(tui): format Codex auth flow

Co-authored-by: 杨浩宇0668001029 <yang.haoyu@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/tui/tui.resolve-codex-bin.test.ts | 65 ++++++++++++------
 src/tui/tui.test.ts                   |  8 +--
 src/tui/tui.ts                        | 98 +++++++++++++++------------
 3 files changed, 103 insertions(+), 68 deletions(-)

diff --git a/src/tui/tui.resolve-codex-bin.test.ts b/src/tui/tui.resolve-codex-bin.test.ts
index 68115ee6cae..a3965d9f6d4 100644
--- a/src/tui/tui.resolve-codex-bin.test.ts
+++ b/src/tui/tui.resolve-codex-bin.test.ts
@@ -1,29 +1,50 @@
-// Covers TUI Codex CLI lookup command selection.
+// Covers bounded TUI Codex CLI lookup command selection.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { withMockedWindowsPlatform } from "../test-utils/vitest-spies.js";
+import { withMockedPlatform, withMockedWindowsPlatform } from "../test-utils/vitest-spies.js";
 
-const execFileSyncMock = vi.hoisted(() => vi.fn());
+const runCommandWithTimeoutMock = vi.hoisted(() => vi.fn());
 
-vi.mock("node:child_process", async () => {
-  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
-  return {
-    ...actual,
-    execFileSync: execFileSyncMock,
-  };
-});
+vi.mock("../process/exec.js", () => ({ runCommandWithTimeout: runCommandWithTimeoutMock }));
 
 import { resolveCodexCliBin } from "./tui.js";
 
 afterEach(() => {
   vi.restoreAllMocks();
   vi.unstubAllEnvs();
-  execFileSyncMock.mockReset();
+  runCommandWithTimeoutMock.mockReset();
 });
 
 describe("resolveCodexCliBin", () => {
-  it("uses the trusted Windows where.exe when resolving codex", async () => {
+  it("bounds lookup and returns the first PATH match", async () => {
+    runCommandWithTimeoutMock.mockResolvedValue({
+      code: 0,
+      stdout: "/usr/local/bin/codex\n/opt/bin/codex\n",
+      termination: "exit",
+    });
+
+    await withMockedPlatform("linux", async () => {
+      await expect(resolveCodexCliBin()).resolves.toBe("/usr/local/bin/codex");
+    });
+    expect(runCommandWithTimeoutMock).toHaveBeenCalledWith(["which", "codex"], {
+      killSignal: "SIGKILL",
+      maxOutputBytes: 64 * 1024,
+      timeoutMs: 5_000,
+    });
+  });
+
+  it("returns null when lookup times out", async () => {
+    runCommandWithTimeoutMock.mockResolvedValue({
+      code: null,
+      stdout: "",
+      termination: "timeout",
+    });
+
+    await expect(resolveCodexCliBin()).resolves.toBeNull();
+  });
+
+  it("uses the trusted Windows where.exe", async () => {
     const accessSync = fs.accessSync.bind(fs);
     vi.spyOn(fs, "accessSync").mockImplementation((filePath, mode) => {
       if (String(filePath).toLowerCase() === "c:\\windows\\system32\\reg.exe") {
@@ -32,16 +53,22 @@ describe("resolveCodexCliBin", () => {
       return accessSync(filePath, mode);
     });
     vi.stubEnv("SystemRoot", "D:\\Windows");
-    execFileSyncMock.mockReturnValue("D:\\Tools\\codex.exe\r\n");
+    runCommandWithTimeoutMock.mockResolvedValue({
+      code: 0,
+      stdout: "D:\\Tools\\codex.exe\r\n",
+      termination: "exit",
+    });
 
     await withMockedWindowsPlatform(async () => {
-      expect(resolveCodexCliBin()).toBe("D:\\Tools\\codex.exe");
+      await expect(resolveCodexCliBin()).resolves.toBe("D:\\Tools\\codex.exe");
     });
-
-    expect(execFileSyncMock).toHaveBeenCalledWith(
-      path.win32.join("D:\\Windows", "System32", "where.exe"),
-      ["codex"],
-      { encoding: "utf8" },
+    expect(runCommandWithTimeoutMock).toHaveBeenCalledWith(
+      [path.win32.join("D:\\Windows", "System32", "where.exe"), "codex"],
+      {
+        killSignal: "SIGKILL",
+        maxOutputBytes: 64 * 1024,
+        timeoutMs: 5_000,
+      },
     );
   });
 });
diff --git a/src/tui/tui.test.ts b/src/tui/tui.test.ts
index 1861a6921ae..39b4e46458d 100644
--- a/src/tui/tui.test.ts
+++ b/src/tui/tui.test.ts
@@ -583,8 +583,8 @@ describe("TUI shutdown safety", () => {
 });
 
 describe("resolveCodexCliBin", () => {
-  it("returns a string path when codex CLI is installed", () => {
-    const result = resolveCodexCliBin();
+  it("returns a string path when codex CLI is installed", async () => {
+    const result = await resolveCodexCliBin();
     // In this test environment codex is installed; verify it returns a non-empty path
     if (result !== null) {
       expect(typeof result).toBe("string");
@@ -593,8 +593,8 @@ describe("resolveCodexCliBin", () => {
     }
   });
 
-  it("returns null or a valid path (never throws)", () => {
-    const result = resolveCodexCliBin();
+  it("returns null or a valid path (never throws)", async () => {
+    const result = await resolveCodexCliBin();
     if (result === null) {
       expect(result).toBeNull();
     } else {
diff --git a/src/tui/tui.ts b/src/tui/tui.ts
index 9b1d446fd8c..a8a618519ad 100644
--- a/src/tui/tui.ts
+++ b/src/tui/tui.ts
@@ -1,5 +1,5 @@
 // Runs the interactive TUI loop and coordinates backend, input, and rendering.
-import { execFileSync, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -23,6 +23,7 @@ import { registerUncaughtExceptionHandler } from "../infra/unhandled-rejections.
 import { getWindowsSystem32ExePath } from "../infra/windows-install-roots.js";
 import { setConsoleSubsystemFilter } from "../logging/console.js";
 import { loggingState } from "../logging/state.js";
+import { runCommandWithTimeout } from "../process/exec.js";
 import {
   buildWindowsCmdExeCommandLine,
   isWindowsBatchCommand,
@@ -102,6 +103,7 @@ const OPENCLAW_DIST_ENTRY_MJS_PATH = fileURLToPath(
 );
 
 const OPENAI_CODEX_PROVIDER = "openai";
+const CODEX_CLI_LOOKUP_TIMEOUT_MS = 5_000;
 
 type RunTuiOptions = TuiOptions & {
   backend?: TuiBackend;
@@ -117,13 +119,20 @@ type RunTuiOptions = TuiOptions & {
 };
 
 /** Resolve the absolute path to the `codex` CLI binary, or `null` if not installed. */
-export function resolveCodexCliBin(): string | null {
+export async function resolveCodexCliBin(): Promise<string | null> {
+  const lookupCommand =
+    process.platform === "win32" ? getWindowsSystem32ExePath("where.exe") : "which";
   try {
-    const lookupCmd =
-      process.platform === "win32" ? getWindowsSystem32ExePath("where.exe") : "which";
-    // `where` on Windows can return multiple lines; take the first match.
-    const raw = execFileSync(lookupCmd, ["codex"], { encoding: "utf8" }).trim();
-    return raw.split(/\r?\n/)[0] || null;
+    const result = await runCommandWithTimeout([lookupCommand, "codex"], {
+      killSignal: "SIGKILL",
+      maxOutputBytes: 64 * 1024,
+      timeoutMs: CODEX_CLI_LOOKUP_TIMEOUT_MS,
+    });
+    if (result.code !== 0 || result.termination !== "exit") {
+      return null;
+    }
+    // `where` on Windows can return multiple matches; use PATH order.
+    return result.stdout.trim().split(/\r?\n/)[0]?.trim() || null;
   } catch {
     return null;
   }
@@ -1183,45 +1192,44 @@ export async function runTui(opts: RunTuiOptions): Promise<TuiResult> {
 
   const runAuthFlow = isLocalMode
     ? async (params: { provider?: string }) =>
-        await withTuiSuspended(
-          async () =>
-            await new Promise<{ exitCode: number | null; signal: NodeJS.Signals | null }>(
-              (resolve, reject) => {
-                const provider = params.provider?.trim() || undefined;
-
-                // Codex owns its auth store; delegate when the CLI is available.
-                const codexBin =
-                  provider === OPENAI_CODEX_PROVIDER ||
-                  (!provider && sessionInfo.modelProvider === OPENAI_CODEX_PROVIDER)
-                    ? resolveCodexCliBin()
-                    : null;
-
-                let command: string;
-                let args: string[];
-                if (codexBin) {
-                  command = codexBin;
-                  args = ["login"];
-                } else {
-                  ({ command, args } = resolveLocalAuthCliInvocation());
-                  if (provider) {
-                    args.push("--provider", provider);
-                  }
+        await withTuiSuspended(async () => {
+          const provider = params.provider?.trim() || undefined;
+
+          // Codex owns its auth store; delegate when the CLI is available.
+          const codexBin =
+            provider === OPENAI_CODEX_PROVIDER ||
+            (!provider && sessionInfo.modelProvider === OPENAI_CODEX_PROVIDER)
+              ? await resolveCodexCliBin()
+              : null;
+
+          return await new Promise<{ exitCode: number | null; signal: NodeJS.Signals | null }>(
+            (resolve, reject) => {
+              let command: string;
+              let args: string[];
+              if (codexBin) {
+                command = codexBin;
+                args = ["login"];
+              } else {
+                ({ command, args } = resolveLocalAuthCliInvocation());
+                if (provider) {
+                  args.push("--provider", provider);
                 }
-
-                const invocation = resolveLocalAuthSpawnInvocation({ command, args });
-                const child = spawn(invocation.command, invocation.args, {
-                  cwd: resolveLocalAuthSpawnCwd({ args, defaultCwd: resolveUsableCwd() }),
-                  env: process.env,
-                  stdio: "inherit",
-                  ...invocation.options,
-                });
-                child.once("error", reject);
-                child.once("exit", (exitCode, signal) => {
-                  resolve({ exitCode, signal });
-                });
-              },
-            ),
-        )
+              }
+
+              const invocation = resolveLocalAuthSpawnInvocation({ command, args });
+              const child = spawn(invocation.command, invocation.args, {
+                cwd: resolveLocalAuthSpawnCwd({ args, defaultCwd: resolveUsableCwd() }),
+                env: process.env,
+                stdio: "inherit",
+                ...invocation.options,
+              });
+              child.once("error", reject);
+              child.once("exit", (exitCode, signal) => {
+                resolve({ exitCode, signal });
+              });
+            },
+          );
+        })
     : undefined;
 
   const updateFooter = () => {

From bc6d9eb16a2243d983e4bd1a3cec5600fba873ab Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:39:01 +0100
Subject: [PATCH 34/76] fix: custom Anthropic models work without maxTokens
 (#110617)

* fix(agents): default Anthropic max output tokens

* fix(agents): bound omitted Anthropic output cap
---
 src/agents/anthropic-transport-stream.test.ts | 84 +++++++++++++++++--
 src/agents/anthropic-transport-stream.ts      | 36 ++++++--
 2 files changed, 104 insertions(+), 16 deletions(-)

diff --git a/src/agents/anthropic-transport-stream.test.ts b/src/agents/anthropic-transport-stream.test.ts
index 90eac8289b8..6fb5429102e 100644
--- a/src/agents/anthropic-transport-stream.test.ts
+++ b/src/agents/anthropic-transport-stream.test.ts
@@ -1262,19 +1262,19 @@ describe("anthropic transport stream", () => {
     expect(latestAnthropicRequest().payload.stream).toBe(true);
   });
 
-  it("fails locally when Anthropic maxTokens is non-positive after resolution", async () => {
+  it("uses a default maxTokens for custom Anthropic models that omit it", async () => {
     const model = attachModelProviderRequestTransport(
       {
-        id: "claude-haiku-4-5",
-        name: "Claude Haiku 4.5",
+        id: "custom-model",
+        name: "Custom Model",
         api: "anthropic-messages",
-        provider: "anthropic",
-        baseUrl: "https://api.anthropic.com",
+        provider: "custom-anthropic",
+        baseUrl: "https://custom.example/anthropic",
         reasoning: false,
         input: ["text"],
         cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 32000,
-        maxTokens: 0,
+        contextWindow: 200_000,
+        maxTokens: undefined as never,
       } satisfies Model<"anthropic-messages">,
       {
         proxy: {
@@ -1298,6 +1298,76 @@ describe("anthropic transport stream", () => {
 
     const result = await stream.result();
 
+    expect(result.stopReason).toBe("stop");
+    expect(latestAnthropicRequest().payload).toMatchObject({
+      model: "custom-model",
+      max_tokens: 4_096,
+      stream: true,
+    });
+  });
+
+  it("clamps the custom Anthropic maxTokens fallback to the context window", async () => {
+    const model = attachModelProviderRequestTransport(
+      {
+        id: "custom-model",
+        name: "Custom Model",
+        api: "anthropic-messages",
+        provider: "custom-anthropic",
+        baseUrl: "https://custom.example/anthropic",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 4_096,
+        maxTokens: undefined as never,
+      } satisfies Model<"anthropic-messages">,
+      {
+        proxy: {
+          mode: "env-proxy",
+        },
+      },
+    );
+
+    await runTransportStream(
+      model,
+      { messages: [{ role: "user", content: "hello" }] } as AnthropicStreamContext,
+      { apiKey: "fake" } as AnthropicStreamOptions,
+    );
+
+    expect(latestAnthropicRequest().payload.max_tokens).toBe(1_024);
+  });
+
+  it("fails locally when a custom Anthropic model has an invalid maxTokens", async () => {
+    const model = attachModelProviderRequestTransport(
+      {
+        id: "custom-model",
+        name: "Custom Model",
+        api: "anthropic-messages",
+        provider: "custom-anthropic",
+        baseUrl: "https://custom.example/anthropic",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 32_000,
+        maxTokens: 0,
+      } satisfies Model<"anthropic-messages">,
+      {
+        proxy: {
+          mode: "env-proxy",
+        },
+      },
+    );
+    const streamFn = createAnthropicMessagesTransportStreamFn();
+
+    const stream = await Promise.resolve(
+      streamFn(
+        model,
+        { messages: [{ role: "user", content: "hello" }] } as Parameters<typeof streamFn>[1],
+        { apiKey: "fake" } as Parameters<typeof streamFn>[2],
+      ),
+    );
+
+    const result = await stream.result();
+
     expect(result.stopReason).toBe("error");
     expect(result.errorMessage).toContain(
       "Anthropic Messages transport requires a positive maxTokens value",
diff --git a/src/agents/anthropic-transport-stream.ts b/src/agents/anthropic-transport-stream.ts
index bf5f21532f5..e17dac85bfb 100644
--- a/src/agents/anthropic-transport-stream.ts
+++ b/src/agents/anthropic-transport-stream.ts
@@ -94,6 +94,8 @@ const CLAUDE_CODE_BILLING_SYSTEM_BLOCK = `x-anthropic-billing-header: cc_version
 const ANTHROPIC_MESSAGES_ERROR_BODY_MAX_BYTES = 8 * 1024;
 const ANTHROPIC_MESSAGES_ERROR_BODY_MAX_CHARS = 400;
 const ANTHROPIC_MESSAGES_ERROR_BODY_READ_IDLE_TIMEOUT_MS = 10_000;
+const ANTHROPIC_MESSAGES_DEFAULT_MAX_TOKENS = 4_096;
+const ANTHROPIC_MESSAGES_FALLBACK_CONTEXT_DIVISOR = 4;
 // Mirror the fetch sanitizer cap here because compatible routes such as Kimi
 // bypass that layer; without a parser-local guard, partial frames grow forever.
 const ANTHROPIC_MESSAGES_SSE_PENDING_BUFFER_MAX_CHARS = 16 * 1024 * 1024;
@@ -242,7 +244,7 @@ function clampReasoningLevel(level: ThinkingLevel): "minimal" | "low" | "medium"
   return level === "xhigh" || level === "max" ? "high" : level;
 }
 
-function resolvePositiveAnthropicMaxTokens(value: unknown): number | undefined {
+function resolvePositiveAnthropicTokenLimit(value: unknown): number | undefined {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return undefined;
   }
@@ -251,20 +253,34 @@ function resolvePositiveAnthropicMaxTokens(value: unknown): number | undefined {
 }
 
 function resolveAnthropicMessagesMaxTokens(params: {
+  modelContextWindow: number | undefined;
   modelMaxTokens: number | undefined;
   requestedMaxTokens: number | undefined;
   useModelDefault?: boolean;
 }): number | undefined {
-  const requested = resolvePositiveAnthropicMaxTokens(params.requestedMaxTokens);
+  const requested = resolvePositiveAnthropicTokenLimit(params.requestedMaxTokens);
   if (requested !== undefined) {
     return requested;
   }
-  const modelMax = resolvePositiveAnthropicMaxTokens(params.modelMaxTokens);
-  return modelMax !== undefined
-    ? params.useModelDefault
-      ? modelMax
-      : Math.min(modelMax, 32_000)
-    : undefined;
+  const modelMax = resolvePositiveAnthropicTokenLimit(params.modelMaxTokens);
+  if (modelMax !== undefined) {
+    return params.useModelDefault ? modelMax : Math.min(modelMax, 32_000);
+  }
+  if (params.modelMaxTokens !== undefined) {
+    return undefined;
+  }
+  // Anthropic requires max_tokens even when an optional custom-model row has no output cap.
+  // Use a conservative compatibility baseline; higher model limits require explicit metadata.
+  const contextWindow = resolvePositiveAnthropicTokenLimit(params.modelContextWindow);
+  return contextWindow === undefined
+    ? ANTHROPIC_MESSAGES_DEFAULT_MAX_TOKENS
+    : Math.max(
+        1,
+        Math.min(
+          ANTHROPIC_MESSAGES_DEFAULT_MAX_TOKENS,
+          Math.floor(contextWindow / ANTHROPIC_MESSAGES_FALLBACK_CONTEXT_DIVISOR),
+        ),
+      );
 }
 
 function adjustMaxTokensForThinking(params: {
@@ -1000,6 +1016,7 @@ function buildAnthropicParams(
   const mandatoryAdaptiveThinking = requiresClaudeAdaptiveThinking(model);
   const replayThinkingEnabled = mandatoryAdaptiveThinking || options?.thinkingEnabled === true;
   const maxTokens = resolveAnthropicMessagesMaxTokens({
+    modelContextWindow: model.contextWindow,
     modelMaxTokens: model.maxTokens,
     requestedMaxTokens: options?.maxTokens,
   });
@@ -1130,6 +1147,7 @@ function resolveAnthropicTransportOptions(
   apiKey: string,
 ): AnthropicTransportOptions {
   const baseMaxTokens = resolveAnthropicMessagesMaxTokens({
+    modelContextWindow: model.contextWindow,
     modelMaxTokens: model.maxTokens,
     requestedMaxTokens: options?.maxTokens,
     useModelDefault: resolveClaudeSonnet5ModelIdentity(model) !== undefined,
@@ -1140,7 +1158,7 @@ function resolveAnthropicTransportOptions(
     );
   }
   const reasoningModelMaxTokens =
-    resolvePositiveAnthropicMaxTokens(model.maxTokens) ?? baseMaxTokens;
+    resolvePositiveAnthropicTokenLimit(model.maxTokens) ?? baseMaxTokens;
   const mandatoryAdaptiveThinking = requiresClaudeAdaptiveThinking(model);
   const reasoning =
     options?.reasoning === "off" && mandatoryAdaptiveThinking ? "low" : options?.reasoning;

From 9d97e10efe08c3b5e3043da19b80883e933e26be Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:42:14 +0100
Subject: [PATCH 35/76] refactor: move non-session runtime journals to SQLite
 (#109427)

* refactor: migrate runtime JSONL state to SQLite

* chore: refresh SQLite migration validation

* fix: preserve safe audit migration order

* fix: sanitize retired audit archives safely

* fix: satisfy SQLite storage architecture gates

* fix: serialize plugin doctor state migrations

* fix: bound memory event SQLite projections

* fix: rotate memory event projections safely

* fix: preserve imported event retention age

* fix: harden memory event export projection

* fix: canonicalize memory event migrations

* fix: harden legacy journal migrations

* fix: report unsafe legacy journal paths

* fix: preserve journal ownership during migration

* fix: keep legacy file imports doctor-only

* fix: align SQLite audit CI coverage

* refactor: keep state helpers module-private

* fix: harden legacy state migration recovery

* fix: reconcile SQLite state audit migration

* test: use neutral audit redaction fixtures

* fix: close SQLite migration recovery gaps

* refactor: split audit migration recovery helpers

* test: prove completed audit pads stay out of backups

* fix: preserve audit record ordinals across blank lines

* fix: align SQLite audit CI contracts

* build: package SQLite audit E2E entries

* fix: preserve audit ordinals in backup snapshots
---
 .../.generated/plugin-sdk-api-baseline.sha256 |    4 +-
 docs/tools/acp-agents.md                      |    7 +-
 .../memory-core/doctor-contract-api.test.ts   |  668 ++++++++++-
 extensions/memory-core/doctor-contract-api.ts |  773 +++++++++++-
 .../memory-core/src/memory-events.test.ts     |   24 +-
 .../memory-core/src/public-artifacts.test.ts  |   44 +-
 extensions/memory-wiki/src/bridge.test.ts     |   15 +-
 .../memory-wiki/src/source-page-shared.ts     |    3 +-
 package.json                                  |    2 +-
 .../check-database-first-legacy-stores.mjs    |    2 +-
 scripts/plugin-sdk-surface-report.mjs         |   11 +-
 ...parent-stream-store.sqlite.test-support.ts |   25 +
 .../acp-parent-stream-store.sqlite.test.ts    |  105 ++
 src/agents/acp-parent-stream-store.sqlite.ts  |   77 ++
 src/agents/acp-spawn-parent-stream.test.ts    |  111 +-
 src/agents/acp-spawn-parent-stream.ts         |  187 +--
 src/agents/acp-spawn.test.ts                  |   27 +-
 src/agents/acp-spawn.ts                       |   18 +-
 .../gateway-cli/run.option-collisions.test.ts |   10 +-
 src/cli/gateway-cli/run.ts                    |   18 +-
 src/commands/doctor-config-audit-scrub.ts     |    4 +-
 src/commands/doctor.e2e-harness.ts            |    4 +
 src/config/io.audit.test-support.ts           |   23 +
 src/config/io.audit.test.ts                   |  132 ++-
 src/config/io.audit.ts                        |  216 +++-
 src/config/io.observe-recovery.test.ts        |   17 +-
 src/config/io.observe-recovery.ts             |    1 -
 src/config/io.observe.ts                      |    2 -
 src/config/io.write.ts                        |    1 -
 src/infra/backup-create.test.ts               |  253 ++++
 src/infra/backup-create.ts                    |   69 +-
 src/infra/backup-volatile-filter.test.ts      |    7 +
 src/infra/fs-safe-advanced.ts                 |    1 +
 src/infra/regular-file.ts                     |    1 -
 src/infra/sqlite-audit-record-store.test.ts   |  120 ++
 src/infra/sqlite-audit-record-store.ts        |  222 ++++
 .../state-migrations.audit-backup.test.ts     |  242 ++++
 src/infra/state-migrations.audit-backup.ts    |  228 ++++
 .../state-migrations.audit-checkpoints.ts     |  273 +++++
 .../state-migrations.audit-coordination.ts    |   25 +
 src/infra/state-migrations.audit-logs.test.ts | 1042 +++++++++++++++++
 src/infra/state-migrations.audit-logs.ts      |  669 +++++++++++
 .../state-migrations.audit-logs.types.ts      |   14 +
 src/infra/state-migrations.audit-records.ts   |   90 ++
 ...tate-migrations.audit-recovery-protocol.ts |  161 +++
 .../state-migrations.audit-recovery.test.ts   |  542 +++++++++
 src/infra/state-migrations.audit-recovery.ts  |  710 +++++++++++
 src/infra/state-migrations.audit-sanitized.ts |   72 ++
 src/infra/state-migrations.doctor.ts          |  151 ++-
 src/infra/state-migrations.test.ts            |   99 ++
 src/infra/state-migrations.types.ts           |    3 +
 src/memory-host-sdk/event-export.ts           |   20 +
 src/memory-host-sdk/event-store.ts            |  359 ++++++
 src/memory-host-sdk/event-types.ts            |   80 ++
 src/memory-host-sdk/events.ts                 |  165 +--
 src/plugin-sdk/memory-core-host-events.ts     |   17 +-
 src/plugin-sdk/memory-host-core.test.ts       |  891 +++++++++++++-
 src/plugin-sdk/memory-host-core.ts            |  429 ++++++-
 .../memory-host-event-export.test.ts          |  223 ++++
 src/plugin-sdk/memory-host-event-export.ts    |  268 +++++
 src/plugin-sdk/memory-host-events.test.ts     |  313 +++--
 src/plugin-sdk/memory-host-events.ts          |    3 +-
 src/plugin-sdk/plugin-state-test-runtime.ts   |    3 +
 src/plugin-state/plugin-state-store.sqlite.ts |  250 +++-
 src/plugin-state/plugin-state-store.test.ts   |   93 ++
 src/plugin-state/plugin-state-store.ts        |  124 ++
 src/plugins/doctor-contract-registry.ts       |   10 +
 src/state/openclaw-agent-db.generated.d.ts    |    9 +
 src/state/openclaw-agent-db.test.ts           |   49 +-
 src/state/openclaw-agent-db.ts                |    3 +-
 src/state/openclaw-agent-schema.generated.ts  |   13 +
 src/state/openclaw-agent-schema.sql           |   13 +
 src/state/openclaw-state-db.generated.d.ts    |    1 +
 src/state/openclaw-state-db.test.ts           |   50 +
 src/state/openclaw-state-db.ts                |   28 +
 src/state/openclaw-state-lease.ts             |   11 +-
 src/state/openclaw-state-schema.generated.ts  |    5 +-
 src/state/openclaw-state-schema.sql           |    5 +-
 src/system-agent/audit.test-support.ts        |   14 +
 src/system-agent/audit.test.ts                |   24 +-
 src/system-agent/audit.ts                     |   51 +-
 src/system-agent/operations-execute.ts        |    4 +-
 src/system-agent/operations.setup.test.ts     |   18 +-
 src/system-agent/operations.test.ts           |   22 +-
 src/system-agent/rescue-channel.live.test.ts  |   13 +-
 src/system-agent/rescue-message.test.ts       |   20 +-
 .../system-agent-first-run-docker-client.ts   |   17 +-
 ...check-database-first-legacy-stores.test.ts |   17 +
 test/scripts/test-projects.test.ts            |    2 +-
 tsdown.config.ts                              |    2 +
 90 files changed, 10449 insertions(+), 715 deletions(-)
 create mode 100644 src/agents/acp-parent-stream-store.sqlite.test-support.ts
 create mode 100644 src/agents/acp-parent-stream-store.sqlite.test.ts
 create mode 100644 src/agents/acp-parent-stream-store.sqlite.ts
 create mode 100644 src/config/io.audit.test-support.ts
 create mode 100644 src/infra/sqlite-audit-record-store.test.ts
 create mode 100644 src/infra/sqlite-audit-record-store.ts
 create mode 100644 src/infra/state-migrations.audit-backup.test.ts
 create mode 100644 src/infra/state-migrations.audit-backup.ts
 create mode 100644 src/infra/state-migrations.audit-checkpoints.ts
 create mode 100644 src/infra/state-migrations.audit-coordination.ts
 create mode 100644 src/infra/state-migrations.audit-logs.test.ts
 create mode 100644 src/infra/state-migrations.audit-logs.ts
 create mode 100644 src/infra/state-migrations.audit-logs.types.ts
 create mode 100644 src/infra/state-migrations.audit-records.ts
 create mode 100644 src/infra/state-migrations.audit-recovery-protocol.ts
 create mode 100644 src/infra/state-migrations.audit-recovery.test.ts
 create mode 100644 src/infra/state-migrations.audit-recovery.ts
 create mode 100644 src/infra/state-migrations.audit-sanitized.ts
 create mode 100644 src/memory-host-sdk/event-export.ts
 create mode 100644 src/memory-host-sdk/event-store.ts
 create mode 100644 src/memory-host-sdk/event-types.ts
 create mode 100644 src/plugin-sdk/memory-host-event-export.test.ts
 create mode 100644 src/plugin-sdk/memory-host-event-export.ts
 create mode 100644 src/system-agent/audit.test-support.ts

diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 001cb093102..10596e14b98 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -166,7 +166,7 @@ ae67c256150b14f1a58738dce0a703071035b86ec26fc344ab03e942253aa72c  module/memory-
 4205ab767b79e740c7c7137079b19b315c85f7f8c748592840f00bbf70a71709  module/memory-core-host-engine-foundation
 cb8dcef652580ca82242d6e9506eda094006c85848f9b16b8b1c1aadff1706a8  module/memory-core-host-engine-qmd
 bbc06f2bb23d9e4a3445744711f691de9f902270e61c9740fd746f222d10fccb  module/memory-core-host-engine-storage
-b3255578cdf355d224d840a57e4ee7e190e60c02cbed1bfff2a222c08c3df3a8  module/memory-core-host-events
+39e86819441281365dedb3d7d59979672bb90196f49206edb50b879bd747c9f0  module/memory-core-host-events
 fe87e7d794bbbdaed3c834b218a787e98c0e69b26b0fac582b0668b8effab9b4  module/memory-core-host-multimodal
 746e155bb06b398749a6a1bfdc1b435b1ec1941dca3854554a912577731218dd  module/memory-core-host-query
 e2377479799d52d8f67dcccf8f499f28a63948b0c03fa6043fc67e476a22ec0d  module/memory-core-host-runtime-cli
@@ -175,7 +175,7 @@ f8eb835f0769eba8324033141ecddb9f45bdb3d3241d2a5959fe8426ba6a2280  module/memory-
 ebbf937b2258487f773b8a6fbd6c648feea96399cae5fbea18ec7d29e027523d  module/memory-core-host-secret
 16bdd82751898ffa98157fd27c86fa0eb9ea415fb8ed703eb4e9b170f0a9501b  module/memory-core-host-status
 646773d8282a2ac6a89101685c406200935ddb3459a2830e820da132fa433b3c  module/memory-host-core
-7d68cbdfa0d5fad1ab32ba3792787daf386bc4ff7975fd5e25117e92563a2897  module/memory-host-events
+f7bde3a0231ac75c128d6ae367d5020de886715fe9edbb2faaf673c6bd168398  module/memory-host-events
 059856bc3671ccba7a2191f47c0295e0a91a374f7048cc2bc22784b389d15182  module/memory-host-files
 ba07f497aa5469915ebb5b6787148ff1f0f267d7e48c48f0c95d32b7dda8d91a  module/memory-host-markdown
 896d315fb78af09effd0af467e2b6e84331272b0123d4132e5b1f2254e80108e  module/memory-host-search
diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md
index 3574190bb44..e55a0e909c2 100644
--- a/docs/tools/acp-agents.md
+++ b/docs/tools/acp-agents.md
@@ -548,10 +548,9 @@ Two ways to start an ACP session:
 </ParamField>
 <ParamField path="streamTo" type='"parent"'>
   `"parent"` streams initial ACP run progress summaries back to the requester
-  session as system events. Accepted responses include `streamLogPath`
-  pointing to a session-scoped JSONL log (`<sessionId>.acp-stream.jsonl`) you
-  can tail for full relay history. Parent progress streams show assistant
-  commentary and ACP status progress by default unless
+  session as system events. OpenClaw records the full relay history in the
+  child agent's SQLite state and removes it with the child session. Parent
+  progress streams show assistant commentary and ACP status progress by default unless
   `streaming.progress.commentary=false`. Discord also defaults parent
   previews to progress mode when no stream mode is configured. Status
   progress still honors `acp.stream.tagVisibility`, so tags such as `plan`
diff --git a/extensions/memory-core/doctor-contract-api.test.ts b/extensions/memory-core/doctor-contract-api.test.ts
index ffea3fcefaf..e0f60fbcc60 100644
--- a/extensions/memory-core/doctor-contract-api.test.ts
+++ b/extensions/memory-core/doctor-contract-api.test.ts
@@ -3,14 +3,16 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { expectDefined } from "@openclaw/normalization-core";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import {
   ensureMemoryIndexSchema,
   loadSqliteVecExtension,
 } from "openclaw/plugin-sdk/memory-core-host-engine-storage";
+import { readMemoryHostEventRecords } from "openclaw/plugin-sdk/memory-host-events";
 import {
   createPluginStateKeyedStoreForTests,
+  getPluginStateCapacityForTests,
+  importPluginStateEntriesForDoctorForTests,
   resetPluginStateStoreForTests,
 } from "openclaw/plugin-sdk/plugin-state-test-runtime";
 import type {
@@ -32,12 +34,18 @@ import {
   shortTermTestState as shortTermTesting,
 } from "./src/test-helpers.js";
 
-function requireStateMigration(index: number) {
-  return expectDefined(stateMigrations[index], `Memory Core state migration ${index}`);
-}
-
 function createDoctorContext(env: NodeJS.ProcessEnv): PluginDoctorStateMigrationContext {
   return {
+    getPluginStateCapacity() {
+      return getPluginStateCapacityForTests("memory-core", env);
+    },
+    importPluginStateEntries(options, entries) {
+      importPluginStateEntriesForDoctorForTests(
+        "memory-core",
+        { ...options, env: options.env ?? env },
+        entries,
+      );
+    },
     openPluginStateKeyedStore<T>(options: OpenKeyedStoreOptions) {
       return createPluginStateKeyedStoreForTests<T>("memory-core", {
         ...options,
@@ -57,6 +65,26 @@ function legacyMemoryIndexMigration() {
   return migration;
 }
 
+function dreamingStateMigration() {
+  const migration = stateMigrations.find(
+    (entry) => entry.id === "memory-core-dreams-json-to-sqlite",
+  );
+  if (!migration) {
+    throw new Error("expected memory-core dreaming state migration");
+  }
+  return migration;
+}
+
+function hostEventsMigration() {
+  const migration = stateMigrations.find(
+    (entry) => entry.id === "memory-core-host-events-jsonl-to-sqlite",
+  );
+  if (!migration) {
+    throw new Error("expected memory-core host events migration");
+  }
+  return migration;
+}
+
 function qmdFileLockMigration() {
   const migration = stateMigrations.find(
     (entry) => entry.id === "memory-core-qmd-file-locks-to-sqlite-leases",
@@ -458,6 +486,628 @@ describe("memory-core doctor dreaming migration", () => {
     };
   }
 
+  it("treats a missing legacy host event directory as no state", async () => {
+    await fs.rm(path.join(workspaceDir, "memory"), { recursive: true });
+    const migration = hostEventsMigration();
+
+    await expect(migration.detectLegacyState(migrationParams())).resolves.toBeNull();
+    await expect(migration.migrateLegacyState(migrationParams())).resolves.toEqual({
+      changes: [],
+      warnings: [],
+    });
+  });
+
+  it("imports legacy memory host events into plugin state", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    await fs.writeFile(
+      eventPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "sqlite policy",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+      "utf8",
+    );
+    const migration = hostEventsMigration();
+    await expect(migration.detectLegacyState(migrationParams())).resolves.toEqual({
+      preview: [expect.stringContaining("Memory Core host events")],
+    });
+    const store = context().openPluginStateKeyedStore<{
+      kind: "event";
+      workspaceKey: string;
+      event: { type: string; query: string };
+      recordedAt: number;
+      sequence: number;
+    }>({ namespace: "memory-host.events", maxEntries: 10_000 });
+    await store.register("runtime-event", {
+      kind: "event",
+      workspaceKey: path.resolve(workspaceDir).replace(/\\/g, "/"),
+      event: {
+        type: "memory.recall.recorded",
+        query: "runtime after upgrade",
+      },
+      recordedAt: Date.parse("2026-07-02T00:00:00.000Z"),
+      sequence: 1,
+    });
+    const result = await migration.migrateLegacyState(migrationParams());
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    const entries = await store.entries();
+    const events = entries
+      .flatMap((entry) => (entry.value.kind === "event" ? [entry.value] : []))
+      .toSorted((left, right) => left.sequence - right.sequence);
+    expect(events.map((entry) => entry.event.query)).toEqual([
+      "sqlite policy",
+      "runtime after upgrade",
+    ]);
+    expect(events[0]?.sequence).toBeLessThan(0);
+    const migratedEntry = entries.find((entry) => entry.value.sequence < 0);
+    expect(migratedEntry?.createdAt).toBe(migratedEntry?.value.sequence);
+    const cursors = await context()
+      .openPluginStateKeyedStore<{ kind: "cursor"; lastSequence: number }>({
+        namespace: "memory-host.event-cursors",
+        maxEntries: 1_000,
+      })
+      .entries();
+    expect(cursors).toHaveLength(1);
+    expect(cursors[0]?.value).toEqual({ kind: "cursor", lastSequence: 1 });
+    await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+  });
+
+  it("keeps identical events recreated by an older writer as a new archive generation", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const event = {
+      type: "memory.recall.recorded",
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query: "repeated after downgrade",
+      resultCount: 0,
+      results: [],
+    };
+    const migration = hostEventsMigration();
+    await fs.writeFile(eventPath, `${JSON.stringify(event)}\n`, "utf8");
+    await migration.migrateLegacyState(migrationParams());
+    await fs.writeFile(eventPath, `${JSON.stringify(event)}\n`, "utf8");
+
+    const repeated = await migration.migrateLegacyState(migrationParams());
+
+    expect(repeated.warnings).toEqual([]);
+    expect(repeated.changes).toEqual([
+      "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+      expect.stringContaining("events.jsonl.migrated.2"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toHaveLength(2);
+    await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+    await expect(fs.access(`${eventPath}.migrated.2`)).resolves.toBeUndefined();
+  });
+
+  it("recovers appends written through an open legacy descriptor after archival", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const event = (query: string) => ({
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query,
+      resultCount: 0,
+      results: [],
+    });
+    await fs.writeFile(eventPath, `${JSON.stringify(event("before claim"))}\n`, "utf8");
+    const oldWriter = await fs.open(eventPath, "a");
+    const migration = hostEventsMigration();
+    try {
+      await migration.migrateLegacyState(migrationParams());
+      await fs.writeFile(eventPath, `${JSON.stringify(event("newer generation"))}\n`, "utf8");
+      await migration.migrateLegacyState(migrationParams());
+      await oldWriter.appendFile(`${JSON.stringify(event("late append"))}\n`, "utf8");
+      await oldWriter.sync();
+    } finally {
+      await oldWriter.close();
+    }
+
+    await expect(migration.detectLegacyState(migrationParams())).resolves.toEqual({
+      preview: [expect.stringContaining("events.jsonl.migrated")],
+    });
+    const recovered = await migration.migrateLegacyState(migrationParams());
+
+    expect(recovered.warnings).toEqual([]);
+    expect(recovered.changes).toEqual([
+      expect.stringContaining("Recovered 1 later Memory Core host event row"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "before claim" },
+      { query: "newer generation" },
+      { query: "late append" },
+    ]);
+    await expect(
+      readMemoryHostEventRecords({ workspaceDir, env, limit: 1 }),
+    ).resolves.toMatchObject([{ query: "late append" }]);
+    await expect(migration.detectLegacyState(migrationParams())).resolves.toBeNull();
+
+    await fs.writeFile(eventPath, `${JSON.stringify(event("after recovery generation"))}\n`);
+    await migration.migrateLegacyState(migrationParams());
+    await expect(
+      readMemoryHostEventRecords({ workspaceDir, env, limit: 1 }),
+    ).resolves.toMatchObject([{ query: "after recovery generation" }]);
+  });
+
+  it("fails closed when a checkpointed host event archive changes other than by append", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const archivedPath = `${eventPath}.migrated`;
+    await fs.writeFile(
+      eventPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "original archive row",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+      "utf8",
+    );
+    const migration = hostEventsMigration();
+    await migration.migrateLegacyState(migrationParams());
+    await fs.writeFile(
+      archivedPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "rewritten archive row",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+      "utf8",
+    );
+
+    const result = await migration.migrateLegacyState(migrationParams());
+
+    expect(result.changes).toEqual([]);
+    expect(result.warnings).toEqual([expect.stringContaining("changed other than by append")]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "original archive row" },
+    ]);
+    await expect(fs.readFile(archivedPath, "utf8")).resolves.toContain("rewritten archive row");
+  });
+
+  it("orders and limits migrated host events by archive generation", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const event = (query: string) => ({
+      type: "memory.recall.recorded",
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query,
+      resultCount: 0,
+      results: [],
+    });
+    const migration = hostEventsMigration();
+    await fs.writeFile(eventPath, `${JSON.stringify(event("older generation"))}\n`, "utf8");
+    await migration.migrateLegacyState(migrationParams());
+    await fs.writeFile(eventPath, `${JSON.stringify(event("newer generation"))}\n`, "utf8");
+    await migration.migrateLegacyState(migrationParams());
+
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "older generation" },
+      { query: "newer generation" },
+    ]);
+    await expect(
+      readMemoryHostEventRecords({ workspaceDir, env, limit: 1 }),
+    ).resolves.toMatchObject([{ query: "newer generation" }]);
+  });
+
+  it("refuses to replay a checkpointless older archive after a newer generation", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const event = (query: string) => ({
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query,
+      resultCount: 0,
+      results: [],
+    });
+    const migration = hostEventsMigration();
+    await fs.writeFile(eventPath, `${JSON.stringify(event("older generation"))}\n`, "utf8");
+    await migration.migrateLegacyState(migrationParams());
+    await context()
+      .openPluginStateKeyedStore({ namespace: "memory-host.events", maxEntries: 10_000 })
+      .clear();
+    await fs.writeFile(eventPath, `${JSON.stringify(event("newer generation"))}\n`, "utf8");
+    await migration.migrateLegacyState(migrationParams());
+    await context()
+      .openPluginStateKeyedStore({
+        namespace: "memory-host.event-migration-checkpoints",
+        maxEntries: 10_000,
+        overflowPolicy: "reject-new",
+      })
+      .clear();
+
+    const replay = await migration.migrateLegacyState(migrationParams());
+
+    expect(replay.changes).toEqual([]);
+    expect(replay.warnings).toEqual([
+      expect.stringContaining(
+        "has no durable checkpoint and later generations are already imported",
+      ),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "newer generation" },
+    ]);
+  });
+
+  it("defers host event import when a source contains invalid rows", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    await fs.writeFile(
+      eventPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "valid before malformed",
+        resultCount: 0,
+        results: [],
+      })}\n${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:01.000Z",
+      })}\n{malformed\n`,
+      "utf8",
+    );
+
+    const result = await hostEventsMigration().migrateLegacyState(migrationParams());
+
+    expect(result.changes).toEqual([]);
+    expect(result.warnings).toEqual([
+      expect.stringContaining("Skipped invalid Memory Core host event"),
+      expect.stringContaining("Skipped malformed Memory Core host event"),
+      expect.stringContaining("invalid rows still require repair"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toEqual([]);
+    await expect(fs.access(eventPath)).resolves.toBeUndefined();
+    await expect(fs.access(`${eventPath}.migrated`)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("does not import newer host event generations before an older source is repaired", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const archivedPath = `${eventPath}.migrated`;
+    const event = (query: string) => ({
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query,
+      resultCount: 0,
+      results: [],
+    });
+    await fs.writeFile(archivedPath, "{malformed\n", "utf8");
+    await fs.writeFile(eventPath, `${JSON.stringify(event("newer generation"))}\n`, "utf8");
+    const migration = hostEventsMigration();
+
+    const blocked = await migration.migrateLegacyState(migrationParams());
+
+    expect(blocked.changes).toEqual([]);
+    expect(blocked.warnings).toEqual([
+      expect.stringContaining("Skipped malformed Memory Core host event"),
+      expect.stringContaining("invalid rows still require repair"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toEqual([]);
+    await expect(fs.access(eventPath)).resolves.toBeUndefined();
+
+    await fs.writeFile(
+      archivedPath,
+      `${JSON.stringify(event("repaired older generation"))}\n`,
+      "utf8",
+    );
+    const repaired = await migration.migrateLegacyState(migrationParams());
+
+    expect(repaired.warnings).toEqual([]);
+    expect(repaired.changes).toEqual([
+      expect.stringContaining("Recovered 1 later Memory Core host event row"),
+      "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "repaired older generation" },
+      { query: "newer generation" },
+    ]);
+  });
+
+  it("imports host events after malformed rows are repaired", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const event = {
+      type: "memory.recall.recorded",
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query: "stable after repair",
+      resultCount: 0,
+      results: [],
+    };
+    await fs.writeFile(eventPath, `{malformed\n${JSON.stringify(event)}\n`, "utf8");
+    const migration = hostEventsMigration();
+
+    await migration.migrateLegacyState(migrationParams());
+    await fs.writeFile(
+      eventPath,
+      `  ${JSON.stringify({
+        results: [],
+        resultCount: 0,
+        query: event.query,
+        timestamp: event.timestamp,
+        type: event.type,
+      })}  \n`,
+      "utf8",
+    );
+    const repaired = await migration.migrateLegacyState(migrationParams());
+
+    expect(repaired.warnings).toEqual([]);
+    expect(repaired.changes).toEqual([
+      "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "stable after repair" },
+    ]);
+    await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+  });
+
+  it("preserves legacy host event append order when timestamps move backward", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const events = [
+      {
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-02T00:00:00.000Z",
+        query: "appended first",
+        resultCount: 0,
+        results: [],
+      },
+      {
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "appended last after clock rollback",
+        resultCount: 0,
+        results: [],
+      },
+    ];
+    await fs.writeFile(eventPath, `${events.map((event) => JSON.stringify(event)).join("\n")}\n`);
+
+    const result = await hostEventsMigration().migrateLegacyState(migrationParams());
+
+    expect(result.warnings).toEqual([]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "appended first" },
+      { query: "appended last after clock rollback" },
+    ]);
+    await expect(
+      readMemoryHostEventRecords({ workspaceDir, env, limit: 1 }),
+    ).resolves.toMatchObject([{ query: "appended last after clock rollback" }]);
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "canonicalizes and deduplicates aliased legacy host event sources",
+    async () => {
+      const workspaceAlias = path.join(rootDir, "workspace-alias");
+      const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+      await fs.symlink(workspaceDir, workspaceAlias);
+      await fs.writeFile(
+        eventPath,
+        `${JSON.stringify({
+          type: "memory.recall.recorded",
+          timestamp: "2026-07-01T00:00:00.000Z",
+          query: "canonical alias",
+          resultCount: 0,
+          results: [],
+        })}\n`,
+        "utf8",
+      );
+      const params = migrationParams({
+        agents: {
+          list: [
+            { id: "main", workspace: workspaceDir },
+            { id: "alias", workspace: workspaceAlias },
+          ],
+        },
+      });
+      const migration = hostEventsMigration();
+
+      await expect(migration.detectLegacyState(params)).resolves.toEqual({
+        preview: [expect.stringContaining("Memory Core host events")],
+      });
+      const result = await migration.migrateLegacyState(params);
+
+      expect(result.warnings).toEqual([]);
+      expect(result.changes).toEqual([
+        "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+        expect.stringContaining("Archived Memory Core host events legacy source"),
+      ]);
+      await expect(
+        readMemoryHostEventRecords({ workspaceDir: workspaceAlias, env }),
+      ).resolves.toMatchObject([{ query: "canonical alias" }]);
+      await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+    },
+  );
+
+  it.runIf(process.platform !== "win32")(
+    "rejects legacy host events beneath symlinked workspace parents",
+    async () => {
+      const externalMemoryDir = await fs.mkdtemp(
+        path.join(os.tmpdir(), "openclaw-memory-core-external-events-"),
+      );
+      const externalEventPath = path.join(externalMemoryDir, ".dreams", "events.jsonl");
+      try {
+        await fs.rm(path.join(workspaceDir, "memory"), { recursive: true });
+        await fs.mkdir(path.dirname(externalEventPath), { recursive: true });
+        await fs.writeFile(
+          externalEventPath,
+          `${JSON.stringify({
+            type: "memory.recall.recorded",
+            timestamp: "2026-07-01T00:00:00.000Z",
+            query: "outside workspace",
+            resultCount: 0,
+            results: [],
+          })}\n`,
+          "utf8",
+        );
+        await fs.symlink(externalMemoryDir, path.join(workspaceDir, "memory"));
+
+        await expect(hostEventsMigration().detectLegacyState(migrationParams())).resolves.toEqual({
+          preview: [expect.stringContaining("requires safe-path repair")],
+        });
+        const result = await hostEventsMigration().migrateLegacyState(migrationParams());
+
+        expect(result.changes).toEqual([]);
+        expect(result.warnings).toEqual([
+          expect.stringContaining("Skipped unsafe Memory Core host event source"),
+        ]);
+        await expect(fs.readFile(externalEventPath, "utf8")).resolves.toContain(
+          "outside workspace",
+        );
+        await expect(fs.access(`${externalEventPath}.migrated`)).rejects.toMatchObject({
+          code: "ENOENT",
+        });
+      } finally {
+        await fs.rm(externalMemoryDir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it("imports the newest retained tail from an oversized legacy host event log", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const events = Array.from({ length: 10_002 }, (_, index) => ({
+      type: "memory.recall.recorded",
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query: `oversized-${index}`,
+      resultCount: 0,
+      results: [],
+    }));
+    await fs.writeFile(eventPath, `${events.map((event) => JSON.stringify(event)).join("\n")}\n`);
+
+    const result = await hostEventsMigration().migrateLegacyState(migrationParams());
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Migrated Memory Core host events -> SQLite plugin state (10000 new row(s))",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    const imported = await readMemoryHostEventRecords({ workspaceDir, env });
+    expect(imported).toHaveLength(10_000);
+    expect(imported[0]).toMatchObject({ query: "oversized-2" });
+    expect(imported.at(-1)).toMatchObject({ query: "oversized-10001" });
+    await context()
+      .openPluginStateKeyedStore({
+        namespace: "memory-host.event-migration-checkpoints",
+        maxEntries: 10_000,
+        overflowPolicy: "reject-new",
+      })
+      .clear();
+    const retriedWithoutCheckpoint =
+      await hostEventsMigration().migrateLegacyState(migrationParams());
+    expect(retriedWithoutCheckpoint.warnings).toEqual([]);
+    const afterCheckpointRetry = await readMemoryHostEventRecords({ workspaceDir, env });
+    expect(afterCheckpointRetry[0]).toMatchObject({ query: "oversized-2" });
+    expect(afterCheckpointRetry.at(-1)).toMatchObject({ query: "oversized-10001" });
+    await fs.writeFile(
+      eventPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-02T00:00:00.000Z",
+        query: "newer recreated generation",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+    );
+    const repeated = await hostEventsMigration().migrateLegacyState(migrationParams());
+    expect(repeated.warnings).toEqual([]);
+    expect(repeated.changes[0]).toContain("1 new row");
+    const afterRepeated = await readMemoryHostEventRecords({ workspaceDir, env });
+    expect(afterRepeated).toHaveLength(10_000);
+    expect(afterRepeated[0]).toMatchObject({ query: "oversized-3" });
+    expect(afterRepeated.at(-1)).toMatchObject({ query: "newer recreated generation" });
+    await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+    await expect(fs.access(`${eventPath}.migrated.2`)).resolves.toBeUndefined();
+  });
+
+  it("leaves legacy host events in place when plugin-wide SQLite capacity is exhausted", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    await fs.writeFile(
+      eventPath,
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-07-01T00:00:00.000Z",
+        query: "sqlite capacity",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+      "utf8",
+    );
+    const params = migrationParams();
+    params.context = {
+      ...params.context,
+      getPluginStateCapacity: () => ({ liveEntries: 50_000, maxEntries: 50_000 }),
+    };
+
+    const result = await hostEventsMigration().migrateLegacyState(params);
+
+    expect(result.changes).toEqual([]);
+    expect(result.warnings).toEqual([expect.stringContaining("no room for its workspace cursor")]);
+    await expect(fs.access(eventPath)).resolves.toBeUndefined();
+    await expect(fs.access(`${eventPath}.migrated`)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("reserves plugin-wide capacity for the migrated workspace cursor and checkpoint", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    const events = Array.from({ length: 3 }, (_, index) => ({
+      type: "memory.recall.recorded",
+      timestamp: "2026-07-01T00:00:00.000Z",
+      query: `capacity-${index}`,
+      resultCount: 0,
+      results: [],
+    }));
+    await fs.writeFile(eventPath, `${events.map((event) => JSON.stringify(event)).join("\n")}\n`);
+    const params = migrationParams();
+    params.context = {
+      ...params.context,
+      getPluginStateCapacity: () => ({ liveEntries: 49_997, maxEntries: 50_000 }),
+    };
+
+    const result = await hostEventsMigration().migrateLegacyState(params);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Migrated Memory Core host events -> SQLite plugin state (1 new row(s))",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    await expect(readMemoryHostEventRecords({ workspaceDir, env })).resolves.toMatchObject([
+      { query: "capacity-2" },
+    ]);
+    const cursors = await context()
+      .openPluginStateKeyedStore<{ kind: "cursor"; lastSequence: number }>({
+        namespace: "memory-host.event-cursors",
+        maxEntries: 1_000,
+      })
+      .entries();
+    expect(cursors).toHaveLength(1);
+    const checkpoints = await context()
+      .openPluginStateKeyedStore({
+        namespace: "memory-host.event-migration-checkpoints",
+        maxEntries: 10_000,
+        overflowPolicy: "reject-new",
+      })
+      .entries();
+    expect(checkpoints).toHaveLength(1);
+  });
+
+  it("retires an empty legacy memory host event source without claiming an import", async () => {
+    const eventPath = path.join(workspaceDir, "memory", ".dreams", "events.jsonl");
+    await fs.writeFile(eventPath, "\n", "utf8");
+
+    const result = await hostEventsMigration().migrateLegacyState(migrationParams());
+
+    expect(result.warnings).toEqual([]);
+    expect(result.changes).toEqual([
+      "Retired empty Memory Core host events legacy source",
+      expect.stringContaining("Archived Memory Core host events legacy source"),
+    ]);
+    const entries = await context()
+      .openPluginStateKeyedStore({ namespace: "memory-host.events", maxEntries: 10_000 })
+      .entries();
+    expect(entries).toEqual([]);
+    await expect(fs.access(`${eventPath}.migrated`)).resolves.toBeUndefined();
+  });
+
   it("imports persistent legacy dreaming state and ignores transient locks", async () => {
     const dreamsDir = path.join(workspaceDir, "memory", ".dreams");
     const dailyPath = path.join(dreamsDir, "daily-ingestion.json");
@@ -542,7 +1192,7 @@ describe("memory-core doctor dreaming migration", () => {
     );
     await fs.writeFile(lockPath, `${process.pid}:${Date.now()}\n`, "utf8");
 
-    const migration = requireStateMigration(0);
+    const migration = dreamingStateMigration();
     const preview = await migration.detectLegacyState(migrationParams());
     expect(preview?.preview).toEqual([
       expect.stringContaining("Memory Core daily ingestion"),
@@ -624,7 +1274,7 @@ describe("memory-core doctor dreaming migration", () => {
     const recallPath = path.join(workspaceDir, "memory", ".dreams", "short-term-recall.json");
     await fs.writeFile(recallPath, "{", "utf8");
 
-    const result = await requireStateMigration(0).migrateLegacyState(migrationParams());
+    const result = await dreamingStateMigration().migrateLegacyState(migrationParams());
 
     expect(result.changes).toEqual([]);
     expect(result.warnings).toEqual([
@@ -666,10 +1316,10 @@ describe("memory-core doctor dreaming migration", () => {
     );
     const config = { agents: { list: [{ id: "main", default: true }] } };
 
-    const preview = await requireStateMigration(0).detectLegacyState(migrationParams(config));
+    const preview = await dreamingStateMigration().detectLegacyState(migrationParams(config));
     expect(preview?.preview).toEqual([expect.stringContaining("Memory Core short-term recall")]);
 
-    const result = await requireStateMigration(0).migrateLegacyState(migrationParams(config));
+    const result = await dreamingStateMigration().migrateLegacyState(migrationParams(config));
 
     expect(result.warnings).toEqual([]);
     expect(result.changes).toEqual([
diff --git a/extensions/memory-core/doctor-contract-api.ts b/extensions/memory-core/doctor-contract-api.ts
index 0bbdcfd5540..c698758ba7d 100644
--- a/extensions/memory-core/doctor-contract-api.ts
+++ b/extensions/memory-core/doctor-contract-api.ts
@@ -6,7 +6,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { DatabaseSync } from "node:sqlite";
 import { reclaimDefinitelyStaleFileLock } from "openclaw/plugin-sdk/file-lock";
-import { resolveUserPath } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
+import { resolveUserPath, root } from "openclaw/plugin-sdk/memory-core-host-engine-foundation";
 import {
   ensureMemoryIndexSchema,
   loadSqliteVecExtension,
@@ -19,10 +19,15 @@ import {
   requireNodeSqlite,
 } from "openclaw/plugin-sdk/memory-core-host-engine-storage";
 import { resolveMemoryDreamingWorkspaces } from "openclaw/plugin-sdk/memory-core-host-status";
+import {
+  normalizeMemoryHostEventRecordForStorage,
+  resolveMemoryHostEventLogPath,
+} from "openclaw/plugin-sdk/memory-host-events";
 import { normalizeAgentId } from "openclaw/plugin-sdk/routing";
 import {
   archiveLegacyStateSource,
   legacyStateFileExists,
+  type PluginDoctorStateMigrationContext,
   type PluginDoctorStateMigration,
 } from "openclaw/plugin-sdk/runtime-doctor";
 import {
@@ -67,6 +72,70 @@ type LegacySource = {
   filePath: string;
 };
 
+type LegacyMemoryHostEventSource =
+  | {
+      kind: "ready";
+      workspaceDir: string;
+      filePath: string;
+      relativePath: string;
+      root: Awaited<ReturnType<typeof root>>;
+      storage: "active" | "claim" | "archive";
+      archiveRelativePath?: string;
+      generationKey?: string;
+    }
+  | {
+      kind: "rejected";
+      workspaceDir: string;
+      filePath: string;
+      reason: string;
+    };
+
+type ReadyLegacyMemoryHostEventSource = Extract<LegacyMemoryHostEventSource, { kind: "ready" }>;
+
+type StoredMemoryHostEvent = {
+  kind: "event";
+  event: NonNullable<ReturnType<typeof normalizeMemoryHostEventRecordForStorage>>;
+  recordedAt: number;
+  sequence: number;
+};
+
+type StoredMemoryHostCursor = {
+  kind: "cursor";
+  lastSequence: number;
+};
+
+type StoredMemoryHostMigrationCheckpoint = {
+  kind: "migration-checkpoint";
+  contentHash: string;
+  recordCount: number;
+  sequenceBase: number;
+  size: number;
+};
+
+const MEMORY_HOST_EVENTS_NAMESPACE = "memory-host.events";
+const MEMORY_HOST_EVENT_CURSORS_NAMESPACE = "memory-host.event-cursors";
+const MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS_NAMESPACE = "memory-host.event-migration-checkpoints";
+// Keep migration aligned with event-store.ts retention so legacy import cannot
+// consume memory-core's plugin-wide budget or starve sibling state namespaces.
+const MAX_MEMORY_HOST_EVENTS = 10_000;
+const MAX_MEMORY_HOST_EVENT_CURSORS = 1_000;
+const MAX_MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS = 10_000;
+const MAX_LEGACY_MEMORY_HOST_EVENT_VALUE_BYTES = 65_536;
+const LEGACY_MEMORY_HOST_SEQUENCE_BASE = Number.MIN_SAFE_INTEGER;
+
+function normalizeMemoryHostWorkspaceKey(workspaceDir: string): string {
+  const resolved = path.resolve(workspaceDir).replace(/\\/g, "/");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function memoryHostWorkspacePrefix(workspaceDir: string): string {
+  return crypto
+    .createHash("sha256")
+    .update(normalizeMemoryHostWorkspaceKey(workspaceDir))
+    .digest("hex")
+    .slice(0, 24);
+}
+
 type LegacyMemorySidecarSource = {
   agentId: string;
   legacyPath: string;
@@ -1175,7 +1244,709 @@ async function migrateSource(source: LegacySource): Promise<number> {
   return await migratePhaseSignals(source);
 }
 
+async function collectLegacyMemoryHostEventSources(
+  config: unknown,
+  env: NodeJS.ProcessEnv,
+): Promise<LegacyMemoryHostEventSource[]> {
+  const sources: LegacyMemoryHostEventSource[] = [];
+  const seenWorkspaces = new Set<string>();
+  for (const workspaceDir of resolveConfiguredWorkspaces(config, env)) {
+    let canonicalWorkspaceDir = path.resolve(workspaceDir);
+    let filePath = resolveMemoryHostEventLogPath(canonicalWorkspaceDir);
+    try {
+      const workspaceRoot = await root(workspaceDir, {
+        hardlinks: "reject",
+        // Legacy doctor import previously read the complete JSONL source.
+        maxBytes: Number.MAX_SAFE_INTEGER,
+        mkdir: false,
+        symlinks: "reject",
+      });
+      canonicalWorkspaceDir = workspaceRoot.rootReal;
+      if (seenWorkspaces.has(canonicalWorkspaceDir)) {
+        continue;
+      }
+      seenWorkspaces.add(canonicalWorkspaceDir);
+      filePath = resolveMemoryHostEventLogPath(canonicalWorkspaceDir);
+      const relativePath = path.relative(canonicalWorkspaceDir, filePath);
+      const directoryRelativePath = path.dirname(relativePath);
+      if (!(await workspaceRoot.exists(directoryRelativePath))) {
+        continue;
+      }
+      const directoryStat = await workspaceRoot.stat(directoryRelativePath);
+      if (!directoryStat.isDirectory) {
+        continue;
+      }
+      const baseName = path.basename(relativePath).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+      const archivePattern = new RegExp(`^${baseName}\\.migrated(?:\\.([2-9]|[1-9][0-9]+))?$`, "u");
+      const claimPattern = new RegExp(
+        `^\\.${baseName}\\.doctor-importing(?:\\.([2-9]|[1-9][0-9]+))?$`,
+        "u",
+      );
+      const entries = await fs.readdir(path.join(workspaceRoot.rootReal, directoryRelativePath));
+      const candidates: Array<{
+        entry: string;
+        storage: "active" | "claim" | "archive";
+        generation: bigint | undefined;
+      }> = [];
+      for (const entry of entries) {
+        if (entry === path.basename(relativePath)) {
+          candidates.push({ entry, storage: "active", generation: undefined });
+          continue;
+        }
+        const claim = claimPattern.exec(entry);
+        if (claim) {
+          candidates.push({ entry, storage: "claim", generation: BigInt(claim[1] ?? "1") });
+          continue;
+        }
+        const archive = archivePattern.exec(entry);
+        if (archive) {
+          candidates.push({ entry, storage: "archive", generation: BigInt(archive[1] ?? "1") });
+        }
+      }
+      candidates.sort((left, right) => {
+        if (left.generation === undefined) {
+          return 1;
+        }
+        if (right.generation === undefined) {
+          return -1;
+        }
+        return left.generation < right.generation ? -1 : left.generation > right.generation ? 1 : 0;
+      });
+      for (const candidate of candidates) {
+        const candidateRelativePath = path.join(directoryRelativePath, candidate.entry);
+        const stat = await workspaceRoot.stat(candidateRelativePath);
+        if (!stat.isFile) {
+          continue;
+        }
+        const generationText = candidate.generation?.toString();
+        const generationKey = generationText?.padStart(20, "0");
+        sources.push({
+          kind: "ready",
+          workspaceDir: canonicalWorkspaceDir,
+          filePath: path.join(canonicalWorkspaceDir, candidateRelativePath),
+          relativePath: candidateRelativePath,
+          root: workspaceRoot,
+          storage: candidate.storage,
+          ...(candidate.storage === "active"
+            ? {}
+            : {
+                archiveRelativePath: `${relativePath}.migrated${candidate.generation === 1n ? "" : `.${candidate.generation}`}`,
+                generationKey,
+              }),
+        });
+      }
+    } catch (error) {
+      const code = (error as { code?: unknown }).code;
+      if (code === "ENOENT" || code === "ENOTDIR" || code === "not-found") {
+        continue;
+      }
+      if (!seenWorkspaces.has(canonicalWorkspaceDir)) {
+        seenWorkspaces.add(canonicalWorkspaceDir);
+      }
+      sources.push({
+        kind: "rejected",
+        workspaceDir: canonicalWorkspaceDir,
+        filePath,
+        reason: String(error),
+      });
+    }
+  }
+  return sources;
+}
+
+async function resolveMemoryHostEventArchivePath(
+  source: ReadyLegacyMemoryHostEventSource,
+): Promise<{ archiveRelativePath: string; claimRelativePath: string; generationKey: string }> {
+  const activeRelativePath = path.relative(
+    source.workspaceDir,
+    resolveMemoryHostEventLogPath(source.workspaceDir),
+  );
+  const directoryPath = path.join(source.root.rootReal, path.dirname(activeRelativePath));
+  const baseName = path.basename(activeRelativePath).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const archivePattern = new RegExp(`^${baseName}\\.migrated(?:\\.([2-9]|[1-9][0-9]+))?$`, "u");
+  const claimPattern = new RegExp(
+    `^\\.${baseName}\\.doctor-importing(?:\\.([2-9]|[1-9][0-9]+))?$`,
+    "u",
+  );
+  let latestGeneration = 0n;
+  for (const entry of await fs.readdir(directoryPath)) {
+    const match = archivePattern.exec(entry) ?? claimPattern.exec(entry);
+    if (!match) {
+      continue;
+    }
+    const generation = BigInt(match[1] ?? "1");
+    if (generation > latestGeneration) {
+      latestGeneration = generation;
+    }
+  }
+  const generation = latestGeneration + 1n;
+  const generationText = generation.toString();
+  if (generationText.length > 20) {
+    throw new RangeError("Memory Core host event archive generation is too large");
+  }
+  const generationSuffix = generation === 1n ? "" : `.${generation}`;
+  return {
+    archiveRelativePath: `${activeRelativePath}.migrated${generationSuffix}`,
+    claimRelativePath: path.join(
+      path.dirname(activeRelativePath),
+      `.${path.basename(activeRelativePath)}.doctor-importing${generationSuffix}`,
+    ),
+    // Fixed-width decimal order keeps key-range reads chronological across archives.
+    generationKey: generationText.padStart(20, "0"),
+  };
+}
+
+function memoryHostMigrationCheckpointKey(source: ReadyLegacyMemoryHostEventSource): string {
+  if (!source.generationKey) {
+    throw new Error(`Missing Memory Core host event archive generation for ${source.filePath}`);
+  }
+  return `${memoryHostWorkspacePrefix(source.workspaceDir)}:archive:${source.generationKey}`;
+}
+
+function memoryHostMigrationSnapshot(raw: string, recordCount: number, sequenceBase: number) {
+  return {
+    kind: "migration-checkpoint" as const,
+    contentHash: crypto.createHash("sha256").update(raw).digest("hex"),
+    recordCount,
+    sequenceBase,
+    size: Buffer.byteLength(raw, "utf8"),
+  };
+}
+
+function isMemoryHostMigrationCheckpoint(
+  value: StoredMemoryHostMigrationCheckpoint | undefined,
+): value is StoredMemoryHostMigrationCheckpoint {
+  return (
+    value?.kind === "migration-checkpoint" &&
+    typeof value.contentHash === "string" &&
+    Number.isSafeInteger(value.recordCount) &&
+    value.recordCount >= 0 &&
+    Number.isSafeInteger(value.sequenceBase) &&
+    Number.isSafeInteger(value.size) &&
+    value.size >= 0
+  );
+}
+
+async function memoryHostEventSourceNeedsMigration(params: {
+  source: ReadyLegacyMemoryHostEventSource;
+  context: PluginDoctorStateMigrationContext;
+}): Promise<boolean> {
+  if (params.source.storage !== "archive") {
+    return true;
+  }
+  const checkpoint = await params.context
+    .openPluginStateKeyedStore<StoredMemoryHostMigrationCheckpoint>({
+      namespace: MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS_NAMESPACE,
+      maxEntries: MAX_MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS,
+      overflowPolicy: "reject-new",
+    })
+    .lookup(memoryHostMigrationCheckpointKey(params.source));
+  if (!isMemoryHostMigrationCheckpoint(checkpoint)) {
+    return true;
+  }
+  const raw = await params.source.root.readText(params.source.relativePath);
+  return (
+    Buffer.byteLength(raw, "utf8") !== checkpoint.size ||
+    crypto.createHash("sha256").update(raw).digest("hex") !== checkpoint.contentHash
+  );
+}
+
+async function finalizeLegacyMemoryHostEventSource(params: {
+  source: ReadyLegacyMemoryHostEventSource;
+  changes: string[];
+  warnings: string[];
+}): Promise<boolean> {
+  if (params.source.storage === "archive") {
+    return true;
+  }
+  const archivedRelativePath = params.source.archiveRelativePath;
+  if (!archivedRelativePath) {
+    throw new Error(`Missing Memory Core host event archive path for ${params.source.filePath}`);
+  }
+  try {
+    await params.source.root.move(params.source.relativePath, archivedRelativePath);
+    params.changes.push(
+      `Archived Memory Core host events legacy source -> ${path.join(params.source.workspaceDir, archivedRelativePath)}`,
+    );
+    return true;
+  } catch (error) {
+    params.warnings.push(
+      `Failed archiving Memory Core host events legacy source: ${String(error)}`,
+    );
+    return false;
+  }
+}
+
+async function restoreClaimedMemoryHostEventSource(params: {
+  source: ReadyLegacyMemoryHostEventSource;
+  activeRelativePath: string;
+  warnings: string[];
+}): Promise<void> {
+  try {
+    if (!(await params.source.root.exists(params.source.relativePath))) {
+      return;
+    }
+    if (!(await params.source.root.exists(params.activeRelativePath))) {
+      await params.source.root.move(params.source.relativePath, params.activeRelativePath);
+      return;
+    }
+    params.warnings.push(
+      `Left claimed Memory Core host events at ${params.source.filePath} because an old writer recreated the active source`,
+    );
+  } catch (error) {
+    params.warnings.push(
+      `Failed restoring claimed Memory Core host events ${params.source.filePath}: ${String(error)}`,
+    );
+  }
+}
+
+async function migrateLegacyMemoryHostEventSource(params: {
+  source: ReadyLegacyMemoryHostEventSource;
+  context: PluginDoctorStateMigrationContext;
+  changes: string[];
+  warnings: string[];
+}): Promise<"completed" | "blocked"> {
+  const activeRelativePath = path.relative(
+    params.source.workspaceDir,
+    resolveMemoryHostEventLogPath(params.source.workspaceDir),
+  );
+  let source = params.source;
+  let restoreNewClaim = false;
+  let claimFinalized = source.storage === "archive";
+  if (source.storage === "active") {
+    const generation = await resolveMemoryHostEventArchivePath(source);
+    await source.root.move(source.relativePath, generation.claimRelativePath);
+    source = {
+      ...source,
+      filePath: path.join(source.workspaceDir, generation.claimRelativePath),
+      relativePath: generation.claimRelativePath,
+      storage: "claim",
+      archiveRelativePath: generation.archiveRelativePath,
+      generationKey: generation.generationKey,
+    };
+    restoreNewClaim = true;
+  }
+
+  try {
+    if (!source.generationKey) {
+      throw new Error(`Missing Memory Core host event generation for ${source.filePath}`);
+    }
+    const warningStart = params.warnings.length;
+    const raw = await source.root.readText(source.relativePath);
+    const prefix = memoryHostWorkspacePrefix(source.workspaceDir);
+    const records: Array<{
+      digest: string;
+      ordinal: number;
+      value: StoredMemoryHostEvent;
+    }> = [];
+    for (const [lineIndex, line] of raw.split(/\r?\n/u).entries()) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+      let event: unknown;
+      try {
+        event = JSON.parse(trimmed) as unknown;
+      } catch (error) {
+        params.warnings.push(
+          `Skipped malformed Memory Core host event at ${source.filePath}:${lineIndex + 1}: ${String(error)}`,
+        );
+        continue;
+      }
+      const normalizedEvent = normalizeMemoryHostEventRecordForStorage(event);
+      if (!normalizedEvent) {
+        params.warnings.push(
+          `Skipped invalid Memory Core host event at ${source.filePath}:${lineIndex + 1}`,
+        );
+        continue;
+      }
+      const canonicalEvent = JSON.stringify(normalizedEvent);
+      const parsedTimestamp = Date.parse(normalizedEvent.timestamp);
+      const recordedAt = Number.isSafeInteger(parsedTimestamp) ? parsedTimestamp : 0;
+      const ordinal = records.length;
+      const digest = crypto.createHash("sha256").update(canonicalEvent).digest("hex");
+      const value: StoredMemoryHostEvent = {
+        kind: "event",
+        event: normalizedEvent,
+        recordedAt,
+        sequence: LEGACY_MEMORY_HOST_SEQUENCE_BASE + ordinal + 1,
+      };
+      if (
+        Buffer.byteLength(JSON.stringify(value), "utf8") > MAX_LEGACY_MEMORY_HOST_EVENT_VALUE_BYTES
+      ) {
+        params.warnings.push(
+          `Skipped oversized Memory Core host event at ${source.filePath}:${lineIndex + 1}`,
+        );
+        continue;
+      }
+      records.push({
+        // Runtime keys use the adjacent `1:` range. Generation plus valid-row
+        // ordinal makes interrupted imports and later raw-archive recovery stable.
+        digest,
+        ordinal,
+        value,
+      });
+    }
+    if (params.warnings.length > warningStart) {
+      params.warnings.push(
+        "Left Memory Core host events legacy source in place because invalid rows still require repair",
+      );
+      return "blocked";
+    }
+
+    const checkpointStore =
+      params.context.openPluginStateKeyedStore<StoredMemoryHostMigrationCheckpoint>({
+        namespace: MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS_NAMESPACE,
+        maxEntries: MAX_MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS,
+        overflowPolicy: "reject-new",
+      });
+    // Plugin-wide shedding is namespace-local. `reject-new` therefore keeps
+    // retained raw-archive checkpoints out of every sibling namespace's
+    // eviction budget and fails before this namespace can rotate its own rows.
+    const checkpointKey = memoryHostMigrationCheckpointKey(source);
+    const checkpointValue = await checkpointStore.lookup(checkpointKey);
+    const previousCheckpoint = isMemoryHostMigrationCheckpoint(checkpointValue)
+      ? checkpointValue
+      : undefined;
+    if (source.storage === "archive" && previousCheckpoint) {
+      const bytes = Buffer.from(raw, "utf8");
+      const prefixHash = crypto
+        .createHash("sha256")
+        .update(bytes.subarray(0, previousCheckpoint.size))
+        .digest("hex");
+      if (
+        bytes.length < previousCheckpoint.size ||
+        prefixHash !== previousCheckpoint.contentHash ||
+        records.length < previousCheckpoint.recordCount
+      ) {
+        params.warnings.push(
+          `Skipped Memory Core host event recovery because ${source.filePath} changed other than by append; left the archive in place`,
+        );
+        return "blocked";
+      }
+    }
+    const firstCandidateOrdinal =
+      source.storage === "archive" && previousCheckpoint ? previousCheckpoint.recordCount : 0;
+    const candidateRecords = records.slice(firstCandidateOrdinal);
+    const store = params.context.openPluginStateKeyedStore<StoredMemoryHostEvent>({
+      namespace: MEMORY_HOST_EVENTS_NAMESPACE,
+      maxEntries: MAX_MEMORY_HOST_EVENTS,
+    });
+    const existingEntries = await store.entries();
+    const existingKeys = new Set(existingEntries.map((entry) => entry.key));
+    const latestLegacySequence = existingEntries.reduce(
+      (latest, entry) =>
+        entry.value.sequence < 0 ? Math.max(latest, entry.value.sequence) : latest,
+      LEGACY_MEMORY_HOST_SEQUENCE_BASE,
+    );
+    const legacyKeyPrefix = `${prefix}:event:0:s:`;
+    const existingByIdentity = new Map<string, (typeof existingEntries)[number]>(
+      existingEntries.flatMap((entry) => {
+        if (!entry.key.startsWith(legacyKeyPrefix) || entry.value.sequence >= 0) {
+          return [];
+        }
+        const parts = entry.key.split(":");
+        return parts.length === 8 ? [[`${parts[5]}:${parts[6]}:${parts[7]}`, entry] as const] : [];
+      }),
+    );
+    const existingSourceBase = candidateRecords.flatMap((record) => {
+      const identity = `${source.generationKey}:${record.ordinal.toString().padStart(16, "0")}:${record.digest}`;
+      const existing = existingByIdentity.get(identity);
+      return existing ? [existing.value.sequence - (record.ordinal + 1)] : [];
+    })[0];
+    const laterGenerationExists = existingEntries.some((entry) => {
+      if (!entry.key.startsWith(legacyKeyPrefix) || entry.value.sequence >= 0) {
+        return false;
+      }
+      const generationKey = entry.key.split(":")[5];
+      return generationKey !== undefined && generationKey > source.generationKey!;
+    });
+    if (
+      source.storage === "archive" &&
+      !previousCheckpoint &&
+      existingSourceBase === undefined &&
+      laterGenerationExists
+    ) {
+      params.warnings.push(
+        `Skipped Memory Core host event recovery because ${source.filePath} has no durable checkpoint and later generations are already imported; left the archive in place`,
+      );
+      return "blocked";
+    }
+    const sourceSequenceBase =
+      previousCheckpoint?.sequenceBase ?? existingSourceBase ?? latestLegacySequence;
+    let nextSequence = latestLegacySequence;
+    const sequencedRecords = candidateRecords.map((record) => {
+      const ordinalKey = record.ordinal.toString().padStart(16, "0");
+      const identity = `${source.generationKey}:${ordinalKey}:${record.digest}`;
+      const existing = existingByIdentity.get(identity);
+      if (existing) {
+        return {
+          ...record,
+          key: existing.key,
+          value: { ...record.value, sequence: existing.value.sequence },
+        };
+      }
+      const sequence = previousCheckpoint
+        ? (nextSequence += 1)
+        : sourceSequenceBase + record.ordinal + 1;
+      const sequenceKey = (sequence - LEGACY_MEMORY_HOST_SEQUENCE_BASE)
+        .toString()
+        .padStart(16, "0");
+      return {
+        ...record,
+        key: `${legacyKeyPrefix}${sequenceKey}:${identity}`,
+        value: { ...record.value, sequence },
+      };
+    });
+    const sourceKeys = new Set(sequencedRecords.map((record) => record.key));
+    if (
+      sequencedRecords.some(
+        (record) => !Number.isSafeInteger(record.value.sequence) || record.value.sequence >= 0,
+      )
+    ) {
+      params.warnings.push(
+        "Skipped Memory Core host event migration because legacy sequence capacity is exhausted; left legacy source in place",
+      );
+      return "blocked";
+    }
+    const nativeCount = existingEntries.filter((entry) => entry.value.sequence >= 0).length;
+    const legacyRetentionLimit = Math.max(0, MAX_MEMORY_HOST_EVENTS - nativeCount);
+    const combinedLegacy = [
+      ...existingEntries
+        .filter((entry) => entry.value.sequence < 0 && !sourceKeys.has(entry.key))
+        .map((entry) => ({ key: entry.key, sequence: entry.value.sequence })),
+      ...sequencedRecords.map((record) => ({
+        key: record.key,
+        sequence: record.value.sequence,
+      })),
+    ].toSorted(
+      (left, right) => left.sequence - right.sequence || left.key.localeCompare(right.key),
+    );
+    const desiredLegacyKeys = new Set(
+      legacyRetentionLimit === 0
+        ? []
+        : combinedLegacy.slice(-legacyRetentionLimit).map((record) => record.key),
+    );
+    let retainedRecords = sequencedRecords.filter((record) => desiredLegacyKeys.has(record.key));
+    const capacity = params.context.getPluginStateCapacity?.();
+    if (!capacity) {
+      params.warnings.push(
+        "Skipped Memory Core host event migration because plugin-wide SQLite capacity is unavailable; left legacy source in place",
+      );
+      return "blocked";
+    }
+    const pluginRemainingCapacity = Math.max(0, capacity.maxEntries - capacity.liveEntries);
+    const cursorStore = params.context.openPluginStateKeyedStore<StoredMemoryHostCursor>({
+      namespace: MEMORY_HOST_EVENT_CURSORS_NAMESPACE,
+      maxEntries: MAX_MEMORY_HOST_EVENT_CURSORS,
+    });
+    const cursorKey = `${prefix}:cursor`;
+    const existingCursor = await cursorStore.lookup(cursorKey);
+    const cursorCapacity = candidateRecords.length > 0 && existingCursor?.kind !== "cursor" ? 1 : 0;
+    if (cursorCapacity > pluginRemainingCapacity) {
+      params.warnings.push(
+        "Skipped Memory Core host event migration because SQLite plugin state has no room for its workspace cursor; left legacy source in place",
+      );
+      return "blocked";
+    }
+    const checkpointCapacity = checkpointValue ? 0 : 1;
+    if (
+      checkpointCapacity > 0 &&
+      (await checkpointStore.entries()).length >= MAX_MEMORY_HOST_EVENT_MIGRATION_CHECKPOINTS
+    ) {
+      // Checkpoints use reject-new and never expire while their raw archives remain.
+      // Stop before import/archive once durable processed-generation capacity is full.
+      params.warnings.push(
+        "Skipped Memory Core host event migration because durable raw-archive checkpoint capacity is exhausted; left legacy source in place",
+      );
+      return "blocked";
+    }
+    if (cursorCapacity + checkpointCapacity > pluginRemainingCapacity) {
+      params.warnings.push(
+        "Skipped Memory Core host event migration because SQLite plugin state has no room for its raw-archive checkpoint; left legacy source in place",
+      );
+      return "blocked";
+    }
+    const importEntries = params.context.importPluginStateEntries;
+    if (candidateRecords.length > 0 && !importEntries) {
+      params.warnings.push(
+        "Skipped Memory Core host event migration because retention-aware SQLite import is unavailable; left legacy source in place",
+      );
+      return "blocked";
+    }
+    let retainedKeys = new Set(retainedRecords.map((record) => record.key));
+    let missing = retainedRecords.filter((record) => !existingKeys.has(record.key));
+    let replaceableLegacyRows = existingEntries.filter(
+      (entry) => entry.value.sequence < 0 && !retainedKeys.has(entry.key),
+    ).length;
+    const reservedCapacity = cursorCapacity + checkpointCapacity;
+    const eventCapacity = pluginRemainingCapacity - reservedCapacity + replaceableLegacyRows;
+    const retentionDeficit = Math.max(0, missing.length - eventCapacity);
+    if (retentionDeficit > 0) {
+      retainedRecords = retainedRecords.slice(Math.min(retentionDeficit, retainedRecords.length));
+      retainedKeys = new Set(retainedRecords.map((record) => record.key));
+      missing = retainedRecords.filter((record) => !existingKeys.has(record.key));
+      replaceableLegacyRows = existingEntries.filter(
+        (entry) => entry.value.sequence < 0 && !retainedKeys.has(entry.key),
+      ).length;
+    }
+    const availableEventCapacity =
+      pluginRemainingCapacity - reservedCapacity + replaceableLegacyRows;
+    if (missing.length > availableEventCapacity) {
+      params.warnings.push(
+        `Skipped Memory Core host event migration because SQLite plugin state has room for ${availableEventCapacity} of ${missing.length} missing rows after reserving its cursor and raw-archive checkpoint; left legacy source in place`,
+      );
+      return "blocked";
+    }
+    if (cursorCapacity > 0) {
+      const lastSequence = existingEntries.reduce(
+        (maximum, entry) =>
+          Number.isSafeInteger(entry.value.sequence)
+            ? Math.max(maximum, entry.value.sequence)
+            : maximum,
+        0,
+      );
+      await cursorStore.register(cursorKey, { kind: "cursor", lastSequence });
+      const registeredCursor = await cursorStore.lookup(cursorKey);
+      if (registeredCursor?.kind !== "cursor") {
+        params.warnings.push(
+          "Skipped Memory Core host event migration because its workspace cursor could not be verified; left legacy source in place",
+        );
+        return "blocked";
+      }
+    }
+    importEntries?.(
+      { namespace: MEMORY_HOST_EVENTS_NAMESPACE, maxEntries: MAX_MEMORY_HOST_EVENTS },
+      missing.map((record) => ({
+        key: record.key,
+        value: record.value,
+        // Negative legacy sequence keeps imported rows older than live runtime rows.
+        createdAt: record.value.sequence,
+      })),
+    );
+    const importedKeys = new Set((await store.entries()).map((entry) => entry.key));
+    const missingKey = retainedRecords.find((record) => !importedKeys.has(record.key))?.key;
+    if (missingKey) {
+      params.warnings.push(
+        `Skipped archiving Memory Core host events because SQLite verification missed ${missingKey}`,
+      );
+      return "blocked";
+    }
+
+    if (source.storage === "archive") {
+      if (missing.length > 0) {
+        params.changes.push(
+          `Recovered ${missing.length} later Memory Core host event row(s) from ${source.filePath}`,
+        );
+      }
+    } else {
+      params.changes.push(
+        records.length === 0
+          ? "Retired empty Memory Core host events legacy source"
+          : `Migrated Memory Core host events -> SQLite plugin state (${missing.length} new row(s))`,
+      );
+      claimFinalized = await finalizeLegacyMemoryHostEventSource({
+        source,
+        changes: params.changes,
+        warnings: params.warnings,
+      });
+      if (!claimFinalized) {
+        params.changes.pop();
+        return "blocked";
+      }
+    }
+    const checkpoint = memoryHostMigrationSnapshot(raw, records.length, sourceSequenceBase);
+    await checkpointStore.register(checkpointKey, checkpoint);
+    const registeredCheckpoint = await checkpointStore.lookup(checkpointKey);
+    if (
+      !isMemoryHostMigrationCheckpoint(registeredCheckpoint) ||
+      registeredCheckpoint.contentHash !== checkpoint.contentHash ||
+      registeredCheckpoint.recordCount !== checkpoint.recordCount ||
+      registeredCheckpoint.sequenceBase !== checkpoint.sequenceBase ||
+      registeredCheckpoint.size !== checkpoint.size
+    ) {
+      params.warnings.push(
+        `Failed verifying Memory Core host event raw-archive checkpoint for ${source.filePath}`,
+      );
+      return "blocked";
+    }
+    if (source.storage !== "archive" && (await source.root.exists(activeRelativePath))) {
+      params.warnings.push(
+        "An old writer recreated the Memory Core host event source; rerun openclaw doctor --fix to import the retained rows",
+      );
+    }
+    return "completed";
+  } finally {
+    if (restoreNewClaim && !claimFinalized) {
+      await restoreClaimedMemoryHostEventSource({
+        source,
+        activeRelativePath,
+        warnings: params.warnings,
+      });
+    }
+  }
+}
+
 export const stateMigrations: PluginDoctorStateMigration[] = [
+  {
+    id: "memory-core-host-events-jsonl-to-sqlite",
+    label: "Memory Core host events",
+    doctorOnly: true,
+    async detectLegacyState(params) {
+      const sources = await collectLegacyMemoryHostEventSources(params.config, params.env);
+      const pending: LegacyMemoryHostEventSource[] = [];
+      for (const source of sources) {
+        if (
+          source.kind === "rejected" ||
+          (await memoryHostEventSourceNeedsMigration({ source, context: params.context }))
+        ) {
+          pending.push(source);
+        }
+      }
+      if (pending.length === 0) {
+        return null;
+      }
+      return {
+        preview: pending.map((source) =>
+          source.kind === "ready"
+            ? `- Memory Core host events: ${source.filePath} -> SQLite plugin state (${MEMORY_HOST_EVENTS_NAMESPACE})`
+            : `- Memory Core host events: ${source.filePath} requires safe-path repair (${source.reason})`,
+        ),
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const blockedWorkspaces = new Set<string>();
+      for (const source of await collectLegacyMemoryHostEventSources(params.config, params.env)) {
+        if (blockedWorkspaces.has(source.workspaceDir)) {
+          continue;
+        }
+        if (source.kind === "rejected") {
+          warnings.push(
+            `Skipped unsafe Memory Core host event source for ${source.workspaceDir}: ${source.reason}`,
+          );
+          blockedWorkspaces.add(source.workspaceDir);
+          continue;
+        }
+        if (!(await memoryHostEventSourceNeedsMigration({ source, context: params.context }))) {
+          continue;
+        }
+        const result = await migrateLegacyMemoryHostEventSource({
+          source,
+          context: params.context,
+          changes,
+          warnings,
+        });
+        if (result === "blocked") {
+          // Archive generations encode append order. A later generation cannot
+          // overtake an older source that still needs repair or durable import.
+          blockedWorkspaces.add(source.workspaceDir);
+        }
+      }
+      return { changes, warnings };
+    },
+  },
   {
     id: "memory-core-dreams-json-to-sqlite",
     label: "Memory Core dreaming state",
diff --git a/extensions/memory-core/src/memory-events.test.ts b/extensions/memory-core/src/memory-events.test.ts
index 44114f51ed8..e46ce61c23a 100644
--- a/extensions/memory-core/src/memory-events.test.ts
+++ b/extensions/memory-core/src/memory-events.test.ts
@@ -2,9 +2,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
+  appendMemoryHostEvent,
   readMemoryHostEventRecords,
   readMemoryHostEvents,
-  resolveMemoryHostEventLogPath,
 } from "openclaw/plugin-sdk/memory-host-events";
 import { describe, expect, it } from "vitest";
 import { writeDailyDreamingPhaseBlock } from "./dreaming-markdown.js";
@@ -193,20 +193,14 @@ describe("memory host event journal integration", () => {
 
   it("keeps legacy dreaming completion events without outcome readable", async () => {
     const workspaceDir = await createTempWorkspace("memory-core-legacy-dream-events-");
-    const eventLogPath = resolveMemoryHostEventLogPath(workspaceDir);
-    await fs.mkdir(path.dirname(eventLogPath), { recursive: true });
-    await fs.writeFile(
-      eventLogPath,
-      `${JSON.stringify({
-        type: "memory.dream.completed",
-        timestamp: "2026-04-05T13:00:00.000Z",
-        phase: "deep",
-        inlinePath: path.join(workspaceDir, "DREAMS.md"),
-        lineCount: 2,
-        storageMode: "inline",
-      })}\n`,
-      "utf8",
-    );
+    await appendMemoryHostEvent(workspaceDir, {
+      type: "memory.dream.completed",
+      timestamp: "2026-04-05T13:00:00.000Z",
+      phase: "deep",
+      inlinePath: path.join(workspaceDir, "DREAMS.md"),
+      lineCount: 2,
+      storageMode: "inline",
+    });
 
     const events = await readMemoryHostEvents({ workspaceDir });
 
diff --git a/extensions/memory-core/src/public-artifacts.test.ts b/extensions/memory-core/src/public-artifacts.test.ts
index 01715810c24..d5813536ad8 100644
--- a/extensions/memory-core/src/public-artifacts.test.ts
+++ b/extensions/memory-core/src/public-artifacts.test.ts
@@ -2,11 +2,9 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import {
-  appendMemoryHostEvent,
-  resolveMemoryHostEventLogPath,
-} from "openclaw/plugin-sdk/memory-host-events";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { appendMemoryHostEvent } from "openclaw/plugin-sdk/memory-host-events";
+import { resetPluginStateStoreForTests } from "openclaw/plugin-sdk/plugin-state-test-runtime";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../api.js";
 import { listMemoryCorePublicArtifacts } from "./public-artifacts.js";
 
@@ -24,8 +22,15 @@ describe("listMemoryCorePublicArtifacts", () => {
     await fs.rm(fixtureRoot, { recursive: true, force: true });
   });
 
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
   it("lists public workspace artifacts with stable kinds", async () => {
     const workspaceDir = path.join(fixtureRoot, "workspace-stable-kinds");
+    vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
     await fs.mkdir(path.join(workspaceDir, "memory", "dreaming"), { recursive: true });
     await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "# Durable Memory\n", "utf8");
     await fs.writeFile(
@@ -38,6 +43,8 @@ describe("listMemoryCorePublicArtifacts", () => {
       "# Dream Report\n",
       "utf8",
     );
+    const eventStoredAt = Date.parse("2026-04-07T09:30:00.000Z");
+    vi.spyOn(Date, "now").mockReturnValue(eventStoredAt);
     await appendMemoryHostEvent(workspaceDir, {
       type: "memory.recall.recorded",
       timestamp: "2026-04-06T12:00:00.000Z",
@@ -52,7 +59,12 @@ describe("listMemoryCorePublicArtifacts", () => {
       },
     };
 
-    await expect(listMemoryCorePublicArtifacts({ cfg })).resolves.toEqual([
+    const artifacts = await listMemoryCorePublicArtifacts({ cfg });
+    const eventArtifact = artifacts.find((artifact) => artifact.kind === "event-log");
+    if (!eventArtifact) {
+      throw new Error("expected memory event export");
+    }
+    expect(artifacts.filter((artifact) => artifact.kind !== "event-log")).toEqual([
       {
         kind: "memory-root",
         workspaceDir,
@@ -77,15 +89,19 @@ describe("listMemoryCorePublicArtifacts", () => {
         agentIds: ["main"],
         contentType: "markdown",
       },
-      {
-        kind: "event-log",
-        workspaceDir,
-        relativePath: "memory/.dreams/events.jsonl",
-        absolutePath: resolveMemoryHostEventLogPath(workspaceDir),
-        agentIds: ["main"],
-        contentType: "json",
-      },
     ]);
+    expect(eventArtifact.relativePath).toMatch(
+      /^memory\/events\/[a-f0-9]{32}\/memory-host-events\.jsonl$/u,
+    );
+    await expect(fs.readFile(eventArtifact.absolutePath, "utf8")).resolves.toBe(
+      `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-04-06T12:00:00.000Z",
+        query: "alpha",
+        resultCount: 0,
+        results: [],
+      })}\n`,
+    );
   });
 
   it("ignores lowercase memory root when only the legacy filename exists", async () => {
diff --git a/extensions/memory-wiki/src/bridge.test.ts b/extensions/memory-wiki/src/bridge.test.ts
index abc1993076f..7dbfa81a2f4 100644
--- a/extensions/memory-wiki/src/bridge.test.ts
+++ b/extensions/memory-wiki/src/bridge.test.ts
@@ -7,10 +7,6 @@ import {
   type MemoryPluginPublicArtifact,
   registerMemoryCapability,
 } from "openclaw/plugin-sdk/memory-host-core";
-import {
-  appendMemoryHostEvent,
-  resolveMemoryHostEventLogPath,
-} from "openclaw/plugin-sdk/memory-host-events";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../api.js";
 import { syncMemoryWikiBridgeSources } from "./bridge.js";
@@ -436,7 +432,7 @@ describe("syncMemoryWikiBridgeSources", () => {
       },
     });
 
-    await appendMemoryHostEvent(workspaceDir, {
+    const eventContent = `${JSON.stringify({
       type: "memory.recall.recorded",
       timestamp: "2026-04-05T12:00:00.000Z",
       query: "bridge events",
@@ -449,13 +445,16 @@ describe("syncMemoryWikiBridgeSources", () => {
           score: 0.8,
         },
       ],
-    });
+    })}\n`;
+    const eventPath = path.join(workspaceDir, "memory", "events", "memory-host-events.jsonl");
+    await fs.mkdir(path.dirname(eventPath), { recursive: true });
+    await fs.writeFile(eventPath, eventContent, "utf8");
     registerBridgeArtifacts([
       {
         kind: "event-log",
         workspaceDir,
-        relativePath: "memory/.dreams/events.jsonl",
-        absolutePath: resolveMemoryHostEventLogPath(workspaceDir),
+        relativePath: "memory/events/memory-host-events.jsonl",
+        absolutePath: eventPath,
         agentIds: ["main"],
         contentType: "json",
       },
diff --git a/extensions/memory-wiki/src/source-page-shared.ts b/extensions/memory-wiki/src/source-page-shared.ts
index cc09dc84b93..52d537d13ad 100644
--- a/extensions/memory-wiki/src/source-page-shared.ts
+++ b/extensions/memory-wiki/src/source-page-shared.ts
@@ -36,6 +36,7 @@ export async function writeImportedSourcePage(params: {
   vaultRoot: string;
   syncKey: string;
   sourcePath: string;
+  sourceContent?: string;
   sourceUpdatedAtMs: number;
   sourceSize: number;
   renderFingerprint: string;
@@ -70,7 +71,7 @@ export async function writeImportedSourcePage(params: {
   });
   const created = !pageStat;
   const updatedAt = timestampMsToIsoString(params.sourceUpdatedAtMs) ?? new Date().toISOString();
-  const raw = await fs.readFile(params.sourcePath, "utf8");
+  const raw = params.sourceContent ?? (await fs.readFile(params.sourcePath, "utf8"));
   const rendered = params.buildRendered(raw, updatedAt);
   const existing = pageStat ? await readExistingImportedSourcePage(vault, params.pagePath) : "";
   const nextRendered = existing ? preserveHumanNotesBlock(rendered, existing) : rendered;
diff --git a/package.json b/package.json
index c2560672fe7..28a708b7aab 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
   "openclaw": {
     "schemaVersions": {
       "state": 4,
-      "agent": 11
+      "agent": 12
     }
   },
   "description": "Multi-channel AI gateway with extensible messaging integrations",
diff --git a/scripts/check-database-first-legacy-stores.mjs b/scripts/check-database-first-legacy-stores.mjs
index b485fcf39a0..173527c69fd 100644
--- a/scripts/check-database-first-legacy-stores.mjs
+++ b/scripts/check-database-first-legacy-stores.mjs
@@ -126,7 +126,7 @@ const legacyStorePatterns = [
   /\b(?:crestodian|openclaw)\/rescue-pending\/[^"'`]*\.json\b/u,
   /\bcron\/(?:runs\/[^"'`]+\.jsonl|jobs\.json|jobs-state\.json)\b/u,
   /\b(?:process-leases|session-toggles|known-users|msteams-conversations|msteams-polls|msteams-sso-tokens|bot-storage|sync-store|thread-bindings|inbound-dedupe|startup-verification|storage-meta|crypto-idb-snapshot|command-deploy-cache|plugin-binding-approvals|plugins\/installs|config-health|port-guard|restart-sentinel|gateway-restart-intent|gateway-supervisor-restart-handoff)\.json\b/u,
-  /\b(?:calls|ref-index|audit\/file-transfer|audit\/openclaw)\.jsonl\b/u,
+  /\b(?:calls|ref-index|config-audit|audit\/(?:file-transfer|openclaw|system-agent|crestodian))\.jsonl\b/u,
   /\b(?:reply-cache|sent-echoes|events|claims)\.jsonl\b/u,
   /\bplugin-state\/state\.sqlite\b/u,
   /\btasks\/(?:runs\.sqlite|flows\/registry\.sqlite)\b/u,
diff --git a/scripts/plugin-sdk-surface-report.mjs b/scripts/plugin-sdk-surface-report.mjs
index d0a003e649b..16af5621b8f 100644
--- a/scripts/plugin-sdk-surface-report.mjs
+++ b/scripts/plugin-sdk-surface-report.mjs
@@ -265,9 +265,10 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
       // +81: meeting-runtime barrel: browser meeting-bot core behind MeetingPlatformAdapter.
       // +3: question-gateway-runtime resolver plus request/result types.
       // +1: async memory prompt preparation registration.
+      // +1: canonical memory host event normalization for SQLite storage.
       // +4: gateway-backed harness question runner, claim/cancel helpers, and caller type.
       // Harvest: internal question runtime exports -2.
-      8155,
+      8156,
       env,
     ),
     publicFunctionExports: readPluginSdkSurfaceBudgetEnv(
@@ -303,9 +304,10 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
       // +32: meeting-runtime barrel: browser meeting-bot core behind MeetingPlatformAdapter.
       // +1: question-gateway-runtime resolver.
       // +1: async memory prompt preparation registration.
+      // +1: canonical memory host event normalization for SQLite storage.
       // +3: gateway-backed harness question runner and claim/cancel helpers.
       // Harvest: internal question runtime callable -1.
-      4537,
+      4538,
       env,
     ),
     publicDeprecatedExports: readPluginSdkSurfaceBudgetEnv(
@@ -330,8 +332,9 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
     publicWildcardReexports: readPluginSdkSurfaceBudgetEnv(
       "OPENCLAW_PLUGIN_SDK_MAX_PUBLIC_WILDCARD_REEXPORTS",
       // Used-union narrowing removes 103 wildcard re-exports.
-      // Harvest: freeze the compat config-schema barrel to explicit exports -1.
-      104,
+      // Harvest: freeze the compat config-schema barrel to explicit exports -1;
+      // retire the Memory Core facade's event-store wildcard -1.
+      103,
       env,
     ),
   };
diff --git a/src/agents/acp-parent-stream-store.sqlite.test-support.ts b/src/agents/acp-parent-stream-store.sqlite.test-support.ts
new file mode 100644
index 00000000000..c8043334a69
--- /dev/null
+++ b/src/agents/acp-parent-stream-store.sqlite.test-support.ts
@@ -0,0 +1,25 @@
+import { executeSqliteQuerySync, getNodeSqliteKysely } from "../infra/kysely-sync.js";
+import type { DB as OpenClawAgentKyselyDatabase } from "../state/openclaw-agent-db.generated.js";
+import {
+  openOpenClawAgentDatabase,
+  type OpenClawAgentDatabaseOptions,
+} from "../state/openclaw-agent-db.js";
+import type { AcpParentStreamEvent } from "./acp-parent-stream-store.sqlite.js";
+
+type AcpParentStreamDatabase = Pick<OpenClawAgentKyselyDatabase, "acp_parent_stream_events">;
+
+export function listAcpParentStreamEventsForTest(
+  options: OpenClawAgentDatabaseOptions & { sessionId: string; runId: string },
+): AcpParentStreamEvent[] {
+  const database = openOpenClawAgentDatabase(options);
+  const db = getNodeSqliteKysely<AcpParentStreamDatabase>(database.db);
+  return executeSqliteQuerySync(
+    database.db,
+    db
+      .selectFrom("acp_parent_stream_events")
+      .select("event_json")
+      .where("session_id", "=", options.sessionId)
+      .where("run_id", "=", options.runId)
+      .orderBy("seq", "asc"),
+  ).rows.map((row) => JSON.parse(row.event_json) as AcpParentStreamEvent);
+}
diff --git a/src/agents/acp-parent-stream-store.sqlite.test.ts b/src/agents/acp-parent-stream-store.sqlite.test.ts
new file mode 100644
index 00000000000..cd7bd53e0f2
--- /dev/null
+++ b/src/agents/acp-parent-stream-store.sqlite.test.ts
@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { executeSqliteQuerySync, getNodeSqliteKysely } from "../infra/kysely-sync.js";
+import type { DB as OpenClawAgentKyselyDatabase } from "../state/openclaw-agent-db.generated.js";
+import {
+  closeOpenClawAgentDatabasesForTest,
+  runOpenClawAgentWriteTransaction,
+} from "../state/openclaw-agent-db.js";
+import { withTempDir } from "../test-helpers/temp-dir.js";
+import { recordAcpParentStreamEvents } from "./acp-parent-stream-store.sqlite.js";
+import { listAcpParentStreamEventsForTest } from "./acp-parent-stream-store.sqlite.test-support.js";
+
+describe("ACP parent stream SQLite store", () => {
+  afterEach(() => {
+    closeOpenClawAgentDatabasesForTest();
+  });
+
+  it("orders run events and removes them with the child session", async () => {
+    await withTempDir({ prefix: "openclaw-acp-parent-stream-" }, async (stateDir) => {
+      const options = {
+        agentId: "codex",
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      };
+      runOpenClawAgentWriteTransaction((database) => {
+        const db = getNodeSqliteKysely<Pick<OpenClawAgentKyselyDatabase, "sessions">>(database.db);
+        executeSqliteQuerySync(
+          database.db,
+          db.insertInto("sessions").values({
+            session_id: "session-1",
+            session_key: "agent:codex:acp:child",
+            session_scope: "conversation",
+            created_at: 1,
+            updated_at: 1,
+          }),
+        );
+      }, options);
+
+      recordAcpParentStreamEvents({
+        ...options,
+        sessionId: "session-1",
+        runId: "run-1",
+        events: [
+          { createdAt: 10, event: { kind: "assistant_delta", delta: "one" } },
+          { createdAt: 11, event: { kind: "lifecycle", phase: "end" } },
+        ],
+      });
+
+      expect(
+        listAcpParentStreamEventsForTest({ ...options, sessionId: "session-1", runId: "run-1" }),
+      ).toEqual([
+        { kind: "assistant_delta", delta: "one" },
+        { kind: "lifecycle", phase: "end" },
+      ]);
+
+      runOpenClawAgentWriteTransaction((database) => {
+        const db = getNodeSqliteKysely<Pick<OpenClawAgentKyselyDatabase, "sessions">>(database.db);
+        executeSqliteQuerySync(
+          database.db,
+          db.deleteFrom("sessions").where("session_id", "=", "session-1"),
+        );
+      }, options);
+      expect(
+        listAcpParentStreamEventsForTest({ ...options, sessionId: "session-1", runId: "run-1" }),
+      ).toEqual([]);
+    });
+  });
+
+  it("drops unserializable events without blocking later diagnostics", async () => {
+    await withTempDir({ prefix: "openclaw-acp-parent-stream-invalid-" }, async (stateDir) => {
+      const options = {
+        agentId: "codex",
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      };
+      runOpenClawAgentWriteTransaction((database) => {
+        const db = getNodeSqliteKysely<Pick<OpenClawAgentKyselyDatabase, "sessions">>(database.db);
+        executeSqliteQuerySync(
+          database.db,
+          db.insertInto("sessions").values({
+            session_id: "session-1",
+            session_key: "agent:codex:acp:invalid",
+            session_scope: "conversation",
+            created_at: 1,
+            updated_at: 1,
+          }),
+        );
+      }, options);
+      const circular: Record<string, unknown> = { kind: "circular" };
+      circular.self = circular;
+
+      recordAcpParentStreamEvents({
+        ...options,
+        sessionId: "session-1",
+        runId: "run-1",
+        events: [
+          { createdAt: 10, event: { toJSON: () => undefined } },
+          { createdAt: 11, event: circular },
+          { createdAt: 12, event: { kind: "lifecycle", phase: "end" } },
+        ],
+      });
+
+      expect(
+        listAcpParentStreamEventsForTest({ ...options, sessionId: "session-1", runId: "run-1" }),
+      ).toEqual([{ kind: "lifecycle", phase: "end" }]);
+    });
+  });
+});
diff --git a/src/agents/acp-parent-stream-store.sqlite.ts b/src/agents/acp-parent-stream-store.sqlite.ts
new file mode 100644
index 00000000000..5cdd003fa3f
--- /dev/null
+++ b/src/agents/acp-parent-stream-store.sqlite.ts
@@ -0,0 +1,77 @@
+// ACP parent-stream diagnostics live with their child session in the per-agent database.
+import {
+  executeSqliteQuerySync,
+  executeSqliteQueryTakeFirstSync,
+  getNodeSqliteKysely,
+} from "../infra/kysely-sync.js";
+import type { DB as OpenClawAgentKyselyDatabase } from "../state/openclaw-agent-db.generated.js";
+import {
+  runOpenClawAgentWriteTransaction,
+  type OpenClawAgentDatabaseOptions,
+} from "../state/openclaw-agent-db.js";
+
+type AcpParentStreamDatabase = Pick<OpenClawAgentKyselyDatabase, "acp_parent_stream_events">;
+
+export type AcpParentStreamEvent = Record<string, unknown>;
+
+function getAcpParentStreamKysely(database: import("node:sqlite").DatabaseSync) {
+  return getNodeSqliteKysely<AcpParentStreamDatabase>(database);
+}
+
+function normalizeSqliteNumber(value: number | bigint): number {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+
+/** Records one ordered batch in the same synchronous commit section as sequence allocation. */
+export function recordAcpParentStreamEvents(
+  options: OpenClawAgentDatabaseOptions & {
+    sessionId: string;
+    runId: string;
+    events: Array<{ event: AcpParentStreamEvent; createdAt: number }>;
+  },
+): void {
+  if (options.events.length === 0) {
+    return;
+  }
+  const prepared = options.events.flatMap((entry) => {
+    try {
+      const eventJson = JSON.stringify(entry.event);
+      if (eventJson !== undefined) {
+        return [{ eventJson, createdAt: entry.createdAt }];
+      }
+    } catch {
+      // One malformed diagnostic must not poison later valid events or retries.
+    }
+    return [];
+  });
+  if (prepared.length === 0) {
+    return;
+  }
+  runOpenClawAgentWriteTransaction((database) => {
+    const db = getAcpParentStreamKysely(database.db);
+    const row = executeSqliteQueryTakeFirstSync(
+      database.db,
+      db
+        .selectFrom("acp_parent_stream_events")
+        .select((eb) => eb.fn.max<number | bigint>("seq").as("max_seq"))
+        .where("session_id", "=", options.sessionId)
+        .where("run_id", "=", options.runId),
+    );
+    const firstSeq =
+      row?.max_seq === null || row?.max_seq === undefined
+        ? 0
+        : normalizeSqliteNumber(row.max_seq) + 1;
+    executeSqliteQuerySync(
+      database.db,
+      db.insertInto("acp_parent_stream_events").values(
+        prepared.map((entry, index) => ({
+          session_id: options.sessionId,
+          run_id: options.runId,
+          seq: firstSeq + index,
+          event_json: entry.eventJson,
+          created_at: entry.createdAt,
+        })),
+      ),
+    );
+  }, options);
+}
diff --git a/src/agents/acp-spawn-parent-stream.test.ts b/src/agents/acp-spawn-parent-stream.test.ts
index 5b3fb1bf0e6..0fca9a5747f 100644
--- a/src/agents/acp-spawn-parent-stream.test.ts
+++ b/src/agents/acp-spawn-parent-stream.test.ts
@@ -1,13 +1,11 @@
-/** Tests ACP child-to-parent stream relay notices, routing, and log path resolution. */
+/** Tests ACP child-to-parent stream relay notices and routing. */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { mergeMockedModule } from "../test-utils/vitest-module-mocks.js";
 
 const enqueueSystemEventMock = vi.fn();
 const requestHeartbeatMock = vi.fn();
-const readAcpSessionEntryMock = vi.fn();
-const resolveSessionFilePathMock = vi.fn();
-const resolveSessionFilePathOptionsMock = vi.fn();
+const recordAcpParentStreamEventsMock = vi.fn();
 
 vi.mock("../infra/system-events.js", () => ({
   enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
@@ -24,32 +22,18 @@ vi.mock("../infra/heartbeat-wake.js", async () => {
   );
 });
 
-vi.mock("../acp/runtime/session-meta.js", async () => {
+vi.mock("./acp-parent-stream-store.sqlite.js", async () => {
   return await mergeMockedModule(
-    await vi.importActual<typeof import("../acp/runtime/session-meta.js")>(
-      "../acp/runtime/session-meta.js",
+    await vi.importActual<typeof import("./acp-parent-stream-store.sqlite.js")>(
+      "./acp-parent-stream-store.sqlite.js",
     ),
     () => ({
-      readAcpSessionEntry: (...args: unknown[]) => readAcpSessionEntryMock(...args),
-    }),
-  );
-});
-
-vi.mock("../config/sessions/paths.js", async () => {
-  return await mergeMockedModule(
-    await vi.importActual<typeof import("../config/sessions/paths.js")>(
-      "../config/sessions/paths.js",
-    ),
-    () => ({
-      resolveSessionFilePath: (...args: unknown[]) => resolveSessionFilePathMock(...args),
-      resolveSessionFilePathOptions: (...args: unknown[]) =>
-        resolveSessionFilePathOptionsMock(...args),
+      recordAcpParentStreamEvents: (...args: unknown[]) => recordAcpParentStreamEventsMock(...args),
     }),
   );
 });
 
 let emitAgentEvent: typeof import("../infra/agent-events.js").emitAgentEvent;
-let resolveAcpSpawnStreamLogPath: typeof import("./acp-spawn-parent-stream.js").resolveAcpSpawnStreamLogPath;
 let startAcpSpawnParentStreamRelay: typeof import("./acp-spawn-parent-stream.js").startAcpSpawnParentStreamRelay;
 
 const progressCommentaryDeliveryContext = {
@@ -103,17 +87,14 @@ function firstMockCall(
 describe("startAcpSpawnParentStreamRelay", () => {
   beforeAll(async () => {
     ({ emitAgentEvent } = await import("../infra/agent-events.js"));
-    ({ resolveAcpSpawnStreamLogPath, startAcpSpawnParentStreamRelay } =
-      await import("./acp-spawn-parent-stream.js"));
+    ({ startAcpSpawnParentStreamRelay } = await import("./acp-spawn-parent-stream.js"));
   });
 
   beforeEach(() => {
     enqueueSystemEventMock.mockClear();
     requestHeartbeatMock.mockClear();
-    readAcpSessionEntryMock.mockReset();
-    resolveSessionFilePathMock.mockReset();
-    resolveSessionFilePathOptionsMock.mockReset();
-    resolveSessionFilePathOptionsMock.mockImplementation((value: unknown) => value);
+    recordAcpParentStreamEventsMock.mockReset();
+    recordAcpParentStreamEventsMock.mockImplementation(() => undefined);
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-03-04T01:00:00.000Z"));
   });
@@ -222,6 +203,50 @@ describe("startAcpSpawnParentStreamRelay", () => {
     relay.dispose();
   });
 
+  it("backs off and caps SQLite diagnostic retries", () => {
+    recordAcpParentStreamEventsMock
+      .mockImplementationOnce(() => {
+        throw new Error("database unavailable");
+      })
+      .mockImplementation(() => undefined);
+    const relay = startAcpSpawnParentStreamRelay({
+      runId: "run-diagnostic-retry",
+      parentSessionKey: "agent:main:main",
+      childSessionKey: "agent:codex:acp:diagnostic-retry",
+      childSessionId: "session-diagnostic-retry",
+      agentId: "codex",
+      streamFlushMs: 120_000,
+      noOutputNoticeMs: 120_000,
+    });
+
+    emitAgentEvent({
+      runId: "run-diagnostic-retry",
+      stream: "assistant",
+      data: { delta: "first" },
+    });
+    vi.advanceTimersByTime(1_000);
+    expect(recordAcpParentStreamEventsMock).toHaveBeenCalledTimes(1);
+
+    for (let index = 0; index < 300; index += 1) {
+      emitAgentEvent({
+        runId: "run-diagnostic-retry",
+        stream: "assistant",
+        data: { delta: `event-${index}` },
+      });
+    }
+    expect(recordAcpParentStreamEventsMock).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(1_999);
+    expect(recordAcpParentStreamEventsMock).toHaveBeenCalledTimes(1);
+    vi.advanceTimersByTime(1);
+
+    expect(recordAcpParentStreamEventsMock).toHaveBeenCalledTimes(2);
+    const retried = recordAcpParentStreamEventsMock.mock.calls[1]?.[0] as
+      | { events?: unknown[] }
+      | undefined;
+    expect(retried?.events).toHaveLength(256);
+    relay.dispose();
+  });
+
   it("remaps cron-run parent session keys while relaying stream events", () => {
     const relay = startAcpSpawnParentStreamRelay({
       runId: "run-cron",
@@ -1436,35 +1461,5 @@ describe("startAcpSpawnParentStreamRelay", () => {
     expect(collectedTexts()[1]).toBe(`codex: ${expected}`);
     relay.dispose();
   });
-
-  it("resolves ACP spawn stream log path from session metadata", () => {
-    readAcpSessionEntryMock.mockReturnValue({
-      storePath: "/tmp/openclaw/agents/codex/sessions/sessions.json",
-      entry: {
-        sessionId: "sess-123",
-        sessionFile: "/tmp/openclaw/agents/codex/sessions/sess-123.jsonl",
-      },
-    });
-    resolveSessionFilePathMock.mockReturnValue(
-      "/tmp/openclaw/agents/codex/sessions/sess-123.jsonl",
-    );
-
-    const resolved = resolveAcpSpawnStreamLogPath({
-      childSessionKey: "agent:codex:acp:child-1",
-    });
-
-    expect(resolved).toBe("/tmp/openclaw/agents/codex/sessions/sess-123.acp-stream.jsonl");
-    expect(readAcpSessionEntryMock).toHaveBeenCalledWith({
-      sessionKey: "agent:codex:acp:child-1",
-    });
-    expect(resolveSessionFilePathMock).toHaveBeenCalledTimes(1);
-    const [sessionId, entry, options] = firstMockCall(
-      resolveSessionFilePathMock,
-      "session file path resolution",
-    ) as [string, { sessionId?: unknown }, { storePath?: unknown }];
-    expect(sessionId).toBe("sess-123");
-    expect(entry.sessionId).toBe("sess-123");
-    expect(options.storePath).toBe("/tmp/openclaw/agents/codex/sessions/sessions.json");
-  });
 });
 /* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */
diff --git a/src/agents/acp-spawn-parent-stream.ts b/src/agents/acp-spawn-parent-stream.ts
index ece106808a1..14d06735138 100644
--- a/src/agents/acp-spawn-parent-stream.ts
+++ b/src/agents/acp-spawn-parent-stream.ts
@@ -1,10 +1,7 @@
 /** Relays child ACP session stream updates back into the requester parent session. */
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
 import { asFiniteNumber } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { sliceUtf16Safe, truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
-import { readAcpSessionEntry } from "../acp/runtime/session-meta.js";
 import {
   isAcpTagVisible,
   resolveAcpProjectionSettings,
@@ -14,7 +11,6 @@ import {
   resolveChannelStreamingProgressCommentary,
   type StreamingCompatEntry,
 } from "../channels/streaming.js";
-import { resolveSessionFilePath, resolveSessionFilePathOptions } from "../config/sessions/paths.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { onAgentEvent } from "../infra/agent-events.js";
 import {
@@ -23,13 +19,17 @@ import {
   scopedHeartbeatWakeOptionsForPolicy,
 } from "../infra/event-session-routing.js";
 import { requestHeartbeat } from "../infra/heartbeat-wake.js";
-import { appendRegularFile } from "../infra/regular-file.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
 import { resolveNormalizedAccountEntry } from "../routing/account-lookup.js";
 import { normalizeAccountId } from "../routing/session-key.js";
 import { normalizeAssistantPhase } from "../shared/chat-message-content.js";
 import { recordTaskRunProgressByRunId } from "../tasks/detached-task-runtime.js";
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
+import {
+  recordAcpParentStreamEvents,
+  type AcpParentStreamEvent,
+} from "./acp-parent-stream-store.sqlite.js";
 
 const DEFAULT_STREAM_FLUSH_MS = 2_500;
 const DEFAULT_NO_OUTPUT_NOTICE_MS = 60_000;
@@ -37,6 +37,11 @@ const DEFAULT_NO_OUTPUT_POLL_MS = 15_000;
 const DEFAULT_MAX_RELAY_LIFETIME_MS = 6 * 60 * 60 * 1000;
 const STREAM_BUFFER_MAX_CHARS = 4_000;
 const STREAM_SNIPPET_MAX_CHARS = 220;
+const STREAM_LOG_BATCH_SIZE = 100;
+const STREAM_LOG_FLUSH_MS = 1_000;
+const STREAM_LOG_MAX_PENDING_EVENTS = 256;
+const STREAM_LOG_MAX_RETRY_MS = 30_000;
+const log = createSubsystemLogger("agents/acp-parent-stream");
 
 type AcpParentProgressStreamingConfig = StreamingCompatEntry & {
   accounts?: Record<string, StreamingCompatEntry | undefined>;
@@ -206,46 +211,14 @@ function shouldRelayAcpStatusProgress(params: {
   return isAcpTagVisible(params.projectionSettings, params.tag);
 }
 
-function resolveAcpStreamLogPathFromSessionFile(sessionFile: string, sessionId: string): string {
-  const baseDir = path.dirname(path.resolve(sessionFile));
-  return path.join(baseDir, `${sessionId}.acp-stream.jsonl`);
-}
-
-/** Resolves the JSONL stream log path for an ACP child session when metadata exists. */
-export function resolveAcpSpawnStreamLogPath(params: {
-  childSessionKey: string;
-}): string | undefined {
-  const childSessionKey = normalizeOptionalString(params.childSessionKey);
-  if (!childSessionKey) {
-    return undefined;
-  }
-  const storeEntry = readAcpSessionEntry({
-    sessionKey: childSessionKey,
-  });
-  const sessionId = normalizeOptionalString(storeEntry?.entry?.sessionId);
-  if (!storeEntry || !sessionId) {
-    return undefined;
-  }
-  try {
-    const sessionFile = resolveSessionFilePath(
-      sessionId,
-      storeEntry.entry,
-      resolveSessionFilePathOptions({
-        storePath: storeEntry.storePath,
-      }),
-    );
-    return resolveAcpStreamLogPathFromSessionFile(sessionFile, sessionId);
-  } catch {
-    return undefined;
-  }
-}
-
 /** Starts a bounded parent-session relay for child ACP output and progress notices. */
 export function startAcpSpawnParentStreamRelay(params: {
   runId: string;
   parentSessionKey: string;
   childSessionKey: string;
+  childSessionId?: string;
   agentId: string;
+  env?: NodeJS.ProcessEnv;
   /**
    * Optional `session.mainKey` from the runtime config. Used to remap
    * cron-run parent session keys to the agent's main queue when relaying
@@ -262,7 +235,6 @@ export function startAcpSpawnParentStreamRelay(params: {
    */
   sessionScope?: "per-sender" | "global";
   eventRouting?: EventSessionRoutingPolicy;
-  logPath?: string;
   deliveryContext?: DeliveryContext;
   surfaceUpdates?: boolean;
   streamFlushMs?: number;
@@ -300,67 +272,105 @@ export function startAcpSpawnParentStreamRelay(params: {
 
   const relayLabel = truncate(compactWhitespace(params.agentId), 40) || "ACP child";
   const contextPrefix = `acp-spawn:${runId}`;
-  const logPath = normalizeOptionalString(params.logPath);
-  let logDirReady = false;
-  let pendingLogLines = "";
-  let logFlushScheduled = false;
-  let logWriteChain: Promise<void> = Promise.resolve();
-  const flushLogBuffer = () => {
-    if (!logPath || !pendingLogLines) {
+  const childSessionId = normalizeOptionalString(params.childSessionId);
+  // Delayed flushes must keep the state database selected when the relay started.
+  const stateEnv = { ...(params.env ?? process.env) };
+  const pendingLogEvents: Array<{ event: AcpParentStreamEvent; createdAt: number }> = [];
+  let logFlushTimer: NodeJS.Timeout | undefined;
+  let logFailureWarned = false;
+  let logBufferWarned = false;
+  let consecutiveLogFailures = 0;
+  let disposed = false;
+  const capPendingLogEvents = () => {
+    const overflow = pendingLogEvents.length - STREAM_LOG_MAX_PENDING_EVENTS;
+    if (overflow <= 0) {
       return;
     }
-    const chunk = pendingLogLines;
-    pendingLogLines = "";
-    logWriteChain = logWriteChain
-      .then(async () => {
-        if (!logDirReady) {
-          await mkdir(path.dirname(logPath), {
-            recursive: true,
-          });
-          logDirReady = true;
-        }
-        await appendRegularFile({ filePath: logPath, content: chunk });
-      })
-      .catch(() => {
-        // Best-effort diagnostics; never break relay flow.
+    pendingLogEvents.splice(0, overflow);
+    if (!logBufferWarned) {
+      log.warn("Capped ACP parent stream diagnostic buffer", {
+        runId,
+        childSessionId,
+        maxPendingEvents: STREAM_LOG_MAX_PENDING_EVENTS,
       });
+      logBufferWarned = true;
+    }
   };
-  const scheduleLogFlush = () => {
-    if (!logPath || logFlushScheduled) {
+  const clearLogFlushTimer = () => {
+    if (!logFlushTimer) {
       return;
     }
-    logFlushScheduled = true;
-    queueMicrotask(() => {
-      logFlushScheduled = false;
-      flushLogBuffer();
-    });
+    clearTimeout(logFlushTimer);
+    logFlushTimer = undefined;
   };
-  const writeLogLine = (entry: Record<string, unknown>) => {
-    if (!logPath) {
+  function flushLogEvents(options: { terminal?: boolean } = {}) {
+    clearLogFlushTimer();
+    if (!childSessionId || pendingLogEvents.length === 0) {
       return;
     }
+    const events = pendingLogEvents.splice(0);
     try {
-      pendingLogLines += `${JSON.stringify(entry)}\n`;
-      if (pendingLogLines.length >= 16_384) {
-        flushLogBuffer();
-        return;
+      recordAcpParentStreamEvents({
+        agentId: params.agentId,
+        env: stateEnv,
+        sessionId: childSessionId,
+        runId,
+        events,
+      });
+      logFailureWarned = false;
+      logBufferWarned = false;
+      consecutiveLogFailures = 0;
+    } catch (error) {
+      if (!options.terminal) {
+        pendingLogEvents.unshift(...events);
+        capPendingLogEvents();
+        consecutiveLogFailures += 1;
+        scheduleLogFlush(
+          Math.min(STREAM_LOG_FLUSH_MS * 2 ** consecutiveLogFailures, STREAM_LOG_MAX_RETRY_MS),
+        );
+      }
+      if (!logFailureWarned || options.terminal) {
+        log.warn("Failed to persist ACP parent stream diagnostics", {
+          runId,
+          childSessionId,
+          retrying: !options.terminal,
+          error: String(error),
+        });
+        logFailureWarned = true;
       }
-      scheduleLogFlush();
-    } catch {
-      // Best-effort diagnostics; never break relay flow.
     }
-  };
+  }
+  function scheduleLogFlush(delayMs = STREAM_LOG_FLUSH_MS) {
+    if (disposed || logFlushTimer || pendingLogEvents.length === 0) {
+      return;
+    }
+    logFlushTimer = setTimeout(() => flushLogEvents(), delayMs);
+    logFlushTimer.unref?.();
+  }
   const logEvent = (kind: string, fields?: Record<string, unknown>) => {
-    writeLogLine({
-      ts: new Date().toISOString(),
-      epochMs: Date.now(),
-      runId,
-      parentSessionKey,
-      childSessionKey: params.childSessionKey,
-      agentId: params.agentId,
-      kind,
-      ...fields,
+    if (!childSessionId) {
+      return;
+    }
+    const createdAt = Date.now();
+    pendingLogEvents.push({
+      createdAt,
+      event: {
+        ts: new Date(createdAt).toISOString(),
+        epochMs: createdAt,
+        runId,
+        parentSessionKey,
+        childSessionKey: params.childSessionKey,
+        agentId: params.agentId,
+        kind,
+        ...fields,
+      },
     });
+    capPendingLogEvents();
+    if (consecutiveLogFailures === 0 && pendingLogEvents.length >= STREAM_LOG_BATCH_SIZE) {
+      flushLogEvents();
+      return;
+    }
+    scheduleLogFlush();
   };
   const shouldSurfaceUpdates = params.surfaceUpdates !== false;
   const shouldRelayProgressCommentary = resolveParentProgressCommentary({
@@ -418,7 +428,6 @@ export function startAcpSpawnParentStreamRelay(params: {
     );
   };
 
-  let disposed = false;
   let pendingText = "";
   let pendingProgressKind: string | undefined;
   let replaceableAssistantSnapshot: string | undefined;
@@ -757,8 +766,8 @@ export function startAcpSpawnParentStreamRelay(params: {
     }
     disposed = true;
     clearFlushTimer();
+    flushLogEvents({ terminal: true });
     clearRelayLifetimeTimer();
-    flushLogBuffer();
     clearInterval(noOutputWatcherTimer);
     unsubscribe();
   };
diff --git a/src/agents/acp-spawn.test.ts b/src/agents/acp-spawn.test.ts
index 9d9bb63a4ce..63a6eea7933 100644
--- a/src/agents/acp-spawn.test.ts
+++ b/src/agents/acp-spawn.test.ts
@@ -58,7 +58,6 @@ const hoisted = vi.hoisted(() => {
   const initializeSessionMock = vi.fn();
   const getAcpSessionManagerMock = vi.fn();
   const startAcpSpawnParentStreamRelayMock = vi.fn();
-  const resolveAcpSpawnStreamLogPathMock = vi.fn();
   const loadSessionStoreMock = vi.fn();
   const readAcpSessionMetaMock = vi.fn();
   const resolveStorePathMock = vi.fn();
@@ -150,7 +149,6 @@ const hoisted = vi.hoisted(() => {
     initializeSessionMock,
     getAcpSessionManagerMock,
     startAcpSpawnParentStreamRelayMock,
-    resolveAcpSpawnStreamLogPathMock,
     loadSessionStoreMock,
     readAcpSessionMetaMock,
     resolveStorePathMock,
@@ -229,7 +227,6 @@ vi.mock("../tasks/detached-task-runtime.js", () => ({
 }));
 
 vi.mock("./acp-spawn-parent-stream.js", () => ({
-  resolveAcpSpawnStreamLogPath: hoisted.resolveAcpSpawnStreamLogPathMock,
   startAcpSpawnParentStreamRelay: hoisted.startAcpSpawnParentStreamRelayMock,
 }));
 
@@ -811,9 +808,6 @@ describe("spawnAcpDirect", () => {
     hoisted.startAcpSpawnParentStreamRelayMock
       .mockReset()
       .mockImplementation(() => createRelayHandle());
-    hoisted.resolveAcpSpawnStreamLogPathMock
-      .mockReset()
-      .mockReturnValue("/tmp/sess-main.acp-stream.jsonl");
     hoisted.resolveStorePathMock.mockReset().mockReturnValue("/tmp/codex-sessions.json");
     hoisted.readAcpSessionMetaMock.mockReset().mockReturnValue(undefined);
     hoisted.loadSessionStoreMock.mockReset().mockImplementation(() => {
@@ -2424,7 +2418,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
     if (expectTranscriptPersistence) {
       expectRecordFields(
@@ -2625,7 +2618,6 @@ describe("spawnAcpDirect", () => {
     );
 
     const accepted = expectAcceptedSpawn(result);
-    expect(accepted.streamLogPath).toBe("/tmp/sess-main.acp-stream.jsonl");
     const agentCall = hoisted.callGatewayMock.mock.calls
       .map((call: unknown[]) => call[0] as { method?: string; params?: Record<string, unknown> })
       .find((request) => request.method === "agent");
@@ -2647,7 +2639,7 @@ describe("spawnAcpDirect", () => {
     expectRelayCallFields({
       parentSessionKey: "agent:main:main",
       agentId: "codex",
-      logPath: "/tmp/sess-main.acp-stream.jsonl",
+      childSessionId: "sess-123",
       emitStartNotice: false,
     });
     const relayRuns = hoisted.startAcpSpawnParentStreamRelayMock.mock.calls.map(
@@ -2655,11 +2647,6 @@ describe("spawnAcpDirect", () => {
     );
     expect(relayRuns).toContain(agentCall?.params?.idempotencyKey);
     expect(relayRuns).toContain(accepted.runId);
-    const streamPathInput = expectRecordFields(
-      firstMockCall(hoisted.resolveAcpSpawnStreamLogPathMock, "stream log path resolution")[0],
-      {},
-    );
-    expect(streamPathInput.childSessionKey).toMatch(/^agent:codex:acp:/);
     expect(firstHandle.dispose).toHaveBeenCalledTimes(1);
     expect(firstHandle.notifyStarted).not.toHaveBeenCalled();
     expect(secondHandle.notifyStarted).toHaveBeenCalledTimes(1);
@@ -2724,7 +2711,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBe("/tmp/sess-main.acp-stream.jsonl");
     const agentCall = hoisted.callGatewayMock.mock.calls
       .map((call: unknown[]) => call[0] as { method?: string; params?: Record<string, unknown> })
       .find((request) => request.method === "agent");
@@ -2735,7 +2721,7 @@ describe("spawnAcpDirect", () => {
     expectRelayCallFields({
       parentSessionKey: "agent:main:subagent:parent",
       agentId: "codex",
-      logPath: "/tmp/sess-main.acp-stream.jsonl",
+      childSessionId: "sess-123",
       deliveryContext: {
         channel: "discord",
         to: "channel:parent-channel",
@@ -2812,7 +2798,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2843,7 +2828,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2877,7 +2861,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2933,7 +2916,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2963,7 +2945,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2982,7 +2963,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -2999,7 +2979,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -3020,7 +2999,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
@@ -3053,7 +3031,6 @@ describe("spawnAcpDirect", () => {
 
     const accepted = expectAcceptedSpawn(result);
     expect(accepted.mode).toBe("run");
-    expect(accepted.streamLogPath).toBeUndefined();
     expect(hoisted.startAcpSpawnParentStreamRelayMock).not.toHaveBeenCalled();
   });
 
diff --git a/src/agents/acp-spawn.ts b/src/agents/acp-spawn.ts
index 0d1172e3d33..5157c6f48f5 100644
--- a/src/agents/acp-spawn.ts
+++ b/src/agents/acp-spawn.ts
@@ -77,7 +77,6 @@ import { listTasksForOwnerKey } from "../tasks/runtime-internal.js";
 import { deliveryContextFromSession, normalizeDeliveryContext } from "../utils/delivery-context.js";
 import {
   type AcpSpawnParentRelayHandle,
-  resolveAcpSpawnStreamLogPath,
   startAcpSpawnParentStreamRelay,
 } from "./acp-spawn-parent-stream.js";
 import { listAgentIds, resolveAgentConfig, resolveDefaultAgentId } from "./agent-scope.js";
@@ -206,7 +205,6 @@ type SpawnAcpResultFields = {
   mode?: SpawnAcpMode;
   runTimeoutSeconds?: number;
   inlineDelivery?: boolean;
-  streamLogPath?: string;
   note?: string;
 };
 
@@ -1478,6 +1476,7 @@ export async function spawnAcpDirect(
 
   let binding: SessionBindingRecord | null = null;
   let sessionCreated = false;
+  let childSessionId: string | undefined;
   let initializedRuntime: AcpSpawnRuntimeCloseHandle | undefined;
   try {
     await callGateway({
@@ -1504,6 +1503,7 @@ export async function spawnAcpDirect(
       cwd: runtimeCwd,
     });
     initializedRuntime = initializedSession.runtimeCloseHandle;
+    childSessionId = initializedSession.sessionId;
 
     if (preparedBinding) {
       ({ binding } = await bindPreparedAcpThread({
@@ -1548,12 +1548,6 @@ export async function spawnAcpDirect(
     requesterSessionKey: requesterInternalKey,
     agentId: targetAgentId,
   });
-  const streamLogPath =
-    effectiveStreamToParent && parentSessionKey
-      ? resolveAcpSpawnStreamLogPath({
-          childSessionKey: sessionKey,
-        })
-      : undefined;
   const parentAgentId = parentSessionKey
     ? resolveAgentIdFromSessionKey(parentSessionKey)
     : undefined;
@@ -1571,6 +1565,7 @@ export async function spawnAcpDirect(
       : undefined;
 
   let parentRelay: AcpSpawnParentRelayHandle | undefined;
+  const parentRelayStateEnv = { ...process.env };
   const parentEventRouting = parentSessionKey
     ? resolveEventSessionRoutingPolicy({ cfg, sessionKey: parentSessionKey })
     : undefined;
@@ -1580,11 +1575,12 @@ export async function spawnAcpDirect(
       runId: childIdem,
       parentSessionKey,
       childSessionKey: sessionKey,
+      childSessionId,
       agentId: targetAgentId,
+      env: parentRelayStateEnv,
       mainKey: cfg.session?.mainKey,
       sessionScope: cfg.session?.scope,
       eventRouting: parentEventRouting,
-      logPath: streamLogPath,
       deliveryContext: parentDeliveryCtx,
       emitStartNotice: false,
       cfg,
@@ -1640,11 +1636,12 @@ export async function spawnAcpDirect(
         runId: childRunId,
         parentSessionKey,
         childSessionKey: sessionKey,
+        childSessionId,
         agentId: targetAgentId,
+        env: parentRelayStateEnv,
         mainKey: cfg.session?.mainKey,
         sessionScope: cfg.session?.scope,
         eventRouting: parentEventRouting,
-        logPath: streamLogPath,
         deliveryContext: parentDeliveryCtx,
         emitStartNotice: false,
         cfg,
@@ -1687,7 +1684,6 @@ export async function spawnAcpDirect(
       runId: childRunId,
       mode: spawnMode,
       runTimeoutSeconds,
-      ...(streamLogPath ? { streamLogPath } : {}),
       note: spawnMode === "session" ? ACP_SPAWN_SESSION_ACCEPTED_NOTE : ACP_SPAWN_ACCEPTED_NOTE,
     };
   }
diff --git a/src/cli/gateway-cli/run.option-collisions.test.ts b/src/cli/gateway-cli/run.option-collisions.test.ts
index 8f191b242aa..e48989ff5db 100644
--- a/src/cli/gateway-cli/run.option-collisions.test.ts
+++ b/src/cli/gateway-cli/run.option-collisions.test.ts
@@ -1,7 +1,7 @@
 // Gateway run option collision tests cover gateway run flag registration boundaries.
-import path from "node:path";
 import { Command } from "commander";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { CONFIG_AUDIT_STORE_LABEL } from "../../config/io.audit.js";
 import type { ConfigFileSnapshot } from "../../config/types.js";
 import { GATEWAY_SERVICE_RUNTIME_PID_ENV } from "../../daemon/constants.js";
 import { SUPERVISOR_HINT_ENV_VARS } from "../../infra/supervisor-markers.js";
@@ -1589,9 +1589,7 @@ describe("gateway run option collisions", () => {
     expect(runtimeErrors).toContain(
       "Gateway start blocked: existing config is missing gateway.mode. Treat this as suspicious or clobbered config. Re-run `openclaw onboard --mode local` or `openclaw setup`, set gateway.mode=local manually, or pass --allow-unconfigured.",
     );
-    expect(runtimeErrors).toContain(
-      `Config write audit: ${path.join("/tmp", "logs", "config-audit.jsonl")}`,
-    );
+    expect(runtimeErrors).toContain(`Config write audit: ${CONFIG_AUDIT_STORE_LABEL}`);
     expect(startGatewayServer).not.toHaveBeenCalled();
     expect(readBestEffortConfig).not.toHaveBeenCalled();
   });
@@ -1613,9 +1611,7 @@ describe("gateway run option collisions", () => {
     expect(runtimeErrors).toContain(
       "Gateway start blocked: existing config is missing gateway.mode. Treat this as suspicious or clobbered config. Re-run `openclaw onboard --mode local` or `openclaw setup`, set gateway.mode=local manually, or pass --allow-unconfigured.",
     );
-    expect(runtimeErrors).toContain(
-      `Config write audit: ${path.join("/tmp", "logs", "config-audit.jsonl")}`,
-    );
+    expect(runtimeErrors).toContain(`Config write audit: ${CONFIG_AUDIT_STORE_LABEL}`);
     expect(readConfigFileSnapshotWithPluginMetadata).toHaveBeenCalledOnce();
     expect(startGatewayServer).not.toHaveBeenCalled();
   });
diff --git a/src/cli/gateway-cli/run.ts b/src/cli/gateway-cli/run.ts
index d8804b749a6..93cc51bfaea 100644
--- a/src/cli/gateway-cli/run.ts
+++ b/src/cli/gateway-cli/run.ts
@@ -2,7 +2,6 @@
 import fs from "node:fs";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
-import path from "node:path";
 import { TLSSocket } from "node:tls";
 import { expectDefined } from "@openclaw/normalization-core";
 import {
@@ -17,16 +16,12 @@ import type {
   ReadConfigFileSnapshotWithPluginMetadataResult,
 } from "../../config/config.js";
 import { ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS_ENV } from "../../config/future-version-guard.js";
+import { CONFIG_AUDIT_STORE_LABEL } from "../../config/io.audit.js";
 import {
   isDoctorRecoverableInvalidConfigError,
   isInvalidConfigError,
 } from "../../config/io.invalid-config.js";
-import {
-  CONFIG_PATH,
-  normalizeStateDirEnv,
-  resolveGatewayPort,
-  resolveStateDir,
-} from "../../config/paths.js";
+import { CONFIG_PATH, normalizeStateDirEnv, resolveGatewayPort } from "../../config/paths.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { hasConfiguredSecretInput } from "../../config/types.secrets.js";
 import { GATEWAY_SERVICE_RUNTIME_PID_ENV } from "../../daemon/constants.js";
@@ -250,7 +245,7 @@ function shouldBlockGatewayBindWithoutExplicitAuth(params: {
 function getGatewayStartGuardErrors(params: {
   allowUnconfigured?: boolean;
   configExists: boolean;
-  configAuditPath: string;
+  configAuditLocation: string;
   mode: string | undefined;
 }): string[] {
   if (params.allowUnconfigured || params.mode === "local") {
@@ -268,12 +263,12 @@ function getGatewayStartGuardErrors(params: {
         "Treat this as suspicious or clobbered config.",
         `Re-run \`${formatCliCommand("openclaw onboard --mode local")}\` or \`${formatCliCommand("openclaw setup")}\`, set gateway.mode=local manually, or pass --allow-unconfigured.`,
       ].join(" "),
-      `Config write audit: ${params.configAuditPath}`,
+      `Config write audit: ${params.configAuditLocation}`,
     ];
   }
   return [
     `Gateway start blocked: set gateway.mode=local (current: ${params.mode}) or pass --allow-unconfigured.`,
-    `Config write audit: ${params.configAuditPath}`,
+    `Config write audit: ${params.configAuditLocation}`,
   ];
 }
 
@@ -959,13 +954,12 @@ async function runGatewayCommandOnce(opts: GatewayRunOpts, hooks: GatewayRunRunt
 
   gatewayLog.info("resolving authentication…");
   const configExists = snapshot?.exists ?? fs.existsSync(CONFIG_PATH);
-  const configAuditPath = path.join(resolveStateDir(process.env), "logs", "config-audit.jsonl");
   const effectiveCfg = snapshot?.valid ? snapshot.config : cfg;
   const mode = effectiveCfg.gateway?.mode;
   const guardErrors = getGatewayStartGuardErrors({
     allowUnconfigured: opts.allowUnconfigured,
     configExists,
-    configAuditPath,
+    configAuditLocation: CONFIG_AUDIT_STORE_LABEL,
     mode,
   });
   if (guardErrors.length > 0) {
diff --git a/src/commands/doctor-config-audit-scrub.ts b/src/commands/doctor-config-audit-scrub.ts
index 915820e1432..50df942aff4 100644
--- a/src/commands/doctor-config-audit-scrub.ts
+++ b/src/commands/doctor-config-audit-scrub.ts
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import { note } from "../../packages/terminal-core/src/note.js";
 import {
-  resolveConfigAuditLogPath,
+  resolveLegacyConfigAuditLogPath,
   scrubConfigAuditLog,
   type ConfigAuditScrubResult,
 } from "../config/io.audit.js";
@@ -30,7 +30,7 @@ export async function detectConfigAuditScrubIssue(params?: {
   });
   return {
     ...result,
-    auditPath: resolveConfigAuditLogPath(env, homedir),
+    auditPath: resolveLegacyConfigAuditLogPath(env, homedir),
   };
 }
 
diff --git a/src/commands/doctor.e2e-harness.ts b/src/commands/doctor.e2e-harness.ts
index 3aa697e5718..8a571fb8e4f 100644
--- a/src/commands/doctor.e2e-harness.ts
+++ b/src/commands/doctor.e2e-harness.ts
@@ -289,6 +289,10 @@ function createLegacyStateMigrationDetectionResult(params?: {
       sourcePath: "/tmp/state/commitments/commitments.json",
       hasLegacy: false,
     },
+    auditLogs: {
+      sources: [],
+      hasLegacy: false,
+    },
     acpReplayLedger: {
       sourcePath: "/tmp/state/acp/event-ledger.json",
       hasLegacy: false,
diff --git a/src/config/io.audit.test-support.ts b/src/config/io.audit.test-support.ts
new file mode 100644
index 00000000000..7cdad42648d
--- /dev/null
+++ b/src/config/io.audit.test-support.ts
@@ -0,0 +1,23 @@
+import { createSqliteAuditRecordStore } from "../infra/sqlite-audit-record-store.js";
+import {
+  CONFIG_AUDIT_MAX_ENTRIES,
+  CONFIG_AUDIT_SCOPE,
+  type ConfigAuditRecord,
+} from "./io.audit.js";
+import { resolveStateDir } from "./paths.js";
+
+export function listConfigAuditRecordsForTests(params: {
+  env: NodeJS.ProcessEnv;
+  homedir: () => string;
+}): ConfigAuditRecord[] {
+  return createSqliteAuditRecordStore<ConfigAuditRecord>({
+    scope: CONFIG_AUDIT_SCOPE,
+    maxEntries: CONFIG_AUDIT_MAX_ENTRIES,
+    env: {
+      ...params.env,
+      OPENCLAW_STATE_DIR: resolveStateDir(params.env, params.homedir),
+    },
+  })
+    .entries()
+    .map((entry) => entry.value);
+}
diff --git a/src/config/io.audit.test.ts b/src/config/io.audit.test.ts
index cfd7738390c..36693322f57 100644
--- a/src/config/io.audit.test.ts
+++ b/src/config/io.audit.test.ts
@@ -2,16 +2,18 @@
 import fs from "node:fs";
 import { promises as fsPromises } from "node:fs";
 import path from "node:path";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import { createSuiteTempRootTracker } from "../test-helpers/temp-dir.js";
 import {
   appendConfigAuditRecord,
   createConfigWriteAuditRecordBase,
   finalizeConfigWriteAuditRecord,
   formatConfigOverwriteLogMessage,
-  resolveConfigAuditLogPath,
+  resolveLegacyConfigAuditLogPath,
   scrubConfigAuditLog,
 } from "./io.audit.js";
+import { listConfigAuditRecordsForTests } from "./io.audit.test-support.js";
 
 function createAuditRecordBase(configPath: string, argv?: string[]) {
   return createConfigWriteAuditRecordBase({
@@ -66,7 +68,7 @@ function createRenameAuditRecord(home: string) {
   });
 }
 
-function readAuditLog(home: string): unknown[] {
+function readLegacyAuditLog(home: string): unknown[] {
   const auditPath = path.join(home, ".openclaw", "logs", "config-audit.jsonl");
   return fs
     .readFileSync(auditPath, "utf-8")
@@ -93,9 +95,13 @@ describe("config io audit helpers", () => {
     await suiteRootTracker.cleanup();
   });
 
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+  });
+
   it('ignores literal "undefined" home env values when choosing the audit log path', async () => {
     const home = await suiteRootTracker.make("home");
-    const auditPath = resolveConfigAuditLogPath(
+    const auditPath = resolveLegacyConfigAuditLogPath(
       {
         HOME: "undefined",
         USERPROFILE: "null",
@@ -196,18 +202,20 @@ describe("config io audit helpers", () => {
     expect(record.errorMessage).toBe("disk full");
   });
 
-  it("appends JSONL audit entries to the resolved audit path", async () => {
+  it("appends audit entries to shared SQLite state", async () => {
     const home = await suiteRootTracker.make("append");
     const record = createRenameAuditRecord(home);
 
     await appendConfigAuditRecord({
-      fs,
       env: {} as NodeJS.ProcessEnv,
       homedir: () => home,
       record,
     });
 
-    const records = readAuditLog(home);
+    const records = listConfigAuditRecordsForTests({
+      env: {} as NodeJS.ProcessEnv,
+      homedir: () => home,
+    });
     expect(records).toHaveLength(1);
     const written = requireAuditRecord(records[0]);
     expect(written.event).toBe("config.write");
@@ -230,15 +238,16 @@ describe("config io audit helpers", () => {
     });
 
     await appendConfigAuditRecord({
-      fs,
       env: {} as NodeJS.ProcessEnv,
       homedir: () => home,
       record,
     });
 
-    const raw = fs.readFileSync(
-      path.join(home, ".openclaw", "logs", "config-audit.jsonl"),
-      "utf-8",
+    const raw = JSON.stringify(
+      listConfigAuditRecordsForTests({
+        env: {} as NodeJS.ProcessEnv,
+        homedir: () => home,
+      }),
     );
     expect(raw).not.toContain("AIzaSyD-very-real-looking");
     expect(raw).not.toContain("ya29.fake-access-token");
@@ -355,6 +364,99 @@ describe("config io audit helpers", () => {
       argv: ["openclaw", "--token"],
       expected: ["openclaw", "--token"],
     },
+    {
+      name: "sensitive config set positional value",
+      argv: ["openclaw", "config", "set", "channels.slack.token", "secret-value"],
+      expected: ["openclaw", "config", "set", "channels.slack.token", "***"],
+    },
+    {
+      name: "sensitive config set value after boolean option",
+      argv: ["openclaw", "config", "set", "--json", "channels.slack.token", '"secret-value"'],
+      expected: ["openclaw", "config", "set", "--json", "channels.slack.token", "***"],
+    },
+    {
+      name: "sensitive config set value after root value option",
+      argv: [
+        "openclaw",
+        "config",
+        "set",
+        "--profile",
+        "work",
+        "channels.slack.token",
+        "secret-value",
+      ],
+      expected: ["openclaw", "config", "set", "--profile", "work", "channels.slack.token", "***"],
+    },
+    {
+      name: "sensitive config set value after option before subcommand",
+      argv: [
+        "openclaw",
+        "config",
+        "--profile",
+        "work",
+        "set",
+        "channels.slack.token",
+        "secret-value",
+      ],
+      expected: ["openclaw", "config", "--profile", "work", "set", "channels.slack.token", "***"],
+    },
+    {
+      name: "sensitive config set value after config parent option",
+      argv: [
+        "openclaw",
+        "config",
+        "--section",
+        "channels",
+        "set",
+        "channels.slack.token",
+        "secret-value",
+      ],
+      expected: [
+        "openclaw",
+        "config",
+        "--section",
+        "channels",
+        "set",
+        "channels.slack.token",
+        "***",
+      ],
+    },
+    {
+      name: "sensitive config set value when a root option value is config",
+      argv: [
+        "openclaw",
+        "--profile",
+        "config",
+        "config",
+        "set",
+        "channels.slack.token",
+        "secret-value",
+      ],
+      expected: ["openclaw", "--profile", "config", "config", "set", "channels.slack.token", "***"],
+    },
+    {
+      name: "sensitive config set value after interleaved option",
+      argv: [
+        "openclaw",
+        "config",
+        "set",
+        "channels.slack.token",
+        "--strict-json",
+        '"secret-value"',
+      ],
+      expected: ["openclaw", "config", "set", "channels.slack.token", "--strict-json", "***"],
+    },
+    {
+      name: "config set batch JSON",
+      argv: [
+        "openclaw",
+        "config",
+        "set",
+        "--batch-json",
+        '[{"path":"channels.slack.token","value":"secret-value"}]',
+      ],
+      expected: ["openclaw", "config", "set", "--batch-json", "***"],
+    },
   ])("redacts $name in persisted audit process info", ({ argv, expected }) => {
     expect(createAuditRecordBase("/tmp/openclaw.json", argv).argv).toEqual(expected);
   });
@@ -364,13 +466,15 @@ describe("config io audit helpers", () => {
     const record = createRenameAuditRecord(home);
 
     await appendConfigAuditRecord({
-      fs,
       env: {} as NodeJS.ProcessEnv,
       homedir: () => home,
       ...record,
     });
 
-    const records = readAuditLog(home);
+    const records = listConfigAuditRecordsForTests({
+      env: {} as NodeJS.ProcessEnv,
+      homedir: () => home,
+    });
     expect(records).toHaveLength(1);
     const written = requireAuditRecord(records[0]);
     expect(written.event).toBe("config.write");
@@ -429,7 +533,7 @@ describe("config io audit helpers", () => {
     });
 
     expect(result).toEqual({ scanned: 2, rewritten: 1, skipped: 0, aborted: false });
-    const after = readAuditLog(home);
+    const after = readLegacyAuditLog(home);
     expect(after).toHaveLength(2);
     const firstAfter = requireAuditRecord(after[0]);
     const secondAfter = requireAuditRecord(after[1]);
diff --git a/src/config/io.audit.ts b/src/config/io.audit.ts
index ffb49503d88..594beb29e3d 100644
--- a/src/config/io.audit.ts
+++ b/src/config/io.audit.ts
@@ -1,13 +1,127 @@
 // Audits config paths and values for diagnostics and safety checks.
+import { randomUUID } from "node:crypto";
 import path from "node:path";
+import { createSqliteAuditRecordStore } from "../infra/sqlite-audit-record-store.js";
 import { redactSecrets } from "../logging/redact.js";
 import { resolveStateDir } from "./paths.js";
 import { redactSensitiveArgv } from "./redact-argv.js";
+import { isSensitiveConfigPath } from "./sensitive-paths.js";
 
 const CONFIG_AUDIT_ARGV_CAP = 8;
+const CONFIG_SET_VALUE_OPTIONS = new Set([
+  "--batch-file",
+  "--batch-json",
+  "--container",
+  "--log-level",
+  "--profile",
+  "--provider-allowlist",
+  "--provider-arg",
+  "--provider-command",
+  "--provider-env",
+  "--provider-max-bytes",
+  "--provider-max-output-bytes",
+  "--provider-mode",
+  "--provider-no-output-timeout-ms",
+  "--provider-pass-env",
+  "--provider-path",
+  "--provider-source",
+  "--provider-timeout-ms",
+  "--provider-trusted-dir",
+  "--ref-id",
+  "--ref-provider",
+  "--ref-source",
+  "--section",
+]);
+
+function findConfigSetPositionals(argv: readonly string[], setIndex: number): number[] {
+  const positionals: number[] = [];
+  let optionsEnded = false;
+  for (let index = setIndex + 1; index < argv.length && positionals.length < 2; index += 1) {
+    const arg = argv[index];
+    if (arg === undefined) {
+      break;
+    }
+    if (!optionsEnded && arg === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (!optionsEnded && arg.startsWith("-")) {
+      const equalsIndex = arg.indexOf("=");
+      const optionName = equalsIndex < 0 ? arg : arg.slice(0, equalsIndex);
+      if (equalsIndex < 0 && CONFIG_SET_VALUE_OPTIONS.has(optionName)) {
+        index += 1;
+      }
+      continue;
+    }
+    positionals.push(index);
+  }
+  return positionals;
+}
+
+function findConfigSetCommandIndex(argv: readonly string[], configIndex: number): number {
+  let optionsEnded = false;
+  for (let index = configIndex + 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === undefined) {
+      return -1;
+    }
+    if (!optionsEnded && arg === "--") {
+      optionsEnded = true;
+      continue;
+    }
+    if (!optionsEnded && arg.startsWith("-")) {
+      const equalsIndex = arg.indexOf("=");
+      const optionName = equalsIndex < 0 ? arg : arg.slice(0, equalsIndex);
+      if (equalsIndex < 0 && CONFIG_SET_VALUE_OPTIONS.has(optionName)) {
+        index += 1;
+      }
+      continue;
+    }
+    return arg === "set" ? index : -1;
+  }
+  return -1;
+}
 
 function redactConfigAuditArgv(argv: readonly string[]): string[] {
-  return redactSensitiveArgv(argv);
+  const redacted = redactSensitiveArgv(argv);
+  let setIndex = -1;
+  for (let index = 0; index < redacted.length; index += 1) {
+    if (redacted[index] !== "config") {
+      continue;
+    }
+    setIndex = findConfigSetCommandIndex(redacted, index);
+    if (setIndex >= 0) {
+      break;
+    }
+  }
+  if (setIndex < 0) {
+    return redacted;
+  }
+  for (let index = setIndex + 1; index < redacted.length; index += 1) {
+    const arg = redacted[index];
+    if (arg === undefined) {
+      break;
+    }
+    if (arg === "--batch-json" && index + 1 < redacted.length) {
+      redacted[index + 1] = "***";
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--batch-json=")) {
+      redacted[index] = "--batch-json=***";
+    }
+  }
+  const positionals = findConfigSetPositionals(redacted, setIndex);
+  if (positionals.length < 2) {
+    return redacted;
+  }
+  const pathIndex = positionals[0]!;
+  const valueIndex = positionals[1]!;
+  const configPath = redacted[pathIndex];
+  if (typeof configPath === "string" && isSensitiveConfigPath(configPath)) {
+    redacted[valueIndex] = "***";
+  }
+  return redacted;
 }
 
 function capArgv(argv: readonly string[] | undefined): string[] {
@@ -27,7 +141,11 @@ export function snapshotConfigAuditProcessInfo(): ConfigAuditProcessInfo {
   };
 }
 
-const CONFIG_AUDIT_LOG_FILENAME = "config-audit.jsonl";
+export const CONFIG_AUDIT_SCOPE = "config-audit";
+export const CONFIG_AUDIT_MAX_ENTRIES = 50_000;
+export const CONFIG_AUDIT_STORE_LABEL =
+  "SQLite diagnostic_events/config-audit state (latest 50000 rows)";
+const LEGACY_CONFIG_AUDIT_LOG_FILENAME = ["config-audit", "jsonl"].join(".");
 
 export type ConfigWriteAuditResult = "rename" | "copy-fallback" | "failed" | "rejected";
 
@@ -127,7 +245,7 @@ export type ConfigObserveAuditRecord = {
   restoreErrorMessage: string | null;
 };
 
-type ConfigAuditRecord = ConfigWriteAuditRecord | ConfigObserveAuditRecord;
+export type ConfigAuditRecord = ConfigWriteAuditRecord | ConfigObserveAuditRecord;
 
 type ConfigAuditStatMetadata = {
   dev: string | null;
@@ -162,23 +280,6 @@ type ConfigWriteAuditRecordBase = Omit<
   nextBytes: number;
 };
 
-type ConfigAuditFs = {
-  promises: {
-    mkdir(path: string, options?: { recursive?: boolean; mode?: number }): Promise<unknown>;
-    appendFile(
-      path: string,
-      data: string,
-      options?: { encoding?: BufferEncoding; mode?: number },
-    ): Promise<unknown>;
-  };
-  mkdirSync(path: string, options?: { recursive?: boolean; mode?: number }): unknown;
-  appendFileSync(
-    path: string,
-    data: string,
-    options?: { encoding?: BufferEncoding; mode?: number },
-  ): unknown;
-};
-
 function normalizeAuditLabel(value: string | undefined): string | null {
   if (typeof value !== "string") {
     return null;
@@ -200,8 +301,11 @@ function resolveConfigAuditProcessInfo(
   return snapshotConfigAuditProcessInfo();
 }
 
-export function resolveConfigAuditLogPath(env: NodeJS.ProcessEnv, homedir: () => string): string {
-  return path.join(resolveStateDir(env, homedir), "logs", CONFIG_AUDIT_LOG_FILENAME);
+export function resolveLegacyConfigAuditLogPath(
+  env: NodeJS.ProcessEnv,
+  homedir: () => string,
+): string {
+  return path.join(resolveStateDir(env, homedir), "logs", LEGACY_CONFIG_AUDIT_LOG_FILENAME);
 }
 
 export function formatConfigOverwriteLogMessage(params: {
@@ -307,13 +411,12 @@ export function finalizeConfigWriteAuditRecord(params: {
     nextNlink: success ? nextMetadata.nlink : null,
     nextUid: success ? nextMetadata.uid : null,
     nextGid: success ? nextMetadata.gid : null,
-    errorCode,
-    errorMessage,
+    ...(errorCode !== undefined ? { errorCode } : {}),
+    ...(errorMessage !== undefined ? { errorMessage } : {}),
   };
 }
 
 type ConfigAuditAppendContext = {
-  fs: ConfigAuditFs;
   env: NodeJS.ProcessEnv;
   homedir: () => string;
 };
@@ -328,10 +431,10 @@ type ConfigAuditAppendParams = ConfigAuditAppendContext &
 
 function resolveConfigAuditAppendRecord(params: ConfigAuditAppendParams): ConfigAuditRecord {
   if ("record" in params) {
-    return redactSecrets(params.record);
+    return params.record;
   }
-  const { fs: _fs, env: _env, homedir: _homedir, ...record } = params;
-  return redactSecrets(record as ConfigAuditRecord);
+  const { env: _env, homedir: _homedir, ...record } = params;
+  return record as ConfigAuditRecord;
 }
 
 export type ConfigAuditScrubResult = {
@@ -376,7 +479,7 @@ export async function scrubConfigAuditLog(params: {
   homedir: () => string;
   dryRun?: boolean;
 }): Promise<ConfigAuditScrubResult> {
-  const auditPath = resolveConfigAuditLogPath(params.env, params.homedir);
+  const auditPath = resolveLegacyConfigAuditLogPath(params.env, params.homedir);
   let raw: string;
   try {
     raw = await params.fs.promises.readFile(auditPath, "utf-8");
@@ -503,15 +606,43 @@ export async function scrubConfigAuditLog(params: {
   return { scanned, rewritten, skipped, aborted: false };
 }
 
+function resolveConfigAuditStoreEnv(params: {
+  env: NodeJS.ProcessEnv;
+  homedir: () => string;
+}): NodeJS.ProcessEnv {
+  return {
+    ...params.env,
+    OPENCLAW_STATE_DIR: resolveStateDir(params.env, params.homedir),
+  };
+}
+
+function openConfigAuditStore(env: NodeJS.ProcessEnv) {
+  return createSqliteAuditRecordStore<ConfigAuditRecord>({
+    scope: CONFIG_AUDIT_SCOPE,
+    maxEntries: CONFIG_AUDIT_MAX_ENTRIES,
+    env,
+  });
+}
+
+function configAuditEntryKey(record: ConfigAuditRecord): string {
+  return `${record.ts}:${record.event}:${randomUUID()}`;
+}
+
+export function sanitizeConfigAuditRecord(record: ConfigAuditRecord): ConfigAuditRecord {
+  const sanitized = structuredClone(record);
+  sanitized.argv = redactConfigAuditArgv(capArgv(sanitized.argv));
+  sanitized.execArgv = redactConfigAuditArgv(capArgv(sanitized.execArgv));
+  return redactSecrets(sanitized);
+}
+
 export async function appendConfigAuditRecord(params: ConfigAuditAppendParams): Promise<void> {
   try {
-    const auditPath = resolveConfigAuditLogPath(params.env, params.homedir);
-    const record = resolveConfigAuditAppendRecord(params);
-    await params.fs.promises.mkdir(path.dirname(auditPath), { recursive: true, mode: 0o700 });
-    await params.fs.promises.appendFile(auditPath, `${JSON.stringify(record)}\n`, {
-      encoding: "utf-8",
-      mode: 0o600,
-    });
+    const record = sanitizeConfigAuditRecord(resolveConfigAuditAppendRecord(params));
+    openConfigAuditStore(resolveConfigAuditStoreEnv(params)).register(
+      configAuditEntryKey(record),
+      record,
+      Date.parse(record.ts),
+    );
   } catch {
     // best-effort
   }
@@ -519,13 +650,12 @@ export async function appendConfigAuditRecord(params: ConfigAuditAppendParams):
 
 export function appendConfigAuditRecordSync(params: ConfigAuditAppendParams): void {
   try {
-    const auditPath = resolveConfigAuditLogPath(params.env, params.homedir);
-    const record = resolveConfigAuditAppendRecord(params);
-    params.fs.mkdirSync(path.dirname(auditPath), { recursive: true, mode: 0o700 });
-    params.fs.appendFileSync(auditPath, `${JSON.stringify(record)}\n`, {
-      encoding: "utf-8",
-      mode: 0o600,
-    });
+    const record = sanitizeConfigAuditRecord(resolveConfigAuditAppendRecord(params));
+    openConfigAuditStore(resolveConfigAuditStoreEnv(params)).register(
+      configAuditEntryKey(record),
+      record,
+      Date.parse(record.ts),
+    );
   } catch {
     // best-effort
   }
diff --git a/src/config/io.observe-recovery.test.ts b/src/config/io.observe-recovery.test.ts
index b9a124dea85..b5c5b110301 100644
--- a/src/config/io.observe-recovery.test.ts
+++ b/src/config/io.observe-recovery.test.ts
@@ -11,6 +11,7 @@ import {
   closeOpenClawStateDatabaseForTest,
   openOpenClawStateDatabase,
 } from "../state/openclaw-state-db.js";
+import { listConfigAuditRecordsForTests } from "./io.audit.test-support.js";
 import { createConfigIO } from "./io.js";
 import {
   maybeRecoverSuspiciousConfigRead,
@@ -101,17 +102,11 @@ describe("config observe recovery", () => {
   }
 
   async function readObserveEvents(auditPath: string): Promise<Record<string, unknown>[]> {
-    const events: Record<string, unknown>[] = [];
-    for (const line of (await fsp.readFile(auditPath, "utf-8")).trim().split("\n")) {
-      if (!line) {
-        continue;
-      }
-      const parsed = JSON.parse(line) as Record<string, unknown>;
-      if (parsed.event === "config.observe") {
-        events.push(parsed);
-      }
-    }
-    return events;
+    const stateDir = path.dirname(path.dirname(auditPath));
+    return listConfigAuditRecordsForTests({
+      env: { OPENCLAW_STATE_DIR: stateDir },
+      homedir: () => stateDir,
+    }).filter((event) => event.event === "config.observe");
   }
 
   async function listClobberFiles(configPath: string): Promise<string[]> {
diff --git a/src/config/io.observe-recovery.ts b/src/config/io.observe-recovery.ts
index fae343b3b2a..3d68a315df5 100644
--- a/src/config/io.observe-recovery.ts
+++ b/src/config/io.observe-recovery.ts
@@ -240,7 +240,6 @@ function createConfigObserveAuditAppendParams(
   params: ConfigObserveAuditRecordParams,
 ) {
   return {
-    fs: deps.fs,
     env: deps.env,
     homedir: deps.homedir,
     record: createConfigObserveAuditRecord(params),
diff --git a/src/config/io.observe.ts b/src/config/io.observe.ts
index a3bde2b2ff5..8d2550d1b4f 100644
--- a/src/config/io.observe.ts
+++ b/src/config/io.observe.ts
@@ -259,7 +259,6 @@ export async function observeConfigSnapshot(
     (baseline?.hash ? baseline : null) ?? (await readConfigFingerprintForPath(deps, backupPath));
   deps.logger.warn(`Config observe anomaly: ${snapshot.path} (${suspicious.join(", ")})`);
   await appendConfigAuditRecord({
-    fs: deps.fs,
     env: deps.env,
     homedir: deps.homedir,
     record: createObserveAuditRecord({ snapshot, current, suspicious, entry, backup }),
@@ -306,7 +305,6 @@ export function observeConfigSnapshotSync(
     (baseline?.hash ? baseline : null) ?? readConfigFingerprintForPathSync(deps, backupPath);
   deps.logger.warn(`Config observe anomaly: ${snapshot.path} (${suspicious.join(", ")})`);
   appendConfigAuditRecordSync({
-    fs: deps.fs,
     env: deps.env,
     homedir: deps.homedir,
     record: createObserveAuditRecord({ snapshot, current, suspicious, entry, backup }),
diff --git a/src/config/io.write.ts b/src/config/io.write.ts
index 20957195264..73fc58a345a 100644
--- a/src/config/io.write.ts
+++ b/src/config/io.write.ts
@@ -294,7 +294,6 @@ export async function writeConfigFileFromContext(
     nextStat?: fs.Stats | null,
   ) => {
     await appendConfigAuditRecord({
-      fs: deps.fs,
       env: deps.env,
       homedir: deps.homedir,
       record: finalizeConfigWriteAuditRecord({
diff --git a/src/infra/backup-create.test.ts b/src/infra/backup-create.test.ts
index 48322101a75..cf9d176960c 100644
--- a/src/infra/backup-create.test.ts
+++ b/src/infra/backup-create.test.ts
@@ -8,6 +8,7 @@ import * as tar from "tar";
 import { describe, expect, it, vi } from "vitest";
 import { saveAuthProfileStore } from "../agents/auth-profiles/store.js";
 import { backupVerifyCommand } from "../commands/backup-verify.js";
+import { CONFIG_AUDIT_MAX_ENTRIES, CONFIG_AUDIT_SCOPE } from "../config/io.audit.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { closeOpenClawAgentDatabasesForTest } from "../state/openclaw-agent-db.js";
 import {
@@ -29,6 +30,8 @@ import { writeTarArchiveWithRetry } from "./backup-tar-retry.js";
 import { isVolatileBackupPath } from "./backup-volatile-filter.js";
 import { createBackupVolatileStatCache } from "./backup-volatile-stat-cache.js";
 import { requireNodeSqlite } from "./node-sqlite.js";
+import { createSqliteAuditRecordStore } from "./sqlite-audit-record-store.js";
+import { detectLegacyAuditLogs, migrateLegacyAuditLogs } from "./state-migrations.audit-logs.js";
 
 function makeResult(overrides: Partial<BackupCreateResult> = {}): BackupCreateResult {
   return {
@@ -239,6 +242,27 @@ describe("sanitizeOpenClawGlobalStateSnapshot", () => {
       database.close();
     }
   });
+
+  it("leaves diagnostic state to its backup-specific sanitizer", () => {
+    const sqlite = requireNodeSqlite();
+    const database = new sqlite.DatabaseSync(":memory:");
+    try {
+      database.exec(`
+        CREATE TABLE diagnostic_events (scope TEXT);
+        INSERT INTO diagnostic_events VALUES ('migration.legacy-audit-raw');
+        INSERT INTO diagnostic_events VALUES ('system-agent.audit');
+      `);
+
+      sanitizeOpenClawGlobalStateSnapshot(database);
+
+      expect(database.prepare("SELECT scope FROM diagnostic_events").all()).toEqual([
+        { scope: "migration.legacy-audit-raw" },
+        { scope: "system-agent.audit" },
+      ]);
+    } finally {
+      database.close();
+    }
+  });
 });
 
 describe("writeTarArchiveWithRetry", () => {
@@ -621,6 +645,235 @@ describe("createBackupArchive", () => {
     );
   });
 
+  it("replaces legacy audit raw archives with sanitized restorable snapshots", async () => {
+    await withOpenClawTestState(
+      {
+        layout: "state-only",
+        prefix: "openclaw-backup-audit-raw-",
+        scenario: "minimal",
+      },
+      async (state) => {
+        const outputDir = state.path("backups");
+        const extractDir = state.path("extract");
+        const rawRelativePath = "logs/config-audit.jsonl.migrated.raw";
+        const marker = "audit-value-7f3c";
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.mkdir(extractDir, { recursive: true });
+        await state.writeText(
+          rawRelativePath,
+          `${JSON.stringify({
+            ts: "2026-07-01T00:00:00.000Z",
+            source: "config-io",
+            event: "config.write",
+            argv: ["openclaw", "config", "set", "token", marker],
+            execArgv: [],
+          })}\n`,
+        );
+        const { db } = openOpenClawStateDatabase({ env: state.env });
+        db.prepare(
+          `
+            INSERT INTO diagnostic_events (
+              scope, event_key, payload_json, created_at, sequence
+            ) VALUES ('migration.legacy-audit-raw', 'checkpoint', '{}', 1, 1)
+          `,
+        ).run();
+
+        try {
+          const result = await createBackupArchive({
+            output: outputDir,
+            includeWorkspace: false,
+            nowMs: Date.UTC(2026, 4, 9, 8, 15, 0),
+          });
+          const entries = await listArchiveEntries(result.archivePath);
+          const rawEntry = expectDefined(
+            entries.find((entry) => entry.endsWith(`/state/${rawRelativePath}`)),
+            "sanitized raw archive entry",
+          );
+          const databaseEntry = expectDefined(
+            entries.find((entry) => entry.endsWith("/state/state/openclaw.sqlite")),
+            "global state database entry",
+          );
+          expect(entries.some((entry) => entry.endsWith(".doctor-scrub-restore"))).toBe(false);
+
+          await tar.x({ file: result.archivePath, gzip: true, cwd: extractDir });
+          const archivedRaw = await fs.readFile(path.join(extractDir, rawEntry), "utf8");
+          expect(archivedRaw).not.toContain(marker);
+          expect(JSON.parse(archivedRaw.trim())).toMatchObject({
+            argv: ["openclaw", "config", "set", "token", "***"],
+          });
+          const sqlite = requireNodeSqlite();
+          const archivedDb = new sqlite.DatabaseSync(path.join(extractDir, databaseEntry), {
+            readOnly: true,
+          });
+          try {
+            expect(
+              archivedDb
+                .prepare(
+                  "SELECT COUNT(*) AS count FROM diagnostic_events WHERE scope = 'migration.legacy-audit-raw'",
+                )
+                .get(),
+            ).toEqual({ count: 0 });
+          } finally {
+            archivedDb.close();
+          }
+        } finally {
+          closeOpenClawStateDatabase();
+        }
+      },
+    );
+  });
+
+  it("omits completed blank audit append pads when dropping their checkpoints", async () => {
+    await withOpenClawTestState(
+      {
+        layout: "state-only",
+        prefix: "openclaw-backup-completed-audit-pad-",
+        scenario: "minimal",
+      },
+      async (state) => {
+        const outputDir = state.path("backups");
+        const extractDir = state.path("extract");
+        const sourcePath = state.statePath("logs/config-audit.jsonl");
+        const rawRelativePath = "logs/config-audit.jsonl.migrated.raw";
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.mkdir(extractDir, { recursive: true });
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(
+          sourcePath,
+          `${JSON.stringify({
+            ts: "2026-07-01T00:00:00.000Z",
+            source: "config-io",
+            event: "config.write",
+            argv: ["openclaw", "config", "set", "safe", "value"],
+            execArgv: [],
+          })}\n`,
+        );
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({
+            stateDir: state.stateDir,
+            doctorOnlyStateMigrations: true,
+          }),
+          stateDir: state.stateDir,
+        });
+        expect(
+          detectLegacyAuditLogs({
+            stateDir: state.stateDir,
+            doctorOnlyStateMigrations: true,
+          }).hasLegacy,
+        ).toBe(false);
+        const { db } = openOpenClawStateDatabase({ env: state.env });
+        expect(
+          db
+            .prepare(
+              "SELECT COUNT(*) AS count FROM diagnostic_events WHERE scope = 'migration.legacy-audit-raw'",
+            )
+            .get(),
+        ).toEqual({ count: 1 });
+
+        try {
+          const result = await createBackupArchive({
+            output: outputDir,
+            includeWorkspace: false,
+            nowMs: Date.UTC(2026, 4, 9, 8, 20, 0),
+          });
+          const entries = await listArchiveEntries(result.archivePath);
+          expect(entries.some((entry) => entry.endsWith(`/state/${rawRelativePath}`))).toBe(false);
+          const databaseEntry = expectDefined(
+            entries.find((entry) => entry.endsWith("/state/state/openclaw.sqlite")),
+            "global state database entry",
+          );
+          await tar.x({ file: result.archivePath, gzip: true, cwd: extractDir });
+          const sqlite = requireNodeSqlite();
+          const archivedDb = new sqlite.DatabaseSync(path.join(extractDir, databaseEntry), {
+            readOnly: true,
+          });
+          try {
+            expect(
+              archivedDb
+                .prepare(
+                  "SELECT COUNT(*) AS count FROM diagnostic_events WHERE scope = 'migration.legacy-audit-raw'",
+                )
+                .get(),
+            ).toEqual({ count: 0 });
+          } finally {
+            archivedDb.close();
+          }
+        } finally {
+          closeOpenClawStateDatabase();
+        }
+      },
+    );
+  });
+
+  it("preserves audit ordinals for identical later appends across backup restore", async () => {
+    await withOpenClawTestState(
+      {
+        layout: "state-only",
+        prefix: "openclaw-backup-audit-ordinal-",
+        scenario: "minimal",
+      },
+      async (state) => {
+        const outputDir = state.path("backups");
+        const extractDir = state.path("extract");
+        const sourcePath = state.statePath("logs/config-audit.jsonl");
+        const rawRelativePath = "logs/config-audit.jsonl.migrated.raw";
+        const record = {
+          ts: "2026-07-01T00:00:00.000Z",
+          source: "config-io",
+          event: "config.write",
+          argv: ["openclaw", "config", "set", "safe", "same"],
+          execArgv: [],
+        };
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.mkdir(extractDir, { recursive: true });
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({
+            stateDir: state.stateDir,
+            doctorOnlyStateMigrations: true,
+          }),
+          stateDir: state.stateDir,
+        });
+        await fs.appendFile(state.statePath(rawRelativePath), `${JSON.stringify(record)}\n`);
+
+        const result = await createBackupArchive({
+          output: outputDir,
+          includeWorkspace: false,
+          nowMs: Date.UTC(2026, 4, 9, 8, 25, 0),
+        });
+        const entries = await listArchiveEntries(result.archivePath);
+        const databaseEntry = expectDefined(
+          entries.find((entry) => entry.endsWith("/state/state/openclaw.sqlite")),
+          "global state database entry",
+        );
+        await tar.x({ file: result.archivePath, gzip: true, cwd: extractDir });
+        closeOpenClawStateDatabase();
+
+        const restoredDatabasePath = path.join(extractDir, databaseEntry);
+        const restoredStateDir = path.dirname(path.dirname(restoredDatabasePath));
+        const restoredDetection = detectLegacyAuditLogs({
+          stateDir: restoredStateDir,
+          doctorOnlyStateMigrations: true,
+        });
+        expect(restoredDetection.hasLegacy).toBe(true);
+        await migrateLegacyAuditLogs({
+          detected: restoredDetection,
+          stateDir: restoredStateDir,
+        });
+        const restoredEntries = createSqliteAuditRecordStore({
+          scope: CONFIG_AUDIT_SCOPE,
+          maxEntries: CONFIG_AUDIT_MAX_ENTRIES,
+          env: { ...process.env, OPENCLAW_STATE_DIR: restoredStateDir },
+        }).entries();
+        expect(restoredEntries).toHaveLength(2);
+        expect(new Set(restoredEntries.map((entry) => entry.key)).size).toBe(2);
+        expect(restoredEntries.map((entry) => entry.value)).toEqual([record, record]);
+        closeOpenClawStateDatabase();
+      },
+    );
+  });
+
   it("scrubs transient SQLite queue and plugin blob rows from archive snapshots", async () => {
     await withOpenClawTestState(
       {
diff --git a/src/infra/backup-create.ts b/src/infra/backup-create.ts
index 7e87dd4f540..457f2c2a69d 100644
--- a/src/infra/backup-create.ts
+++ b/src/infra/backup-create.ts
@@ -33,6 +33,14 @@ import { formatErrorMessage } from "./errors.js";
 import { sameFileIdentity } from "./fs-safe-advanced.js";
 import { writeJson } from "./json-files.js";
 import { createVerifiedSqliteSnapshot } from "./sqlite-snapshot.js";
+import {
+  createLegacyAuditBackupSnapshots,
+  hasLegacyAuditBackupSources,
+  isLegacyAuditMigrationBackupPath,
+  rewriteLegacyAuditBackupCheckpoints,
+  type LegacyAuditBackupSnapshot,
+} from "./state-migrations.audit-backup.js";
+import { withLegacyAuditMigrationLease } from "./state-migrations.audit-coordination.js";
 
 const loadTarRuntime = createLazyRuntimeModule(() => import("tar"));
 
@@ -618,6 +626,7 @@ async function createStateSqliteBackupPlan(params: {
   stateDir: string;
   tempDir: string;
   preservedStatePaths?: readonly string[];
+  legacyAuditSnapshots: readonly LegacyAuditBackupSnapshot[];
 }): Promise<StateSqliteBackupPlan> {
   // Complete discovery before writing snapshots. chooseBackupTempRoot keeps
   // tempDir outside stateDir, and this ordering prevents future overlap from
@@ -676,7 +685,10 @@ async function createStateSqliteBackupPlan(params: {
         // Agent coordination is transient, while unrelated plugin databases
         // remain owner-defined. Queue and TTL-blob policy is global-only.
         transform: isGlobalStateDatabase
-          ? sanitizeOpenClawGlobalStateSnapshot
+          ? (database) => {
+              sanitizeOpenClawGlobalStateSnapshot(database);
+              rewriteLegacyAuditBackupCheckpoints(database, params.legacyAuditSnapshots);
+            }
           : canonicalAgentSource
             ? sanitizeOpenClawStateLeaseRows
             : undefined,
@@ -771,19 +783,47 @@ export async function createBackupArchive(
       .map((asset) => asset.sourcePath),
   ].filter((entry) => stateAsset && isPathWithin(entry, stateAsset.sourcePath));
   try {
-    const stateSqliteBackup = stateAsset
-      ? await createStateSqliteBackupPlan({
-          stateDir: stateAsset.sourcePath,
-          tempDir,
-          preservedStatePaths,
-        })
-      : { snapshots: [], discoveredSourcePaths: new Set<string>() };
+    // Capture every legacy file first, including active and claimed sources.
+    // A concurrent Doctor then leaves each row in this snapshot, the later
+    // SQLite snapshot, or both; restore-side import keys make overlap harmless.
+    const hasLegacyAuditSources = stateAsset
+      ? await hasLegacyAuditBackupSources(stateAsset.sourcePath)
+      : false;
+    const createSnapshotPlans = async () => {
+      const legacyAuditSnapshots =
+        stateAsset && hasLegacyAuditSources
+          ? await createLegacyAuditBackupSnapshots({
+              stateDir: stateAsset.sourcePath,
+              tempDir,
+            })
+          : [];
+      const stateSqliteBackup = stateAsset
+        ? await createStateSqliteBackupPlan({
+            stateDir: stateAsset.sourcePath,
+            tempDir,
+            preservedStatePaths,
+            legacyAuditSnapshots,
+          })
+        : { snapshots: [], discoveredSourcePaths: new Set<string>() };
+      return { legacyAuditSnapshots, stateSqliteBackup };
+    };
+    const snapshotPlans =
+      stateAsset && hasLegacyAuditSources
+        ? await withLegacyAuditMigrationLease(stateAsset.sourcePath, createSnapshotPlans)
+        : await createSnapshotPlans();
+    const { legacyAuditSnapshots, stateSqliteBackup } = snapshotPlans;
     const sourcePathRemaps = new Map<string, string>();
-    const skippedSqliteSourcePaths = new Set<string>();
+    const skippedStateSourcePaths = new Set<string>();
     for (const snapshot of stateSqliteBackup.snapshots) {
       sourcePathRemaps.set(path.resolve(snapshot.sourcePath), snapshot.archiveSourcePath);
       for (const skippedSourcePath of snapshot.skippedSourcePaths) {
-        skippedSqliteSourcePaths.add(skippedSourcePath);
+        skippedStateSourcePaths.add(skippedSourcePath);
+      }
+    }
+    for (const snapshot of legacyAuditSnapshots) {
+      sourcePathRemaps.set(path.resolve(snapshot.sourcePath), snapshot.archiveSourcePath);
+      for (const skippedSourcePath of snapshot.skippedSourcePaths) {
+        skippedStateSourcePaths.add(skippedSourcePath);
       }
     }
     const manifest = buildManifest({
@@ -822,13 +862,19 @@ export async function createBackupArchive(
       if (stateFilter && !stateFilter(entryPath)) {
         return false;
       }
+      if (
+        stateAsset &&
+        isLegacyAuditMigrationBackupPath(resolvedEntryPath, stateAsset.sourcePath)
+      ) {
+        return false;
+      }
       const sqliteSourceKind = stateAsset
         ? classifyStateSqliteBackupSourcePath(resolvedEntryPath, stateAsset.sourcePath)
         : undefined;
       if (sqliteSourceKind === "excluded") {
         return false;
       }
-      if (skippedSqliteSourcePaths.has(resolvedEntryPath)) {
+      if (skippedStateSourcePaths.has(resolvedEntryPath)) {
         return false;
       }
       if (
@@ -878,6 +924,7 @@ export async function createBackupArchive(
             [
               manifestPath,
               ...stateSqliteBackup.snapshots.map((snapshot) => snapshot.sourcePath),
+              ...legacyAuditSnapshots.map((snapshot) => snapshot.sourcePath),
               ...result.assets.map((asset) => asset.sourcePath),
             ],
           ),
diff --git a/src/infra/backup-volatile-filter.test.ts b/src/infra/backup-volatile-filter.test.ts
index 847117a575a..25abfd7fa78 100644
--- a/src/infra/backup-volatile-filter.test.ts
+++ b/src/infra/backup-volatile-filter.test.ts
@@ -22,6 +22,12 @@ describe("isVolatileBackupPath", () => {
     [`${stateDir}/ipc/gateway.sock`, true],
     [`${stateDir}/gateway.pid`, true],
     [`${stateDir}/tmp/pending.tmp`, true],
+    [`${stateDir}/audit/system-agent.jsonl.migrated.raw`, false],
+    [`${stateDir}/audit/system-agent.jsonl.migrated.2.raw`, false],
+    [`${stateDir}/audit/system-agent.jsonl.migrated.10.raw`, false],
+    [`${stateDir}/audit/system-agent.jsonl.migrated.raw.doctor-scrub-restore`, false],
+    [`${stateDir}/logs/config-audit.jsonl.migrated.raw.doctor-scrub-staging`, false],
+    [`${stateDir}/logs/config-audit.jsonl.migrated.raw.doctor-scrub-progress`, false],
     [`${stateDir}/delivery-queue/pending.tmp`, true],
     [`${stateDir}/session-delivery-queue/pending.tmp`, true],
 
@@ -38,6 +44,7 @@ describe("isVolatileBackupPath", () => {
     ["/home/user/project/README.md", false],
     ["/home/user/project/Cargo.lock", false],
     ["/home/user/project/pending.tmp", false],
+    ["/home/user/project/config.jsonl.doctor-scrub-restore", false],
     // non-volatile: log-like name outside scope
     ["/home/user/notes/daily.log", false],
   ])("classifies %s as volatile=%s", (p, expected) => {
diff --git a/src/infra/fs-safe-advanced.ts b/src/infra/fs-safe-advanced.ts
index 695fe7ea915..c90f1a434a5 100644
--- a/src/infra/fs-safe-advanced.ts
+++ b/src/infra/fs-safe-advanced.ts
@@ -5,6 +5,7 @@ import "./fs-safe-defaults.js";
 export {
   assertNoSymlinkParents,
   assertNoSymlinkParentsSync,
+  type FileIdentityStat,
   sameFileIdentity,
   sanitizeUntrustedFileName,
 } from "@openclaw/fs-safe/advanced";
diff --git a/src/infra/regular-file.ts b/src/infra/regular-file.ts
index faf6e036661..d503a1bf415 100644
--- a/src/infra/regular-file.ts
+++ b/src/infra/regular-file.ts
@@ -4,7 +4,6 @@ import "./fs-safe-defaults.js";
 // Regular-file IO helpers reject symlinks and non-file targets before reads or
 // appends touch user-controlled paths.
 export {
-  appendRegularFile,
   appendRegularFileSync,
   readRegularFile,
   readRegularFileSync,
diff --git a/src/infra/sqlite-audit-record-store.test.ts b/src/infra/sqlite-audit-record-store.test.ts
new file mode 100644
index 00000000000..b4037322870
--- /dev/null
+++ b/src/infra/sqlite-audit-record-store.test.ts
@@ -0,0 +1,120 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { closeOpenClawStateDatabase } from "../state/openclaw-state-db.js";
+import { withTempDir } from "../test-helpers/temp-dir.js";
+import { createSqliteAuditRecordStore } from "./sqlite-audit-record-store.js";
+
+describe("SQLite audit record store", () => {
+  afterEach(() => {
+    closeOpenClawStateDatabase();
+  });
+
+  it("keeps the newest configured number of rows per scope", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "bounded-test",
+        maxEntries: 2,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.register("one", { value: 1 }, 1);
+      store.register("two", { value: 2 }, 2);
+      store.register("three", { value: 3 }, 3);
+
+      expect(store.size()).toBe(2);
+      expect(store.entries().map((entry) => entry.key)).toEqual(["two", "three"]);
+    });
+  });
+
+  it("preserves insertion order and prunes the oldest row when timestamps tie", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-ties-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "tied-timestamps",
+        maxEntries: 2,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.register("z-first", { value: 1 }, 1);
+      store.register("a-second", { value: 2 }, 1);
+      expect(store.entries().map((entry) => entry.key)).toEqual(["z-first", "a-second"]);
+
+      store.register("m-third", { value: 3 }, 1);
+      expect(store.entries().map((entry) => entry.key)).toEqual(["a-second", "m-third"]);
+    });
+  });
+
+  it("prunes by insertion order when wall-clock timestamps move", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-clock-skew-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "clock-skew",
+        maxEntries: 2,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.register("future-first", { value: 1 }, 4_000_000_000_000);
+      store.register("past-second", { value: 2 }, 1);
+      store.register("current-third", { value: 3 }, 2_000_000_000_000);
+
+      expect(store.entries().map((entry) => entry.key)).toEqual(["past-second", "current-third"]);
+    });
+  });
+
+  it("commits batch inserts with one retention pass", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-batch-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "batch-test",
+        maxEntries: 2,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.registerLegacyMany([
+        { key: "one", value: { value: 1 }, createdAt: 1 },
+        { key: "two", value: { value: 2 }, createdAt: 2 },
+        { key: "three", value: { value: 3 }, createdAt: 3 },
+      ]);
+
+      expect(store.entries().map((entry) => entry.key)).toEqual(["two", "three"]);
+    });
+  });
+
+  it("updates a retained key without consuming another bounded entry", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-upsert-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "upsert-test",
+        maxEntries: 2,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.register("one", { value: 1 }, 1);
+      store.register("two", { value: 2 }, 2);
+      store.upsert("one", { value: 3 }, 3);
+
+      expect(store.size()).toBe(2);
+      expect(store.entries()).toEqual([
+        { key: "one", value: { value: 3 }, createdAt: 3 },
+        { key: "two", value: { value: 2 }, createdAt: 2 },
+      ]);
+    });
+  });
+
+  it("orders legacy batches before existing runtime rows", async () => {
+    await withTempDir({ prefix: "openclaw-audit-store-legacy-order-" }, async (stateDir) => {
+      const store = createSqliteAuditRecordStore<{ value: number }>({
+        scope: "legacy-order",
+        maxEntries: 4,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      });
+
+      store.register("runtime", { value: 3 }, 3);
+      store.registerLegacyMany([
+        { key: "legacy-one", value: { value: 1 }, createdAt: 1 },
+        { key: "legacy-two", value: { value: 2 }, createdAt: 2 },
+      ]);
+
+      expect(store.entries().map((entry) => entry.key)).toEqual([
+        "legacy-one",
+        "legacy-two",
+        "runtime",
+      ]);
+    });
+  });
+});
diff --git a/src/infra/sqlite-audit-record-store.ts b/src/infra/sqlite-audit-record-store.ts
new file mode 100644
index 00000000000..2461a00836e
--- /dev/null
+++ b/src/infra/sqlite-audit-record-store.ts
@@ -0,0 +1,222 @@
+// Shared SQLite storage for append-only diagnostic audit records.
+import type { DatabaseSync } from "node:sqlite";
+import type { Selectable } from "kysely";
+import type { DB as OpenClawStateKyselyDatabase } from "../state/openclaw-state-db.generated.js";
+import {
+  openOpenClawStateDatabase,
+  runOpenClawStateWriteTransaction,
+  type OpenClawStateDatabaseOptions,
+} from "../state/openclaw-state-db.js";
+import {
+  executeSqliteQuerySync,
+  executeSqliteQueryTakeFirstSync,
+  getNodeSqliteKysely,
+} from "./kysely-sync.js";
+
+type DiagnosticEventsTable = OpenClawStateKyselyDatabase["diagnostic_events"];
+type AuditRecordDatabase = Pick<OpenClawStateKyselyDatabase, "diagnostic_events">;
+type DiagnosticEventRow = Pick<
+  Selectable<DiagnosticEventsTable>,
+  "event_key" | "payload_json" | "created_at" | "sequence"
+>;
+type PreparedDiagnosticEventRow = Omit<DiagnosticEventRow, "sequence">;
+
+const LEGACY_AUDIT_SEQUENCE_BASE = Number.MIN_SAFE_INTEGER;
+
+type SqliteAuditRecordEntry<T> = {
+  key: string;
+  value: T;
+  createdAt: number;
+};
+
+function getAuditRecordKysely(database: DatabaseSync) {
+  return getNodeSqliteKysely<AuditRecordDatabase>(database);
+}
+
+function parseAuditRecord<T>(row: DiagnosticEventRow): SqliteAuditRecordEntry<T> {
+  return {
+    key: row.event_key,
+    value: JSON.parse(row.payload_json) as T,
+    createdAt: row.created_at,
+  };
+}
+
+function countAuditRecords(database: DatabaseSync, scope: string): number {
+  const row = executeSqliteQueryTakeFirstSync(
+    database,
+    getAuditRecordKysely(database)
+      .selectFrom("diagnostic_events")
+      .select((eb) => eb.fn.countAll<number | bigint>().as("count"))
+      .where("scope", "=", scope),
+  );
+  return typeof row?.count === "bigint" ? Number(row.count) : (row?.count ?? 0);
+}
+
+function nextAuditSequence(params: {
+  database: DatabaseSync;
+  scope: string;
+  legacy: boolean;
+}): number {
+  const row = executeSqliteQueryTakeFirstSync(
+    params.database,
+    getAuditRecordKysely(params.database)
+      .selectFrom("diagnostic_events")
+      .select((eb) => eb.fn.max<number>("sequence").as("sequence"))
+      .where("scope", "=", params.scope)
+      .where("sequence", params.legacy ? "<" : ">=", 0),
+  );
+  const current = row?.sequence ?? (params.legacy ? LEGACY_AUDIT_SEQUENCE_BASE : 0);
+  const next = current + 1;
+  if (!Number.isSafeInteger(next) || (params.legacy && next >= 0)) {
+    throw new Error(`Audit sequence exhausted for scope ${params.scope}`);
+  }
+  return next;
+}
+
+function pruneAuditRecords(params: {
+  database: DatabaseSync;
+  scope: string;
+  maxEntries: number;
+  protectedKey?: string;
+}): void {
+  const overflow = countAuditRecords(params.database, params.scope) - params.maxEntries;
+  if (overflow <= 0) {
+    return;
+  }
+  const protectedKey = params.protectedKey;
+  const baseCandidates = getAuditRecordKysely(params.database)
+    .selectFrom("diagnostic_events")
+    .select("event_key")
+    .where("scope", "=", params.scope);
+  const candidates = (
+    protectedKey === undefined
+      ? baseCandidates
+      : baseCandidates.where("event_key", "!=", protectedKey)
+  )
+    .orderBy("sequence", "asc")
+    .limit(overflow);
+  const rows = executeSqliteQuerySync(params.database, candidates).rows;
+  for (const row of rows) {
+    executeSqliteQuerySync(
+      params.database,
+      getAuditRecordKysely(params.database)
+        .deleteFrom("diagnostic_events")
+        .where("scope", "=", params.scope)
+        .where("event_key", "=", row.event_key),
+    );
+  }
+}
+
+/** Opens one bounded append-only audit scope in the shared state database. */
+export function createSqliteAuditRecordStore<T>(
+  options: OpenClawStateDatabaseOptions & { scope: string; maxEntries: number },
+) {
+  const scope = options.scope;
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries));
+  function prepareRecord(record: SqliteAuditRecordEntry<T>): PreparedDiagnosticEventRow {
+    const payloadJson = JSON.stringify(record.value);
+    if (payloadJson === undefined) {
+      throw new Error(`Audit record ${scope}/${record.key} is not JSON-serializable`);
+    }
+    return {
+      event_key: record.key,
+      payload_json: payloadJson,
+      created_at: record.createdAt,
+    };
+  }
+
+  function insertRecord(database: DatabaseSync, record: DiagnosticEventRow): void {
+    executeSqliteQuerySync(
+      database,
+      getAuditRecordKysely(database)
+        .insertInto("diagnostic_events")
+        .values({
+          scope,
+          event_key: record.event_key,
+          payload_json: record.payload_json,
+          created_at: record.created_at,
+          sequence: record.sequence,
+        })
+        .onConflict((conflict) => conflict.columns(["scope", "event_key"]).doNothing()),
+    );
+  }
+
+  return {
+    register(key: string, value: T, createdAt = Date.now()): void {
+      const record = prepareRecord({ key, value, createdAt });
+      runOpenClawStateWriteTransaction((database) => {
+        insertRecord(database.db, {
+          ...record,
+          sequence: nextAuditSequence({ database: database.db, scope, legacy: false }),
+        });
+        // Audit retention is scope-local. Keep the just-written row and evict the oldest
+        // prior rows in the same synchronous commit section.
+        pruneAuditRecords({
+          database: database.db,
+          scope,
+          maxEntries,
+          protectedKey: key,
+        });
+      }, options);
+    },
+    upsert(key: string, value: T, createdAt = Date.now()): void {
+      const record = prepareRecord({ key, value, createdAt });
+      runOpenClawStateWriteTransaction((database) => {
+        executeSqliteQuerySync(
+          database.db,
+          getAuditRecordKysely(database.db)
+            .insertInto("diagnostic_events")
+            .values({
+              scope,
+              event_key: record.event_key,
+              payload_json: record.payload_json,
+              created_at: record.created_at,
+              sequence: nextAuditSequence({ database: database.db, scope, legacy: false }),
+            })
+            .onConflict((conflict) =>
+              conflict.columns(["scope", "event_key"]).doUpdateSet({
+                payload_json: record.payload_json,
+                created_at: record.created_at,
+              }),
+            ),
+        );
+        pruneAuditRecords({
+          database: database.db,
+          scope,
+          maxEntries,
+          protectedKey: key,
+        });
+      }, options);
+    },
+    registerLegacyMany(records: readonly SqliteAuditRecordEntry<T>[]): void {
+      const prepared = records.map(prepareRecord);
+      if (prepared.length === 0) {
+        return;
+      }
+      // Legacy imports can contain tens of thousands of rows. Serialize first,
+      // then assign ordered negative sequences before runtime audit history.
+      runOpenClawStateWriteTransaction((database) => {
+        let sequence = nextAuditSequence({ database: database.db, scope, legacy: true });
+        for (const record of prepared) {
+          insertRecord(database.db, { ...record, sequence });
+          sequence += 1;
+        }
+        pruneAuditRecords({ database: database.db, scope, maxEntries });
+      }, options);
+    },
+    size(): number {
+      return countAuditRecords(openOpenClawStateDatabase(options).db, scope);
+    },
+    entries(): SqliteAuditRecordEntry<T>[] {
+      const database = openOpenClawStateDatabase(options);
+      return executeSqliteQuerySync(
+        database.db,
+        getAuditRecordKysely(database.db)
+          .selectFrom("diagnostic_events")
+          .select(["event_key", "payload_json", "created_at", "sequence"])
+          .where("scope", "=", scope)
+          .orderBy("sequence", "asc"),
+      ).rows.map((row) => parseAuditRecord<T>(row));
+    },
+  };
+}
diff --git a/src/infra/state-migrations.audit-backup.test.ts b/src/infra/state-migrations.audit-backup.test.ts
new file mode 100644
index 00000000000..5c632e2253b
--- /dev/null
+++ b/src/infra/state-migrations.audit-backup.test.ts
@@ -0,0 +1,242 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { expectDefined } from "@openclaw/normalization-core";
+import { afterEach, describe, expect, it } from "vitest";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
+import { withTempDir } from "../test-helpers/temp-dir.js";
+import {
+  createLegacyAuditBackupSnapshots,
+  hasLegacyAuditBackupSources,
+  isLegacyAuditMigrationBackupPath,
+} from "./state-migrations.audit-backup.js";
+
+const TEST_SCRUB_PATTERN = Buffer.from(
+  Array.from({ length: 32 }, (_, index) => (index % 2 === 0 ? 0x20 : 0x09)),
+);
+
+function configAuditRecord(value: string) {
+  return {
+    ts: "2026-07-01T00:00:00.000Z",
+    source: "config-io",
+    event: "config.write",
+    argv: ["openclaw", "config", "set", "token", value],
+    execArgv: [],
+  };
+}
+
+async function buildTestAuditRestoreJournal(
+  rawPath: string,
+  sourceRaw: Buffer,
+  scrubbedBytes = 0,
+): Promise<string> {
+  const stat = await fs.stat(rawPath);
+  const journal = `${JSON.stringify({
+    schemaVersion: 6,
+    rawBase64: sourceRaw.toString("base64"),
+    scrubPatternBase64: TEST_SCRUB_PATTERN.toString("base64"),
+    target: { dev: stat.dev, ino: stat.ino, size: sourceRaw.length },
+  })}\n`;
+  await fs.writeFile(
+    `${rawPath}.doctor-scrub-progress`,
+    `${JSON.stringify({
+      schemaVersion: 1,
+      journalHash: createHash("sha256").update(journal).digest("hex"),
+      direction: "scrubbing",
+      committedBytes: scrubbedBytes,
+      pendingEnd: scrubbedBytes,
+      extentBytes: sourceRaw.length,
+    })}\n`,
+  );
+  return journal;
+}
+
+describe("legacy audit raw backup snapshots", () => {
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+  });
+
+  it("recognizes only supported audit migration paths", () => {
+    const stateDir = "/opt/openclaw/state";
+    expect(
+      isLegacyAuditMigrationBackupPath(
+        `${stateDir}/logs/config-audit.jsonl.migrated.10.raw.doctor-scrub-restore`,
+        stateDir,
+      ),
+    ).toBe(true);
+    expect(
+      isLegacyAuditMigrationBackupPath(
+        `${stateDir}/audit/.system-agent.jsonl.doctor-importing.2`,
+        stateDir,
+      ),
+    ).toBe(true);
+    expect(
+      isLegacyAuditMigrationBackupPath(
+        `${stateDir}/logs/config-audit.jsonl.migrated.raw.doctor-scrub-progress`,
+        stateDir,
+      ),
+    ).toBe(true);
+    expect(
+      isLegacyAuditMigrationBackupPath(
+        `${stateDir}/plugins/example/cache.jsonl.migrated.raw`,
+        stateDir,
+      ),
+    ).toBe(false);
+  });
+
+  it("propagates audit-directory inspection failures", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-inspection-" }, async (stateDir) => {
+      await fs.writeFile(path.join(stateDir, "logs"), "not a directory");
+
+      await expect(hasLegacyAuditBackupSources(stateDir)).rejects.toMatchObject({
+        code: "ENOTDIR",
+      });
+    });
+  });
+
+  it("captures an active legacy source before the later SQLite snapshot", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-active-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "state");
+      const tempDir = path.join(rootDir, "backup-temp");
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.mkdir(tempDir);
+      await fs.writeFile(sourcePath, `${JSON.stringify(configAuditRecord("active-value-7f3c"))}\n`);
+
+      const snapshots = await createLegacyAuditBackupSnapshots({ stateDir, tempDir });
+      const snapshotAsset = expectDefined(snapshots[0], "snapshot");
+      const snapshot = await fs.readFile(snapshotAsset.sourcePath, "utf8");
+
+      expect(snapshotAsset.archiveSourcePath).toBe(sourcePath);
+      expect(snapshot).not.toContain("active-value-7f3c");
+      expect(JSON.parse(snapshot.trim())).toMatchObject({
+        argv: ["openclaw", "config", "set", "token", "***"],
+      });
+    });
+  });
+
+  it("captures a stable active prefix while an old writer keeps appending", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-appending-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "state");
+      const tempDir = path.join(rootDir, "backup-temp");
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.mkdir(tempDir);
+      await fs.writeFile(
+        sourcePath,
+        Buffer.concat([
+          Buffer.from(`${JSON.stringify(configAuditRecord("initial-value-7f3c"))}\n`),
+          Buffer.alloc(4 * 1024 * 1024, 0x20),
+        ]),
+      );
+
+      const snapshotPromise = createLegacyAuditBackupSnapshots({ stateDir, tempDir });
+      for (let index = 0; index < 8; index += 1) {
+        await fs.appendFile(
+          sourcePath,
+          `${JSON.stringify(configAuditRecord(`late-value-${index}-9a21`))}\n`,
+        );
+      }
+      const snapshots = await snapshotPromise;
+      const snapshotAsset = expectDefined(snapshots[0], "snapshot");
+      const snapshot = await fs.readFile(snapshotAsset.sourcePath, "utf8");
+
+      expect(snapshot).not.toContain("initial-value-7f3c");
+      expect(snapshot).not.toContain("late-value-");
+      expect(
+        snapshot
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line)),
+      ).not.toHaveLength(0);
+    });
+  });
+
+  it("captures an unimported append without archiving its secret", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "state");
+      const tempDir = path.join(rootDir, "backup-temp");
+      const rawPath = path.join(stateDir, "logs", "config-audit.jsonl.migrated.raw");
+      await fs.mkdir(path.dirname(rawPath), { recursive: true });
+      await fs.mkdir(tempDir);
+      await fs.writeFile(rawPath, `${JSON.stringify(configAuditRecord("late-value-7f3c"))}\n`);
+
+      const snapshots = await createLegacyAuditBackupSnapshots({ stateDir, tempDir });
+
+      expect(snapshots).toHaveLength(1);
+      const snapshotAsset = expectDefined(snapshots[0], "snapshot");
+      expect(snapshotAsset.archiveSourcePath).toBe(rawPath);
+      const snapshot = await fs.readFile(snapshotAsset.sourcePath, "utf8");
+      expect(snapshot).not.toContain("late-value-7f3c");
+      expect(JSON.parse(snapshot.trim())).toMatchObject({
+        argv: ["openclaw", "config", "set", "token", "***"],
+      });
+    });
+  });
+
+  it("reconstructs a scrub-in-progress source and sanitizes its later append", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-recovery-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "state");
+      const tempDir = path.join(rootDir, "backup-temp");
+      const rawPath = path.join(stateDir, "logs", "config-audit.jsonl.migrated.raw");
+      const original = Buffer.from(`${JSON.stringify(configAuditRecord("original-value-7f3c"))}\n`);
+      const later = `${JSON.stringify(configAuditRecord("later-value-9a21"))}\n`;
+      const partial = Buffer.from(original);
+      for (let index = 0; index < Math.floor(partial.length / 2); index += 1) {
+        partial[index] = TEST_SCRUB_PATTERN[index % TEST_SCRUB_PATTERN.length]!;
+      }
+      await fs.mkdir(path.dirname(rawPath), { recursive: true });
+      await fs.mkdir(tempDir);
+      await fs.writeFile(rawPath, Buffer.concat([partial, Buffer.from(later)]));
+      await fs.writeFile(
+        `${rawPath}.doctor-scrub-restore`,
+        await buildTestAuditRestoreJournal(rawPath, original, Math.floor(partial.length / 2)),
+      );
+
+      const snapshots = await createLegacyAuditBackupSnapshots({ stateDir, tempDir });
+      const snapshotAsset = expectDefined(snapshots[0], "snapshot");
+      const snapshot = await fs.readFile(snapshotAsset.sourcePath, "utf8");
+
+      expect(snapshot).not.toContain("original-value-7f3c");
+      expect(snapshot).not.toContain("later-value-9a21");
+      expect(
+        snapshot
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line)),
+      ).toMatchObject([
+        { argv: ["openclaw", "config", "set", "token", "***"] },
+        { argv: ["openclaw", "config", "set", "token", "***"] },
+      ]);
+    });
+  });
+
+  it("ignores a stale restore journal after the raw archive is replaced", async () => {
+    await withTempDir({ prefix: "openclaw-audit-backup-stale-journal-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "state");
+      const tempDir = path.join(rootDir, "backup-temp");
+      const rawPath = path.join(stateDir, "logs", "config-audit.jsonl.migrated.raw");
+      const original = Buffer.from(`${JSON.stringify(configAuditRecord("old-value-7f3c"))}\n`);
+      const replacement = {
+        ...configAuditRecord("replacement-value-9a21"),
+        event: "config.delete",
+      };
+      await fs.mkdir(path.dirname(rawPath), { recursive: true });
+      await fs.mkdir(tempDir);
+      await fs.writeFile(rawPath, `${JSON.stringify(replacement)}\n`);
+      await fs.writeFile(
+        `${rawPath}.doctor-scrub-restore`,
+        await buildTestAuditRestoreJournal(rawPath, original),
+      );
+
+      const snapshots = await createLegacyAuditBackupSnapshots({ stateDir, tempDir });
+      const snapshotAsset = expectDefined(snapshots[0], "snapshot");
+      const snapshot = JSON.parse(await fs.readFile(snapshotAsset.sourcePath, "utf8"));
+
+      expect(snapshot).toMatchObject({
+        event: "config.delete",
+        argv: ["openclaw", "config", "set", "token", "***"],
+      });
+    });
+  });
+});
diff --git a/src/infra/state-migrations.audit-backup.ts b/src/infra/state-migrations.audit-backup.ts
new file mode 100644
index 00000000000..deadf5f7b2a
--- /dev/null
+++ b/src/infra/state-migrations.audit-backup.ts
@@ -0,0 +1,228 @@
+// Builds secret-sanitized backup replacements for legacy audit append archives.
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import { root as createFsSafeRoot } from "./fs-safe.js";
+import {
+  detectLegacyAuditLogs,
+  legacyAuditRawCheckpointKey,
+  legacyAuditSourceGenerationKey,
+  type LegacyAuditRawCheckpoint,
+} from "./state-migrations.audit-checkpoints.js";
+import {
+  prepareLegacyAuditRecords,
+  serializePreparedAuditRecords,
+} from "./state-migrations.audit-records.js";
+import {
+  findPreviousLegacyAuditRawCheckpoint,
+  readLegacyAuditRecoverySourceForBackup,
+  readLegacyAuditSourcePrefixSnapshotForBackup,
+} from "./state-migrations.audit-recovery.js";
+
+const LEGACY_AUDIT_LOGICAL_PATHS = [
+  { directory: "logs", basename: "config-audit.jsonl" },
+  { directory: "audit", basename: "system-agent.jsonl" },
+  { directory: "audit", basename: "crestodian.jsonl" },
+] as const;
+
+export async function hasLegacyAuditBackupSources(stateDir: string): Promise<boolean> {
+  for (const logical of LEGACY_AUDIT_LOGICAL_PATHS) {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(path.join(stateDir, logical.directory));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    const escaped = logical.basename.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const sourcePattern = new RegExp(
+      `^(?:${escaped}|\\.${escaped}\\.doctor-importing(?:\\.(?:[2-9]|[1-9][0-9]+))?|${escaped}\\.migrated(?:\\.(?:[2-9]|[1-9][0-9]+))?\\.raw(?:\\.doctor-scrub-(?:progress|restore|staging))?)$`,
+      "u",
+    );
+    if (entries.some((entry) => sourcePattern.test(entry))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function isLegacyAuditMigrationBackupPath(sourcePath: string, stateDir: string): boolean {
+  const relativePath = path.relative(path.resolve(stateDir), path.resolve(sourcePath));
+  if (!relativePath || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+    return false;
+  }
+  const directory = path.dirname(relativePath);
+  const basename = path.basename(relativePath);
+  for (const logical of LEGACY_AUDIT_LOGICAL_PATHS) {
+    if (directory !== logical.directory) {
+      continue;
+    }
+    if (basename === logical.basename) {
+      return true;
+    }
+    const escaped = logical.basename.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const claimPattern = new RegExp(
+      `^\\.${escaped}\\.doctor-importing(?:\\.(?:[2-9]|[1-9][0-9]+))?$`,
+      "u",
+    );
+    const rawPattern = new RegExp(
+      `^${escaped}\\.migrated(?:\\.(?:[2-9]|[1-9][0-9]+))?\\.raw(?:\\.doctor-scrub-(?:progress|restore|staging))?$`,
+      "u",
+    );
+    if (claimPattern.test(basename) || rawPattern.test(basename)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+type LegacyAuditBackupCheckpoint = {
+  key: string;
+  value: LegacyAuditRawCheckpoint;
+};
+
+export type LegacyAuditBackupSnapshot = {
+  sourcePath: string;
+  archiveSourcePath: string;
+  skippedSourcePaths: Set<string>;
+  checkpoint?: LegacyAuditBackupCheckpoint;
+};
+
+/** Replaces live raw checkpoints with metadata for the transformed backup files. */
+export function rewriteLegacyAuditBackupCheckpoints(
+  database: DatabaseSync,
+  snapshots: readonly LegacyAuditBackupSnapshot[],
+): void {
+  const hasDiagnosticEvents = database // sqlite-allow-raw -- Offline snapshot maintenance boundary.
+    .prepare("SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get("diagnostic_events") as { ok?: unknown } | undefined;
+  if (hasDiagnosticEvents?.ok !== 1) {
+    return;
+  }
+  const scope = "migration.legacy-audit-raw";
+  database.prepare("DELETE FROM diagnostic_events WHERE scope = ?").run(scope); // sqlite-allow-raw -- Offline snapshot maintenance boundary.
+  const insert = database // sqlite-allow-raw -- Offline snapshot maintenance boundary.
+    .prepare(
+      `INSERT INTO diagnostic_events (
+        scope, event_key, payload_json, created_at, sequence
+      ) VALUES (?, ?, ?, ?, ?)`,
+    );
+  let sequence = 1;
+  for (const snapshot of snapshots) {
+    if (!snapshot.checkpoint) {
+      continue;
+    }
+    insert.run(
+      scope,
+      snapshot.checkpoint.key,
+      JSON.stringify(snapshot.checkpoint.value),
+      0,
+      sequence,
+    );
+    sequence += 1;
+  }
+}
+
+async function createLegacyAuditBackupSnapshotsOnce(params: {
+  stateDir: string;
+  tempDir: string;
+}): Promise<LegacyAuditBackupSnapshot[]> {
+  const detected = detectLegacyAuditLogs({
+    stateDir: params.stateDir,
+    doctorOnlyStateMigrations: true,
+  });
+  if (detected.sources.length === 0) {
+    return [];
+  }
+  const root = await createFsSafeRoot(params.stateDir, {
+    hardlinks: "reject",
+    maxBytes: Number.MAX_SAFE_INTEGER,
+    mkdir: false,
+    mode: 0o600,
+    symlinks: "reject",
+  });
+  const snapshots: LegacyAuditBackupSnapshot[] = [];
+  for (const [index, source] of detected.sources.entries()) {
+    const sourceRelativePath = path.relative(path.resolve(params.stateDir), source.sourcePath);
+    const snapshot =
+      source.storage === "raw-archive"
+        ? await readLegacyAuditRecoverySourceForBackup(root, sourceRelativePath)
+        : await readLegacyAuditSourcePrefixSnapshotForBackup(root, sourceRelativePath);
+    const sourceGeneration = legacyAuditSourceGenerationKey(sourceRelativePath);
+    const previousCheckpoint =
+      source.storage === "raw-archive"
+        ? findPreviousLegacyAuditRawCheckpoint(params.stateDir, sourceRelativePath)
+        : undefined;
+    const prepared = prepareLegacyAuditRecords(
+      source,
+      snapshot.raw,
+      sourceGeneration,
+      previousCheckpoint?.recordOrdinalBase ?? 0,
+    );
+    if (!prepared.ok) {
+      throw new Error(
+        `Legacy ${source.label} append archive cannot be sanitized for backup: ${prepared.warnings.join("; ")}`,
+      );
+    }
+    const sourcePath = path.join(params.tempDir, `legacy-audit-raw-${index}.jsonl`);
+    await fs.writeFile(sourcePath, prepared.sanitizedJsonl, { mode: 0o600 });
+    let checkpoint: LegacyAuditBackupCheckpoint | undefined;
+    if (previousCheckpoint) {
+      if (previousCheckpoint.recordCount > prepared.records.length) {
+        throw new Error(
+          `Legacy ${source.label} append archive is shorter than its durable checkpoint`,
+        );
+      }
+      // Backup rewrites raw bytes to sanitized JSONL. Preserve the source ordinal
+      // and rebase the checkpoint hash onto the equivalent transformed prefix.
+      const transformedPrefix = Buffer.from(
+        serializePreparedAuditRecords(prepared.records.slice(0, previousCheckpoint.recordCount)),
+        "utf8",
+      );
+      const value: LegacyAuditRawCheckpoint = {
+        ...previousCheckpoint,
+        dev: 0,
+        ino: 0,
+        mtimeMs: 0,
+        size: transformedPrefix.length,
+        contentHash: createHash("sha256").update(transformedPrefix).digest("hex"),
+      };
+      checkpoint = { key: legacyAuditRawCheckpointKey(value), value };
+    }
+    snapshots.push({
+      sourcePath,
+      archiveSourcePath: source.sourcePath,
+      ...(checkpoint ? { checkpoint } : {}),
+      skippedSourcePaths: new Set([
+        path.resolve(source.sourcePath),
+        path.resolve(`${source.sourcePath}.doctor-scrub-progress`),
+        path.resolve(`${source.sourcePath}.doctor-scrub-restore`),
+        path.resolve(`${source.sourcePath}.doctor-scrub-staging`),
+      ]),
+    });
+  }
+  return snapshots;
+}
+
+export async function createLegacyAuditBackupSnapshots(params: {
+  stateDir: string;
+  tempDir: string;
+}): Promise<LegacyAuditBackupSnapshot[]> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      return await createLegacyAuditBackupSnapshotsOnce(params);
+    } catch (error) {
+      lastError = error;
+      if (attempt < 2) {
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 25);
+        });
+      }
+    }
+  }
+  throw lastError;
+}
diff --git a/src/infra/state-migrations.audit-checkpoints.ts b/src/infra/state-migrations.audit-checkpoints.ts
new file mode 100644
index 00000000000..5efbed057d9
--- /dev/null
+++ b/src/infra/state-migrations.audit-checkpoints.ts
@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createSqliteAuditRecordStore } from "./sqlite-audit-record-store.js";
+import type {
+  LegacyAuditLogSource,
+  LegacyAuditLogsDetection,
+} from "./state-migrations.audit-logs.types.js";
+
+export type LegacyAuditFileCheckpoint = {
+  dev: number;
+  ino: number;
+  mtimeMs: number;
+  size: number;
+};
+
+export type LegacyAuditRawCheckpoint = LegacyAuditFileCheckpoint & {
+  phase: "merge-intent" | "raw";
+  generationKey: string;
+  recordCount: number;
+  recordOrdinalBase: number;
+  contentHash: string;
+  sanitizedContentHash: string;
+  sanitizedSize: number;
+};
+
+const LEGACY_AUDIT_RAW_CHECKPOINT_SCOPE = "migration.legacy-audit-raw";
+const LEGACY_AUDIT_RAW_CHECKPOINT_MAX_ENTRIES = 10_000;
+
+export function legacyAuditRawCheckpointKey(checkpoint: LegacyAuditRawCheckpoint): string {
+  return checkpoint.generationKey;
+}
+
+export function legacyAuditSourceGenerationKey(rawArchiveRelativePath: string): string {
+  // The numbered raw archive path is the durable generation identity. Unlike
+  // device/inode metadata, it survives backup restore and cross-device moves.
+  return createHash("sha256")
+    .update(rawArchiveRelativePath.replace(/\\/gu, "/"))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export function openLegacyAuditRawCheckpointStore(stateDir: string) {
+  return createSqliteAuditRecordStore<LegacyAuditRawCheckpoint>({
+    scope: LEGACY_AUDIT_RAW_CHECKPOINT_SCOPE,
+    maxEntries: LEGACY_AUDIT_RAW_CHECKPOINT_MAX_ENTRIES,
+    env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+  });
+}
+
+export function hasLegacyAuditRawCheckpointCapacity(
+  stateDir: string,
+  rawArchiveRelativePath: string,
+): boolean {
+  const generationKey = legacyAuditSourceGenerationKey(rawArchiveRelativePath);
+  const entries = openLegacyAuditRawCheckpointStore(stateDir).entries();
+  return (
+    entries.some((entry) => entry.value.generationKey === generationKey) ||
+    entries.length < LEGACY_AUDIT_RAW_CHECKPOINT_MAX_ENTRIES
+  );
+}
+
+function statLegacyAuditRawCheckpoint(sourcePath: string): LegacyAuditFileCheckpoint | undefined {
+  try {
+    const stat = fs.lstatSync(sourcePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      return undefined;
+    }
+    return { dev: stat.dev, ino: stat.ino, mtimeMs: stat.mtimeMs, size: stat.size };
+  } catch {
+    return undefined;
+  }
+}
+
+export function legacyAuditRawCheckpointsMatch(
+  left: LegacyAuditFileCheckpoint | undefined,
+  right: LegacyAuditFileCheckpoint | undefined,
+): boolean {
+  return (
+    left !== undefined &&
+    right !== undefined &&
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.mtimeMs === right.mtimeMs &&
+    left.size === right.size
+  );
+}
+
+function legacyAuditRawCheckpointIsCurrent(
+  sourcePath: string,
+  checkpoint: LegacyAuditRawCheckpoint,
+): boolean {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(sourcePath, "r");
+    const beforeStat = fs.fstatSync(fd);
+    const before = {
+      dev: beforeStat.dev,
+      ino: beforeStat.ino,
+      mtimeMs: beforeStat.mtimeMs,
+      size: beforeStat.size,
+    };
+    if (!beforeStat.isFile() || !legacyAuditRawCheckpointsMatch(checkpoint, before)) {
+      return false;
+    }
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let offset = 0;
+    while (offset < checkpoint.size) {
+      const bytesRead = fs.readSync(
+        fd,
+        chunk,
+        0,
+        Math.min(chunk.byteLength, checkpoint.size - offset),
+        offset,
+      );
+      if (bytesRead === 0) {
+        return false;
+      }
+      hash.update(chunk.subarray(0, bytesRead));
+      offset += bytesRead;
+    }
+    const afterStat = fs.fstatSync(fd);
+    const after = {
+      dev: afterStat.dev,
+      ino: afterStat.ino,
+      mtimeMs: afterStat.mtimeMs,
+      size: afterStat.size,
+    };
+    return (
+      legacyAuditRawCheckpointsMatch(before, after) &&
+      offset === checkpoint.size &&
+      hash.digest("hex") === checkpoint.contentHash
+    );
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      fs.closeSync(fd);
+    }
+  }
+}
+
+export function detectLegacyAuditLogs(params: {
+  stateDir: string;
+  doctorOnlyStateMigrations?: boolean;
+}): LegacyAuditLogsDetection {
+  const logicalSources: Array<Pick<LegacyAuditLogSource, "kind" | "label" | "sourcePath">> = [
+    {
+      kind: "config",
+      label: "config audit log",
+      sourcePath: path.join(params.stateDir, "logs", "config-audit.jsonl"),
+    },
+    {
+      kind: "system-agent",
+      label: "system-agent audit log",
+      sourcePath: path.join(params.stateDir, "audit", "system-agent.jsonl"),
+    },
+    {
+      kind: "crestodian",
+      label: "Crestodian audit log",
+      sourcePath: path.join(params.stateDir, "audit", "crestodian.jsonl"),
+    },
+  ];
+  // Startup migrates every detected source. Retired audit imports belong only
+  // to explicit `doctor --fix` repair.
+  if (params.doctorOnlyStateMigrations !== true) {
+    return { sources: [], hasLegacy: false };
+  }
+  let checkpoints: LegacyAuditRawCheckpoint[] | undefined;
+  const loadCheckpoints = () => {
+    if (checkpoints) {
+      return checkpoints;
+    }
+    try {
+      checkpoints = openLegacyAuditRawCheckpointStore(params.stateDir)
+        .entries()
+        .map((entry) => entry.value);
+    } catch {
+      checkpoints = [];
+    }
+    return checkpoints;
+  };
+  const sources: LegacyAuditLogSource[] = [];
+  for (const logical of logicalSources) {
+    let directoryEntries: string[] = [];
+    try {
+      directoryEntries = fs.readdirSync(path.dirname(logical.sourcePath));
+    } catch {
+      // The active-path check below still preserves the ordinary detection result.
+    }
+    const baseName = path.basename(logical.sourcePath).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const rawArchivePattern = new RegExp(
+      `^${baseName}\\.migrated(?:\\.([2-9]|[1-9][0-9]+))?\\.raw$`,
+      "u",
+    );
+    const claimPattern = new RegExp(
+      `^\\.${baseName}\\.doctor-importing(?:\\.([2-9]|[1-9][0-9]+))?$`,
+      "u",
+    );
+    const rawArchives = directoryEntries
+      .flatMap((entry) => {
+        const match = rawArchivePattern.exec(entry);
+        return match ? [{ entry, generation: BigInt(match[1] ?? "1") }] : [];
+      })
+      .toSorted(
+        (left, right) =>
+          (left.generation < right.generation ? -1 : left.generation > right.generation ? 1 : 0) ||
+          left.entry.localeCompare(right.entry),
+      );
+    for (const { entry } of rawArchives) {
+      const rawPath = path.join(path.dirname(logical.sourcePath), entry);
+      const rawRelativePath = path.relative(path.resolve(params.stateDir), rawPath);
+      const generationKey = legacyAuditSourceGenerationKey(rawRelativePath);
+      const checkpoint = statLegacyAuditRawCheckpoint(rawPath);
+      const hasRecoveryJournal =
+        statLegacyAuditRawCheckpoint(`${rawPath}.doctor-scrub-restore`) !== undefined;
+      if (
+        !hasRecoveryJournal &&
+        checkpoint &&
+        loadCheckpoints().some(
+          (candidate) =>
+            candidate.generationKey === generationKey &&
+            candidate.phase === "raw" &&
+            candidate.recordCount === 0 &&
+            legacyAuditRawCheckpointsMatch(candidate, checkpoint) &&
+            legacyAuditRawCheckpointIsCurrent(rawPath, candidate),
+        )
+      ) {
+        continue;
+      }
+      sources.push({
+        ...logical,
+        sourcePath: rawPath,
+        logicalSourcePath: logical.sourcePath,
+        storage: "raw-archive",
+        sanitizedArchivePath: rawPath.slice(0, -".raw".length),
+      });
+    }
+    // Claims reserve their archive generation across a crash. An older
+    // sanitized-only generation cannot be reused by a later claim.
+    const claims = directoryEntries
+      .flatMap((entry) => {
+        const match = claimPattern.exec(entry);
+        return match ? [{ entry, generation: BigInt(match[1] ?? "1") }] : [];
+      })
+      .toSorted(
+        (left, right) =>
+          (left.generation < right.generation ? -1 : left.generation > right.generation ? 1 : 0) ||
+          left.entry.localeCompare(right.entry),
+      );
+    for (const { entry, generation } of claims) {
+      const generationSuffix = generation === 1n ? "" : `.${generation}`;
+      const sanitizedArchivePath = `${logical.sourcePath}.migrated${generationSuffix}`;
+      sources.push({
+        ...logical,
+        sourcePath: path.join(path.dirname(logical.sourcePath), entry),
+        logicalSourcePath: logical.sourcePath,
+        storage: "claim",
+        sanitizedArchivePath,
+        rawArchivePath: `${sanitizedArchivePath}.raw`,
+      });
+    }
+    if (fs.existsSync(logical.sourcePath)) {
+      sources.push({
+        ...logical,
+        logicalSourcePath: logical.sourcePath,
+        storage: "active",
+      });
+    }
+  }
+  return { sources, hasLegacy: sources.length > 0 };
+}
diff --git a/src/infra/state-migrations.audit-coordination.ts b/src/infra/state-migrations.audit-coordination.ts
new file mode 100644
index 00000000000..13f36af58cc
--- /dev/null
+++ b/src/infra/state-migrations.audit-coordination.ts
@@ -0,0 +1,25 @@
+import { withOpenClawStateLease } from "../state/openclaw-state-lease.js";
+
+const LEGACY_AUDIT_COORDINATION_SCOPE = "migration.legacy-audit";
+const LEGACY_AUDIT_COORDINATION_KEY = "filesystem-sqlite-boundary";
+
+export function withLegacyAuditMigrationLease<T>(
+  stateDir: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  return withOpenClawStateLease(
+    {
+      scope: LEGACY_AUDIT_COORDINATION_SCOPE,
+      key: LEGACY_AUDIT_COORDINATION_KEY,
+      database: {
+        scope: "shared",
+        options: { env: { ...process.env, OPENCLAW_STATE_DIR: stateDir } },
+      },
+      leaseMs: 60_000,
+      waitMs: 5_000,
+      leaseLabel: "legacy audit migration lease",
+      operationLabel: "migration.legacy-audit.lease",
+    },
+    async () => await run(),
+  );
+}
diff --git a/src/infra/state-migrations.audit-logs.test.ts b/src/infra/state-migrations.audit-logs.test.ts
new file mode 100644
index 00000000000..f4d535b36f8
--- /dev/null
+++ b/src/infra/state-migrations.audit-logs.test.ts
@@ -0,0 +1,1042 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CONFIG_AUDIT_MAX_ENTRIES, CONFIG_AUDIT_SCOPE } from "../config/io.audit.js";
+import { listConfigAuditRecordsForTests } from "../config/io.audit.test-support.js";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
+import { SYSTEM_AGENT_AUDIT_SCOPE } from "../system-agent/audit.js";
+import { listSystemAgentAuditEntriesForTests } from "../system-agent/audit.test-support.js";
+import { withTempDir } from "../test-helpers/temp-dir.js";
+import { acquireGatewayLock } from "./gateway-lock.js";
+import { createSqliteAuditRecordStore } from "./sqlite-audit-record-store.js";
+import { detectLegacyAuditLogs, migrateLegacyAuditLogs } from "./state-migrations.audit-logs.js";
+
+const TEST_AUDIT_SCRUB_PATTERN = Buffer.from(
+  Array.from({ length: 32 }, (_, index) => (index % 2 === 0 ? 0x20 : 0x09)),
+);
+
+function buildTestAuditScrubbedContent(length: number): Buffer {
+  const content = Buffer.allocUnsafe(length);
+  for (let offset = 0; offset < length; offset += TEST_AUDIT_SCRUB_PATTERN.length) {
+    TEST_AUDIT_SCRUB_PATTERN.copy(
+      content,
+      offset,
+      0,
+      Math.min(TEST_AUDIT_SCRUB_PATTERN.length, length - offset),
+    );
+  }
+  return content;
+}
+
+async function buildTestAuditRestoreJournal(
+  rawPath: string,
+  sourceRaw: Buffer,
+  progress: { restoredBytes: number; scrubbedBytes: number } = {
+    restoredBytes: 0,
+    scrubbedBytes: 0,
+  },
+): Promise<string> {
+  const stat = await fs.stat(rawPath);
+  const journal = `${JSON.stringify({
+    schemaVersion: 6,
+    rawBase64: sourceRaw.toString("base64"),
+    scrubPatternBase64: TEST_AUDIT_SCRUB_PATTERN.toString("base64"),
+    target: { dev: stat.dev, ino: stat.ino, size: sourceRaw.length },
+  })}\n`;
+  await fs.writeFile(
+    `${rawPath}.doctor-scrub-progress`,
+    `${JSON.stringify({
+      schemaVersion: 1,
+      journalHash: createHash("sha256").update(journal).digest("hex"),
+      direction: progress.restoredBytes > 0 ? "restoring" : "scrubbing",
+      committedBytes: progress.restoredBytes > 0 ? progress.restoredBytes : progress.scrubbedBytes,
+      pendingEnd: progress.restoredBytes > 0 ? progress.restoredBytes : progress.scrubbedBytes,
+      extentBytes: progress.restoredBytes > 0 ? progress.scrubbedBytes : sourceRaw.length,
+    })}\n`,
+  );
+  return journal;
+}
+
+describe("legacy core audit log migration", () => {
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+  });
+
+  it("imports config and system audit JSONL only through explicit doctor repair", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-" }, async (stateDir) => {
+      const configPath = path.join(stateDir, "logs", "config-audit.jsonl");
+      const systemPath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const crestodianPath = path.join(stateDir, "audit", "crestodian.jsonl");
+      await fs.mkdir(path.dirname(configPath), { recursive: true });
+      await fs.mkdir(path.dirname(systemPath), { recursive: true });
+      const unredactedConfigRecord = {
+        ts: "2026-07-01T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "token", "must-redact"],
+        execArgv: [],
+      };
+      const unredactedDigest = createHash("sha256")
+        .update(JSON.stringify(unredactedConfigRecord))
+        .digest("hex")
+        .slice(0, 16);
+      await fs.writeFile(configPath, `${JSON.stringify(unredactedConfigRecord)}\n`);
+      await fs.writeFile(
+        systemPath,
+        `${JSON.stringify({
+          timestamp: "2026-07-02T00:00:00.000Z",
+          operation: "config.set",
+          summary: "Set config",
+        })}\n`,
+      );
+      await fs.writeFile(
+        crestodianPath,
+        `${JSON.stringify({
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Restarted gateway",
+        })}\n`,
+      );
+
+      expect(detectLegacyAuditLogs({ stateDir }).hasLegacy).toBe(false);
+      const detected = detectLegacyAuditLogs({
+        stateDir,
+        doctorOnlyStateMigrations: true,
+      });
+      expect(detected.sources).toHaveLength(3);
+
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+      expect(result.warnings).toEqual([]);
+      expect(result.changes).toHaveLength(6);
+
+      const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+      const configRecords = listConfigAuditRecordsForTests({ env, homedir: () => stateDir });
+      expect(configRecords).toHaveLength(1);
+      expect(JSON.stringify(configRecords)).not.toContain("must-redact");
+      const configEntries = createSqliteAuditRecordStore({
+        scope: CONFIG_AUDIT_SCOPE,
+        maxEntries: CONFIG_AUDIT_MAX_ENTRIES,
+        env,
+      }).entries();
+      expect(configEntries[0]?.key).not.toContain(unredactedDigest);
+      const archivedConfig = await fs.readFile(`${configPath}.migrated`, "utf8");
+      expect(archivedConfig).not.toContain("must-redact");
+      const rawArchivedConfig = await fs.readFile(`${configPath}.migrated.raw`, "utf8");
+      expect(rawArchivedConfig).not.toContain("must-redact");
+      expect(rawArchivedConfig.trim()).toBe("");
+      if (process.platform !== "win32") {
+        expect((await fs.stat(`${configPath}.migrated`)).mode & 0o777).toBe(0o600);
+        expect((await fs.stat(`${configPath}.migrated.raw`)).mode & 0o777).toBe(0o600);
+      }
+      expect(JSON.parse(archivedConfig.trim())).toMatchObject({
+        argv: ["openclaw", "config", "set", "token", "***"],
+      });
+      expect(
+        listSystemAgentAuditEntriesForTests({ env })
+          .map((entry) => entry.value.operation)
+          .toSorted(),
+      ).toEqual(["config.set", "gateway.restart"]);
+      await expect(fs.access(configPath)).rejects.toThrow();
+      await expect(fs.access(systemPath)).rejects.toThrow();
+      await expect(fs.access(crestodianPath)).rejects.toThrow();
+
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        false,
+      );
+      const laterConfigRecord = {
+        ...unredactedConfigRecord,
+        ts: "2026-07-04T00:00:00.000Z",
+        argv: ["openclaw", "config", "set", "token", "later-redaction-marker"],
+      };
+      await fs.appendFile(`${configPath}.migrated.raw`, `${JSON.stringify(laterConfigRecord)}\n`);
+      const rawRecovery = detectLegacyAuditLogs({
+        stateDir,
+        doctorOnlyStateMigrations: true,
+      });
+      expect(rawRecovery.sources).toMatchObject([{ storage: "raw-archive" }]);
+      const recovered = await migrateLegacyAuditLogs({ detected: rawRecovery, stateDir });
+      expect(recovered.warnings).toEqual([]);
+      expect(recovered.changes.join("\n")).toContain("Recovered 1 later config audit log row");
+      expect(listConfigAuditRecordsForTests({ env, homedir: () => stateDir })).toHaveLength(2);
+      await expect(fs.readFile(`${configPath}.migrated`, "utf8")).resolves.not.toContain(
+        "later-redaction-marker",
+      );
+      await expect(fs.readFile(`${configPath}.migrated.raw`, "utf8")).resolves.not.toContain(
+        "later-redaction-marker",
+      );
+      const recoveredArchiveRows = (await fs.readFile(`${configPath}.migrated`, "utf8"))
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line) as { ts: string });
+      expect(recoveredArchiveRows.map((row) => row.ts)).toEqual([
+        "2026-07-01T00:00:00.000Z",
+        "2026-07-04T00:00:00.000Z",
+      ]);
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        false,
+      );
+    });
+  });
+
+  it("rehashes a checkpointed raw archive before treating it as clean", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-rehash-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const original = {
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "original",
+      };
+      const modified = { ...original, summary: "modified" };
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, `${JSON.stringify(original)}\n`);
+      const stableMtime = new Date("2026-07-03T01:00:00.000Z");
+      await fs.utimes(sourcePath, stableMtime, stableMtime);
+      await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      const checkpointedStat = await fs.stat(rawPath);
+      const modifiedRaw = `${JSON.stringify(modified)}\n`;
+      expect(Buffer.byteLength(modifiedRaw)).toBe(checkpointedStat.size);
+      await fs.writeFile(rawPath, modifiedRaw);
+      await fs.utimes(rawPath, checkpointedStat.atimeMs / 1_000, checkpointedStat.mtimeMs / 1_000);
+      const rewrittenStat = await fs.stat(rawPath);
+      expect(rewrittenStat.mtimeMs).toBe(checkpointedStat.mtimeMs);
+      expect(rewrittenStat.size).toBe(checkpointedStat.size);
+
+      const detected = detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true });
+      expect(detected.sources).toMatchObject([{ sourcePath: rawPath, storage: "raw-archive" }]);
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+      expect(result.warnings.join("\n")).toContain("changed other than by append");
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["original"]);
+    });
+  });
+
+  it("restores the captured archive prefix when an in-place scrub write fails", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-scrub-write-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const originalRecord = {
+        ts: "2026-07-01T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "token", "scrub-write-marker"],
+        execArgv: [],
+      };
+      const originalContent = `${JSON.stringify(originalRecord)}\n`;
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, originalContent);
+
+      const probe = await fs.open(path.join(stateDir, "write-probe"), "w+");
+      const fileHandlePrototype = Object.getPrototypeOf(probe) as {
+        write(
+          buffer: Uint8Array,
+          offset: number,
+          length: number,
+          position: number | null,
+        ): Promise<{ bytesWritten: number; buffer: Uint8Array }>;
+      };
+      await probe.close();
+      const originalWrite = Reflect.get(
+        fileHandlePrototype,
+        "write",
+      ) as typeof fileHandlePrototype.write;
+      let scrubWriteCalls = 0;
+      const writeSpy = vi.spyOn(fileHandlePrototype, "write").mockImplementation(async function (
+        this: typeof fileHandlePrototype,
+        buffer: Uint8Array,
+        offset: number,
+        length: number,
+        position: number | null,
+      ) {
+        scrubWriteCalls += 1;
+        if (scrubWriteCalls === 1) {
+          return await originalWrite.call(
+            this,
+            buffer,
+            offset,
+            Math.max(1, Math.floor(length / 2)),
+            position,
+          );
+        }
+        if (scrubWriteCalls === 2) {
+          throw new Error("simulated scrub write failure");
+        }
+        return await originalWrite.call(this, buffer, offset, length, position);
+      });
+
+      let failed: Awaited<ReturnType<typeof migrateLegacyAuditLogs>>;
+      try {
+        failed = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+      } finally {
+        writeSpy.mockRestore();
+      }
+
+      expect(failed.warnings.join("\n")).toContain("restored it for Doctor retry");
+      await expect(fs.readFile(rawPath, "utf8")).resolves.toBe(originalContent);
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        true,
+      );
+
+      const recovered = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      expect(recovered.warnings).toEqual([]);
+      await expect(fs.readFile(rawPath, "utf8")).resolves.not.toContain("scrub-write-marker");
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        false,
+      );
+    });
+  });
+
+  it("restores a moved scrub journal before parsing an interrupted archive", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-scrub-restart-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      const sanitizedPath = `${sourcePath}.migrated`;
+      const rawPath = `${sanitizedPath}.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalRecord = {
+        ts: "2026-07-01T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "token", "restart-redaction-marker"],
+        execArgv: [],
+      };
+      const originalContent = `${JSON.stringify(originalRecord)}\n`;
+      const damagedContent = Buffer.from(originalContent, "utf8");
+      buildTestAuditScrubbedContent(damagedContent.length)
+        .subarray(0, Math.floor(damagedContent.length / 2))
+        .copy(damagedContent);
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sanitizedPath, "{}\n");
+      await fs.writeFile(rawPath, damagedContent);
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, Buffer.from(originalContent, "utf8"), {
+          restoredBytes: 0,
+          scrubbedBytes: Math.floor(damagedContent.length / 2),
+        }),
+      );
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings).toEqual([]);
+      await expect(fs.access(restorePath)).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(fs.readFile(rawPath, "utf8")).resolves.not.toContain("restart-redaction-marker");
+      expect(
+        listConfigAuditRecordsForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          homedir: () => stateDir,
+        }),
+      ).toHaveLength(1);
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        false,
+      );
+    });
+  });
+
+  it("discards a stale restore journal while recovering a post-checkpoint append", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-stale-journal-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalContent = `${JSON.stringify({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "config.set",
+        summary: ["token", "redaction-marker"].join("="),
+      })}\n`;
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, originalContent);
+      await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, Buffer.from(originalContent, "utf8")),
+      );
+      await fs.appendFile(
+        rawPath,
+        `${JSON.stringify({
+          timestamp: "2026-07-04T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "later",
+        })}\n`,
+      );
+
+      const detected = detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true });
+      expect(detected.hasLegacy).toBe(true);
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+      expect(result.warnings).toEqual([]);
+      expect(result.changes.join("\n")).toContain("Recovered 1 later");
+      await expect(fs.readFile(rawPath, "utf8")).resolves.not.toContain(
+        ["token", "redaction-marker"].join("="),
+      );
+      await expect(fs.access(restorePath)).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("does not replay a scrub journal over a same-inode replacement archive", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-scrub-replaced-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const sanitizedPath = `${sourcePath}.migrated`;
+      const rawPath = `${sanitizedPath}.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalContent = `${JSON.stringify({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "original archive",
+      })}\n`;
+      const replacementContent = `${JSON.stringify({
+        timestamp: "2026-07-04T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "replacement archive",
+      })}\n`;
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sanitizedPath, "{}\n");
+      await fs.writeFile(rawPath, originalContent);
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, Buffer.from(originalContent, "utf8")),
+      );
+      await fs.writeFile(rawPath, replacementContent);
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings.join("\n")).toContain("no longer matches its restore journal target");
+      await expect(fs.readFile(rawPath, "utf8")).resolves.toBe(replacementContent);
+      await expect(fs.access(restorePath)).resolves.toBeUndefined();
+    });
+  });
+
+  it("resumes a deterministic audit claim left by an interrupted Doctor", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-resume-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const claimPath = path.join(
+        path.dirname(sourcePath),
+        `.${path.basename(sourcePath)}.doctor-importing`,
+      );
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(
+        sourcePath,
+        `${JSON.stringify({
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Restarted gateway",
+        })}\n`,
+      );
+      await fs.rename(sourcePath, claimPath);
+
+      const detected = detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true });
+      expect(detected.sources).toMatchObject([{ sourcePath: claimPath, storage: "claim" }]);
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+      expect(result.warnings).toEqual([]);
+      await expect(fs.access(claimPath)).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(fs.access(`${sourcePath}.migrated.raw`)).resolves.toBeUndefined();
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toHaveLength(1);
+
+      const tenthRawArchive = `${sourcePath}.migrated.10.raw`;
+      await fs.writeFile(
+        tenthRawArchive,
+        `${JSON.stringify({
+          timestamp: "2026-07-04T00:00:00.000Z",
+          operation: "gateway.reload",
+          summary: "Reloaded gateway",
+        })}\n`,
+      );
+      const numberedRaw = detectLegacyAuditLogs({
+        stateDir,
+        doctorOnlyStateMigrations: true,
+      });
+      expect(numberedRaw.sources).toMatchObject([
+        { sourcePath: tenthRawArchive, storage: "raw-archive" },
+      ]);
+      await migrateLegacyAuditLogs({ detected: numberedRaw, stateDir });
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toHaveLength(2);
+    });
+  });
+
+  it("does not resurrect a pruned raw-archive head when later rows are appended", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-late-tail-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const records = ["first", "second", "third"].map((summary, index) => ({
+        timestamp: `2026-07-03T00:00:0${index}.000Z`,
+        operation: "gateway.restart",
+        summary,
+      }));
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(
+        sourcePath,
+        `${records.map((record) => JSON.stringify(record)).join("\n")}\n`,
+      );
+      await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      createSqliteAuditRecordStore({
+        scope: SYSTEM_AGENT_AUDIT_SCOPE,
+        maxEntries: 3,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      }).register("runtime", {
+        timestamp: "2026-07-04T00:00:00.000Z",
+        operation: "gateway.reload",
+        summary: "runtime",
+      });
+      await fs.appendFile(
+        `${sourcePath}.migrated.raw`,
+        `${JSON.stringify({
+          timestamp: "2026-07-05T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "appended",
+        })}\n`,
+      );
+
+      const recovered = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(recovered.warnings).toEqual([]);
+      expect(recovered.changes.join("\n")).toContain("Recovered 1 later");
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["second", "third", "appended", "runtime"]);
+      const rawCheckpoints = createSqliteAuditRecordStore<{ recordCount: number }>({
+        scope: "migration.legacy-audit-raw",
+        maxEntries: 10_000,
+        env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+      }).entries();
+      expect(rawCheckpoints).toHaveLength(1);
+      expect(rawCheckpoints[0]?.value.recordCount).toBe(0);
+    });
+  });
+
+  it("keeps identical rows from separate raw archive generations", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-generations-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const record = {
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "Repeated operation",
+      };
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(`${sourcePath}.migrated.raw`, `${JSON.stringify(record)}\n`);
+      await fs.writeFile(`${sourcePath}.migrated.2.raw`, `${JSON.stringify(record)}\n`);
+      await fs.writeFile(`${sourcePath}.migrated.10.raw`, `${JSON.stringify(record)}\n`);
+      const claimPath = path.join(
+        path.dirname(sourcePath),
+        `.${path.basename(sourcePath)}.doctor-importing.11`,
+      );
+      await fs.writeFile(claimPath, `${JSON.stringify(record)}\n`);
+      await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+
+      const detected = detectLegacyAuditLogs({
+        stateDir,
+        doctorOnlyStateMigrations: true,
+      });
+      expect(detected.sources.map((source) => path.basename(source.sourcePath))).toEqual([
+        "system-agent.jsonl.migrated.raw",
+        "system-agent.jsonl.migrated.2.raw",
+        "system-agent.jsonl.migrated.10.raw",
+        ".system-agent.jsonl.doctor-importing.11",
+        "system-agent.jsonl",
+      ]);
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+      expect(result.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toHaveLength(5);
+      expect(detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).hasLegacy).toBe(
+        false,
+      );
+    });
+  });
+
+  it("keeps restored raw archives idempotent after device and inode changes", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-restored-" }, async (rootDir) => {
+      const stateDir = path.join(rootDir, "source-state");
+      const restoredStateDir = path.join(rootDir, "restored-state");
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(
+        sourcePath,
+        `${JSON.stringify({
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Restored operation",
+        })}\n`,
+      );
+      await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      resetPluginStateStoreForTests();
+      await fs.cp(stateDir, restoredStateDir, { recursive: true });
+      createSqliteAuditRecordStore({
+        scope: SYSTEM_AGENT_AUDIT_SCOPE,
+        maxEntries: 1,
+        env: { ...process.env, OPENCLAW_STATE_DIR: restoredStateDir },
+      }).register("runtime-after-restore", {
+        timestamp: "2026-07-04T00:00:00.000Z",
+        operation: "gateway.reload",
+        summary: "Runtime after restore",
+      });
+
+      const restored = detectLegacyAuditLogs({
+        stateDir: restoredStateDir,
+        doctorOnlyStateMigrations: true,
+      });
+      expect(restored.sources).toMatchObject([{ storage: "raw-archive" }]);
+      const result = await migrateLegacyAuditLogs({
+        detected: restored,
+        stateDir: restoredStateDir,
+      });
+
+      expect(result.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: restoredStateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["Runtime after restore"]);
+      expect(
+        detectLegacyAuditLogs({
+          stateDir: restoredStateDir,
+          doctorOnlyStateMigrations: true,
+        }).hasLegacy,
+      ).toBe(false);
+    });
+  });
+
+  it("resumes the stable generation of an interrupted sanitized archive", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-sanitized-resume-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const claimPath = path.join(
+          path.dirname(sourcePath),
+          `.${path.basename(sourcePath)}.doctor-importing`,
+        );
+        const record = {
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Interrupted operation",
+        };
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(claimPath, `${JSON.stringify(record)}\n`);
+        await fs.writeFile(`${sourcePath}.migrated`, `${JSON.stringify(record)}\n`);
+
+        const result = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+
+        expect(result.warnings).toEqual([]);
+        await expect(fs.access(`${sourcePath}.migrated.raw`)).resolves.toBeUndefined();
+        await expect(fs.access(`${sourcePath}.migrated.2.raw`)).rejects.toMatchObject({
+          code: "ENOENT",
+        });
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }),
+        ).toHaveLength(1);
+      },
+    );
+  });
+
+  it("allocates a new generation when an active source follows a sanitized-only archive", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-sanitized-recreated-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const record = {
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Repeated after downgrade",
+        };
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        await fs.rm(`${sourcePath}.migrated.raw`);
+        const firstSanitized = await fs.readFile(`${sourcePath}.migrated`, "utf8");
+        await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+
+        const repeated = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+
+        expect(repeated.warnings).toEqual([]);
+        expect(repeated.changes.join("\n")).toContain("1 new row");
+        await expect(fs.readFile(`${sourcePath}.migrated`, "utf8")).resolves.toBe(firstSanitized);
+        await expect(fs.access(`${sourcePath}.migrated.2.raw`)).resolves.toBeUndefined();
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }),
+        ).toHaveLength(2);
+      },
+    );
+  });
+
+  it("resumes a claim at its reserved generation instead of an older sanitized-only slot", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-claimed-generation-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const secondClaimPath = path.join(
+          path.dirname(sourcePath),
+          `.${path.basename(sourcePath)}.doctor-importing.2`,
+        );
+        const record = {
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Repeated after interrupted downgrade",
+        };
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        await fs.rm(`${sourcePath}.migrated.raw`);
+        await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+        await fs.rename(sourcePath, secondClaimPath);
+
+        const detected = detectLegacyAuditLogs({
+          stateDir,
+          doctorOnlyStateMigrations: true,
+        });
+        expect(detected.sources).toMatchObject([
+          {
+            sourcePath: secondClaimPath,
+            storage: "claim",
+            sanitizedArchivePath: `${sourcePath}.migrated.2`,
+            rawArchivePath: `${sourcePath}.migrated.2.raw`,
+          },
+        ]);
+        const resumed = await migrateLegacyAuditLogs({ detected, stateDir });
+
+        expect(resumed.warnings).toEqual([]);
+        await expect(fs.access(`${sourcePath}.migrated.2.raw`)).resolves.toBeUndefined();
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }),
+        ).toHaveLength(2);
+      },
+    );
+  });
+
+  it("leaves malformed audit sources in place without partial imports", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-invalid-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, "{bad json\n");
+      const detected = detectLegacyAuditLogs({
+        stateDir,
+        doctorOnlyStateMigrations: true,
+      });
+
+      const result = await migrateLegacyAuditLogs({ detected, stateDir });
+      expect(result.warnings.join("\n")).toContain("Failed reading system-agent audit log");
+      await expect(fs.access(sourcePath)).resolves.toBeUndefined();
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toEqual([]);
+    });
+  });
+
+  it("does not migrate newer audit generations before an older source is repaired", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-order-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const event = (summary: string) => ({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary,
+      });
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(rawPath, "{bad json\n");
+      await fs.writeFile(sourcePath, `${JSON.stringify(event("newer generation"))}\n`);
+
+      const blocked = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(blocked.changes).toEqual([]);
+      expect(blocked.warnings.join("\n")).toContain("Failed reading system-agent audit log");
+      await expect(fs.access(sourcePath)).resolves.toBeUndefined();
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toEqual([]);
+
+      await fs.writeFile(rawPath, `${JSON.stringify(event("repaired older generation"))}\n`);
+      const repaired = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(repaired.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["repaired older generation", "newer generation"]);
+    });
+  });
+
+  it("restores the active source when raw archive hardening fails", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-permissions-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      const record = {
+        ts: "2026-07-01T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "token", "must-redact"],
+        execArgv: [],
+      };
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, `${JSON.stringify(record)}\n`);
+      const probe = await fs.open(path.join(stateDir, "chmod-probe"), "w");
+      const fileHandlePrototype = Object.getPrototypeOf(probe) as {
+        chmod(mode: number): Promise<void>;
+      };
+      await probe.close();
+      const originalChmod = Reflect.get(fileHandlePrototype, "chmod") as (
+        this: typeof fileHandlePrototype,
+        mode: number,
+      ) => Promise<void>;
+      let chmodCalls = 0;
+      const chmodSpy = vi.spyOn(fileHandlePrototype, "chmod").mockImplementation(function (
+        this: typeof fileHandlePrototype,
+        mode: number,
+      ) {
+        chmodCalls += 1;
+        if (chmodCalls === 3) {
+          return Promise.reject(new Error("simulated chmod failure"));
+        }
+        return originalChmod.call(this, mode);
+      });
+
+      let failed: Awaited<ReturnType<typeof migrateLegacyAuditLogs>>;
+      try {
+        failed = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+      } finally {
+        chmodSpy.mockRestore();
+      }
+
+      expect(failed.changes).toEqual([]);
+      expect(failed.warnings.join("\n")).toContain("Failed securing raw archived config audit log");
+      await expect(fs.readFile(sourcePath, "utf8")).resolves.toContain("must-redact");
+      await expect(fs.access(`${sourcePath}.migrated`)).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(fs.access(`${sourcePath}.migrated.raw`)).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+
+      const recovered = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      expect(recovered.warnings).toEqual([]);
+      await expect(fs.access(sourcePath)).rejects.toMatchObject({ code: "ENOENT" });
+      await expect(fs.access(`${sourcePath}.migrated.raw`)).resolves.toBeUndefined();
+    });
+  });
+
+  it("requires exclusive state ownership before claiming legacy audit files", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-lock-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(
+        sourcePath,
+        `${JSON.stringify({
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "Restarted gateway",
+        })}\n`,
+      );
+      const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+      const gatewayLock = await acquireGatewayLock({
+        allowInTests: true,
+        env,
+        pollIntervalMs: 10,
+        port: 18_791,
+        timeoutMs: 100,
+      });
+      if (!gatewayLock) {
+        throw new Error("expected test Gateway lock");
+      }
+
+      let result: Awaited<ReturnType<typeof migrateLegacyAuditLogs>>;
+      try {
+        result = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+      } finally {
+        await gatewayLock.release();
+      }
+
+      expect(result.warnings.join("\n")).toContain("exclusive state ownership is unavailable");
+      await expect(fs.access(sourcePath)).resolves.toBeUndefined();
+      expect(listSystemAgentAuditEntriesForTests({ env })).toEqual([]);
+    });
+  });
+
+  it("leaves rows from an old config writer at the recreated source path", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-concurrent-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      const records = Array.from({ length: 10_000 }, (_, index) =>
+        JSON.stringify({
+          ts: new Date(Date.UTC(2026, 6, 1, 0, 0, index)).toISOString(),
+          source: "config-io",
+          event: "config.write",
+          argv: ["openclaw", "config", "set", `key-${index}`, "value"],
+          execArgv: [],
+        }),
+      );
+      await fs.writeFile(sourcePath, `${records.join("\n")}\n`);
+      const retainedRecord = {
+        ts: "2026-07-02T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "later", "value"],
+        execArgv: [],
+      };
+
+      let settled = false;
+      const migration = migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      }).finally(() => {
+        settled = true;
+      });
+      for (let attempt = 0; attempt < 500; attempt += 1) {
+        try {
+          await fs.access(sourcePath);
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            break;
+          }
+          throw error;
+        }
+        await new Promise<void>((resolve) => {
+          setImmediate(resolve);
+        });
+      }
+      expect(settled).toBe(false);
+      await fs.appendFile(sourcePath, `${JSON.stringify(retainedRecord)}\n`);
+
+      const first = await migration;
+      expect(first.warnings.join("\n")).toContain("An old writer recreated config audit log");
+      await expect(fs.readFile(sourcePath, "utf8")).resolves.toBe(
+        `${JSON.stringify(retainedRecord)}\n`,
+      );
+
+      const second = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      expect(second.warnings).toEqual([]);
+      await expect(fs.access(sourcePath)).rejects.toMatchObject({ code: "ENOENT" });
+      expect(
+        createSqliteAuditRecordStore({
+          scope: CONFIG_AUDIT_SCOPE,
+          maxEntries: CONFIG_AUDIT_MAX_ENTRIES,
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).entries(),
+      ).toHaveLength(10_001);
+    });
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "rejects audit sources beneath symlinked state parents",
+    async () => {
+      const externalAuditDir = await fs.mkdtemp(
+        path.join(os.tmpdir(), "openclaw-audit-migration-external-"),
+      );
+      try {
+        await withTempDir({ prefix: "openclaw-audit-migration-symlink-" }, async (stateDir) => {
+          const externalSource = path.join(externalAuditDir, "system-agent.jsonl");
+          await fs.writeFile(
+            externalSource,
+            `${JSON.stringify({
+              timestamp: "2026-07-03T00:00:00.000Z",
+              operation: "gateway.restart",
+              summary: "Outside state root",
+            })}\n`,
+          );
+          await fs.symlink(externalAuditDir, path.join(stateDir, "audit"));
+          const detected = detectLegacyAuditLogs({
+            stateDir,
+            doctorOnlyStateMigrations: true,
+          });
+
+          const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+          expect(result.changes).toEqual([]);
+          expect(result.warnings.join("\n")).toMatch(/alias|symlink|outside workspace/u);
+          await expect(fs.readFile(externalSource, "utf8")).resolves.toContain(
+            "Outside state root",
+          );
+          await expect(fs.access(`${externalSource}.migrated`)).rejects.toMatchObject({
+            code: "ENOENT",
+          });
+          expect(
+            listSystemAgentAuditEntriesForTests({
+              env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+            }),
+          ).toEqual([]);
+        });
+      } finally {
+        await fs.rm(externalAuditDir, { recursive: true, force: true });
+      }
+    },
+  );
+});
diff --git a/src/infra/state-migrations.audit-logs.ts b/src/infra/state-migrations.audit-logs.ts
new file mode 100644
index 00000000000..af95fff4bdd
--- /dev/null
+++ b/src/infra/state-migrations.audit-logs.ts
@@ -0,0 +1,669 @@
+// Doctor-only import for retired core JSONL audit stores.
+import fs from "node:fs";
+import path from "node:path";
+import {
+  CONFIG_AUDIT_MAX_ENTRIES,
+  CONFIG_AUDIT_SCOPE,
+  type ConfigAuditRecord,
+} from "../config/io.audit.js";
+import {
+  SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+  SYSTEM_AGENT_AUDIT_SCOPE,
+  type SystemAgentAuditEntry,
+} from "../system-agent/audit.js";
+import { root as createFsSafeRoot } from "./fs-safe.js";
+import { acquireGatewayLock } from "./gateway-lock.js";
+import { createSqliteAuditRecordStore } from "./sqlite-audit-record-store.js";
+import {
+  hasLegacyAuditRawCheckpointCapacity,
+  legacyAuditSourceGenerationKey,
+} from "./state-migrations.audit-checkpoints.js";
+import { withLegacyAuditMigrationLease } from "./state-migrations.audit-coordination.js";
+import type {
+  LegacyAuditLogSource,
+  LegacyAuditLogsDetection,
+} from "./state-migrations.audit-logs.types.js";
+import {
+  prepareLegacyAuditRecords,
+  serializePreparedAuditRecords,
+  type PreparedAuditRecord,
+} from "./state-migrations.audit-records.js";
+import {
+  finalizeLegacyAuditRecoveryArchive,
+  findPreviousLegacyAuditRawCheckpoint,
+  readLegacyAuditSourceSnapshot,
+  recordLegacyAuditRawCheckpoint,
+  recordsAfterLegacyAuditRawCheckpoint,
+  restoreInterruptedAuditRecoveryArchive,
+  scrubLegacyAuditRecoveryArchive,
+  type AuditMigrationRoot,
+  type LegacyAuditSourceSnapshot,
+} from "./state-migrations.audit-recovery.js";
+import { writeRecoveredSanitizedAuditArchive } from "./state-migrations.audit-sanitized.js";
+import type { MigrationMessages } from "./state-migrations.types.js";
+
+function legacyAuditClaimPathForArchive(sourcePath: string, sanitizedArchivePath: string): string {
+  const archivePrefix = `${sourcePath}.migrated`;
+  if (!sanitizedArchivePath.startsWith(archivePrefix)) {
+    throw new Error(`Invalid legacy audit archive path ${sanitizedArchivePath}`);
+  }
+  const generationSuffix = sanitizedArchivePath.slice(archivePrefix.length);
+  return path.join(
+    path.dirname(sourcePath),
+    `.${path.basename(sourcePath)}.doctor-importing${generationSuffix}`,
+  );
+}
+
+export { detectLegacyAuditLogs } from "./state-migrations.audit-checkpoints.js";
+
+type AuditArchiveRelativePaths = {
+  sanitized: string;
+  raw: string;
+  resumeSanitized: boolean;
+};
+
+async function resolveAuditArchiveRelativePaths(
+  root: AuditMigrationRoot,
+  sourceRelativePath: string,
+): Promise<AuditArchiveRelativePaths> {
+  const directoryPath = path.join(root.rootReal, path.dirname(sourceRelativePath));
+  const baseName = path.basename(sourceRelativePath).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const archivePattern = new RegExp(
+    `^${baseName}\\.migrated(?:\\.([2-9]|[1-9][0-9]+))?(?:\\.raw)?$`,
+    "u",
+  );
+  const claimPattern = new RegExp(
+    `^\\.${baseName}\\.doctor-importing(?:\\.([2-9]|[1-9][0-9]+))?$`,
+    "u",
+  );
+  let latestGeneration = 0n;
+  for (const entry of fs.readdirSync(directoryPath)) {
+    const match = archivePattern.exec(entry) ?? claimPattern.exec(entry);
+    if (!match) {
+      continue;
+    }
+    const generation = BigInt(match[1] ?? "1");
+    if (generation > latestGeneration) {
+      latestGeneration = generation;
+    }
+  }
+  const generation = latestGeneration + 1n;
+  const sanitized = `${sourceRelativePath}.migrated${generation === 1n ? "" : `.${generation}`}`;
+  return { sanitized, raw: `${sanitized}.raw`, resumeSanitized: false };
+}
+
+async function secureAuditArchiveFile(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  label: string;
+  warnings: string[];
+}): Promise<boolean> {
+  try {
+    const opened = await params.root.open(params.relativePath);
+    try {
+      await opened.handle.chmod(0o600);
+      await opened.handle.sync();
+    } finally {
+      await opened.handle.close();
+    }
+    return true;
+  } catch (error) {
+    params.warnings.push(`Failed securing ${params.label} legacy source: ${String(error)}`);
+    return false;
+  }
+}
+
+async function archiveLegacyAuditClaim(params: {
+  source: LegacyAuditLogSource;
+  claimRelativePath: string;
+  archivePaths: { sanitized: string; raw: string; resumeSanitized: boolean };
+  snapshot: LegacyAuditSourceSnapshot;
+  sanitizedJsonl: string;
+  root: AuditMigrationRoot;
+  changes: string[];
+  warnings: string[];
+}): Promise<{
+  moved: boolean;
+  rawRelativePath?: string;
+  scrubbedSnapshot?: LegacyAuditSourceSnapshot;
+}> {
+  let moved = false;
+  let sanitizedCreated = false;
+  const archivePaths = params.archivePaths;
+  try {
+    if (archivePaths.resumeSanitized) {
+      await params.root.write(archivePaths.sanitized, params.sanitizedJsonl, {
+        mkdir: false,
+        mode: 0o600,
+      });
+    } else {
+      await params.root.create(archivePaths.sanitized, params.sanitizedJsonl, { mode: 0o600 });
+    }
+    sanitizedCreated = true;
+    if (
+      !(await secureAuditArchiveFile({
+        root: params.root,
+        relativePath: archivePaths.sanitized,
+        label: `sanitized ${params.source.label}`,
+        warnings: params.warnings,
+      }))
+    ) {
+      return { moved: false };
+    }
+    // Keep the claimed inode intact. A predecessor CLI may already hold an append
+    // descriptor across the claim; moving that inode to a named migration backup
+    // preserves any late write while the sanitized sibling remains safe to inspect.
+    await params.root.move(params.claimRelativePath, archivePaths.raw);
+    if (
+      !(await secureAuditArchiveFile({
+        root: params.root,
+        relativePath: archivePaths.raw,
+        label: `raw archived ${params.source.label}`,
+        warnings: params.warnings,
+      }))
+    ) {
+      try {
+        await params.root.move(archivePaths.raw, params.claimRelativePath);
+      } catch (error) {
+        params.warnings.push(
+          `Failed restoring unsecured ${params.source.label} legacy source: ${String(error)}`,
+        );
+      }
+      return { moved: false };
+    }
+    moved = true;
+    const scrubbedSnapshot = await scrubLegacyAuditRecoveryArchive({
+      root: params.root,
+      relativePath: archivePaths.raw,
+      expectedSnapshot: params.snapshot,
+      label: params.source.label,
+      warnings: params.warnings,
+    });
+    params.changes.push(
+      `Archived sanitized ${params.source.label} legacy source → ${path.join(path.dirname(params.source.logicalSourcePath), path.basename(archivePaths.sanitized))}; ${scrubbedSnapshot ? "scrubbed same-inode append recovery archive" : "retained same-inode append recovery archive for Doctor retry"} → ${path.join(path.dirname(params.source.logicalSourcePath), path.basename(archivePaths.raw))}`,
+    );
+    return {
+      moved: true,
+      rawRelativePath: archivePaths.raw,
+      ...(scrubbedSnapshot ? { scrubbedSnapshot } : {}),
+    };
+  } catch (error) {
+    params.warnings.push(
+      `Failed archiving ${params.source.label} ${params.source.logicalSourcePath}: ${String(error)}`,
+    );
+  } finally {
+    if (!moved && sanitizedCreated) {
+      await params.root.remove(archivePaths.sanitized).catch(() => undefined);
+    }
+  }
+  return { moved, ...(moved ? { rawRelativePath: archivePaths.raw } : {}) };
+}
+
+async function restoreOrPreserveLegacyAuditClaim(params: {
+  source: LegacyAuditLogSource;
+  claimRelativePath: string;
+  sourceRelativePath: string;
+  archivePaths: AuditArchiveRelativePaths;
+  root: AuditMigrationRoot;
+  warnings: string[];
+}): Promise<void> {
+  try {
+    if (!(await params.root.exists(params.claimRelativePath))) {
+      return;
+    }
+    if (!(await params.root.exists(params.sourceRelativePath))) {
+      await params.root.move(params.claimRelativePath, params.sourceRelativePath);
+      await secureAuditArchiveFile({
+        root: params.root,
+        relativePath: params.sourceRelativePath,
+        label: params.source.label,
+        warnings: params.warnings,
+      });
+      return;
+    }
+    await params.root.move(params.claimRelativePath, params.archivePaths.raw);
+    await secureAuditArchiveFile({
+      root: params.root,
+      relativePath: params.archivePaths.raw,
+      label: `preserved ${params.source.label}`,
+      warnings: params.warnings,
+    });
+    params.warnings.push(
+      `Preserved claimed ${params.source.label} at ${path.join(path.dirname(params.source.logicalSourcePath), path.basename(params.archivePaths.raw))} because an old writer recreated ${params.source.logicalSourcePath}`,
+    );
+  } catch (error) {
+    params.warnings.push(
+      `Failed restoring claimed ${params.source.label} ${params.source.logicalSourcePath}: ${String(error)}`,
+    );
+  }
+}
+
+async function migrateLegacyAuditLogSource(params: {
+  source: LegacyAuditLogSource;
+  stateDir: string;
+  recreatedSourceScheduled?: boolean;
+}): Promise<MigrationMessages & { completed: boolean }> {
+  const changes: string[] = [];
+  const warnings: string[] = [];
+  const result = (completed: boolean) => ({ changes, warnings, completed });
+  const root = await createFsSafeRoot(params.stateDir, {
+    hardlinks: "reject",
+    // Doctor previously accepted the complete legacy log; keep that migration
+    // contract while root operations enforce path and symlink boundaries.
+    maxBytes: Number.MAX_SAFE_INTEGER,
+    mkdir: false,
+    mode: 0o600,
+    symlinks: "reject",
+  });
+  const sourceRelativePath = path.relative(
+    path.resolve(params.stateDir),
+    params.source.logicalSourcePath,
+  );
+  const detectedRelativePath = path.relative(
+    path.resolve(params.stateDir),
+    params.source.sourcePath,
+  );
+  let archivePaths: AuditArchiveRelativePaths | undefined;
+  let claimRelativePath = detectedRelativePath;
+  if (params.source.storage === "active") {
+    archivePaths = await resolveAuditArchiveRelativePaths(root, sourceRelativePath);
+    claimRelativePath = path.relative(
+      path.resolve(params.stateDir),
+      legacyAuditClaimPathForArchive(
+        params.source.logicalSourcePath,
+        path.join(params.stateDir, archivePaths.sanitized),
+      ),
+    );
+    await root.move(detectedRelativePath, claimRelativePath);
+  } else if (params.source.storage === "claim") {
+    if (!params.source.sanitizedArchivePath || !params.source.rawArchivePath) {
+      throw new Error(`Missing reserved archive generation for ${params.source.sourcePath}`);
+    }
+    const sanitized = path.relative(
+      path.resolve(params.stateDir),
+      params.source.sanitizedArchivePath,
+    );
+    const raw = path.relative(path.resolve(params.stateDir), params.source.rawArchivePath);
+    archivePaths = {
+      sanitized,
+      raw,
+      resumeSanitized: (await root.exists(sanitized)) && !(await root.exists(raw)),
+    };
+  }
+  let claimFinalized = params.source.storage === "raw-archive";
+  try {
+    if (
+      !(await secureAuditArchiveFile({
+        root,
+        relativePath: claimRelativePath,
+        label: `claimed ${params.source.label}`,
+        warnings,
+      }))
+    ) {
+      return result(false);
+    }
+    const rawArchiveRelativePath = archivePaths?.raw ?? detectedRelativePath;
+    if (!hasLegacyAuditRawCheckpointCapacity(params.stateDir, rawArchiveRelativePath)) {
+      warnings.push(
+        `Skipped ${params.source.label} migration because durable raw-archive checkpoint capacity is exhausted; left the legacy source in place`,
+      );
+      return result(false);
+    }
+    if (
+      !(await restoreInterruptedAuditRecoveryArchive({
+        root,
+        relativePath: claimRelativePath,
+        label: params.source.label,
+        warnings,
+      }))
+    ) {
+      return result(false);
+    }
+    const snapshot = await readLegacyAuditSourceSnapshot(root, claimRelativePath);
+    const sourceGeneration = legacyAuditSourceGenerationKey(rawArchiveRelativePath);
+    const sanitizedRelativePath =
+      params.source.storage === "raw-archive" && params.source.sanitizedArchivePath
+        ? path.relative(path.resolve(params.stateDir), params.source.sanitizedArchivePath)
+        : undefined;
+    const previousCheckpoint =
+      params.source.storage === "raw-archive"
+        ? findPreviousLegacyAuditRawCheckpoint(params.stateDir, rawArchiveRelativePath)
+        : undefined;
+    if (params.source.storage === "raw-archive" && !previousCheckpoint) {
+      if (!sanitizedRelativePath) {
+        throw new Error(`Missing sanitized archive path for ${params.source.sourcePath}`);
+      }
+      const firstContentByte = snapshot.rawBytes.findIndex(
+        (byte) => byte !== 0x20 && byte !== 0x09 && byte !== 0x0a && byte !== 0x0d,
+      );
+      if (snapshot.rawBytes.length > 0 && firstContentByte !== 0) {
+        warnings.push(
+          `Skipped ${params.source.label} recovery because its checkpointless raw archive begins with ambiguous whitespace; left the archive in place`,
+        );
+        return result(false);
+      }
+    }
+    const prepared = prepareLegacyAuditRecords(
+      params.source,
+      snapshot.raw,
+      sourceGeneration,
+      previousCheckpoint?.recordOrdinalBase ?? 0,
+    );
+    if (!prepared.ok) {
+      warnings.push(...prepared.warnings);
+      return result(false);
+    }
+    const env = { ...process.env, OPENCLAW_STATE_DIR: params.stateDir };
+    const maxEntries =
+      params.source.kind === "config" ? CONFIG_AUDIT_MAX_ENTRIES : SYSTEM_AGENT_AUDIT_MAX_ENTRIES;
+    const store = createSqliteAuditRecordStore<ConfigAuditRecord | SystemAgentAuditEntry>({
+      scope: params.source.kind === "config" ? CONFIG_AUDIT_SCOPE : SYSTEM_AGENT_AUDIT_SCOPE,
+      maxEntries,
+      env,
+    });
+    const existingEntries = store.entries();
+    const existingKeys = new Set(existingEntries.map((entry) => entry.key));
+    let candidateRecords: readonly PreparedAuditRecord[] = prepared.records;
+    if (params.source.storage === "raw-archive") {
+      if (previousCheckpoint) {
+        const appendedRecords = recordsAfterLegacyAuditRawCheckpoint({
+          checkpoint: previousCheckpoint,
+          snapshot,
+          records: prepared.records,
+        });
+        if (!appendedRecords) {
+          warnings.push(
+            `Skipped ${params.source.label} recovery because ${params.source.sourcePath} changed other than by append; left the raw archive in place`,
+          );
+          return result(false);
+        }
+        candidateRecords = appendedRecords;
+      }
+    }
+    if (!previousCheckpoint && candidateRecords === prepared.records) {
+      const lastRetainedSourceIndex = prepared.records.findLastIndex((record) =>
+        existingKeys.has(record.key),
+      );
+      if (lastRetainedSourceIndex >= 0) {
+        // A crash can occur after bounded insertion but before its raw checkpoint.
+        // Continue after the latest retained source ordinal instead of resurrecting
+        // the pruned head as newly appended audit history.
+        candidateRecords = prepared.records.slice(lastRetainedSourceIndex + 1);
+      }
+    }
+    const missing = candidateRecords.filter((record) => !existingKeys.has(record.key));
+    // SQLite may commit before the sanitized merge/checkpoint. Keep raw-derived
+    // candidates intact so retry can still prove and materialize the artifact tail.
+    store.registerLegacyMany(missing);
+    const importedKeys = new Set(store.entries().map((entry) => entry.key));
+    const retainedNewRows = missing.filter((record) => importedKeys.has(record.key)).length;
+    const retentionNote =
+      retainedNewRows === missing.length
+        ? ""
+        : `; ${retainedNewRows} retained after bounded retention`;
+    if (params.source.storage === "raw-archive") {
+      if (!sanitizedRelativePath) {
+        throw new Error(`Missing sanitized archive path for ${params.source.sourcePath}`);
+      }
+      if (
+        !(await writeRecoveredSanitizedAuditArchive({
+          sourceLabel: params.source.label,
+          root,
+          relativePath: sanitizedRelativePath,
+          allRecordsJsonl: prepared.sanitizedJsonl,
+          candidateRecordsJsonl: serializePreparedAuditRecords(candidateRecords),
+          previousCheckpoint,
+          warnings,
+        }))
+      ) {
+        return result(false);
+      }
+      // Checkpoint the unscrubbed append before hardening/scrubbing. A retry can
+      // then prove the sanitized tail was already written instead of duplicating it.
+      // A merge-intent count describes its exact raw snapshot. Keep an existing
+      // intent untouched when retry has no later rows; the final raw checkpoint replaces it.
+      if (previousCheckpoint?.phase !== "merge-intent" || candidateRecords.length > 0) {
+        if (
+          !(await recordLegacyAuditRawCheckpoint({
+            stateDir: params.stateDir,
+            rawPath: params.source.sourcePath,
+            rawRelativePath: claimRelativePath,
+            sanitizedRelativePath,
+            root,
+            snapshot,
+            phase: "merge-intent",
+            recordCount: prepared.records.length,
+            recordOrdinalBase: previousCheckpoint?.recordOrdinalBase ?? 0,
+            warnings,
+          }))
+        ) {
+          return result(false);
+        }
+      }
+      if (
+        !(await secureAuditArchiveFile({
+          root,
+          relativePath: sanitizedRelativePath,
+          label: `sanitized ${params.source.label}`,
+          warnings,
+        }))
+      ) {
+        return result(false);
+      }
+      if (missing.length > 0) {
+        changes.push(
+          `Recovered ${missing.length} later ${params.source.label} row(s) from ${params.source.sourcePath}${retentionNote}`,
+        );
+      }
+      const scrubbedSnapshot = await scrubLegacyAuditRecoveryArchive({
+        root,
+        relativePath: claimRelativePath,
+        expectedSnapshot: snapshot,
+        label: params.source.label,
+        warnings,
+      });
+      if (!scrubbedSnapshot) {
+        return result(false);
+      }
+      const scrubbedRecords = prepareLegacyAuditRecords(
+        params.source,
+        scrubbedSnapshot.raw,
+        legacyAuditSourceGenerationKey(rawArchiveRelativePath),
+      );
+      if (!scrubbedRecords.ok) {
+        warnings.push(...scrubbedRecords.warnings);
+        warnings.push(
+          `Retained uncheckpointed ${params.source.label} recovery archive; rerun openclaw doctor --fix`,
+        );
+        return result(false);
+      }
+      if (scrubbedRecords.records.length !== 0) {
+        warnings.push(
+          `A legacy ${params.source.label} writer appended during recovery; rerun openclaw doctor --fix to import the retained rows`,
+        );
+        return result(false);
+      }
+      const checkpointed = await recordLegacyAuditRawCheckpoint({
+        stateDir: params.stateDir,
+        rawPath: params.source.sourcePath,
+        rawRelativePath: claimRelativePath,
+        sanitizedRelativePath,
+        root,
+        snapshot: scrubbedSnapshot,
+        phase: "raw",
+        recordCount: 0,
+        recordOrdinalBase:
+          (previousCheckpoint?.recordOrdinalBase ?? 0) +
+          Math.max(previousCheckpoint?.recordCount ?? 0, prepared.records.length),
+        warnings,
+      });
+      if (checkpointed) {
+        await finalizeLegacyAuditRecoveryArchive({ root, relativePath: claimRelativePath }).catch(
+          (error: unknown) => {
+            warnings.push(
+              `Failed removing completed ${params.source.label} recovery journal: ${String(error)}`,
+            );
+          },
+        );
+      }
+      return result(checkpointed);
+    }
+    if (!archivePaths) {
+      throw new Error(`Missing archive generation for ${params.source.sourcePath}`);
+    }
+    changes.push(
+      `Migrated ${params.source.label} -> shared SQLite state (${missing.length} new row(s)${retentionNote})`,
+    );
+    const archived = await archiveLegacyAuditClaim({
+      source: params.source,
+      claimRelativePath,
+      archivePaths,
+      snapshot,
+      sanitizedJsonl: prepared.sanitizedJsonl,
+      root,
+      changes,
+      warnings,
+    });
+    claimFinalized = archived.moved;
+    if (!archived.moved || !archived.rawRelativePath) {
+      changes.pop();
+      return result(false);
+    }
+    if (!archived.scrubbedSnapshot) {
+      return result(false);
+    }
+    const scrubbedRecords = prepareLegacyAuditRecords(
+      params.source,
+      archived.scrubbedSnapshot.raw,
+      legacyAuditSourceGenerationKey(archived.rawRelativePath),
+    );
+    if (!scrubbedRecords.ok) {
+      warnings.push(...scrubbedRecords.warnings);
+      warnings.push(
+        `Retained uncheckpointed ${params.source.label} recovery archive; rerun openclaw doctor --fix`,
+      );
+      return result(false);
+    }
+    if (scrubbedRecords.records.length !== 0) {
+      warnings.push(
+        `A legacy ${params.source.label} writer appended during migration; rerun openclaw doctor --fix to import the retained rows`,
+      );
+      return result(false);
+    }
+    const rawPath = path.join(params.stateDir, archived.rawRelativePath);
+    const checkpointed = await recordLegacyAuditRawCheckpoint({
+      stateDir: params.stateDir,
+      rawPath,
+      rawRelativePath: archived.rawRelativePath,
+      sanitizedRelativePath: archivePaths.sanitized,
+      root,
+      snapshot: archived.scrubbedSnapshot,
+      phase: "raw",
+      recordCount: 0,
+      recordOrdinalBase: prepared.records.length,
+      warnings,
+    });
+    if (checkpointed) {
+      await finalizeLegacyAuditRecoveryArchive({
+        root,
+        relativePath: archived.rawRelativePath,
+      }).catch((error: unknown) => {
+        warnings.push(
+          `Failed removing completed ${params.source.label} recovery journal: ${String(error)}`,
+        );
+      });
+    }
+    if ((await root.exists(sourceRelativePath)) && !params.recreatedSourceScheduled) {
+      warnings.push(
+        `An old writer recreated ${params.source.label} at ${params.source.logicalSourcePath}; rerun openclaw doctor --fix to import the retained rows`,
+      );
+    }
+    return result(checkpointed);
+  } finally {
+    if (!claimFinalized && params.source.storage === "active" && archivePaths) {
+      await restoreOrPreserveLegacyAuditClaim({
+        source: params.source,
+        claimRelativePath,
+        sourceRelativePath,
+        archivePaths,
+        root,
+        warnings,
+      });
+    }
+  }
+}
+
+export async function migrateLegacyAuditLogs(params: {
+  detected: LegacyAuditLogsDetection;
+  stateDir: string;
+}): Promise<MigrationMessages> {
+  const changes: string[] = [];
+  const warnings: string[] = [];
+  if (params.detected.sources.length === 0) {
+    return { changes, warnings };
+  }
+  const env = { ...process.env, OPENCLAW_STATE_DIR: params.stateDir };
+  let lock: Awaited<ReturnType<typeof acquireGatewayLock>>;
+  try {
+    // Exclusive state ownership excludes a predecessor Gateway and sibling doctor.
+    // Each source is also atomically claimed because old short-lived CLI processes
+    // can append config audit rows without participating in the Gateway lock.
+    lock = await acquireGatewayLock({
+      allowInTests: true,
+      env,
+      pollIntervalMs: 25,
+      role: "sqlite-maintenance",
+      timeoutMs: 250,
+    });
+  } catch (error) {
+    warnings.push(
+      `Skipped legacy audit migration because exclusive state ownership is unavailable: ${String(error)}`,
+    );
+    return { changes, warnings };
+  }
+  if (!lock) {
+    warnings.push(
+      "Skipped legacy audit migration because exclusive state ownership is unavailable",
+    );
+    return { changes, warnings };
+  }
+  try {
+    await withLegacyAuditMigrationLease(params.stateDir, async () => {
+      const blockedLogicalSources = new Set<string>();
+      for (const [index, source] of params.detected.sources.entries()) {
+        if (blockedLogicalSources.has(source.logicalSourcePath)) {
+          continue;
+        }
+        try {
+          const recreatedSourceScheduled = params.detected.sources
+            .slice(index + 1)
+            .some(
+              (candidate) =>
+                candidate.storage === "active" &&
+                candidate.logicalSourcePath === source.logicalSourcePath,
+            );
+          const result = await migrateLegacyAuditLogSource({
+            source,
+            stateDir: params.stateDir,
+            ...(recreatedSourceScheduled ? { recreatedSourceScheduled: true } : {}),
+          });
+          changes.push(...result.changes);
+          warnings.push(...result.warnings);
+          if (!result.completed) {
+            // Generations encode append order. A later archive must not overtake
+            // an older source that still needs repair or durable checkpointing.
+            blockedLogicalSources.add(source.logicalSourcePath);
+          }
+        } catch (error) {
+          warnings.push(`Failed migrating ${source.label}: ${String(error)}`);
+          blockedLogicalSources.add(source.logicalSourcePath);
+        }
+      }
+    });
+  } catch (error) {
+    warnings.push(`Skipped legacy audit migration because coordination failed: ${String(error)}`);
+  } finally {
+    await lock.release();
+  }
+  return { changes, warnings };
+}
diff --git a/src/infra/state-migrations.audit-logs.types.ts b/src/infra/state-migrations.audit-logs.types.ts
new file mode 100644
index 00000000000..1dac8ee027f
--- /dev/null
+++ b/src/infra/state-migrations.audit-logs.types.ts
@@ -0,0 +1,14 @@
+export type LegacyAuditLogSource = {
+  kind: "config" | "system-agent" | "crestodian";
+  label: string;
+  sourcePath: string;
+  logicalSourcePath: string;
+  storage: "active" | "claim" | "raw-archive";
+  sanitizedArchivePath?: string;
+  rawArchivePath?: string;
+};
+
+export type LegacyAuditLogsDetection = {
+  sources: LegacyAuditLogSource[];
+  hasLegacy: boolean;
+};
diff --git a/src/infra/state-migrations.audit-records.ts b/src/infra/state-migrations.audit-records.ts
new file mode 100644
index 00000000000..9eb61cae95d
--- /dev/null
+++ b/src/infra/state-migrations.audit-records.ts
@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { sanitizeConfigAuditRecord, type ConfigAuditRecord } from "../config/io.audit.js";
+import { redactSecrets } from "../logging/redact.js";
+import type { SystemAgentAuditEntry } from "../system-agent/audit.js";
+import type { LegacyAuditLogSource } from "./state-migrations.audit-logs.types.js";
+
+export type PreparedAuditRecord = {
+  key: string;
+  value: ConfigAuditRecord | SystemAgentAuditEntry;
+  createdAt: number;
+};
+
+export function serializePreparedAuditRecords(records: readonly PreparedAuditRecord[]): string {
+  return records.length > 0
+    ? `${records.map((record) => JSON.stringify(record.value)).join("\n")}\n`
+    : "";
+}
+
+function legacyAuditRecordCreatedAt(
+  source: LegacyAuditLogSource,
+  value: ConfigAuditRecord | SystemAgentAuditEntry,
+): number {
+  const timestamp =
+    source.kind === "config"
+      ? (value as Partial<ConfigAuditRecord>).ts
+      : (value as Partial<SystemAgentAuditEntry>).timestamp;
+  if (typeof timestamp !== "string") {
+    return 0;
+  }
+  const parsed = Date.parse(timestamp);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+type PreparedLegacyAuditRecords =
+  | { ok: false; warnings: string[] }
+  | {
+      ok: true;
+      records: PreparedAuditRecord[];
+      sanitizedJsonl: string;
+    };
+
+export function prepareLegacyAuditRecords(
+  source: LegacyAuditLogSource,
+  raw: string,
+  sourceGeneration: string,
+  sourceOrdinalBase = 0,
+): PreparedLegacyAuditRecords {
+  const records: PreparedAuditRecord[] = [];
+  const warnings: string[] = [];
+  for (const [index, line] of raw.split(/\r?\n/u).entries()) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmed) as unknown;
+    } catch (error) {
+      warnings.push(
+        `Failed reading ${source.label} record at ${source.sourcePath}:${index + 1}: ${String(error)}`,
+      );
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      warnings.push(
+        `Skipped non-object ${source.label} record at ${source.sourcePath}:${index + 1}`,
+      );
+      continue;
+    }
+    const value =
+      source.kind === "config"
+        ? sanitizeConfigAuditRecord(parsed as ConfigAuditRecord)
+        : (redactSecrets(parsed) as SystemAgentAuditEntry);
+    const digest = createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+    const recordOrdinal = sourceOrdinalBase + records.length + 1;
+    records.push({
+      key: `legacy:${source.kind}:${sourceGeneration}:${recordOrdinal}:${digest}`,
+      value,
+      createdAt: legacyAuditRecordCreatedAt(source, value),
+    });
+  }
+  if (warnings.length > 0) {
+    return { ok: false, warnings };
+  }
+  return {
+    ok: true,
+    records,
+    sanitizedJsonl: serializePreparedAuditRecords(records),
+  };
+}
diff --git a/src/infra/state-migrations.audit-recovery-protocol.ts b/src/infra/state-migrations.audit-recovery-protocol.ts
new file mode 100644
index 00000000000..afc61860900
--- /dev/null
+++ b/src/infra/state-migrations.audit-recovery-protocol.ts
@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import type { LegacyAuditFileCheckpoint } from "./state-migrations.audit-checkpoints.js";
+
+type AuditRecoveryRestoreJournal = {
+  schemaVersion: 6;
+  rawBase64: string;
+  scrubPatternBase64: string;
+  target: Pick<LegacyAuditFileCheckpoint, "dev" | "ino" | "size">;
+};
+
+export type ParsedAuditRecoveryRestoreJournal = {
+  sourceRaw: Buffer;
+  scrubPattern: Buffer;
+  target: AuditRecoveryRestoreJournal["target"];
+  journalHash: string;
+};
+
+export type AuditRecoveryProgress = {
+  schemaVersion: 1;
+  journalHash: string;
+  direction: "restoring" | "scrubbing";
+  committedBytes: number;
+  pendingEnd: number;
+  extentBytes: number;
+};
+
+const AUDIT_RECOVERY_SCRUB_PATTERN_BYTES = 32;
+
+export function serializeAuditRecoveryRestoreJournal(params: {
+  rawBytes: Buffer;
+  scrubPattern: Buffer;
+  target: AuditRecoveryRestoreJournal["target"];
+}): string {
+  const journal: AuditRecoveryRestoreJournal = {
+    schemaVersion: 6,
+    rawBase64: params.rawBytes.toString("base64"),
+    scrubPatternBase64: params.scrubPattern.toString("base64"),
+    target: params.target,
+  };
+  return `${JSON.stringify(journal)}\n`;
+}
+
+export function parseAuditRecoveryRestoreJournal(raw: string): ParsedAuditRecoveryRestoreJournal {
+  const parsed = JSON.parse(raw) as Partial<AuditRecoveryRestoreJournal>;
+  if (
+    parsed.schemaVersion !== 6 ||
+    typeof parsed.rawBase64 !== "string" ||
+    typeof parsed.scrubPatternBase64 !== "string" ||
+    !parsed.target ||
+    typeof parsed.target.dev !== "number" ||
+    typeof parsed.target.ino !== "number" ||
+    typeof parsed.target.size !== "number"
+  ) {
+    throw new Error("invalid legacy audit recovery restore journal");
+  }
+  const scrubPattern = Buffer.from(parsed.scrubPatternBase64, "base64");
+  if (
+    scrubPattern.length !== AUDIT_RECOVERY_SCRUB_PATTERN_BYTES ||
+    scrubPattern.some((byte) => byte !== 0x09 && byte !== 0x20)
+  ) {
+    throw new Error("invalid legacy audit recovery scrub pattern");
+  }
+  const sourceRaw = Buffer.from(parsed.rawBase64, "base64");
+  if (sourceRaw.length !== parsed.target.size) {
+    throw new Error("invalid legacy audit recovery source size");
+  }
+  return {
+    sourceRaw,
+    scrubPattern,
+    target: parsed.target,
+    journalHash: createHash("sha256").update(raw).digest("hex"),
+  };
+}
+
+export function serializeAuditRecoveryProgress(progress: AuditRecoveryProgress): string {
+  return `${JSON.stringify(progress)}\n`;
+}
+
+export function parseAuditRecoveryProgress(
+  raw: string,
+  journal: ParsedAuditRecoveryRestoreJournal,
+): AuditRecoveryProgress {
+  const parsed = JSON.parse(raw) as Partial<AuditRecoveryProgress>;
+  if (
+    parsed.schemaVersion !== 1 ||
+    parsed.journalHash !== journal.journalHash ||
+    (parsed.direction !== "restoring" && parsed.direction !== "scrubbing") ||
+    !Number.isSafeInteger(parsed.committedBytes) ||
+    !Number.isSafeInteger(parsed.pendingEnd) ||
+    !Number.isSafeInteger(parsed.extentBytes) ||
+    parsed.committedBytes! < 0 ||
+    parsed.pendingEnd! < parsed.committedBytes! ||
+    parsed.extentBytes! < parsed.pendingEnd! ||
+    parsed.extentBytes! > journal.target.size ||
+    (parsed.direction === "scrubbing" && parsed.extentBytes !== journal.target.size)
+  ) {
+    throw new Error("invalid legacy audit recovery progress");
+  }
+  return parsed as AuditRecoveryProgress;
+}
+
+function auditRecoveryTransitionMatches(
+  current: Buffer,
+  previous: Buffer,
+  desired: Buffer,
+  start: number,
+  end: number,
+): boolean {
+  let boundary = start;
+  while (boundary < end && current[boundary] === desired[boundary]) {
+    boundary += 1;
+  }
+  return current.subarray(boundary, end).equals(previous.subarray(boundary, end));
+}
+
+export function auditRecoveryStateMatchesJournal(params: {
+  current: Buffer;
+  original: Buffer;
+  scrubbed: Buffer;
+  progress: AuditRecoveryProgress;
+}): boolean {
+  const { current, original, scrubbed, progress } = params;
+  if (current.length < original.length) {
+    return false;
+  }
+  if (progress.direction === "scrubbing") {
+    return (
+      current
+        .subarray(0, progress.committedBytes)
+        .equals(scrubbed.subarray(0, progress.committedBytes)) &&
+      auditRecoveryTransitionMatches(
+        current,
+        original,
+        scrubbed,
+        progress.committedBytes,
+        progress.pendingEnd,
+      ) &&
+      current
+        .subarray(progress.pendingEnd, original.length)
+        .equals(original.subarray(progress.pendingEnd))
+    );
+  }
+  return (
+    current
+      .subarray(0, progress.committedBytes)
+      .equals(original.subarray(0, progress.committedBytes)) &&
+    auditRecoveryTransitionMatches(
+      current,
+      scrubbed,
+      original,
+      progress.committedBytes,
+      progress.pendingEnd,
+    ) &&
+    current
+      .subarray(progress.pendingEnd, progress.extentBytes)
+      .equals(scrubbed.subarray(progress.pendingEnd, progress.extentBytes)) &&
+    current
+      .subarray(progress.extentBytes, original.length)
+      .equals(original.subarray(progress.extentBytes))
+  );
+}
diff --git a/src/infra/state-migrations.audit-recovery.test.ts b/src/infra/state-migrations.audit-recovery.test.ts
new file mode 100644
index 00000000000..c8316f394cf
--- /dev/null
+++ b/src/infra/state-migrations.audit-recovery.test.ts
@@ -0,0 +1,542 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
+import { runOpenClawStateWriteTransaction } from "../state/openclaw-state-db.js";
+import { listSystemAgentAuditEntriesForTests } from "../system-agent/audit.test-support.js";
+import { withTempDir } from "../test-helpers/temp-dir.js";
+import { openLegacyAuditRawCheckpointStore } from "./state-migrations.audit-checkpoints.js";
+import { detectLegacyAuditLogs, migrateLegacyAuditLogs } from "./state-migrations.audit-logs.js";
+
+const TEST_AUDIT_SCRUB_PATTERN = Buffer.from(
+  Array.from({ length: 32 }, (_, index) => (index % 2 === 0 ? 0x20 : 0x09)),
+);
+
+function buildTestAuditScrubbedContent(length: number): Buffer {
+  const content = Buffer.allocUnsafe(length);
+  for (let offset = 0; offset < length; offset += TEST_AUDIT_SCRUB_PATTERN.length) {
+    TEST_AUDIT_SCRUB_PATTERN.copy(
+      content,
+      offset,
+      0,
+      Math.min(TEST_AUDIT_SCRUB_PATTERN.length, length - offset),
+    );
+  }
+  return content;
+}
+
+async function buildTestAuditRestoreJournal(
+  rawPath: string,
+  sourceRaw: Buffer,
+  progress: { restoredBytes: number; scrubbedBytes: number } = {
+    restoredBytes: 0,
+    scrubbedBytes: 0,
+  },
+): Promise<string> {
+  const stat = await fs.stat(rawPath);
+  const journal = `${JSON.stringify({
+    schemaVersion: 6,
+    rawBase64: sourceRaw.toString("base64"),
+    scrubPatternBase64: TEST_AUDIT_SCRUB_PATTERN.toString("base64"),
+    target: { dev: stat.dev, ino: stat.ino, size: sourceRaw.length },
+  })}\n`;
+  await fs.writeFile(
+    `${rawPath}.doctor-scrub-progress`,
+    `${JSON.stringify({
+      schemaVersion: 1,
+      journalHash: createHash("sha256").update(journal).digest("hex"),
+      direction: progress.restoredBytes > 0 ? "restoring" : "scrubbing",
+      committedBytes: progress.restoredBytes > 0 ? progress.restoredBytes : progress.scrubbedBytes,
+      pendingEnd: progress.restoredBytes > 0 ? progress.restoredBytes : progress.scrubbedBytes,
+      extentBytes: progress.restoredBytes > 0 ? progress.scrubbedBytes : sourceRaw.length,
+    })}\n`,
+  );
+  return journal;
+}
+
+describe("legacy audit recovery byte handling", () => {
+  afterEach(() => {
+    resetPluginStateStoreForTests();
+  });
+
+  it("blanks a zero-slack source within the fixed-size recovery inode", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-short-secret-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "logs", "config-audit.jsonl");
+      const record = {
+        ts: "2026-07-01T00:00:00.000Z",
+        source: "config-io",
+        event: "config.write",
+        argv: ["openclaw", "config", "set", "token", "x"],
+        execArgv: [],
+      };
+      const original = `${JSON.stringify(record)}\n`;
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, original);
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings).toEqual([]);
+      const sanitized = await fs.readFile(`${sourcePath}.migrated`, "utf8");
+      const recovery = await fs.readFile(`${sourcePath}.migrated.raw`, "utf8");
+      expect(Buffer.byteLength(recovery)).toBe(Buffer.byteLength(original));
+      expect(JSON.parse(sanitized.trim())).toMatchObject({
+        argv: ["openclaw", "config", "set", "token", "***"],
+      });
+      expect(recovery.trim()).toBe("");
+      await expect(
+        fs.access(`${sourcePath}.migrated.raw.doctor-scrub-restore`),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("uses original byte offsets when decoded audit text contains replacement characters", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-invalid-utf8-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const original = Buffer.concat([
+        Buffer.from(
+          '{"timestamp":"2026-07-03T00:00:00.000Z","operation":"gateway.restart","summary":"',
+        ),
+        Buffer.from([0x80]),
+        Buffer.from('"}'),
+      ]);
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, original);
+
+      const migrated = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(migrated.warnings).toEqual([]);
+      const blanked = await fs.readFile(rawPath);
+      expect(blanked).toHaveLength(original.length);
+      expect(blanked.every((byte) => byte === 0x20 || byte === 0x09)).toBe(true);
+
+      await fs.appendFile(
+        rawPath,
+        `${JSON.stringify({
+          timestamp: "2026-07-04T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary: "later",
+        })}\n`,
+      );
+      const recovered = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(recovered.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["�", "later"]);
+    });
+  });
+
+  it("upgrades a legacy nonzero raw checkpoint to the blank append pad", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-checkpoint-upgrade-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(
+          sourcePath,
+          `${JSON.stringify({
+            timestamp: "2026-07-03T00:00:00.000Z",
+            operation: "gateway.restart",
+            summary: "original",
+          })}\n`,
+        );
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        const rawPath = `${sourcePath}.migrated.raw`;
+        const legacyRaw = Buffer.concat([
+          Buffer.from(
+            '{"timestamp":"2026-07-03T00:00:00.000Z","operation":"gateway.restart","summary":"',
+          ),
+          Buffer.from([0x80]),
+          Buffer.from('"}\n'),
+        ]);
+        await fs.writeFile(rawPath, legacyRaw);
+        const legacyStat = await fs.stat(rawPath);
+        const checkpointStore = openLegacyAuditRawCheckpointStore(stateDir);
+        const checkpoint = checkpointStore.entries()[0]!;
+        checkpointStore.upsert(checkpoint.key, {
+          ...checkpoint.value,
+          dev: legacyStat.dev,
+          ino: legacyStat.ino,
+          mtimeMs: legacyStat.mtimeMs,
+          size: legacyStat.size,
+          contentHash: createHash("sha256").update(legacyRaw.toString("utf8")).digest("hex"),
+          recordCount: 1,
+        });
+
+        const detected = detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true });
+        expect(detected.hasLegacy).toBe(true);
+        const result = await migrateLegacyAuditLogs({ detected, stateDir });
+
+        expect(result.warnings).toEqual([]);
+        expect(openLegacyAuditRawCheckpointStore(stateDir).entries()[0]?.value.recordCount).toBe(0);
+      },
+    );
+  });
+
+  it("does not confuse an older prefix checkpoint with a later scrub generation", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-scrub-generation-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const rawPath = `${sourcePath}.migrated.raw`;
+        const restorePath = `${rawPath}.doctor-scrub-restore`;
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(
+          sourcePath,
+          `${JSON.stringify({
+            timestamp: "2026-07-03T00:00:00.000Z",
+            operation: "gateway.restart",
+            summary: "original",
+          })}\n`,
+        );
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        await fs.appendFile(
+          rawPath,
+          `${JSON.stringify({
+            timestamp: "2026-07-04T00:00:00.000Z",
+            operation: "gateway.restart",
+            summary: "later",
+          })}\n`,
+        );
+        const interruptedRaw = await fs.readFile(rawPath);
+        await fs.writeFile(
+          restorePath,
+          await buildTestAuditRestoreJournal(rawPath, interruptedRaw, {
+            restoredBytes: 0,
+            scrubbedBytes: interruptedRaw.length,
+          }),
+        );
+        await fs.writeFile(rawPath, buildTestAuditScrubbedContent(interruptedRaw.length));
+
+        const result = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+
+        expect(result.warnings).toEqual([]);
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }).map((entry) => entry.value.summary),
+        ).toEqual(["original", "later"]);
+        await expect(fs.access(restorePath)).rejects.toMatchObject({ code: "ENOENT" });
+      },
+    );
+  });
+
+  it("does not replay a scrub journal over an equal-width space redaction", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-scrub-redacted-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalContent = `${JSON.stringify({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "secret archive value",
+      })}\n`;
+      const replacementContent = originalContent.replace("secret archive value", " ".repeat(20));
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(`${sourcePath}.migrated`, "{}\n");
+      await fs.writeFile(rawPath, replacementContent);
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, Buffer.from(originalContent, "utf8")),
+      );
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings.join("\n")).toContain("no longer matches its restore journal target");
+      await expect(fs.readFile(rawPath, "utf8")).resolves.toBe(replacementContent);
+      await expect(fs.access(restorePath)).resolves.toBeUndefined();
+    });
+  });
+
+  it("resumes a one-byte scrub interruption using exact journal progress", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-scrub-one-byte-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalContent = `${JSON.stringify({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "original archive",
+      })}\n`;
+      const replacementBytes = Buffer.from(originalContent);
+      replacementBytes[0] = TEST_AUDIT_SCRUB_PATTERN[0]!;
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(`${sourcePath}.migrated`, "{}\n");
+      await fs.writeFile(rawPath, replacementBytes);
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, Buffer.from(originalContent), {
+          restoredBytes: 0,
+          scrubbedBytes: 1,
+        }),
+      );
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings).toEqual([]);
+      expect((await fs.readFile(rawPath, "utf8")).trim()).toBe("");
+      await expect(fs.access(restorePath)).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("resumes restoration after an interrupted rollback write", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-restore-restart-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const restorePath = `${rawPath}.doctor-scrub-restore`;
+      const originalContent = `${JSON.stringify({
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "restore after restart",
+      })}\n`;
+      const originalBytes = Buffer.from(originalContent, "utf8");
+      const interruptedRestore = buildTestAuditScrubbedContent(originalBytes.length);
+      originalBytes.subarray(0, Math.floor(originalBytes.length / 2)).copy(interruptedRestore);
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(`${sourcePath}.migrated`, "{}\n");
+      await fs.writeFile(rawPath, interruptedRestore);
+      await fs.writeFile(
+        restorePath,
+        await buildTestAuditRestoreJournal(rawPath, originalBytes, {
+          restoredBytes: Math.floor(originalBytes.length / 2),
+          scrubbedBytes: originalBytes.length,
+        }),
+      );
+
+      const result = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(result.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["restore after restart"]);
+      await expect(fs.access(restorePath)).rejects.toMatchObject({ code: "ENOENT" });
+    });
+  });
+
+  it("retries raw archive recovery when sanitized archive hardening fails", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-recovery-permissions-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const event = (summary: string) => ({
+          timestamp: "2026-07-03T00:00:00.000Z",
+          operation: "gateway.restart",
+          summary,
+        });
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(sourcePath, `${JSON.stringify(event("before archive"))}\n`);
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        await fs.appendFile(
+          `${sourcePath}.migrated.raw`,
+          `${JSON.stringify(event("later row"))}\n`,
+        );
+        const probe = await fs.open(path.join(stateDir, "recovery-chmod-probe"), "w");
+        const fileHandlePrototype = Object.getPrototypeOf(probe) as {
+          chmod(mode: number): Promise<void>;
+        };
+        await probe.close();
+        const originalChmod = Reflect.get(fileHandlePrototype, "chmod") as (
+          this: typeof fileHandlePrototype,
+          mode: number,
+        ) => Promise<void>;
+        let chmodCalls = 0;
+        const chmodSpy = vi.spyOn(fileHandlePrototype, "chmod").mockImplementation(function (
+          this: typeof fileHandlePrototype,
+          mode: number,
+        ) {
+          chmodCalls += 1;
+          if (chmodCalls === 2) {
+            return Promise.reject(new Error("simulated recovery chmod failure"));
+          }
+          return originalChmod.call(this, mode);
+        });
+
+        let failed: Awaited<ReturnType<typeof migrateLegacyAuditLogs>>;
+        try {
+          failed = await migrateLegacyAuditLogs({
+            detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+            stateDir,
+          });
+        } finally {
+          chmodSpy.mockRestore();
+        }
+
+        expect(failed.changes).toEqual([]);
+        expect(failed.warnings.join("\n")).toContain(
+          "Failed securing sanitized system-agent audit log",
+        );
+        expect(
+          detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).sources,
+        ).toMatchObject([{ storage: "raw-archive" }]);
+
+        const recovered = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        expect(recovered.warnings).toEqual([]);
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }).map((entry) => entry.value.summary),
+        ).toEqual(["before archive", "later row"]);
+        const sanitizedRows = (await fs.readFile(`${sourcePath}.migrated`, "utf8"))
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line) as { summary: string });
+        expect(sanitizedRows.map((row) => row.summary)).toEqual(["before archive", "later row"]);
+        expect(
+          detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }).sources,
+        ).toEqual([]);
+      },
+    );
+  });
+
+  it("completes a verified partial sanitized tail after an interrupted write", async () => {
+    await withTempDir(
+      { prefix: "openclaw-audit-migration-partial-sanitized-tail-" },
+      async (stateDir) => {
+        const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+        const sanitizedPath = `${sourcePath}.migrated`;
+        const rawPath = `${sanitizedPath}.raw`;
+        const event = (day: string, summary: string) => ({
+          timestamp: `2026-07-${day}T00:00:00.000Z`,
+          operation: "gateway.restart",
+          summary,
+        });
+        await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+        await fs.writeFile(sourcePath, `${JSON.stringify(event("01", "before archive"))}\n`);
+        await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+        const firstLater = event("02", "first later row");
+        const secondLater = event("03", "second later row");
+        await fs.appendFile(
+          rawPath,
+          `${JSON.stringify(firstLater)}\n${JSON.stringify(secondLater)}\n`,
+        );
+        // Simulate a stopped sanitized write: the durable checkpoint prefix plus
+        // one complete candidate row is a byte-for-byte prefix of the desired file.
+        await fs.appendFile(sanitizedPath, `${JSON.stringify(firstLater)}\n`);
+
+        const recovered = await migrateLegacyAuditLogs({
+          detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+          stateDir,
+        });
+
+        expect(recovered.warnings).toEqual([]);
+        expect(
+          listSystemAgentAuditEntriesForTests({
+            env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+          }).map((entry) => entry.value.summary),
+        ).toEqual(["before archive", "first later row", "second later row"]);
+        const sanitizedRows = (await fs.readFile(sanitizedPath, "utf8"))
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line) as { summary: string });
+        expect(sanitizedRows.map((row) => row.summary)).toEqual([
+          "before archive",
+          "first later row",
+          "second later row",
+        ]);
+      },
+    );
+  });
+
+  it("preserves identical appends and blocks checkpointless whitespace ambiguity", async () => {
+    await withTempDir({ prefix: "openclaw-audit-migration-duplicate-tail-" }, async (stateDir) => {
+      const sourcePath = path.join(stateDir, "audit", "system-agent.jsonl");
+      const rawPath = `${sourcePath}.migrated.raw`;
+      const event = {
+        timestamp: "2026-07-03T00:00:00.000Z",
+        operation: "gateway.restart",
+        summary: "Repeated operation",
+      };
+      await fs.mkdir(path.dirname(sourcePath), { recursive: true });
+      await fs.writeFile(sourcePath, `${JSON.stringify(event)}\n\n${JSON.stringify(event)}\n`);
+      await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      await fs.appendFile(rawPath, `${JSON.stringify(event)}\n`);
+
+      const recovered = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+
+      expect(recovered.warnings).toEqual([]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }).map((entry) => entry.value.summary),
+      ).toEqual(["Repeated operation", "Repeated operation", "Repeated operation"]);
+      const sanitizedRows = (await fs.readFile(`${sourcePath}.migrated`, "utf8"))
+        .trim()
+        .split("\n");
+      expect(sanitizedRows).toHaveLength(3);
+
+      runOpenClawStateWriteTransaction(
+        (database) => {
+          database.db
+            .prepare("DELETE FROM diagnostic_events WHERE scope = ?")
+            .run("migration.legacy-audit-raw");
+        },
+        { env: { ...process.env, OPENCLAW_STATE_DIR: stateDir } },
+      );
+      await fs.appendFile(rawPath, `${JSON.stringify(event)}\n`);
+      const ambiguous = await migrateLegacyAuditLogs({
+        detected: detectLegacyAuditLogs({ stateDir, doctorOnlyStateMigrations: true }),
+        stateDir,
+      });
+      expect(ambiguous.changes).toEqual([]);
+      expect(ambiguous.warnings).toEqual([
+        expect.stringContaining("checkpointless raw archive begins with ambiguous whitespace"),
+      ]);
+      expect(
+        listSystemAgentAuditEntriesForTests({
+          env: { ...process.env, OPENCLAW_STATE_DIR: stateDir },
+        }),
+      ).toHaveLength(3);
+      expect((await fs.readFile(`${sourcePath}.migrated`, "utf8")).trim().split("\n")).toHaveLength(
+        3,
+      );
+    });
+  });
+});
diff --git a/src/infra/state-migrations.audit-recovery.ts b/src/infra/state-migrations.audit-recovery.ts
new file mode 100644
index 00000000000..68ed2a45912
--- /dev/null
+++ b/src/infra/state-migrations.audit-recovery.ts
@@ -0,0 +1,710 @@
+import { createHash, randomBytes } from "node:crypto";
+import path from "node:path";
+import { root as createFsSafeRoot } from "./fs-safe.js";
+import { syncDirectoryBestEffort } from "./sqlite-snapshot.js";
+import {
+  legacyAuditRawCheckpointKey,
+  legacyAuditRawCheckpointsMatch,
+  legacyAuditSourceGenerationKey,
+  openLegacyAuditRawCheckpointStore,
+  type LegacyAuditFileCheckpoint,
+  type LegacyAuditRawCheckpoint,
+} from "./state-migrations.audit-checkpoints.js";
+import {
+  auditRecoveryStateMatchesJournal,
+  parseAuditRecoveryProgress,
+  parseAuditRecoveryRestoreJournal,
+  serializeAuditRecoveryProgress,
+  serializeAuditRecoveryRestoreJournal,
+  type AuditRecoveryProgress,
+  type ParsedAuditRecoveryRestoreJournal,
+} from "./state-migrations.audit-recovery-protocol.js";
+
+export type AuditMigrationRoot = Awaited<ReturnType<typeof createFsSafeRoot>>;
+export type LegacyAuditSourceSnapshot = LegacyAuditFileCheckpoint & {
+  raw: string;
+  rawBytes: Buffer;
+};
+
+const AUDIT_RECOVERY_RESTORE_SUFFIX = ".doctor-scrub-restore";
+const AUDIT_RECOVERY_STAGING_SUFFIX = ".doctor-scrub-staging";
+const AUDIT_RECOVERY_PROGRESS_SUFFIX = ".doctor-scrub-progress";
+const AUDIT_RECOVERY_SCRUB_PATTERN_BYTES = 32;
+
+function auditRecoverySiblingPath(relativePath: string, suffix: string): string {
+  return `${relativePath}${suffix}`;
+}
+
+function auditRecoveryJournalTargetsSnapshot(
+  snapshot: LegacyAuditSourceSnapshot,
+  journal: Pick<ParsedAuditRecoveryRestoreJournal, "target">,
+): boolean {
+  return (
+    snapshot.dev === journal.target.dev &&
+    snapshot.ino === journal.target.ino &&
+    snapshot.rawBytes.length >= journal.target.size
+  );
+}
+
+function auditRecoveryCheckpointPrefixMatches(
+  snapshot: LegacyAuditSourceSnapshot,
+  checkpoint: LegacyAuditRawCheckpoint,
+): boolean {
+  if (snapshot.rawBytes.length < checkpoint.size) {
+    return false;
+  }
+  return (
+    createHash("sha256").update(snapshot.rawBytes.subarray(0, checkpoint.size)).digest("hex") ===
+    checkpoint.contentHash
+  );
+}
+
+async function syncAuditRecoveryDirectory(
+  root: AuditMigrationRoot,
+  relativePath: string,
+): Promise<void> {
+  await syncDirectoryBestEffort(path.join(root.rootReal, path.dirname(relativePath)));
+}
+
+export async function readLegacyAuditSourceSnapshot(
+  root: AuditMigrationRoot,
+  relativePath: string,
+): Promise<LegacyAuditSourceSnapshot> {
+  const opened = await root.open(relativePath);
+  try {
+    const before = await opened.handle.stat();
+    if (!before.isFile()) {
+      throw new Error("legacy audit source is not a regular file");
+    }
+    const rawBytes = await opened.handle.readFile();
+    const after = await opened.handle.stat();
+    const beforeCheckpoint = {
+      dev: before.dev,
+      ino: before.ino,
+      mtimeMs: before.mtimeMs,
+      size: before.size,
+    };
+    const afterCheckpoint = {
+      dev: after.dev,
+      ino: after.ino,
+      mtimeMs: after.mtimeMs,
+      size: after.size,
+    };
+    if (!legacyAuditRawCheckpointsMatch(beforeCheckpoint, afterCheckpoint)) {
+      throw new Error("legacy audit source changed while Doctor was reading it");
+    }
+    return { ...afterCheckpoint, raw: rawBytes.toString("utf8"), rawBytes };
+  } finally {
+    await opened.handle.close();
+  }
+}
+
+export async function readLegacyAuditSourcePrefixSnapshotForBackup(
+  root: AuditMigrationRoot,
+  relativePath: string,
+): Promise<LegacyAuditSourceSnapshot> {
+  const opened = await root.open(relativePath);
+  try {
+    const before = await opened.handle.stat();
+    if (!before.isFile()) {
+      throw new Error("legacy audit source is not a regular file");
+    }
+    const rawBytes = Buffer.allocUnsafe(before.size);
+    let offset = 0;
+    while (offset < rawBytes.length) {
+      const length = Math.min(64 * 1024, rawBytes.length - offset);
+      const { bytesRead } = await opened.handle.read(rawBytes, offset, length, offset);
+      if (bytesRead === 0) {
+        throw new Error("legacy audit source was truncated while backup was reading it");
+      }
+      offset += bytesRead;
+    }
+    const after = await opened.handle.stat();
+    if (before.dev !== after.dev || before.ino !== after.ino || after.size < before.size) {
+      throw new Error("legacy audit source changed other than by append during backup");
+    }
+    const checkpoint = {
+      dev: before.dev,
+      ino: before.ino,
+      mtimeMs: before.mtimeMs,
+      size: before.size,
+    };
+    return { ...checkpoint, raw: rawBytes.toString("utf8"), rawBytes };
+  } finally {
+    await opened.handle.close();
+  }
+}
+
+export async function readLegacyAuditRecoverySourceForBackup(
+  root: AuditMigrationRoot,
+  relativePath: string,
+): Promise<LegacyAuditSourceSnapshot> {
+  const current = await readLegacyAuditSourcePrefixSnapshotForBackup(root, relativePath);
+  const restoreRelativePath = auditRecoverySiblingPath(relativePath, AUDIT_RECOVERY_RESTORE_SUFFIX);
+  if (!(await root.exists(restoreRelativePath))) {
+    return current;
+  }
+  const restoreSnapshot = await readLegacyAuditSourceSnapshot(root, restoreRelativePath);
+  const journal = parseAuditRecoveryRestoreJournal(restoreSnapshot.raw);
+  const progress = await readAuditRecoveryProgress({ root, relativePath, journal });
+  const scrubbedContent = buildScrubbedAuditRecoveryContent(
+    journal.sourceRaw,
+    journal.scrubPattern,
+  );
+  if (
+    !auditRecoveryJournalTargetsSnapshot(current, journal) ||
+    !auditRecoveryStateMatchesJournal({
+      current: current.rawBytes,
+      original: journal.sourceRaw,
+      scrubbed: scrubbedContent,
+      progress,
+    })
+  ) {
+    return current;
+  }
+  const rawBytes = Buffer.concat([
+    journal.sourceRaw,
+    current.rawBytes.subarray(journal.sourceRaw.length),
+  ]);
+  return { ...current, raw: rawBytes.toString("utf8"), rawBytes };
+}
+
+function createAuditRecoveryScrubPattern(): Buffer {
+  const pattern = randomBytes(AUDIT_RECOVERY_SCRUB_PATTERN_BYTES);
+  for (let index = 0; index < pattern.length; index += 1) {
+    pattern[index] = (pattern[index]! & 1) === 0 ? 0x20 : 0x09;
+  }
+  for (let offset = 0; offset < pattern.length; offset += 8) {
+    const block = pattern.subarray(offset, offset + 8);
+    if (block.every((byte) => byte === 0x20)) {
+      pattern[offset + 7] = 0x09;
+    } else if (block.every((byte) => byte === 0x09)) {
+      pattern[offset + 7] = 0x20;
+    }
+  }
+  return pattern;
+}
+
+function buildScrubbedAuditRecoveryContent(rawBytes: Buffer, scrubPattern: Buffer): Buffer {
+  if (rawBytes.length === 0) {
+    return Buffer.alloc(0);
+  }
+  // The readable sanitized sibling owns migrated history. This same-inode file
+  // is only an append landing pad for predecessor writers, so blank the complete
+  // fixed-size prefix and checkpoint it with zero records. Leading whitespace is
+  // valid before any late JSONL row and preserves an open O_APPEND offset.
+  const scrubbed = Buffer.allocUnsafe(rawBytes.length);
+  for (let offset = 0; offset < scrubbed.length; offset += scrubPattern.length) {
+    scrubPattern.copy(scrubbed, offset, 0, Math.min(scrubPattern.length, scrubbed.length - offset));
+  }
+  return scrubbed;
+}
+
+async function writeAuditRecoveryRange(
+  handle: Awaited<ReturnType<AuditMigrationRoot["openWritable"]>>["handle"],
+  content: Buffer,
+  position: number,
+): Promise<void> {
+  let offset = 0;
+  while (offset < content.byteLength) {
+    const { bytesWritten } = await handle.write(
+      content,
+      offset,
+      content.byteLength - offset,
+      position + offset,
+    );
+    if (bytesWritten === 0) {
+      throw new Error("zero-byte write while updating legacy recovery archive");
+    }
+    offset += bytesWritten;
+  }
+}
+
+const AUDIT_RECOVERY_WRITE_CHUNK_BYTES = 64 * 1024;
+
+async function writeAuditRecoveryProgress(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  progress: AuditRecoveryProgress;
+}): Promise<void> {
+  const progressRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_PROGRESS_SUFFIX,
+  );
+  await params.root.write(progressRelativePath, serializeAuditRecoveryProgress(params.progress), {
+    mkdir: false,
+    mode: 0o600,
+  });
+  const opened = await params.root.open(progressRelativePath);
+  try {
+    await opened.handle.chmod(0o600);
+    await opened.handle.sync();
+  } finally {
+    await opened.handle.close();
+  }
+  await syncAuditRecoveryDirectory(params.root, params.relativePath);
+}
+
+async function readAuditRecoveryProgress(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  journal: ReturnType<typeof parseAuditRecoveryRestoreJournal>;
+}): Promise<AuditRecoveryProgress> {
+  const progressRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_PROGRESS_SUFFIX,
+  );
+  if (!(await params.root.exists(progressRelativePath))) {
+    return {
+      schemaVersion: 1,
+      journalHash: params.journal.journalHash,
+      direction: "scrubbing",
+      committedBytes: 0,
+      pendingEnd: 0,
+      extentBytes: params.journal.target.size,
+    };
+  }
+  const snapshot = await readLegacyAuditSourceSnapshot(params.root, progressRelativePath);
+  return parseAuditRecoveryProgress(snapshot.raw, params.journal);
+}
+
+async function advanceAuditRecoveryWrite(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  progress: AuditRecoveryProgress;
+  desiredContent: Buffer;
+  handle: Awaited<ReturnType<AuditMigrationRoot["openWritable"]>>["handle"];
+}): Promise<AuditRecoveryProgress> {
+  let progress = params.progress;
+  if (progress.pendingEnd > progress.committedBytes) {
+    await writeAuditRecoveryRange(
+      params.handle,
+      params.desiredContent.subarray(progress.committedBytes, progress.pendingEnd),
+      progress.committedBytes,
+    );
+    await params.handle.sync();
+    progress = { ...progress, committedBytes: progress.pendingEnd };
+    await writeAuditRecoveryProgress({ ...params, progress });
+  }
+  while (progress.committedBytes < progress.extentBytes) {
+    const end = Math.min(
+      progress.committedBytes + AUDIT_RECOVERY_WRITE_CHUNK_BYTES,
+      progress.extentBytes,
+    );
+    // Commit intent before target bytes. A crash can leave any prefix of this
+    // range changed; pendingEnd lets recovery finish it without guessing.
+    progress = { ...progress, pendingEnd: end };
+    await writeAuditRecoveryProgress({ ...params, progress });
+    await writeAuditRecoveryRange(
+      params.handle,
+      params.desiredContent.subarray(progress.committedBytes, end),
+      progress.committedBytes,
+    );
+    await params.handle.sync();
+    progress = { ...progress, committedBytes: end };
+    await writeAuditRecoveryProgress({ ...params, progress });
+  }
+  return progress;
+}
+
+async function reconcileAuditRecoveryPendingWrite(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  progress: AuditRecoveryProgress;
+  desiredContent: Buffer;
+  handle: Awaited<ReturnType<AuditMigrationRoot["openWritable"]>>["handle"];
+}): Promise<AuditRecoveryProgress> {
+  if (params.progress.pendingEnd === params.progress.committedBytes) {
+    return params.progress;
+  }
+  await writeAuditRecoveryRange(
+    params.handle,
+    params.desiredContent.subarray(params.progress.committedBytes, params.progress.pendingEnd),
+    params.progress.committedBytes,
+  );
+  await params.handle.sync();
+  const progress = { ...params.progress, committedBytes: params.progress.pendingEnd };
+  await writeAuditRecoveryProgress({ ...params, progress });
+  return progress;
+}
+
+async function stageAuditRecoveryRestore(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  snapshot: LegacyAuditSourceSnapshot;
+  scrubPattern: Buffer;
+}): Promise<AuditRecoveryProgress> {
+  const restoreRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_RESTORE_SUFFIX,
+  );
+  const stagingRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_STAGING_SUFFIX,
+  );
+  await params.root.remove(stagingRelativePath).catch(() => undefined);
+  const journalRaw = serializeAuditRecoveryRestoreJournal({
+    rawBytes: params.snapshot.rawBytes,
+    scrubPattern: params.scrubPattern,
+    target: {
+      dev: params.snapshot.dev,
+      ino: params.snapshot.ino,
+      size: params.snapshot.size,
+    },
+  });
+  await params.root.create(stagingRelativePath, journalRaw, { mode: 0o600 });
+  const staged = await params.root.open(stagingRelativePath);
+  try {
+    await staged.handle.chmod(0o600);
+    await staged.handle.sync();
+  } finally {
+    await staged.handle.close();
+  }
+  await params.root.move(stagingRelativePath, restoreRelativePath);
+  await syncAuditRecoveryDirectory(params.root, params.relativePath);
+  const journal = parseAuditRecoveryRestoreJournal(journalRaw);
+  const progress: AuditRecoveryProgress = {
+    schemaVersion: 1,
+    journalHash: journal.journalHash,
+    direction: "scrubbing",
+    committedBytes: 0,
+    pendingEnd: 0,
+    extentBytes: journal.target.size,
+  };
+  await writeAuditRecoveryProgress({
+    root: params.root,
+    relativePath: params.relativePath,
+    progress,
+  });
+  return progress;
+}
+
+export async function restoreInterruptedAuditRecoveryArchive(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  label: string;
+  warnings: string[];
+}): Promise<boolean> {
+  const restoreRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_RESTORE_SUFFIX,
+  );
+  const stagingRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_STAGING_SUFFIX,
+  );
+  const progressRelativePath = auditRecoverySiblingPath(
+    params.relativePath,
+    AUDIT_RECOVERY_PROGRESS_SUFFIX,
+  );
+  if (!(await params.root.exists(restoreRelativePath))) {
+    await params.root.remove(stagingRelativePath).catch(() => undefined);
+    await params.root.remove(progressRelativePath).catch(() => undefined);
+    return true;
+  }
+  try {
+    const currentSnapshot = await readLegacyAuditSourceSnapshot(params.root, params.relativePath);
+    const restoreSnapshot = await readLegacyAuditSourceSnapshot(params.root, restoreRelativePath);
+    const journal = parseAuditRecoveryRestoreJournal(restoreSnapshot.raw);
+    let progress = await readAuditRecoveryProgress({
+      root: params.root,
+      relativePath: params.relativePath,
+      journal,
+    });
+    const scrubbedContent = buildScrubbedAuditRecoveryContent(
+      journal.sourceRaw,
+      journal.scrubPattern,
+    );
+    let completedCheckpoint: LegacyAuditRawCheckpoint | undefined;
+    try {
+      completedCheckpoint = findPreviousLegacyAuditRawCheckpoint(
+        params.root.rootReal,
+        params.relativePath,
+      );
+    } catch {
+      completedCheckpoint = undefined;
+    }
+    if (
+      completedCheckpoint &&
+      completedCheckpoint.phase === "raw" &&
+      completedCheckpoint.recordCount === 0 &&
+      completedCheckpoint.size === journal.sourceRaw.length &&
+      auditRecoveryCheckpointPrefixMatches(currentSnapshot, completedCheckpoint)
+    ) {
+      // Checkpoint commit won the crash race; the restore journal is stale and
+      // must not roll the already-checkpointed sanitized inode backward.
+      await params.root.remove(progressRelativePath).catch(() => undefined);
+      await params.root.remove(stagingRelativePath).catch(() => undefined);
+      await params.root.remove(restoreRelativePath);
+      await syncAuditRecoveryDirectory(params.root, params.relativePath);
+      return true;
+    }
+    const writable = await params.root.openWritable(params.relativePath, {
+      mode: 0o600,
+      writeMode: "update",
+    });
+    try {
+      const verification = await readLegacyAuditSourceSnapshot(params.root, params.relativePath);
+      if (
+        writable.stat.dev !== verification.dev ||
+        writable.stat.ino !== verification.ino ||
+        !auditRecoveryJournalTargetsSnapshot(verification, journal) ||
+        !auditRecoveryStateMatchesJournal({
+          current: verification.rawBytes,
+          original: journal.sourceRaw,
+          scrubbed: scrubbedContent,
+          progress,
+        })
+      ) {
+        throw new Error("legacy recovery archive no longer matches its restore journal target");
+      }
+      progress = await reconcileAuditRecoveryPendingWrite({
+        root: params.root,
+        relativePath: params.relativePath,
+        progress,
+        desiredContent: progress.direction === "scrubbing" ? scrubbedContent : journal.sourceRaw,
+        handle: writable.handle,
+      });
+      if (progress.direction === "scrubbing") {
+        progress = {
+          schemaVersion: 1,
+          journalHash: journal.journalHash,
+          direction: "restoring",
+          committedBytes: 0,
+          pendingEnd: 0,
+          extentBytes: progress.committedBytes,
+        };
+        await writeAuditRecoveryProgress({
+          root: params.root,
+          relativePath: params.relativePath,
+          progress,
+        });
+      }
+      await advanceAuditRecoveryWrite({
+        root: params.root,
+        relativePath: params.relativePath,
+        progress,
+        desiredContent: journal.sourceRaw,
+        handle: writable.handle,
+      });
+      await writable.handle.chmod(0o600);
+      await writable.handle.sync();
+    } finally {
+      await writable.handle.close().catch(() => undefined);
+    }
+    await params.root.remove(progressRelativePath).catch(() => undefined);
+    await params.root.remove(stagingRelativePath).catch(() => undefined);
+    await params.root.remove(restoreRelativePath);
+    await syncAuditRecoveryDirectory(params.root, params.relativePath);
+    return true;
+  } catch (error) {
+    params.warnings.push(
+      `Failed restoring interrupted ${params.label} legacy recovery archive: ${String(error)}`,
+    );
+    return false;
+  }
+}
+
+export async function finalizeLegacyAuditRecoveryArchive(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+}): Promise<void> {
+  await params.root
+    .remove(auditRecoverySiblingPath(params.relativePath, AUDIT_RECOVERY_PROGRESS_SUFFIX))
+    .catch(() => undefined);
+  await params.root
+    .remove(auditRecoverySiblingPath(params.relativePath, AUDIT_RECOVERY_STAGING_SUFFIX))
+    .catch(() => undefined);
+  await params.root.remove(
+    auditRecoverySiblingPath(params.relativePath, AUDIT_RECOVERY_RESTORE_SUFFIX),
+  );
+  await syncAuditRecoveryDirectory(params.root, params.relativePath);
+}
+
+export async function scrubLegacyAuditRecoveryArchive(params: {
+  root: AuditMigrationRoot;
+  relativePath: string;
+  expectedSnapshot: LegacyAuditSourceSnapshot;
+  label: string;
+  warnings: string[];
+}): Promise<LegacyAuditSourceSnapshot | undefined> {
+  const scrubPattern = createAuditRecoveryScrubPattern();
+  const scrubbedContent = buildScrubbedAuditRecoveryContent(
+    params.expectedSnapshot.rawBytes,
+    scrubPattern,
+  );
+  let progress: AuditRecoveryProgress;
+  try {
+    progress = await stageAuditRecoveryRestore({
+      root: params.root,
+      relativePath: params.relativePath,
+      snapshot: params.expectedSnapshot,
+      scrubPattern,
+    });
+  } catch (error) {
+    params.warnings.push(
+      `Failed staging ${params.label} legacy recovery restore journal: ${String(error)}`,
+    );
+    return undefined;
+  }
+  let writable: Awaited<ReturnType<AuditMigrationRoot["openWritable"]>>;
+  try {
+    writable = await params.root.openWritable(params.relativePath, {
+      mode: 0o600,
+      writeMode: "update",
+    });
+  } catch (error) {
+    params.warnings.push(
+      `Failed scrubbing ${params.label} legacy recovery archive: ${String(error)}`,
+    );
+    return undefined;
+  }
+  try {
+    if (!legacyAuditRawCheckpointsMatch(params.expectedSnapshot, writable.stat)) {
+      params.warnings.push(
+        `Skipped scrubbing changed ${params.label} legacy recovery archive; rerun openclaw doctor --fix`,
+      );
+      return undefined;
+    }
+    await advanceAuditRecoveryWrite({
+      root: params.root,
+      relativePath: params.relativePath,
+      progress,
+      desiredContent: scrubbedContent,
+      handle: writable.handle,
+    });
+    await writable.handle.chmod(0o600);
+    await writable.handle.sync();
+  } catch (error) {
+    await writable.handle.close().catch(() => undefined);
+    const recoveryWarnings: string[] = [];
+    const restored = await restoreInterruptedAuditRecoveryArchive({
+      root: params.root,
+      relativePath: params.relativePath,
+      label: params.label,
+      warnings: recoveryWarnings,
+    });
+    if (restored) {
+      params.warnings.push(
+        `Failed scrubbing ${params.label} legacy recovery archive; restored it for Doctor retry: ${String(error)}`,
+      );
+    } else {
+      params.warnings.push(...recoveryWarnings);
+      params.warnings.push(
+        `Failed scrubbing ${params.label} legacy recovery archive; left its progress journal for Doctor retry: ${String(error)}`,
+      );
+    }
+    return undefined;
+  } finally {
+    await writable.handle.close().catch(() => undefined);
+  }
+  let scrubbedSnapshot: LegacyAuditSourceSnapshot;
+  try {
+    scrubbedSnapshot = await readLegacyAuditSourceSnapshot(params.root, params.relativePath);
+  } catch (error) {
+    params.warnings.push(
+      `Changed ${params.label} legacy recovery archive during scrub verification; rerun openclaw doctor --fix: ${String(error)}`,
+    );
+    return undefined;
+  }
+  const scrubbedPrefix = scrubbedSnapshot.rawBytes.subarray(0, scrubbedContent.length);
+  if (!scrubbedPrefix.equals(scrubbedContent)) {
+    params.warnings.push(
+      `Failed verifying scrubbed ${params.label} legacy recovery archive; rerun openclaw doctor --fix`,
+    );
+    return undefined;
+  }
+  return scrubbedSnapshot;
+}
+
+export async function recordLegacyAuditRawCheckpoint(params: {
+  stateDir: string;
+  rawPath: string;
+  rawRelativePath: string;
+  sanitizedRelativePath: string;
+  root: AuditMigrationRoot;
+  snapshot: LegacyAuditSourceSnapshot;
+  phase: "merge-intent" | "raw";
+  recordCount: number;
+  recordOrdinalBase: number;
+  warnings: string[];
+}): Promise<boolean> {
+  try {
+    const sanitizedSnapshot = await readLegacyAuditSourceSnapshot(
+      params.root,
+      params.sanitizedRelativePath,
+    );
+    const opened = await params.root.open(params.rawRelativePath);
+    let checkpoint: LegacyAuditRawCheckpoint;
+    try {
+      const stat = await opened.handle.stat();
+      checkpoint = {
+        dev: stat.dev,
+        ino: stat.ino,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        phase: params.phase,
+        generationKey: legacyAuditSourceGenerationKey(params.rawRelativePath),
+        recordCount: params.recordCount,
+        recordOrdinalBase: params.recordOrdinalBase,
+        contentHash: createHash("sha256").update(params.snapshot.rawBytes).digest("hex"),
+        sanitizedContentHash: createHash("sha256").update(sanitizedSnapshot.rawBytes).digest("hex"),
+        sanitizedSize: sanitizedSnapshot.rawBytes.length,
+      };
+    } finally {
+      await opened.handle.close();
+    }
+    if (!legacyAuditRawCheckpointsMatch(checkpoint, params.snapshot)) {
+      params.warnings.push(
+        `Retained changed legacy audit backup ${params.rawPath}; rerun openclaw doctor --fix to import its later rows`,
+      );
+      return false;
+    }
+    openLegacyAuditRawCheckpointStore(params.stateDir).upsert(
+      legacyAuditRawCheckpointKey(checkpoint),
+      checkpoint,
+    );
+    return true;
+  } catch (error) {
+    params.warnings.push(
+      `Failed recording legacy audit backup checkpoint for ${params.rawPath}: ${String(error)}`,
+    );
+    return false;
+  }
+}
+
+export function findPreviousLegacyAuditRawCheckpoint(
+  stateDir: string,
+  rawRelativePath: string,
+): LegacyAuditRawCheckpoint | undefined {
+  const generationKey = legacyAuditSourceGenerationKey(rawRelativePath);
+  return openLegacyAuditRawCheckpointStore(stateDir)
+    .entries()
+    .toReversed()
+    .find((entry) => entry.value.generationKey === generationKey)?.value;
+}
+
+export function recordsAfterLegacyAuditRawCheckpoint<T>(params: {
+  checkpoint: LegacyAuditRawCheckpoint;
+  snapshot: LegacyAuditSourceSnapshot;
+  records: readonly T[];
+}): readonly T[] | undefined {
+  const rawBytes = params.snapshot.rawBytes;
+  if (rawBytes.length < params.checkpoint.size) {
+    return undefined;
+  }
+  const prefixHash = createHash("sha256")
+    .update(rawBytes.subarray(0, params.checkpoint.size))
+    .digest("hex");
+  const legacyUtf8PrefixHash = createHash("sha256")
+    .update(rawBytes.subarray(0, params.checkpoint.size).toString("utf8"))
+    .digest("hex");
+  if (
+    (prefixHash !== params.checkpoint.contentHash &&
+      legacyUtf8PrefixHash !== params.checkpoint.contentHash) ||
+    params.records.length < params.checkpoint.recordCount
+  ) {
+    return undefined;
+  }
+  return params.records.slice(params.checkpoint.recordCount);
+}
diff --git a/src/infra/state-migrations.audit-sanitized.ts b/src/infra/state-migrations.audit-sanitized.ts
new file mode 100644
index 00000000000..0ab995de0d3
--- /dev/null
+++ b/src/infra/state-migrations.audit-sanitized.ts
@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import type { LegacyAuditRawCheckpoint } from "./state-migrations.audit-checkpoints.js";
+import {
+  readLegacyAuditSourceSnapshot,
+  type AuditMigrationRoot,
+} from "./state-migrations.audit-recovery.js";
+
+export async function writeRecoveredSanitizedAuditArchive(params: {
+  sourceLabel: string;
+  root: AuditMigrationRoot;
+  relativePath: string;
+  allRecordsJsonl: string;
+  candidateRecordsJsonl: string;
+  previousCheckpoint: LegacyAuditRawCheckpoint | undefined;
+  warnings: string[];
+}): Promise<boolean> {
+  const current = (await params.root.exists(params.relativePath))
+    ? await readLegacyAuditSourceSnapshot(params.root, params.relativePath)
+    : undefined;
+  let desired: Buffer;
+  if (params.previousCheckpoint) {
+    if (!current || current.rawBytes.length < params.previousCheckpoint.sanitizedSize) {
+      params.warnings.push(
+        `Skipped ${params.sourceLabel} recovery because its sanitized archive is missing or truncated`,
+      );
+      return false;
+    }
+    const checkpointedPrefix = current.rawBytes.subarray(
+      0,
+      params.previousCheckpoint.sanitizedSize,
+    );
+    if (
+      createHash("sha256").update(checkpointedPrefix).digest("hex") !==
+      params.previousCheckpoint.sanitizedContentHash
+    ) {
+      params.warnings.push(
+        `Skipped ${params.sourceLabel} recovery because its sanitized archive changed after checkpoint`,
+      );
+      return false;
+    }
+    // The caller already removed checkpointed raw records. For merge-intent,
+    // this sanitized prefix also contains that previously materialized batch.
+    desired = Buffer.concat([
+      checkpointedPrefix,
+      Buffer.from(params.candidateRecordsJsonl, "utf8"),
+    ]);
+    if (current.rawBytes.equals(desired)) {
+      return true;
+    }
+    const currentIsVerifiedDesiredPrefix = desired
+      .subarray(0, current.rawBytes.length)
+      .equals(current.rawBytes);
+    if (
+      current.rawBytes.length !== params.previousCheckpoint.sanitizedSize &&
+      !currentIsVerifiedDesiredPrefix
+    ) {
+      params.warnings.push(
+        `Skipped ${params.sourceLabel} recovery because its sanitized archive has an uncheckpointed tail`,
+      );
+      return false;
+    }
+  } else {
+    // A checkpointless unscrubbed raw archive is authoritative. Replacing from
+    // the complete sanitized projection is idempotent before checkpoint commit.
+    desired = Buffer.from(params.allRecordsJsonl, "utf8");
+    if (current?.rawBytes.equals(desired)) {
+      return true;
+    }
+  }
+  await params.root.write(params.relativePath, desired, { mkdir: false, mode: 0o600 });
+  return true;
+}
diff --git a/src/infra/state-migrations.doctor.ts b/src/infra/state-migrations.doctor.ts
index 22a84774161..fc31680fabb 100644
--- a/src/infra/state-migrations.doctor.ts
+++ b/src/infra/state-migrations.doctor.ts
@@ -11,6 +11,8 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import {
   createPluginStateKeyedStore,
+  getPluginStateCapacity as resolvePluginStateCapacity,
+  importPluginStateEntriesForDoctor,
   type OpenKeyedStoreOptions,
 } from "../plugin-state/plugin-state-store.js";
 import {
@@ -27,6 +29,7 @@ import {
   repairOpenClawStateDatabaseSchema,
   type OpenClawStateDatabaseSchemaMigration,
 } from "../state/openclaw-state-db.js";
+import { acquireGatewayLock } from "./gateway-lock.js";
 import {
   detectLegacyAcpReplayLedger,
   migrateLegacyAcpReplayLedger,
@@ -35,6 +38,7 @@ import {
   detectLegacyApnsRegistrations,
   migrateLegacyApnsRegistrations,
 } from "./state-migrations.apns.js";
+import { detectLegacyAuditLogs, migrateLegacyAuditLogs } from "./state-migrations.audit-logs.js";
 import {
   detectLegacyChannelPairingState,
   migrateLegacyChannelPairingState,
@@ -164,6 +168,9 @@ function describeStateSchemaMigration(migration: OpenClawStateDatabaseSchemaMigr
 
 let autoMigrateChecked = false;
 
+const PLUGIN_DOCTOR_MIGRATION_LOCK_TIMEOUT_MS = 250;
+const PLUGIN_DOCTOR_MIGRATION_LOCK_POLL_INTERVAL_MS = 25;
+
 export function resetAutoMigrateLegacyStateForTest(): void {
   autoMigrateChecked = false;
   resetAutoMigrateLegacyTaskStateSidecarsForTest();
@@ -206,6 +213,7 @@ async function collectPluginDoctorStateMigrationPlans(params: {
   env: NodeJS.ProcessEnv;
   stateDir: string;
   oauthDir: string;
+  includeDoctorOnly?: boolean;
   warnings?: string[];
 }): Promise<DetectedPluginDoctorStateMigrationPlan[]> {
   const plans: DetectedPluginDoctorStateMigrationPlan[] = [];
@@ -214,6 +222,9 @@ async function collectPluginDoctorStateMigrationPlans(params: {
     config,
     env: params.env,
   })) {
+    if (entry.migration.doctorOnly === true && params.includeDoctorOnly !== true) {
+      continue;
+    }
     let detected: PluginDoctorStateMigrationDetection | null;
     try {
       detected = await entry.migration.detectLegacyState({
@@ -243,6 +254,15 @@ function createPluginDoctorStateMigrationContext(
   env: NodeJS.ProcessEnv,
 ): PluginDoctorStateMigrationContext {
   return {
+    getPluginStateCapacity() {
+      return resolvePluginStateCapacity(pluginId, env);
+    },
+    importPluginStateEntries(
+      options: OpenKeyedStoreOptions,
+      entries: readonly { key: string; value: unknown; createdAt: number }[],
+    ) {
+      importPluginStateEntriesForDoctor(pluginId, { ...options, env: options.env ?? env }, entries);
+    },
     openPluginStateKeyedStore<T>(options: OpenKeyedStoreOptions) {
       return createPluginStateKeyedStore<T>(pluginId, {
         ...options,
@@ -406,6 +426,10 @@ export async function detectLegacyStateMigrations(params: {
     stateDir,
     doctorOnlyStateMigrations: params.doctorOnlyStateMigrations,
   });
+  const auditLogs = detectLegacyAuditLogs({
+    stateDir,
+    doctorOnlyStateMigrations: params.doctorOnlyStateMigrations,
+  });
   const acpReplayLedger = detectLegacyAcpReplayLedger({
     stateDir,
     doctorOnlyStateMigrations: params.doctorOnlyStateMigrations,
@@ -522,6 +546,7 @@ export async function detectLegacyStateMigrations(params: {
           env,
           stateDir,
           oauthDir,
+          includeDoctorOnly: params.doctorOnlyStateMigrations === true,
           warnings: pluginPlanWarnings,
         });
 
@@ -593,6 +618,9 @@ export async function detectLegacyStateMigrations(params: {
   if (commitments.hasLegacy) {
     preview.push("- Commitments: legacy JSON file → shared SQLite state");
   }
+  for (const source of auditLogs.sources) {
+    preview.push(`- ${source.label}: legacy JSONL file → shared SQLite state`);
+  }
   if (acpReplayLedger.hasLegacy) {
     preview.push("- ACP replay ledger: legacy JSON file → shared SQLite state");
   }
@@ -634,6 +662,7 @@ export async function detectLegacyStateMigrations(params: {
   }
 
   return {
+    doctorOnlyStateMigrations: params.doctorOnlyStateMigrations === true,
     targetAgentId,
     targetMainKey,
     targetScope,
@@ -707,6 +736,7 @@ export async function detectLegacyStateMigrations(params: {
     },
     tuiLastSessions,
     commitments,
+    auditLogs,
     acpReplayLedger,
     managedOutgoingImages,
     apns,
@@ -737,6 +767,7 @@ async function runPluginDoctorStateMigrationPlans(params: {
     env: params.env,
     stateDir: params.detected.stateDir,
     oauthDir: params.detected.oauthDir,
+    includeDoctorOnly: params.detected.doctorOnlyStateMigrations,
     warnings,
   });
   const hasDetectorFailure = warnings.length > 0;
@@ -746,21 +777,80 @@ async function runPluginDoctorStateMigrationPlans(params: {
     refreshedPlans.length > 0 || hasDetectorFailure
       ? refreshedPlans
       : (params.detected.pluginPlans?.plans ?? []);
-  for (const plan of plans) {
-    try {
-      const result = await plan.migration.migrateLegacyState({
-        config: params.config,
-        env: params.env,
-        stateDir: params.detected.stateDir,
-        oauthDir: params.detected.oauthDir,
-        context: createPluginDoctorStateMigrationContext(plan.pluginId, params.env),
-      });
-      changes.push(...result.changes);
-      warnings.push(...result.warnings);
-      notices.push(...(result.notices ?? []));
-    } catch (err) {
-      warnings.push(`Failed migrating ${plan.migration.label}: ${String(err)}`);
+  const migrated = await migratePluginDoctorStatePlans({
+    plans,
+    config: params.config,
+    env: params.env,
+    stateDir: params.detected.stateDir,
+    oauthDir: params.detected.oauthDir,
+  });
+  changes.push(...migrated.changes);
+  warnings.push(...migrated.warnings);
+  notices.push(...(migrated.notices ?? []));
+  return notices.length > 0 ? { changes, warnings, notices } : { changes, warnings };
+}
+
+async function migratePluginDoctorStatePlans(params: {
+  plans: readonly DetectedPluginDoctorStateMigrationPlan[];
+  config: OpenClawConfig;
+  env: NodeJS.ProcessEnv;
+  stateDir: string;
+  oauthDir: string;
+}): Promise<MigrationMessages> {
+  const changes: string[] = [];
+  const warnings: string[] = [];
+  const notices: string[] = [];
+  if (params.plans.length === 0) {
+    return { changes, warnings };
+  }
+
+  let lock: Awaited<ReturnType<typeof acquireGatewayLock>>;
+  try {
+    lock = await acquireGatewayLock({
+      allowInTests: true,
+      env: { ...params.env, OPENCLAW_STATE_DIR: params.stateDir },
+      pollIntervalMs: PLUGIN_DOCTOR_MIGRATION_LOCK_POLL_INTERVAL_MS,
+      role: "sqlite-maintenance",
+      timeoutMs: PLUGIN_DOCTOR_MIGRATION_LOCK_TIMEOUT_MS,
+    });
+  } catch (error) {
+    return {
+      changes,
+      warnings: [
+        `Skipped plugin doctor state migrations because exclusive state ownership is unavailable: ${String(error)}`,
+      ],
+    };
+  }
+  if (!lock) {
+    return {
+      changes,
+      warnings: [
+        "Skipped plugin doctor state migrations because exclusive state ownership is unavailable",
+      ],
+    };
+  }
+
+  try {
+    // Plugin migrations may claim retired files after verified import. Keep the
+    // predecessor Gateway excluded for the full read, import, and archive window.
+    for (const plan of params.plans) {
+      try {
+        const result = await plan.migration.migrateLegacyState({
+          config: params.config,
+          env: params.env,
+          stateDir: params.stateDir,
+          oauthDir: params.oauthDir,
+          context: createPluginDoctorStateMigrationContext(plan.pluginId, params.env),
+        });
+        changes.push(...result.changes);
+        warnings.push(...result.warnings);
+        notices.push(...(result.notices ?? []));
+      } catch (err) {
+        warnings.push(`Failed migrating ${plan.migration.label}: ${String(err)}`);
+      }
     }
+  } finally {
+    await lock.release();
   }
   return notices.length > 0 ? { changes, warnings, notices } : { changes, warnings };
 }
@@ -807,22 +897,16 @@ export async function autoMigrateLegacyPluginDoctorState(params: {
     oauthDir,
     warnings,
   });
-  for (const plan of plans) {
-    try {
-      const result = await plan.migration.migrateLegacyState({
-        config: params.config,
-        env,
-        stateDir,
-        oauthDir,
-        context: createPluginDoctorStateMigrationContext(plan.pluginId, env),
-      });
-      changes.push(...result.changes);
-      warnings.push(...result.warnings);
-      notices.push(...(result.notices ?? []));
-    } catch (err) {
-      warnings.push(`Failed migrating ${plan.migration.label}: ${String(err)}`);
-    }
-  }
+  const migrated = await migratePluginDoctorStatePlans({
+    plans,
+    config: params.config,
+    env,
+    stateDir,
+    oauthDir,
+  });
+  changes.push(...migrated.changes);
+  warnings.push(...migrated.warnings);
+  notices.push(...(migrated.notices ?? []));
   return {
     migrated: stateDirResult.migrated || stateSchema.changes.length > 0 || plans.length > 0,
     skipped: false,
@@ -902,6 +986,10 @@ export async function runLegacyStateMigrations(params: {
     detected: detected.commitments,
     stateDir: detected.stateDir,
   });
+  const auditLogs = await migrateLegacyAuditLogs({
+    detected: detected.auditLogs,
+    stateDir: detected.stateDir,
+  });
   const acpReplayLedger = await migrateLegacyAcpReplayLedger({
     detected: detected.acpReplayLedger,
     stateDir: detected.stateDir,
@@ -980,6 +1068,7 @@ export async function runLegacyStateMigrations(params: {
     updateCheck,
     tuiLastSessions,
     commitments,
+    auditLogs,
     acpReplayLedger,
     managedOutgoingImages,
     apns,
@@ -1006,6 +1095,7 @@ export async function runLegacyStateMigrations(params: {
       ...currentConversationBindings.changes,
       ...tuiLastSessions.changes,
       ...commitments.changes,
+      ...auditLogs.changes,
       ...acpReplayLedger.changes,
       ...managedOutgoingImages.changes,
       ...apns.changes,
@@ -1039,6 +1129,7 @@ export async function runLegacyStateMigrations(params: {
       ...currentConversationBindings.warnings,
       ...tuiLastSessions.warnings,
       ...commitments.warnings,
+      ...auditLogs.warnings,
       ...acpReplayLedger.warnings,
       ...managedOutgoingImages.warnings,
       ...apns.warnings,
diff --git a/src/infra/state-migrations.test.ts b/src/infra/state-migrations.test.ts
index 0ea28ea9ec3..e1995dfac46 100644
--- a/src/infra/state-migrations.test.ts
+++ b/src/infra/state-migrations.test.ts
@@ -16,6 +16,7 @@ import {
   OPENCLAW_STATE_SCHEMA_VERSION,
 } from "../state/openclaw-state-db.js";
 import { createTrackedTempDirs } from "../test-utils/tracked-temp-dirs.js";
+import { acquireGatewayLock } from "./gateway-lock.js";
 import {
   executeSqliteQuerySync,
   executeSqliteQueryTakeFirstSync,
@@ -48,6 +49,7 @@ const pluginDoctorStateMigrationEntries = vi.hoisted(
         migration: {
           id: string;
           label: string;
+          doctorOnly?: boolean;
           detectLegacyState: (params: {
             config: OpenClawConfig;
             env: NodeJS.ProcessEnv;
@@ -546,6 +548,54 @@ describe("state migrations", () => {
     expect(result.changes).toContain("Migrated fixture environment");
   });
 
+  it("runs doctor-only plugin file imports only during explicit Doctor repair", async () => {
+    const root = await createTempDir();
+    const stateDir = path.join(root, ".openclaw");
+    const env = createEnv(stateDir);
+    const cfg = createConfig();
+    const detectLegacyState = vi.fn(() => ({ preview: ["doctor-only plugin state"] }));
+    const migrateLegacyState = vi.fn(() => ({
+      changes: ["doctor-only plugin state migrated"],
+      warnings: [],
+    }));
+    pluginDoctorStateMigrationEntries.entries = [
+      {
+        pluginId: "memory-core",
+        migration: {
+          id: "memory-core-doctor-only-test",
+          label: "Memory Core doctor-only test migration",
+          doctorOnly: true,
+          detectLegacyState,
+          migrateLegacyState,
+        },
+      },
+    ];
+
+    const automatic = await autoMigrateLegacyPluginDoctorState({
+      config: cfg,
+      env,
+      homedir: () => root,
+    });
+    expect(automatic.changes).not.toContain("doctor-only plugin state migrated");
+    expect(detectLegacyState).not.toHaveBeenCalled();
+    expect(migrateLegacyState).not.toHaveBeenCalled();
+
+    const detected = await detectLegacyStateMigrations({
+      cfg,
+      env,
+      homedir: () => root,
+      doctorOnlyStateMigrations: true,
+    });
+    expect(detected.pluginPlans).toMatchObject({ hasLegacy: true });
+    expect(detected.preview).toContain("doctor-only plugin state");
+
+    const repaired = await runLegacyStateMigrations({ detected, config: cfg, env });
+    expect(repaired.warnings).toStrictEqual([]);
+    expect(repaired.changes).toContain("doctor-only plugin state migrated");
+    expect(detectLegacyState).toHaveBeenCalledTimes(2);
+    expect(migrateLegacyState).toHaveBeenCalledOnce();
+  });
+
   it("detects legacy sessions, agent files, channel auth, and pairing state", () => {
     expect(detectionCase.targetAgentId).toBe("worker-1");
     expect(detectionCase.targetMainKey).toBe("desk");
@@ -2011,6 +2061,55 @@ describe("state migrations", () => {
     expect(migrateLegacyState).toHaveBeenCalledOnce();
   });
 
+  it("requires exclusive state ownership before plugin doctor migrations", async () => {
+    const root = await createTempDir();
+    const stateDir = path.join(root, ".openclaw");
+    const env = createEnv(stateDir);
+    const cfg = createConfig();
+    openOpenClawStateDatabase({ env });
+    closeOpenClawStateDatabaseForTest();
+    const migrateLegacyState = vi.fn(() => ({
+      changes: ["plugin state migrated"],
+      warnings: [],
+    }));
+    pluginDoctorStateMigrationEntries.entries = [
+      {
+        pluginId: "memory-core",
+        migration: {
+          id: "memory-core-lock-test",
+          label: "Memory Core lock test migration",
+          detectLegacyState: () => ({ preview: ["plugin state"] }),
+          migrateLegacyState,
+        },
+      },
+    ];
+    const gatewayLock = await acquireGatewayLock({
+      allowInTests: true,
+      env,
+      pollIntervalMs: 10,
+      port: 18_791,
+      timeoutMs: 100,
+    });
+    if (!gatewayLock) {
+      throw new Error("expected test Gateway lock");
+    }
+
+    let result: Awaited<ReturnType<typeof autoMigrateLegacyPluginDoctorState>>;
+    try {
+      result = await autoMigrateLegacyPluginDoctorState({
+        config: cfg,
+        env,
+        homedir: () => root,
+      });
+    } finally {
+      await gatewayLock.release();
+    }
+
+    expect(result.changes).not.toContain("plugin state migrated");
+    expect(result.warnings.join("\n")).toContain("exclusive state ownership is unavailable");
+    expect(migrateLegacyState).not.toHaveBeenCalled();
+  });
+
   it("skips stale plugin doctor plans when refresh detection fails", async () => {
     const root = await createTempDir();
     const stateDir = path.join(root, ".openclaw");
diff --git a/src/infra/state-migrations.types.ts b/src/infra/state-migrations.types.ts
index bbe853f514f..5b3e3dcca3f 100644
--- a/src/infra/state-migrations.types.ts
+++ b/src/infra/state-migrations.types.ts
@@ -1,6 +1,7 @@
 import type { ChannelLegacyStateMigrationPlan } from "../channels/plugins/types.core.js";
 import type { SessionScope } from "../config/sessions/types.js";
 import type { PluginDoctorStateMigration } from "../plugins/doctor-contract-registry.js";
+import type { LegacyAuditLogsDetection } from "./state-migrations.audit-logs.types.js";
 import type { LegacyChannelPairingStateDetection } from "./state-migrations.channel-pairing.js";
 import type { LegacyMcpOAuthDetection } from "./state-migrations.mcp-oauth.types.js";
 import type { LegacyRestartSentinelDetection } from "./state-migrations.restart-sentinel.types.js";
@@ -18,6 +19,7 @@ export type SessionStoreAliasPlan = {
 };
 
 export type LegacyStateDetection = {
+  doctorOnlyStateMigrations?: boolean;
   targetAgentId: string;
   targetMainKey: string;
   targetScope?: SessionScope;
@@ -103,6 +105,7 @@ export type LegacyStateDetection = {
     sourcePath: string;
     hasLegacy: boolean;
   };
+  auditLogs: LegacyAuditLogsDetection;
   acpReplayLedger: {
     sourcePath: string;
     hasLegacy: boolean;
diff --git a/src/memory-host-sdk/event-export.ts b/src/memory-host-sdk/event-export.ts
new file mode 100644
index 00000000000..40c28fa742f
--- /dev/null
+++ b/src/memory-host-sdk/event-export.ts
@@ -0,0 +1,20 @@
+import type { PersistedMemoryHostEvent } from "./event-store.js";
+
+export const MAX_MEMORY_HOST_PUBLIC_EXPORT_BYTES = 1024 * 1024;
+
+export function serializeMemoryHostEventExport(
+  storedEvents: readonly PersistedMemoryHostEvent[],
+): string {
+  const lines: string[] = [];
+  let sizeBytes = 0;
+  for (const entry of storedEvents.toReversed()) {
+    const line = JSON.stringify(entry.value.event);
+    const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+    if (sizeBytes + lineBytes > MAX_MEMORY_HOST_PUBLIC_EXPORT_BYTES) {
+      break;
+    }
+    lines.push(line);
+    sizeBytes += lineBytes;
+  }
+  return lines.toReversed().join("\n") + "\n";
+}
diff --git a/src/memory-host-sdk/event-store.ts b/src/memory-host-sdk/event-store.ts
new file mode 100644
index 00000000000..96dc7c1c944
--- /dev/null
+++ b/src/memory-host-sdk/event-store.ts
@@ -0,0 +1,359 @@
+import { createHash } from "node:crypto";
+import { resolveWorkspaceStateIdentity } from "../agents/workspace-state-store.js";
+import {
+  pluginStateEntriesInKeyRange,
+  registerPluginStateSyncSequencedJournalEntry,
+} from "../plugin-state/plugin-state-store.js";
+import type { MemoryHostEventRecord } from "./event-types.js";
+
+const MEMORY_HOST_EVENTS_PLUGIN_ID = "memory-core";
+const MEMORY_HOST_EVENTS_NAMESPACE = "memory-host.events";
+const MEMORY_HOST_EVENT_CURSORS_NAMESPACE = "memory-host.event-cursors";
+// Event rotation retains deep diagnostics without consuming memory-core's
+// plugin-wide 50,000-row budget or starving sibling state namespaces.
+const MAX_MEMORY_HOST_EVENTS = 10_000;
+const MAX_MEMORY_HOST_EVENT_CURSORS = 1_000;
+const MAX_MEMORY_HOST_EVENT_JSON_BYTES = 8 * 1024;
+const MAX_MEMORY_HOST_EVENT_ITEMS = 10;
+const MAX_MEMORY_HOST_EVENT_TEXT_BYTES = 2 * 1024;
+const MAX_MEMORY_HOST_EVENT_PATH_BYTES = 256;
+const WORKSPACE_HASH_BYTES = 24;
+
+type StoredMemoryHostEvent = {
+  kind: "event";
+  event: MemoryHostEventRecord;
+  recordedAt: number;
+  sequence: number;
+};
+
+let maxMemoryHostEventsForTests: number | undefined;
+
+export type PersistedMemoryHostEvent = {
+  key: string;
+  value: StoredMemoryHostEvent;
+  createdAt: number;
+};
+
+function normalizeMemoryHostWorkspaceKey(workspaceDir: string): string {
+  // Workspace aliases must share one event/cursor namespace. Otherwise two
+  // configured paths to the same workspace can publish conflicting exports.
+  const resolved = resolveWorkspaceStateIdentity(workspaceDir).workspacePath.replace(/\\/g, "/");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function memoryHostWorkspacePrefix(workspaceDir: string): string {
+  return createHash("sha256")
+    .update(normalizeMemoryHostWorkspaceKey(workspaceDir))
+    .digest("hex")
+    .slice(0, WORKSPACE_HASH_BYTES);
+}
+
+function eventKeyPrefix(workspaceDir: string): string {
+  return `${memoryHostWorkspacePrefix(workspaceDir)}:event:`;
+}
+
+function eventKeyRangeEnd(workspaceDir: string): string {
+  return `${memoryHostWorkspacePrefix(workspaceDir)}:event;`;
+}
+
+function memoryHostEventStorageKey(workspaceDir: string, sequence: number): string {
+  if (!Number.isSafeInteger(sequence)) {
+    throw new Error("Memory host event sequence must be a safe integer");
+  }
+  return `${eventKeyPrefix(workspaceDir)}1:${sequence.toString().padStart(16, "0")}`;
+}
+
+function cursorKey(workspaceDir: string): string {
+  return `${memoryHostWorkspacePrefix(workspaceDir)}:cursor`;
+}
+
+function truncateUtf8(value: string, maxBytes: number): { value: string; truncated: boolean } {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) {
+    return { value, truncated: false };
+  }
+  let low = 0;
+  let high = value.length;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(value.slice(0, middle), "utf8") <= maxBytes - 3) {
+      low = middle;
+    } else {
+      high = middle - 1;
+    }
+  }
+  const end = low > 0 && /[\uD800-\uDBFF]/u.test(value.charAt(low - 1)) ? low - 1 : low;
+  return { value: `${value.slice(0, end)}…`, truncated: true };
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Validate and bound one diagnostic event before storing it in plugin state. */
+export function normalizeMemoryHostEventRecordForStorage(
+  value: unknown,
+): MemoryHostEventRecord | null {
+  if (!isRecord(value) || typeof value.type !== "string" || typeof value.timestamp !== "string") {
+    return null;
+  }
+  const timestamp = truncateUtf8(value.timestamp, 128);
+  let truncated = timestamp.truncated || value.storageTruncated === true;
+
+  if (value.type === "memory.recall.recorded" || value.type === "memory.recall.skipped") {
+    if (
+      typeof value.query !== "string" ||
+      !Array.isArray(value.results) ||
+      (value.type === "memory.recall.recorded"
+        ? !isFiniteNumber(value.resultCount)
+        : !isFiniteNumber(value.skippedResultCount))
+    ) {
+      return null;
+    }
+    if (
+      value.type === "memory.recall.skipped" &&
+      (value.reason !== "non-short-term-memory-path" ||
+        !isFiniteNumber(value.eligibleResultCount) ||
+        !isFiniteNumber(value.skippedResultCount))
+    ) {
+      return null;
+    }
+    const query = truncateUtf8(value.query, MAX_MEMORY_HOST_EVENT_TEXT_BYTES);
+    truncated ||= query.truncated || value.results.length > MAX_MEMORY_HOST_EVENT_ITEMS;
+    const results: Array<{
+      path: string;
+      startLine: number;
+      endLine: number;
+      score: number;
+      reason?: "non-short-term-memory-path";
+    }> = [];
+    for (const result of value.results.slice(0, MAX_MEMORY_HOST_EVENT_ITEMS)) {
+      if (
+        !isRecord(result) ||
+        typeof result.path !== "string" ||
+        !isFiniteNumber(result.startLine) ||
+        !isFiniteNumber(result.endLine) ||
+        !isFiniteNumber(result.score) ||
+        (value.type === "memory.recall.skipped" && result.reason !== "non-short-term-memory-path")
+      ) {
+        return null;
+      }
+      const resultPath = truncateUtf8(result.path, MAX_MEMORY_HOST_EVENT_PATH_BYTES);
+      truncated ||= resultPath.truncated;
+      results.push({
+        path: resultPath.value,
+        startLine: result.startLine,
+        endLine: result.endLine,
+        score: result.score,
+        ...(value.type === "memory.recall.skipped"
+          ? { reason: "non-short-term-memory-path" as const }
+          : {}),
+      });
+    }
+    const normalized =
+      value.type === "memory.recall.recorded"
+        ? {
+            type: "memory.recall.recorded" as const,
+            timestamp: timestamp.value,
+            query: query.value,
+            resultCount: value.resultCount as number,
+            results: results.map((result) => ({
+              path: result.path,
+              startLine: result.startLine,
+              endLine: result.endLine,
+              score: result.score,
+            })),
+            ...(truncated ? { storageTruncated: true as const } : {}),
+          }
+        : {
+            type: "memory.recall.skipped" as const,
+            timestamp: timestamp.value,
+            query: query.value,
+            reason: "non-short-term-memory-path" as const,
+            eligibleResultCount: value.eligibleResultCount as number,
+            skippedResultCount: value.skippedResultCount as number,
+            results: results.map((result) => ({
+              path: result.path,
+              startLine: result.startLine,
+              endLine: result.endLine,
+              score: result.score,
+              reason: "non-short-term-memory-path" as const,
+            })),
+            ...(truncated ? { storageTruncated: true as const } : {}),
+          };
+    return Buffer.byteLength(JSON.stringify(normalized), "utf8") <= MAX_MEMORY_HOST_EVENT_JSON_BYTES
+      ? normalized
+      : { ...normalized, results: [], storageTruncated: true as const };
+  }
+
+  if (value.type === "memory.promotion.applied") {
+    if (
+      typeof value.memoryPath !== "string" ||
+      !isFiniteNumber(value.applied) ||
+      !Array.isArray(value.candidates)
+    ) {
+      return null;
+    }
+    const memoryPath = truncateUtf8(value.memoryPath, MAX_MEMORY_HOST_EVENT_PATH_BYTES);
+    truncated ||= memoryPath.truncated || value.candidates.length > MAX_MEMORY_HOST_EVENT_ITEMS;
+    const candidates: Array<{
+      key: string;
+      path: string;
+      startLine: number;
+      endLine: number;
+      score: number;
+      recallCount: number;
+    }> = [];
+    for (const candidate of value.candidates.slice(0, MAX_MEMORY_HOST_EVENT_ITEMS)) {
+      if (
+        !isRecord(candidate) ||
+        typeof candidate.key !== "string" ||
+        typeof candidate.path !== "string" ||
+        !isFiniteNumber(candidate.startLine) ||
+        !isFiniteNumber(candidate.endLine) ||
+        !isFiniteNumber(candidate.score) ||
+        !isFiniteNumber(candidate.recallCount)
+      ) {
+        return null;
+      }
+      const key = truncateUtf8(candidate.key, MAX_MEMORY_HOST_EVENT_PATH_BYTES);
+      const candidatePath = truncateUtf8(candidate.path, MAX_MEMORY_HOST_EVENT_PATH_BYTES);
+      truncated ||= key.truncated || candidatePath.truncated;
+      candidates.push({
+        key: key.value,
+        path: candidatePath.value,
+        startLine: candidate.startLine,
+        endLine: candidate.endLine,
+        score: candidate.score,
+        recallCount: candidate.recallCount,
+      });
+    }
+    const normalized = {
+      type: "memory.promotion.applied" as const,
+      timestamp: timestamp.value,
+      memoryPath: memoryPath.value,
+      applied: value.applied,
+      candidates,
+      ...(truncated ? { storageTruncated: true as const } : {}),
+    };
+    return Buffer.byteLength(JSON.stringify(normalized), "utf8") <= MAX_MEMORY_HOST_EVENT_JSON_BYTES
+      ? normalized
+      : { ...normalized, candidates: [], storageTruncated: true as const };
+  }
+
+  if (value.type === "memory.dream.completed") {
+    if (
+      (value.phase !== "light" && value.phase !== "deep" && value.phase !== "rem") ||
+      (value.outcome !== undefined &&
+        value.outcome !== "completed" &&
+        value.outcome !== "failed") ||
+      (value.error !== undefined && typeof value.error !== "string") ||
+      (value.inlinePath !== undefined && typeof value.inlinePath !== "string") ||
+      (value.reportPath !== undefined && typeof value.reportPath !== "string") ||
+      !isFiniteNumber(value.lineCount) ||
+      (value.storageMode !== "inline" &&
+        value.storageMode !== "separate" &&
+        value.storageMode !== "both")
+    ) {
+      return null;
+    }
+    const error = value.error
+      ? truncateUtf8(value.error, MAX_MEMORY_HOST_EVENT_TEXT_BYTES)
+      : undefined;
+    const inlinePath = value.inlinePath
+      ? truncateUtf8(value.inlinePath, MAX_MEMORY_HOST_EVENT_PATH_BYTES)
+      : undefined;
+    const reportPath = value.reportPath
+      ? truncateUtf8(value.reportPath, MAX_MEMORY_HOST_EVENT_PATH_BYTES)
+      : undefined;
+    truncated ||= Boolean(error?.truncated || inlinePath?.truncated || reportPath?.truncated);
+    return {
+      type: value.type,
+      timestamp: timestamp.value,
+      phase: value.phase,
+      ...(value.outcome ? { outcome: value.outcome } : {}),
+      ...(error ? { error: error.value } : {}),
+      ...(inlinePath ? { inlinePath: inlinePath.value } : {}),
+      ...(reportPath ? { reportPath: reportPath.value } : {}),
+      lineCount: value.lineCount,
+      storageMode: value.storageMode,
+      ...(truncated ? { storageTruncated: true } : {}),
+    };
+  }
+
+  return null;
+}
+
+export function registerMemoryHostEvent(params: {
+  workspaceDir: string;
+  event: MemoryHostEventRecord;
+  env?: NodeJS.ProcessEnv;
+}): void {
+  const event = normalizeMemoryHostEventRecordForStorage(params.event);
+  if (!event) {
+    throw new TypeError("Memory host event is invalid");
+  }
+  const initialSequence = Math.max(
+    0,
+    listStoredMemoryHostEvents({
+      workspaceDir: params.workspaceDir,
+      limit: 1,
+      ...(params.env ? { env: params.env } : {}),
+    }).at(-1)?.value.sequence ?? 0,
+  );
+  const recordedAt = Date.now();
+  registerPluginStateSyncSequencedJournalEntry({
+    pluginId: MEMORY_HOST_EVENTS_PLUGIN_ID,
+    cursorOptions: {
+      namespace: MEMORY_HOST_EVENT_CURSORS_NAMESPACE,
+      maxEntries: MAX_MEMORY_HOST_EVENT_CURSORS,
+      ...(params.env ? { env: params.env } : {}),
+    },
+    cursorKey: cursorKey(params.workspaceDir),
+    journalOptions: {
+      namespace: MEMORY_HOST_EVENTS_NAMESPACE,
+      maxEntries: maxMemoryHostEventsForTests ?? MAX_MEMORY_HOST_EVENTS,
+      ...(params.env ? { env: params.env } : {}),
+    },
+    initialSequence,
+    journalKey: (sequence) => memoryHostEventStorageKey(params.workspaceDir, sequence),
+    journalValue: (sequence) => ({ kind: "event", event, recordedAt, sequence }),
+  });
+}
+
+export function listStoredMemoryHostEvents(params: {
+  workspaceDir: string;
+  limit?: number;
+  env?: NodeJS.ProcessEnv;
+}): PersistedMemoryHostEvent[] {
+  const limit = Number.isFinite(params.limit)
+    ? Math.max(
+        1,
+        Math.min(
+          maxMemoryHostEventsForTests ?? MAX_MEMORY_HOST_EVENTS,
+          Math.floor(params.limit as number),
+        ),
+      )
+    : (maxMemoryHostEventsForTests ?? MAX_MEMORY_HOST_EVENTS);
+  const entries = pluginStateEntriesInKeyRange({
+    pluginId: MEMORY_HOST_EVENTS_PLUGIN_ID,
+    namespace: MEMORY_HOST_EVENTS_NAMESPACE,
+    keyStartInclusive: eventKeyPrefix(params.workspaceDir),
+    keyEndExclusive: eventKeyRangeEnd(params.workspaceDir),
+    limit,
+    order: "desc",
+    ...(params.env ? { env: params.env } : {}),
+  }).flatMap((entry): PersistedMemoryHostEvent[] => {
+    const value = entry.value as StoredMemoryHostEvent;
+    return value.kind === "event" ? [{ ...entry, value }] : [];
+  });
+  return entries.toReversed();
+}
+
+/** Test-only retention override; production keeps a 10,000-event namespace budget. */
+export function setMaxMemoryHostEventsForTests(maxEntries?: number): void {
+  maxMemoryHostEventsForTests = maxEntries;
+}
diff --git a/src/memory-host-sdk/event-types.ts b/src/memory-host-sdk/event-types.ts
new file mode 100644
index 00000000000..f2bba538094
--- /dev/null
+++ b/src/memory-host-sdk/event-types.ts
@@ -0,0 +1,80 @@
+import type { MemoryDreamingPhaseName } from "./dreaming.js";
+
+type MemoryHostEventStorageMetadata = {
+  /** True when diagnostic detail was bounded before persistence. Aggregate counts stay exact. */
+  storageTruncated?: true;
+};
+
+/** Event emitted when a recall query records the selected memory snippets. */
+export type MemoryHostRecallRecordedEvent = MemoryHostEventStorageMetadata & {
+  type: "memory.recall.recorded";
+  timestamp: string;
+  query: string;
+  resultCount: number;
+  results: Array<{
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+  }>;
+};
+
+/** Event emitted when recall hits are visible but excluded from short-term promotion. */
+export type MemoryHostRecallSkippedEvent = MemoryHostEventStorageMetadata & {
+  type: "memory.recall.skipped";
+  timestamp: string;
+  query: string;
+  reason: "non-short-term-memory-path";
+  eligibleResultCount: number;
+  skippedResultCount: number;
+  results: Array<{
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    reason: "non-short-term-memory-path";
+  }>;
+};
+
+/** Event emitted when deep-dream candidates are promoted into durable memory. */
+export type MemoryHostPromotionAppliedEvent = MemoryHostEventStorageMetadata & {
+  type: "memory.promotion.applied";
+  timestamp: string;
+  memoryPath: string;
+  applied: number;
+  candidates: Array<{
+    key: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    score: number;
+    recallCount: number;
+  }>;
+};
+
+/** Normalized outcome for a dreaming phase run. */
+export type MemoryDreamOutcome = "completed" | "failed";
+
+/** Event emitted after a dreaming phase writes inline memory and/or reports. */
+export type MemoryHostDreamCompletedEvent = MemoryHostEventStorageMetadata & {
+  type: "memory.dream.completed";
+  timestamp: string;
+  phase: MemoryDreamingPhaseName;
+  /** Missing on older event logs; readers should treat absent as "completed". */
+  outcome?: MemoryDreamOutcome;
+  /** Error detail when outcome is "failed". */
+  error?: string;
+  inlinePath?: string;
+  reportPath?: string;
+  lineCount: number;
+  storageMode: "inline" | "separate" | "both";
+};
+
+/** Durable memory host events consumed by status and public-artifact readers. */
+export type MemoryHostEvent =
+  | MemoryHostRecallRecordedEvent
+  | MemoryHostPromotionAppliedEvent
+  | MemoryHostDreamCompletedEvent;
+
+/** Full event record schema, including opt-in diagnostic variants. */
+export type MemoryHostEventRecord = MemoryHostEvent | MemoryHostRecallSkippedEvent;
diff --git a/src/memory-host-sdk/events.ts b/src/memory-host-sdk/events.ts
index eac122e5557..06ae73d4f44 100644
--- a/src/memory-host-sdk/events.ts
+++ b/src/memory-host-sdk/events.ts
@@ -1,150 +1,52 @@
-// Memory host event helpers append and read memory host event logs.
-import fs from "node:fs/promises";
+// Memory host event helpers append and read persisted memory host events.
 import path from "node:path";
-import { appendRegularFile } from "../infra/fs-safe.js";
-import type { MemoryDreamingPhaseName } from "./dreaming.js";
+import {
+  listStoredMemoryHostEvents,
+  normalizeMemoryHostEventRecordForStorage,
+  registerMemoryHostEvent,
+} from "./event-store.js";
+import type { MemoryHostEvent, MemoryHostEventRecord } from "./event-types.js";
 
-/** Workspace-relative JSONL audit log for memory recall, promotion, and dream events. */
-export const MEMORY_HOST_EVENT_LOG_RELATIVE_PATH = path.join("memory", ".dreams", "events.jsonl");
-
-/** Event emitted when a recall query records the selected memory snippets. */
-export type MemoryHostRecallRecordedEvent = {
-  type: "memory.recall.recorded";
-  timestamp: string;
-  query: string;
-  resultCount: number;
-  results: Array<{
-    path: string;
-    startLine: number;
-    endLine: number;
-    score: number;
-  }>;
-};
-
-/** Event emitted when recall hits are visible but excluded from short-term promotion. */
-export type MemoryHostRecallSkippedEvent = {
-  type: "memory.recall.skipped";
-  timestamp: string;
-  query: string;
-  reason: "non-short-term-memory-path";
-  eligibleResultCount: number;
-  skippedResultCount: number;
-  results: Array<{
-    path: string;
-    startLine: number;
-    endLine: number;
-    score: number;
-    reason: "non-short-term-memory-path";
-  }>;
-};
-
-/** Event emitted when deep-dream candidates are promoted into durable memory. */
-export type MemoryHostPromotionAppliedEvent = {
-  type: "memory.promotion.applied";
-  timestamp: string;
-  memoryPath: string;
-  applied: number;
-  candidates: Array<{
-    key: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    score: number;
-    recallCount: number;
-  }>;
-};
+export type {
+  MemoryDreamOutcome,
+  MemoryHostDreamCompletedEvent,
+  MemoryHostEvent,
+  MemoryHostEventRecord,
+  MemoryHostPromotionAppliedEvent,
+  MemoryHostRecallRecordedEvent,
+  MemoryHostRecallSkippedEvent,
+} from "./event-types.js";
 
-/** Normalized outcome for a dreaming phase run. */
-export type MemoryDreamOutcome = "completed" | "failed";
+export { normalizeMemoryHostEventRecordForStorage };
 
-/** Event emitted after a dreaming phase writes inline memory and/or reports. */
-export type MemoryHostDreamCompletedEvent = {
-  type: "memory.dream.completed";
-  timestamp: string;
-  phase: MemoryDreamingPhaseName;
-  /** Missing on older event logs; readers should treat absent as "completed". */
-  outcome?: MemoryDreamOutcome;
-  /** Error detail when outcome is "failed". */
-  error?: string;
-  inlinePath?: string;
-  reportPath?: string;
-  lineCount: number;
-  storageMode: "inline" | "separate" | "both";
-};
-
-/** Append-only memory host event schema stored as JSONL. */
-export type MemoryHostEvent =
-  | MemoryHostRecallRecordedEvent
-  | MemoryHostPromotionAppliedEvent
-  | MemoryHostDreamCompletedEvent;
-
-/** Full event-log record schema, including opt-in diagnostic variants. */
-export type MemoryHostEventRecord = MemoryHostEvent | MemoryHostRecallSkippedEvent;
+/** Legacy workspace JSONL path retained only for doctor migration discovery. */
+export const MEMORY_HOST_EVENT_LOG_RELATIVE_PATH = path.join("memory", ".dreams", "events.jsonl");
 
-/** Resolve the event log path inside a workspace without touching the filesystem. */
+/** Resolve the retired JSONL source path without reading it at runtime. */
 export function resolveMemoryHostEventLogPath(workspaceDir: string): string {
   return path.join(workspaceDir, MEMORY_HOST_EVENT_LOG_RELATIVE_PATH);
 }
 
-/** Append one memory host event, creating the dreams directory with symlink-safe writes. */
+/** Append one memory host event to shared SQLite plugin state. */
 export async function appendMemoryHostEvent(
   workspaceDir: string,
   event: MemoryHostEventRecord,
+  options: { env?: NodeJS.ProcessEnv } = {},
 ): Promise<void> {
-  const eventLogPath = resolveMemoryHostEventLogPath(workspaceDir);
-  await fs.mkdir(path.dirname(eventLogPath), { recursive: true });
-  await appendRegularFile({
-    filePath: eventLogPath,
-    content: `${JSON.stringify(event)}\n`,
-    rejectSymlinkParents: true,
+  registerMemoryHostEvent({
+    workspaceDir,
+    event,
+    ...(options.env ? { env: options.env } : {}),
   });
 }
 
-function parseMemoryHostEventRecord(line: string): MemoryHostEventRecord | null {
-  try {
-    const record = JSON.parse(line) as MemoryHostEventRecord;
-    if (
-      record.type === "memory.recall.recorded" ||
-      record.type === "memory.recall.skipped" ||
-      record.type === "memory.promotion.applied" ||
-      record.type === "memory.dream.completed"
-    ) {
-      return record;
-    }
-  } catch {
-    // The log is best-effort diagnostics; one malformed line must not hide
-    // later valid events or break memory status rendering.
-  }
-  return null;
-}
-
 async function readMemoryHostEventRecordsRaw(params: {
   workspaceDir: string;
   limit?: number;
+  env?: NodeJS.ProcessEnv;
 }): Promise<MemoryHostEventRecord[]> {
-  const eventLogPath = resolveMemoryHostEventLogPath(params.workspaceDir);
-  const raw = await fs.readFile(eventLogPath, "utf8").catch((err: unknown) => {
-    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
-      return "";
-    }
-    throw err;
-  });
-  if (!raw.trim()) {
-    return [];
-  }
-  const events = raw
-    .split("\n")
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .flatMap((line) => {
-      const record = parseMemoryHostEventRecord(line);
-      return record ? [record] : [];
-    });
-  if (!Number.isFinite(params.limit)) {
-    return events;
-  }
-  const limit = Math.max(0, Math.floor(params.limit as number));
-  return limit === 0 ? [] : events.slice(-limit);
+  const events = listStoredMemoryHostEvents(params).map((entry) => entry.value.event);
+  return applyMemoryHostEventLimit(events, params.limit);
 }
 
 function applyMemoryHostEventLimit<T>(events: T[], limit: number | undefined): T[] {
@@ -155,12 +57,16 @@ function applyMemoryHostEventLimit<T>(events: T[], limit: number | undefined): T
   return normalizedLimit === 0 ? [] : events.slice(-normalizedLimit);
 }
 
-/** Read recent memory host events, ignoring corrupt JSONL lines left by partial writes. */
+/** Read recent memory host events, excluding opt-in diagnostic variants. */
 export async function readMemoryHostEvents(params: {
   workspaceDir: string;
   limit?: number;
+  env?: NodeJS.ProcessEnv;
 }): Promise<MemoryHostEvent[]> {
-  const events = await readMemoryHostEventRecordsRaw({ workspaceDir: params.workspaceDir });
+  const events = await readMemoryHostEventRecordsRaw({
+    workspaceDir: params.workspaceDir,
+    ...(params.env ? { env: params.env } : {}),
+  });
   const legacyEvents = events.filter(
     (event): event is MemoryHostEvent => event.type !== "memory.recall.skipped",
   );
@@ -171,6 +77,7 @@ export async function readMemoryHostEvents(params: {
 export async function readMemoryHostEventRecords(params: {
   workspaceDir: string;
   limit?: number;
+  env?: NodeJS.ProcessEnv;
 }): Promise<MemoryHostEventRecord[]> {
   return await readMemoryHostEventRecordsRaw(params);
 }
diff --git a/src/plugin-sdk/memory-core-host-events.ts b/src/plugin-sdk/memory-core-host-events.ts
index 2effe90b472..8e1c48a6b72 100644
--- a/src/plugin-sdk/memory-core-host-events.ts
+++ b/src/plugin-sdk/memory-core-host-events.ts
@@ -3,4 +3,19 @@
  * `openclaw/plugin-sdk/memory-host-events` instead.
  */
 
-export * from "../memory-host-sdk/events.js";
+export {
+  appendMemoryHostEvent,
+  MEMORY_HOST_EVENT_LOG_RELATIVE_PATH,
+  readMemoryHostEventRecords,
+  readMemoryHostEvents,
+  resolveMemoryHostEventLogPath,
+} from "../memory-host-sdk/events.js";
+export type {
+  MemoryDreamOutcome,
+  MemoryHostDreamCompletedEvent,
+  MemoryHostEvent,
+  MemoryHostEventRecord,
+  MemoryHostPromotionAppliedEvent,
+  MemoryHostRecallRecordedEvent,
+  MemoryHostRecallSkippedEvent,
+} from "../memory-host-sdk/events.js";
diff --git a/src/plugin-sdk/memory-host-core.test.ts b/src/plugin-sdk/memory-host-core.test.ts
index 801b5239265..3ed306fbb92 100644
--- a/src/plugin-sdk/memory-host-core.test.ts
+++ b/src/plugin-sdk/memory-host-core.test.ts
@@ -1,10 +1,15 @@
 /**
  * Tests memory host core public artifact discovery and workspace handling.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createPluginStateKeyedStore,
+  resetPluginStateStoreForTests,
+} from "../plugin-state/plugin-state-store.js";
 import {
   clearMemoryPluginState,
   registerMemoryCapability,
@@ -16,11 +21,14 @@ import {
   listMemoryHostPublicArtifacts,
   listActiveMemoryPublicArtifacts,
 } from "./memory-host-core.js";
-import { appendMemoryHostEvent, resolveMemoryHostEventLogPath } from "./memory-host-events.js";
+import { appendMemoryHostEvent } from "./memory-host-events.js";
 
 describe("memory-host-core helpers", () => {
   afterEach(() => {
     clearMemoryPluginState();
+    resetPluginStateStoreForTests();
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
   });
 
   it("exposes the active memory prompt guidance builder for context engines", () => {
@@ -68,9 +76,429 @@ describe("memory-host-core helpers", () => {
     ]);
   });
 
+  it("propagates workspace inspection failures", async () => {
+    vi.spyOn(fs, "stat").mockRejectedValueOnce(
+      Object.assign(new Error("permission denied"), { code: "EACCES" }),
+    );
+
+    await expect(
+      listMemoryHostPublicArtifacts({
+        cfg: {
+          agents: {
+            list: [{ id: "main", default: true, workspace: "/protected/workspace" }],
+          },
+        },
+      }),
+    ).rejects.toMatchObject({ code: "EACCES" });
+  });
+
+  it("lists readable workspaces without requiring workspace-root writes", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-readonly-workspace-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", path.join(fixtureRoot, "state"));
+      await fs.mkdir(workspaceDir);
+      await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "# Read-only memory\n", "utf8");
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "read-only",
+        resultCount: 0,
+        results: [],
+      });
+      await fs.chmod(workspaceDir, 0o500);
+
+      await expect(
+        listMemoryHostPublicArtifacts({
+          cfg: {
+            agents: {
+              list: [{ id: "main", default: true, workspace: workspaceDir }],
+            },
+          },
+        }),
+      ).resolves.toMatchObject([
+        {
+          kind: "memory-root",
+          workspaceDir,
+          relativePath: "MEMORY.md",
+        },
+      ]);
+    } finally {
+      await fs.chmod(workspaceDir, 0o700).catch(() => undefined);
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "propagates failures reading an existing event export",
+    async () => {
+      const fixtureRoot = await fs.mkdtemp(
+        path.join(os.tmpdir(), "memory-host-unreadable-export-"),
+      );
+      const workspaceDir = path.join(fixtureRoot, "workspace");
+      let eventExportPath: string | undefined;
+      try {
+        vi.stubEnv("OPENCLAW_STATE_DIR", path.join(fixtureRoot, "state"));
+        await fs.mkdir(workspaceDir);
+        await appendMemoryHostEvent(workspaceDir, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:00:00.000Z",
+          query: "unreadable export",
+          resultCount: 0,
+          results: [],
+        });
+        const firstListing = await listMemoryHostPublicArtifacts({
+          cfg: {
+            agents: {
+              list: [{ id: "main", default: true, workspace: workspaceDir }],
+            },
+          },
+        });
+        eventExportPath = firstListing.find(
+          (artifact) => artifact.kind === "event-log",
+        )?.absolutePath;
+        if (!eventExportPath) {
+          throw new Error("expected memory event export");
+        }
+        await fs.chmod(eventExportPath, 0o000);
+
+        await expect(
+          listMemoryHostPublicArtifacts({
+            cfg: {
+              agents: {
+                list: [{ id: "main", default: true, workspace: workspaceDir }],
+              },
+            },
+          }),
+        ).rejects.toThrow();
+      } finally {
+        if (eventExportPath) {
+          await fs.chmod(eventExportPath, 0o600).catch(() => undefined);
+        }
+        await fs.rm(fixtureRoot, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it.runIf(process.platform !== "win32")(
+    "does not delete an event export through a symlinked parent",
+    async () => {
+      const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-symlink-"));
+      const workspaceDir = path.join(fixtureRoot, "workspace");
+      const externalMemoryDir = path.join(fixtureRoot, "external-memory");
+      const stateDir = path.join(fixtureRoot, "state");
+      try {
+        vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+        await fs.mkdir(workspaceDir);
+        await fs.mkdir(stateDir);
+        const stateHash = createHash("sha256")
+          .update(await fs.realpath(stateDir))
+          .digest("hex")
+          .slice(0, 32);
+        const externalExport = path.join(
+          externalMemoryDir,
+          "events",
+          stateHash,
+          "memory-host-events.jsonl",
+        );
+        const externalOwner = path.join(
+          path.dirname(externalExport),
+          ".openclaw-memory-host-events-owner.json",
+        );
+        await fs.mkdir(path.dirname(externalExport), { recursive: true });
+        await fs.writeFile(externalExport, '{"type":"external"}\n', "utf8");
+        await fs.writeFile(externalOwner, '{"kind":"external"}\n', "utf8");
+        await fs.symlink(externalMemoryDir, path.join(workspaceDir, "memory"));
+
+        await expect(
+          listMemoryHostPublicArtifacts({
+            cfg: {
+              agents: {
+                list: [{ id: "main", default: true, workspace: workspaceDir }],
+              },
+            },
+          }),
+        ).resolves.toEqual([]);
+        await expect(fs.readFile(externalExport, "utf8")).resolves.toBe('{"type":"external"}\n');
+        await expect(fs.readFile(externalOwner, "utf8")).resolves.toBe('{"kind":"external"}\n');
+      } finally {
+        await fs.rm(fixtureRoot, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it("does not replace or delete an unowned event export path", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-unowned-export-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir);
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "must not replace user file",
+        resultCount: 0,
+        results: [],
+      });
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(fixtureRoot))
+        .digest("hex")
+        .slice(0, 32);
+      const exportPath = path.join(
+        workspaceDir,
+        "memory",
+        "events",
+        stateHash,
+        "memory-host-events.jsonl",
+      );
+      await fs.mkdir(path.dirname(exportPath), { recursive: true });
+      await fs.writeFile(exportPath, '{"owner":"user"}\n', "utf8");
+
+      const listed = await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+      expect(listed.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe('{"owner":"user"}\n');
+
+      await createPluginStateKeyedStore("memory-core", {
+        namespace: "memory-host.events",
+        maxEntries: 10_000,
+        env: { ...process.env, OPENCLAW_STATE_DIR: fixtureRoot },
+      }).clear();
+      await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe('{"owner":"user"}\n');
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not let an orphaned owner marker authorize a later workspace file", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-orphan-owner-"));
+    const stateDir = path.join(fixtureRoot, "state");
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+      await fs.mkdir(workspaceDir);
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "expected export",
+        resultCount: 0,
+        results: [],
+      });
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(stateDir))
+        .digest("hex")
+        .slice(0, 32);
+      const workspaceHash = createHash("sha256")
+        .update(await fs.realpath(workspaceDir))
+        .digest("hex")
+        .slice(0, 32);
+      const exportDir = path.join(workspaceDir, "memory", "events", stateHash);
+      const exportPath = path.join(exportDir, "memory-host-events.jsonl");
+      const ownerPath = path.join(exportDir, ".openclaw-memory-host-events-owner.json");
+      const expectedContent = `${JSON.stringify({
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "expected export",
+        resultCount: 0,
+        results: [],
+      })}\n`;
+      await fs.mkdir(exportDir, { recursive: true });
+      await fs.writeFile(
+        ownerPath,
+        `${JSON.stringify({
+          schemaVersion: 3,
+          kind: "openclaw-memory-host-events-export",
+          stateHash,
+          workspaceHash,
+          pendingContentSha256: createHash("sha256").update(expectedContent).digest("hex"),
+        })}\n`,
+        "utf8",
+      );
+      await fs.writeFile(exportPath, '{"owner":"user after crash"}\n', "utf8");
+
+      const listed = await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+
+      expect(listed.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe('{"owner":"user after crash"}\n');
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not claim a same-content inode that replaces an exclusive export", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-create-replace-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    const event = {
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-05-18T12:00:00.000Z",
+      query: "exclusive create",
+      resultCount: 0,
+      results: [],
+    };
+    const expectedContent = `${JSON.stringify(event)}\n`;
+    const originalOpen = fs.open.bind(fs);
+    let exportOpenCount = 0;
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir, { recursive: true });
+      await appendMemoryHostEvent(workspaceDir, event);
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(fixtureRoot))
+        .digest("hex")
+        .slice(0, 32);
+      const exportPath = path.join(
+        workspaceDir,
+        "memory",
+        "events",
+        stateHash,
+        "memory-host-events.jsonl",
+      );
+      vi.spyOn(fs, "open").mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+        const target = args[0];
+        if (typeof target === "string" && path.resolve(target) === path.resolve(exportPath)) {
+          exportOpenCount += 1;
+          if (exportOpenCount === 4) {
+            await fs.rename(exportPath, `${exportPath}.openclaw-created`);
+            const replacement = await originalOpen(exportPath, "wx", 0o600);
+            try {
+              await replacement.writeFile(expectedContent, "utf8");
+            } finally {
+              await replacement.close();
+            }
+          }
+        }
+        return await originalOpen(...args);
+      });
+
+      const racedArtifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(racedArtifacts.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe(expectedContent);
+
+      vi.restoreAllMocks();
+      await appendMemoryHostEvent(workspaceDir, { ...event, query: "must stay foreign" });
+      const retriedArtifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(retriedArtifacts.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe(expectedContent);
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not claim a hash-only pending event export after interruption", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-pending-owner-"));
+    const stateDir = path.join(fixtureRoot, "state");
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const firstEvent = {
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-05-18T12:00:00.000Z",
+      query: "pending export",
+      resultCount: 0,
+      results: [],
+    };
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+      await fs.mkdir(workspaceDir);
+      await appendMemoryHostEvent(workspaceDir, firstEvent);
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(stateDir))
+        .digest("hex")
+        .slice(0, 32);
+      const workspaceHash = createHash("sha256")
+        .update(await fs.realpath(workspaceDir))
+        .digest("hex")
+        .slice(0, 32);
+      const exportDir = path.join(workspaceDir, "memory", "events", stateHash);
+      const exportPath = path.join(exportDir, "memory-host-events.jsonl");
+      const ownerPath = path.join(exportDir, ".openclaw-memory-host-events-owner.json");
+      const pendingContent = `${JSON.stringify(firstEvent)}\n`;
+      await fs.mkdir(exportDir, { recursive: true });
+      await fs.writeFile(exportPath, pendingContent, "utf8");
+      await fs.writeFile(
+        ownerPath,
+        `${JSON.stringify({
+          schemaVersion: 3,
+          kind: "openclaw-memory-host-events-export",
+          stateHash,
+          workspaceHash,
+          pendingContentSha256: createHash("sha256").update(pendingContent).digest("hex"),
+        })}\n`,
+        "utf8",
+      );
+      await appendMemoryHostEvent(workspaceDir, {
+        ...firstEvent,
+        timestamp: "2026-05-18T12:01:00.000Z",
+        query: "after interruption",
+      });
+
+      const listed = await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+
+      expect(listed.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe(pendingContent);
+      const owner = JSON.parse(await fs.readFile(ownerPath, "utf8")) as {
+        contentSha256?: string;
+        fileDev?: string;
+        fileIno?: string;
+        pendingContentSha256?: string;
+      };
+      expect(owner.pendingContentSha256).toBe(
+        createHash("sha256")
+          .update(await fs.readFile(exportPath))
+          .digest("hex"),
+      );
+      expect(owner.contentSha256).toBeUndefined();
+      expect(owner.fileDev).toBeUndefined();
+      expect(owner.fileIno).toBeUndefined();
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("omits the event export when a workspace path component is a file", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-blocked-export-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", path.join(fixtureRoot, "state"));
+      await fs.mkdir(workspaceDir);
+      await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "# Still visible\n", "utf8");
+      await fs.writeFile(path.join(workspaceDir, "memory"), "user file\n", "utf8");
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "blocked export",
+        resultCount: 0,
+        results: [],
+      });
+
+      await expect(
+        listMemoryHostPublicArtifacts({
+          cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+        }),
+      ).resolves.toEqual([
+        expect.objectContaining({ kind: "memory-root", relativePath: "MEMORY.md" }),
+      ]);
+      await expect(fs.readFile(path.join(workspaceDir, "memory"), "utf8")).resolves.toBe(
+        "user file\n",
+      );
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
   it("lists shared public artifacts from memory workspaces", async () => {
     const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-public-artifacts-"));
     try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
       const workspaceDir = path.join(fixtureRoot, "workspace");
       await fs.mkdir(path.join(workspaceDir, "memory", "dreaming"), { recursive: true });
       await fs.writeFile(path.join(workspaceDir, "MEMORY.md"), "# Durable Memory\n", "utf8");
@@ -84,6 +512,8 @@ describe("memory-host-core helpers", () => {
         "# Dream Report\n",
         "utf8",
       );
+      const eventStoredAt = Date.parse("2026-05-19T09:30:00.000Z");
+      vi.spyOn(Date, "now").mockReturnValue(eventStoredAt);
       await appendMemoryHostEvent(workspaceDir, {
         type: "memory.recall.recorded",
         timestamp: "2026-05-18T12:00:00.000Z",
@@ -92,15 +522,18 @@ describe("memory-host-core helpers", () => {
         results: [],
       });
 
-      await expect(
-        listMemoryHostPublicArtifacts({
-          cfg: {
-            agents: {
-              list: [{ id: "main", default: true, workspace: workspaceDir }],
-            },
+      const artifacts = await listMemoryHostPublicArtifacts({
+        cfg: {
+          agents: {
+            list: [{ id: "main", default: true, workspace: workspaceDir }],
           },
-        }),
-      ).resolves.toEqual([
+        },
+      });
+      const eventArtifact = artifacts.find((artifact) => artifact.kind === "event-log");
+      if (!eventArtifact) {
+        throw new Error("expected memory event export");
+      }
+      expect(artifacts.filter((artifact) => artifact.kind !== "event-log")).toEqual([
         {
           kind: "memory-root",
           workspaceDir,
@@ -125,15 +558,437 @@ describe("memory-host-core helpers", () => {
           agentIds: ["main"],
           contentType: "markdown",
         },
-        {
-          kind: "event-log",
-          workspaceDir,
-          relativePath: "memory/.dreams/events.jsonl",
-          absolutePath: resolveMemoryHostEventLogPath(workspaceDir),
-          agentIds: ["main"],
-          contentType: "json",
-        },
       ]);
+      expect(eventArtifact).toMatchObject({
+        kind: "event-log",
+        workspaceDir,
+        agentIds: ["main"],
+        contentType: "json",
+      });
+      expect(eventArtifact.relativePath).toMatch(
+        /^memory\/events\/[a-f0-9]{32}\/memory-host-events\.jsonl$/u,
+      );
+      expect(eventArtifact.absolutePath).toBe(
+        path.join(workspaceDir, ...eventArtifact.relativePath.split("/")),
+      );
+      const eventExportPath = eventArtifact.absolutePath;
+      await expect(fs.readFile(eventExportPath, "utf8")).resolves.toBe(
+        `${JSON.stringify({
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:00:00.000Z",
+          query: "bridge",
+          resultCount: 0,
+          results: [],
+        })}\n`,
+      );
+      const exportStat = await fs.stat(eventExportPath);
+      const exportOwner = JSON.parse(
+        await fs.readFile(
+          path.join(path.dirname(eventExportPath), ".openclaw-memory-host-events-owner.json"),
+          "utf8",
+        ),
+      ) as { fileDev?: string; fileIno?: string };
+      expect(exportOwner.fileDev).toBe(String(exportStat.dev));
+      expect(exportOwner.fileIno).toBe(String(exportStat.ino));
+      await expect(
+        fs.access(path.join(workspaceDir, ".memory-host-events-export.lock")),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+      expect(
+        (await fs.readdir(fixtureRoot)).some((entry) =>
+          entry.startsWith(".memory-host-events-export-"),
+        ),
+      ).toBe(false);
+
+      await createPluginStateKeyedStore("memory-core", {
+        namespace: "memory-host.events",
+        maxEntries: 10_000,
+        env: { ...process.env, OPENCLAW_STATE_DIR: fixtureRoot },
+      }).clear();
+      const afterRetention = await listMemoryHostPublicArtifacts({
+        cfg: {
+          agents: {
+            list: [{ id: "main", default: true, workspace: workspaceDir }],
+          },
+        },
+      });
+      expect(afterRetention.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(eventExportPath, "utf8")).resolves.toBe("");
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "does not let a workspace alias overwrite a newer event export",
+    async () => {
+      const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-race-"));
+      const workspaceDir = path.join(fixtureRoot, "workspace");
+      const workspaceAlias = path.join(fixtureRoot, "workspace-alias");
+      const cfg = {
+        agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+      };
+      const aliasCfg = {
+        agents: { list: [{ id: "main", default: true, workspace: workspaceAlias }] },
+      };
+      const originalOpen = fs.open.bind(fs);
+      let releaseFirstRead: (() => void) | undefined;
+      let signalFirstRead: (() => void) | undefined;
+      let shouldBlockFirstRead = true;
+      const firstReadStarted = new Promise<void>((resolve) => {
+        signalFirstRead = resolve;
+      });
+      const openSpy = vi
+        .spyOn(fs, "open")
+        .mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+          const target = args[0];
+          if (
+            shouldBlockFirstRead &&
+            typeof target === "string" &&
+            path.basename(target) === "memory-host-events.jsonl" &&
+            path.resolve(target).startsWith(`${path.resolve(workspaceDir)}${path.sep}`)
+          ) {
+            shouldBlockFirstRead = false;
+            signalFirstRead?.();
+            await new Promise<void>((resolve) => {
+              releaseFirstRead = resolve;
+            });
+          }
+          return await originalOpen(...args);
+        });
+
+      try {
+        vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+        await fs.mkdir(workspaceDir, { recursive: true });
+        await fs.symlink(workspaceDir, workspaceAlias);
+        await appendMemoryHostEvent(workspaceAlias, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:00:00.000Z",
+          query: "older",
+          resultCount: 0,
+          results: [],
+        });
+        const olderListing = listMemoryHostPublicArtifacts({ cfg });
+        await firstReadStarted;
+
+        await appendMemoryHostEvent(workspaceDir, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:01:00.000Z",
+          query: "newer",
+          resultCount: 0,
+          results: [],
+        });
+        const newerListing = listMemoryHostPublicArtifacts({ cfg: aliasCfg });
+        await Promise.race([
+          newerListing,
+          new Promise<void>((resolve) => {
+            setTimeout(resolve, 250);
+          }),
+        ]);
+        releaseFirstRead?.();
+        const [olderArtifacts, newerArtifacts] = await Promise.all([olderListing, newerListing]);
+        const olderExport = olderArtifacts.find((artifact) => artifact.kind === "event-log");
+        const newerExport = newerArtifacts.find((artifact) => artifact.kind === "event-log");
+        expect(olderExport?.absolutePath).toBe(newerExport?.absolutePath);
+        const eventExportPath = newerExport?.absolutePath;
+        if (!eventExportPath) {
+          throw new Error("expected memory event export");
+        }
+
+        const exported = (await fs.readFile(eventExportPath, "utf8"))
+          .trim()
+          .split("\n")
+          .map((line) => JSON.parse(line) as { query: string });
+        expect(exported.map((event) => event.query)).toEqual(["older", "newer"]);
+      } finally {
+        releaseFirstRead?.();
+        openSpy.mockRestore();
+        await fs.rm(fixtureRoot, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it.each([
+    { name: "refresh", clearEvents: false },
+    { name: "retirement", clearEvents: true },
+  ])("preserves a replacement installed during event export $name", async ({ clearEvents }) => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-replace-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    const replacement = '{"owner":"workspace"}\n';
+    const originalOpen = fs.open.bind(fs);
+    let exportOpenCount = 0;
+    let eventExportPath: string | undefined;
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir, { recursive: true });
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "first",
+        resultCount: 0,
+        results: [],
+      });
+      eventExportPath = (await listMemoryHostPublicArtifacts({ cfg })).find(
+        (artifact) => artifact.kind === "event-log",
+      )?.absolutePath;
+      if (!eventExportPath) {
+        throw new Error("expected memory event export");
+      }
+      if (clearEvents) {
+        await createPluginStateKeyedStore("memory-core", {
+          namespace: "memory-host.events",
+          maxEntries: 10_000,
+          env: { ...process.env, OPENCLAW_STATE_DIR: fixtureRoot },
+        }).clear();
+      } else {
+        await appendMemoryHostEvent(workspaceDir, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:01:00.000Z",
+          query: "second",
+          resultCount: 0,
+          results: [],
+        });
+      }
+
+      const expectedExportPath = path.resolve(eventExportPath);
+      vi.spyOn(fs, "open").mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+        const target = args[0];
+        if (typeof target === "string" && path.resolve(target) === expectedExportPath) {
+          exportOpenCount += 1;
+          if (exportOpenCount === 2) {
+            await fs.rename(expectedExportPath, `${expectedExportPath}.openclaw-owned`);
+            await fs.writeFile(expectedExportPath, replacement, "utf8");
+          }
+        }
+        return await originalOpen(...args);
+      });
+
+      const artifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(artifacts.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(expectedExportPath, "utf8")).resolves.toBe(replacement);
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    { name: "refresh", clearEvents: false },
+    { name: "retirement", clearEvents: true },
+  ])("keeps ownership through same-inode event export $name", async ({ clearEvents }) => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-inode-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    const originalOpen = fs.open.bind(fs);
+    let exportOpenCount = 0;
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir, { recursive: true });
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "first",
+        resultCount: 0,
+        results: [],
+      });
+      const eventExportPath = (await listMemoryHostPublicArtifacts({ cfg })).find(
+        (artifact) => artifact.kind === "event-log",
+      )?.absolutePath;
+      if (!eventExportPath) {
+        throw new Error("expected memory event export");
+      }
+      if (clearEvents) {
+        await createPluginStateKeyedStore("memory-core", {
+          namespace: "memory-host.events",
+          maxEntries: 10_000,
+          env: { ...process.env, OPENCLAW_STATE_DIR: fixtureRoot },
+        }).clear();
+      } else {
+        await appendMemoryHostEvent(workspaceDir, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:01:00.000Z",
+          query: "second",
+          resultCount: 0,
+          results: [],
+        });
+      }
+
+      const expectedExportPath = path.resolve(eventExportPath);
+      const originalStat = await fs.stat(expectedExportPath);
+      vi.spyOn(fs, "open").mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+        const target = args[0];
+        if (typeof target === "string" && path.resolve(target) === expectedExportPath) {
+          exportOpenCount += 1;
+          if (exportOpenCount === 2) {
+            const writer = await originalOpen(expectedExportPath, "w");
+            try {
+              await writer.writeFile('{"owner":"same inode"}\n', "utf8");
+            } finally {
+              await writer.close();
+            }
+          }
+        }
+        return await originalOpen(...args);
+      });
+
+      const artifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect((await fs.stat(expectedExportPath)).ino).toBe(originalStat.ino);
+      if (clearEvents) {
+        expect(artifacts.some((artifact) => artifact.kind === "event-log")).toBe(false);
+        await expect(fs.readFile(expectedExportPath, "utf8")).resolves.toBe("");
+      } else {
+        expect(artifacts.some((artifact) => artifact.kind === "event-log")).toBe(true);
+        await expect(fs.readFile(expectedExportPath, "utf8")).resolves.toContain("second");
+      }
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("retries an owned event export after a same-inode post-write race", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-retry-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    const originalOpen = fs.open.bind(fs);
+    let exportOpenCount = 0;
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir, { recursive: true });
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "first",
+        resultCount: 0,
+        results: [],
+      });
+      const eventExportPath = (await listMemoryHostPublicArtifacts({ cfg })).find(
+        (artifact) => artifact.kind === "event-log",
+      )?.absolutePath;
+      if (!eventExportPath) {
+        throw new Error("expected memory event export");
+      }
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:01:00.000Z",
+        query: "second",
+        resultCount: 0,
+        results: [],
+      });
+
+      const expectedExportPath = path.resolve(eventExportPath);
+      const openSpy = vi
+        .spyOn(fs, "open")
+        .mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+          const target = args[0];
+          if (typeof target === "string" && path.resolve(target) === expectedExportPath) {
+            exportOpenCount += 1;
+            if (exportOpenCount === 4) {
+              const writer = await originalOpen(expectedExportPath, "w");
+              try {
+                await writer.writeFile('{"owner":"post-write race"}\n', "utf8");
+              } finally {
+                await writer.close();
+              }
+            }
+          }
+          return await originalOpen(...args);
+        });
+
+      const racedArtifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(racedArtifacts.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      openSpy.mockRestore();
+
+      const retriedArtifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(retriedArtifacts.some((artifact) => artifact.kind === "event-log")).toBe(true);
+      await expect(fs.readFile(expectedExportPath, "utf8")).resolves.toContain("second");
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("repairs an oversized owned event export by inode", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-oversized-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", fixtureRoot);
+      await fs.mkdir(workspaceDir, { recursive: true });
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:00:00.000Z",
+        query: "first",
+        resultCount: 0,
+        results: [],
+      });
+      const eventExportPath = (await listMemoryHostPublicArtifacts({ cfg })).find(
+        (artifact) => artifact.kind === "event-log",
+      )?.absolutePath;
+      if (!eventExportPath) {
+        throw new Error("expected memory event export");
+      }
+      const originalStat = await fs.stat(eventExportPath);
+      await fs.appendFile(eventExportPath, "x".repeat(1024 * 1024 + 1), "utf8");
+      await appendMemoryHostEvent(workspaceDir, {
+        type: "memory.recall.recorded",
+        timestamp: "2026-05-18T12:01:00.000Z",
+        query: "second",
+        resultCount: 0,
+        results: [],
+      });
+
+      const artifacts = await listMemoryHostPublicArtifacts({ cfg });
+      expect(artifacts.some((artifact) => artifact.kind === "event-log")).toBe(true);
+      expect((await fs.stat(eventExportPath)).ino).toBe(originalStat.ino);
+      expect((await fs.stat(eventExportPath)).size).toBeLessThan(1024 * 1024);
+      await expect(fs.readFile(eventExportPath, "utf8")).resolves.toContain("second");
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps public event exports isolated across state directories", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-export-owner-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const cfg = {
+      agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] },
+    };
+    try {
+      await fs.mkdir(workspaceDir, { recursive: true });
+
+      const exports: string[] = [];
+      for (const profile of ["profile-a", "profile-b"]) {
+        vi.stubEnv("OPENCLAW_STATE_DIR", path.join(fixtureRoot, profile));
+        await appendMemoryHostEvent(workspaceDir, {
+          type: "memory.recall.recorded",
+          timestamp: "2026-05-18T12:00:00.000Z",
+          query: profile,
+          resultCount: 0,
+          results: [],
+        });
+        const artifact = (await listMemoryHostPublicArtifacts({ cfg })).find(
+          (candidate) => candidate.kind === "event-log",
+        );
+        if (!artifact) {
+          throw new Error("expected memory event export");
+        }
+        exports.push(artifact.absolutePath);
+        await expect(fs.readFile(artifact.absolutePath, "utf8")).resolves.toContain(profile);
+      }
+
+      expect(new Set(exports).size).toBe(2);
+      const [profileAExport, profileBExport] = exports;
+      if (!profileAExport || !profileBExport) {
+        throw new Error("expected state-qualified memory event exports");
+      }
+      await expect(fs.readFile(profileAExport, "utf8")).resolves.toContain("profile-a");
+      await expect(fs.readFile(profileBExport, "utf8")).resolves.toContain("profile-b");
     } finally {
       await fs.rm(fixtureRoot, { recursive: true, force: true });
     }
diff --git a/src/plugin-sdk/memory-host-core.ts b/src/plugin-sdk/memory-host-core.ts
index 632989c0c64..1fa94858ce1 100644
--- a/src/plugin-sdk/memory-host-core.ts
+++ b/src/plugin-sdk/memory-host-core.ts
@@ -4,9 +4,208 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
+import { resolveStateDir } from "../config/paths.js";
+import { sha256Hex, sha256HexPrefix } from "../infra/crypto-digest.js";
+import { withFileLock } from "../infra/file-lock.js";
+import { sameFileIdentity, type FileIdentityStat } from "../infra/fs-safe-advanced.js";
+import { FsSafeError, root as createFsSafeRoot } from "../infra/fs-safe.js";
+import { syncDirectoryBestEffort } from "../infra/sqlite-snapshot.js";
+import {
+  MAX_MEMORY_HOST_PUBLIC_EXPORT_BYTES,
+  serializeMemoryHostEventExport,
+} from "../memory-host-sdk/event-export.js";
+import { listStoredMemoryHostEvents } from "../memory-host-sdk/event-store.js";
 import type { MemoryPluginPublicArtifact } from "../plugins/memory-state.js";
+import { KeyedAsyncQueue } from "./keyed-async-queue.js";
 import { resolveMemoryDreamingWorkspaces } from "./memory-core-host-status.js";
-import { resolveMemoryHostEventLogPath } from "./memory-host-events.js";
+import {
+  isMemoryHostEventArtifactAtIdentity,
+  isMissingPathError,
+  isRejectedWorkspaceArtifactPath,
+  memoryHostEventExportOwnerContent,
+  publishMemoryHostEventArtifact,
+  rewriteMemoryHostEventArtifactIfUnchanged,
+} from "./memory-host-event-export.js";
+
+const MEMORY_HOST_EVENTS_FILENAME = "memory-host-events.jsonl";
+const MEMORY_HOST_EVENTS_OWNER_FILENAME = ".openclaw-memory-host-events-owner.json";
+const MAX_MEMORY_HOST_PUBLIC_EXPORT_EVENTS = 1_000;
+const MEMORY_HOST_EVENT_EXPORT_LOCK_OPTIONS = {
+  retries: { retries: 20, factor: 1.3, minTimeout: 25, maxTimeout: 250, randomize: true },
+  stale: 30_000,
+} as const;
+const memoryHostEventExportQueue = new KeyedAsyncQueue();
+
+function isWorkspaceWriteUnavailable(error: unknown, seen = new Set<unknown>()): boolean {
+  if (!error || typeof error !== "object" || seen.has(error)) {
+    return false;
+  }
+  seen.add(error);
+  const code = (error as { code?: unknown }).code;
+  if (
+    code === "EACCES" ||
+    code === "EEXIST" ||
+    code === "ENOTDIR" ||
+    code === "EPERM" ||
+    code === "EROFS" ||
+    (error instanceof FsSafeError && (code === "not-file" || code === "not-removable"))
+  ) {
+    return true;
+  }
+  if (error instanceof FsSafeError && error.category === "policy" && code !== "invalid-path") {
+    return false;
+  }
+  return isWorkspaceWriteUnavailable((error as { cause?: unknown }).cause, seen);
+}
+
+async function resolveMemoryHostEventExportOwner(workspaceDir: string): Promise<{
+  queueKey: string;
+  lockTarget: string;
+  relativePath: string;
+  ownerRelativePath: string;
+  stateHash: string;
+  workspaceHash: string;
+}> {
+  const requestedStateDir = path.resolve(resolveStateDir());
+  await fs.mkdir(requestedStateDir, { recursive: true, mode: 0o700 });
+  const stateDir = await fs.realpath(requestedStateDir);
+  const stateHash = sha256HexPrefix(stateDir, 32);
+  const workspaceHash = sha256HexPrefix(path.resolve(workspaceDir), 32);
+  const exportDirectory = path.posix.join("memory", "events", stateHash);
+  return {
+    queueKey: `${stateHash}\0${workspaceHash}`,
+    lockTarget: path.join(stateDir, `.memory-host-events-export-${workspaceHash}`),
+    relativePath: path.posix.join(exportDirectory, MEMORY_HOST_EVENTS_FILENAME),
+    ownerRelativePath: path.posix.join(exportDirectory, MEMORY_HOST_EVENTS_OWNER_FILENAME),
+    stateHash,
+    workspaceHash,
+  };
+}
+
+async function readMemoryHostEventExportOwnership(
+  workspaceRoot: Awaited<ReturnType<typeof createFsSafeRoot>>,
+  owner: Awaited<ReturnType<typeof resolveMemoryHostEventExportOwner>>,
+): Promise<
+  | {
+      kind: "owned";
+      content: string | undefined;
+      identity: FileIdentityStat;
+      ownerContent: string;
+      needsFinalize: boolean;
+    }
+  | { kind: "missing" }
+  | { kind: "orphan"; ownerContent: string }
+  | { kind: "pending-missing"; ownerContent: string }
+  | { kind: "foreign" }
+> {
+  const content = await workspaceRoot.readText(owner.ownerRelativePath).catch((error: unknown) => {
+    if (isMissingPathError(error)) {
+      return undefined;
+    }
+    if (isRejectedWorkspaceArtifactPath(error)) {
+      return null;
+    }
+    throw error;
+  });
+  if (content === null) {
+    return { kind: "foreign" };
+  }
+  if (content === undefined) {
+    return { kind: "missing" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content) as unknown;
+  } catch {
+    return { kind: "foreign" };
+  }
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed) ||
+    (parsed as { schemaVersion?: unknown }).schemaVersion !== 3 ||
+    (parsed as { kind?: unknown }).kind !== "openclaw-memory-host-events-export" ||
+    (parsed as { stateHash?: unknown }).stateHash !== owner.stateHash ||
+    (parsed as { workspaceHash?: unknown }).workspaceHash !== owner.workspaceHash ||
+    ((parsed as { contentSha256?: unknown }).contentSha256 !== undefined &&
+      typeof (parsed as { contentSha256?: unknown }).contentSha256 !== "string") ||
+    ((parsed as { pendingContentSha256?: unknown }).pendingContentSha256 !== undefined &&
+      typeof (parsed as { pendingContentSha256?: unknown }).pendingContentSha256 !== "string") ||
+    ((parsed as { contentSha256?: unknown }).contentSha256 === undefined &&
+      (parsed as { pendingContentSha256?: unknown }).pendingContentSha256 === undefined) ||
+    ((parsed as { fileDev?: unknown }).fileDev === undefined) !==
+      ((parsed as { fileIno?: unknown }).fileIno === undefined) ||
+    ((parsed as { fileDev?: unknown }).fileDev !== undefined &&
+      (typeof (parsed as { fileDev?: unknown }).fileDev !== "string" ||
+        !/^\d+$/u.test((parsed as { fileDev: string }).fileDev) ||
+        typeof (parsed as { fileIno?: unknown }).fileIno !== "string" ||
+        !/^\d+$/u.test((parsed as { fileIno: string }).fileIno)))
+  ) {
+    return { kind: "foreign" };
+  }
+  const storedIdentity =
+    typeof (parsed as { fileDev?: unknown }).fileDev === "string" &&
+    typeof (parsed as { fileIno?: unknown }).fileIno === "string"
+      ? {
+          dev: BigInt((parsed as { fileDev: string }).fileDev),
+          ino: BigInt((parsed as { fileIno: string }).fileIno),
+        }
+      : undefined;
+  let openedExport: Awaited<ReturnType<typeof workspaceRoot.open>> | undefined;
+  try {
+    openedExport = await workspaceRoot.open(owner.relativePath);
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      openedExport = undefined;
+    } else if (isRejectedWorkspaceArtifactPath(error)) {
+      return { kind: "foreign" };
+    } else {
+      throw error;
+    }
+  }
+  if (!openedExport) {
+    return typeof (parsed as { pendingContentSha256?: unknown }).pendingContentSha256 === "string"
+      ? { kind: "pending-missing", ownerContent: content }
+      : { kind: "orphan", ownerContent: content };
+  }
+  let exportContent: string;
+  const exportIdentity: FileIdentityStat = {
+    dev: openedExport.stat.dev,
+    ino: openedExport.stat.ino,
+  };
+  const identityOwned =
+    storedIdentity !== undefined && sameFileIdentity(storedIdentity, exportIdentity);
+  try {
+    if (openedExport.stat.size > MAX_MEMORY_HOST_PUBLIC_EXPORT_BYTES) {
+      return identityOwned
+        ? {
+            kind: "owned",
+            content: undefined,
+            identity: exportIdentity,
+            ownerContent: content,
+            needsFinalize: true,
+          }
+        : { kind: "foreign" };
+    }
+    exportContent = await openedExport.handle.readFile({ encoding: "utf8" });
+  } finally {
+    await openedExport.handle.close().catch(() => undefined);
+  }
+  const exportSha256 = sha256Hex(exportContent);
+  const currentSha256 = (parsed as { contentSha256?: string }).contentSha256;
+  const pendingSha256 = (parsed as { pendingContentSha256?: string }).pendingContentSha256;
+  // Hash-only markers never reach the owned branch; only the persisted inode
+  // identity authorizes later mutation of this workspace artifact.
+  return identityOwned
+    ? {
+        kind: "owned",
+        content: exportContent,
+        identity: exportIdentity,
+        ownerContent: content,
+        needsFinalize: exportSha256 !== currentSha256 || pendingSha256 !== undefined,
+      }
+    : { kind: "foreign" };
+}
 
 export {
   buildMemoryPromptSection as buildActiveMemoryPromptSection,
@@ -25,15 +224,6 @@ export { resolveDefaultAgentId } from "../agents/agent-scope-config.js";
 export { resolveSessionAgentId } from "../agents/agent-scope.js";
 export { resolveSessionTranscriptsDirForAgent } from "../config/sessions/paths.js";
 
-async function pathExists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function listMarkdownFilesRecursive(rootDir: string): Promise<string[]> {
   const entries = await fs.readdir(rootDir, { withFileTypes: true }).catch(() => []);
   const files: string[] = [];
@@ -50,6 +240,215 @@ async function listMarkdownFilesRecursive(rootDir: string): Promise<string[]> {
   return files.toSorted((left, right) => left.localeCompare(right));
 }
 
+async function materializeMemoryHostEventExport(params: {
+  workspaceDir: string;
+}): Promise<{ absolutePath: string; relativePath: string } | undefined> {
+  const requestedWorkspace = path.resolve(params.workspaceDir);
+  const workspace = await fs.stat(requestedWorkspace).catch((error: unknown) => {
+    if (isMissingPathError(error)) {
+      return undefined;
+    }
+    throw error;
+  });
+  if (!workspace?.isDirectory()) {
+    return undefined;
+  }
+  const workspaceRoot = await createFsSafeRoot(requestedWorkspace, {
+    hardlinks: "reject",
+    mkdir: true,
+    mode: 0o600,
+    symlinks: "reject",
+  });
+  const workspaceKey = workspaceRoot.rootReal;
+  const owner = await resolveMemoryHostEventExportOwner(workspaceKey);
+  // The queue handles re-entrant calls in this process; the sidecar lock makes
+  // snapshot, cleanup, and replacement one ordered operation across processes.
+  // State-qualified paths keep different profiles from replacing each other's export.
+  return memoryHostEventExportQueue.enqueue(owner.queueKey, async () => {
+    const absolutePath = path.join(workspaceKey, ...owner.relativePath.split("/"));
+    return await withFileLock(owner.lockTarget, MEMORY_HOST_EVENT_EXPORT_LOCK_OPTIONS, async () => {
+      const storedEvents = listStoredMemoryHostEvents({
+        workspaceDir: workspaceKey,
+        limit: MAX_MEMORY_HOST_PUBLIC_EXPORT_EVENTS,
+      });
+      const ownership = await readMemoryHostEventExportOwnership(workspaceRoot, owner);
+      if (ownership.kind === "foreign") {
+        return undefined;
+      }
+      if (storedEvents.length === 0 && ownership.kind !== "owned") {
+        return undefined;
+      }
+      const content = storedEvents.length > 0 ? serializeMemoryHostEventExport(storedEvents) : "";
+      const contentSha256 = sha256Hex(content);
+      let publishedIdentity: FileIdentityStat | undefined;
+      if (ownership.kind === "missing") {
+        const existing = await workspaceRoot
+          .readText(owner.relativePath)
+          .catch((error: unknown) => {
+            if (isMissingPathError(error)) {
+              return undefined;
+            }
+            if (isRejectedWorkspaceArtifactPath(error)) {
+              return null;
+            }
+            throw error;
+          });
+        if (existing !== undefined) {
+          return undefined;
+        }
+        try {
+          const pendingOwnerContent = memoryHostEventExportOwnerContent(owner, {
+            pendingSha256: contentSha256,
+          });
+          await workspaceRoot.create(owner.ownerRelativePath, pendingOwnerContent, {
+            mkdir: true,
+            mode: 0o600,
+          });
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+          publishedIdentity = await publishMemoryHostEventArtifact({
+            workspaceRoot,
+            owner,
+            absolutePath,
+            expectedOwnerContent: pendingOwnerContent,
+            content,
+            contentSha256,
+          });
+          if (!publishedIdentity) {
+            return undefined;
+          }
+        } catch (error) {
+          if (isWorkspaceWriteUnavailable(error)) {
+            return undefined;
+          }
+          throw error;
+        }
+      } else if (ownership.kind === "pending-missing" || ownership.kind === "orphan") {
+        try {
+          const pendingOwnerContent = memoryHostEventExportOwnerContent(owner, {
+            pendingSha256: contentSha256,
+          });
+          if (
+            !(await rewriteMemoryHostEventArtifactIfUnchanged({
+              workspaceRoot,
+              relativePath: owner.ownerRelativePath,
+              expectedContent: ownership.ownerContent,
+              nextContent: pendingOwnerContent,
+            }))
+          ) {
+            return undefined;
+          }
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+          publishedIdentity = await publishMemoryHostEventArtifact({
+            workspaceRoot,
+            owner,
+            absolutePath,
+            expectedOwnerContent: pendingOwnerContent,
+            content,
+            contentSha256,
+          });
+          if (!publishedIdentity) {
+            return undefined;
+          }
+        } catch (error) {
+          if (isWorkspaceWriteUnavailable(error)) {
+            return undefined;
+          }
+          throw error;
+        }
+      } else if (ownership.content !== content) {
+        publishedIdentity = ownership.identity;
+        try {
+          const updateOwnerContent = memoryHostEventExportOwnerContent(owner, {
+            pendingSha256: contentSha256,
+            identity: ownership.identity,
+            ...(ownership.content === undefined
+              ? {}
+              : { currentSha256: sha256Hex(ownership.content) }),
+          });
+          const currentOwnerContent = memoryHostEventExportOwnerContent(owner, {
+            currentSha256: contentSha256,
+            identity: ownership.identity,
+          });
+          if (
+            !(await rewriteMemoryHostEventArtifactIfUnchanged({
+              workspaceRoot,
+              relativePath: owner.ownerRelativePath,
+              expectedContent: ownership.ownerContent,
+              nextContent: updateOwnerContent,
+            }))
+          ) {
+            return undefined;
+          }
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+          if (
+            !(await rewriteMemoryHostEventArtifactIfUnchanged({
+              workspaceRoot,
+              relativePath: owner.relativePath,
+              expectedIdentity: ownership.identity,
+              nextContent: content,
+            }))
+          ) {
+            return undefined;
+          }
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+          if (
+            !(await rewriteMemoryHostEventArtifactIfUnchanged({
+              workspaceRoot,
+              relativePath: owner.ownerRelativePath,
+              expectedContent: updateOwnerContent,
+              nextContent: currentOwnerContent,
+            }))
+          ) {
+            return undefined;
+          }
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+        } catch (error) {
+          if (isWorkspaceWriteUnavailable(error)) {
+            return undefined;
+          }
+          throw error;
+        }
+      } else if (ownership.needsFinalize) {
+        publishedIdentity = ownership.identity;
+        try {
+          if (
+            !(await rewriteMemoryHostEventArtifactIfUnchanged({
+              workspaceRoot,
+              relativePath: owner.ownerRelativePath,
+              expectedContent: ownership.ownerContent,
+              nextContent: memoryHostEventExportOwnerContent(owner, {
+                currentSha256: contentSha256,
+                identity: ownership.identity,
+              }),
+            }))
+          ) {
+            return undefined;
+          }
+          await syncDirectoryBestEffort(path.dirname(absolutePath));
+        } catch (error) {
+          if (isWorkspaceWriteUnavailable(error)) {
+            return undefined;
+          }
+          throw error;
+        }
+      } else {
+        publishedIdentity = ownership.identity;
+      }
+      if (storedEvents.length === 0 || !publishedIdentity) {
+        return undefined;
+      }
+      return (await isMemoryHostEventArtifactAtIdentity({
+        workspaceRoot,
+        relativePath: owner.relativePath,
+        expectedIdentity: publishedIdentity,
+        expectedContent: content,
+      }))
+        ? { absolutePath, relativePath: owner.relativePath }
+        : undefined;
+    });
+  });
+}
+
 /** Lists public memory artifacts for one workspace, including notes and event logs. */
 async function listMemoryWorkspacePublicArtifacts(params: {
   workspaceDir: string;
@@ -87,13 +486,15 @@ async function listMemoryWorkspacePublicArtifacts(params: {
     });
   }
 
-  const eventLogPath = resolveMemoryHostEventLogPath(params.workspaceDir);
-  if (await pathExists(eventLogPath)) {
+  const eventExport = await materializeMemoryHostEventExport({
+    workspaceDir: params.workspaceDir,
+  });
+  if (eventExport) {
     artifacts.push({
       kind: "event-log",
       workspaceDir: params.workspaceDir,
-      relativePath: path.relative(params.workspaceDir, eventLogPath).replace(/\\/g, "/"),
-      absolutePath: eventLogPath,
+      relativePath: eventExport.relativePath,
+      absolutePath: eventExport.absolutePath,
       agentIds: [...params.agentIds],
       contentType: "json",
     });
diff --git a/src/plugin-sdk/memory-host-event-export.test.ts b/src/plugin-sdk/memory-host-event-export.test.ts
new file mode 100644
index 00000000000..26914323f4e
--- /dev/null
+++ b/src/plugin-sdk/memory-host-event-export.test.ts
@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { root as createFsSafeRoot } from "../infra/fs-safe.js";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
+import { clearMemoryPluginState } from "../plugins/memory-state.test-fixtures.js";
+import { listMemoryHostPublicArtifacts } from "./memory-host-core.js";
+import {
+  memoryHostEventExportOwnerContent,
+  publishMemoryHostEventArtifact,
+} from "./memory-host-event-export.js";
+import { appendMemoryHostEvent } from "./memory-host-events.js";
+
+describe("memory host event export recovery", () => {
+  afterEach(() => {
+    clearMemoryPluginState();
+    resetPluginStateStoreForTests();
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  it("does not finalize an initial export changed through the published inode", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-publish-race-"));
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const relativePath = "memory/events/state/memory-host-events.jsonl";
+    const ownerRelativePath = "memory/events/state/.openclaw-memory-host-events-owner.json";
+    const absolutePath = path.join(workspaceDir, relativePath);
+    const owner = {
+      queueKey: "state\0workspace",
+      lockTarget: path.join(fixtureRoot, "lock"),
+      relativePath,
+      ownerRelativePath,
+      stateHash: "state",
+      workspaceHash: "workspace",
+    };
+    const content = '{"type":"memory.recall.recorded","query":"�"}\n';
+    const expectedBytes = Buffer.from(content, "utf8");
+    const replacementBytes = Buffer.from("�", "utf8");
+    const replacementOffset = expectedBytes.indexOf(replacementBytes);
+    const foreignBytes = Buffer.concat([
+      expectedBytes.subarray(0, replacementOffset),
+      Buffer.from([0x80]),
+      expectedBytes.subarray(replacementOffset + replacementBytes.length),
+    ]);
+    const contentSha256 = createHash("sha256").update(content).digest("hex");
+    const expectedOwnerContent = memoryHostEventExportOwnerContent(owner, {
+      pendingSha256: contentSha256,
+    });
+    try {
+      await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+      await fs.writeFile(path.join(workspaceDir, ownerRelativePath), expectedOwnerContent, "utf8");
+      const workspaceRoot = await createFsSafeRoot(workspaceDir, {
+        hardlinks: "reject",
+        mkdir: true,
+        mode: 0o600,
+        symlinks: "reject",
+      });
+      const originalOpen = workspaceRoot.open.bind(workspaceRoot);
+      let replacedContent = false;
+      const interceptedWorkspaceRoot = new Proxy(workspaceRoot, {
+        get(target, property, receiver) {
+          if (property === "open") {
+            return async (
+              openedRelativePath: string,
+              options?: Parameters<typeof workspaceRoot.open>[1],
+            ) => {
+              if (openedRelativePath === relativePath && !replacedContent) {
+                replacedContent = true;
+                await fs.writeFile(absolutePath, foreignBytes);
+              }
+              return await originalOpen(openedRelativePath, options);
+            };
+          }
+          const value = Reflect.get(target, property, receiver) as unknown;
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      });
+
+      await expect(
+        publishMemoryHostEventArtifact({
+          workspaceRoot: interceptedWorkspaceRoot,
+          owner,
+          absolutePath,
+          expectedOwnerContent,
+          content,
+          contentSha256,
+        }),
+      ).resolves.toBeUndefined();
+      expect(foreignBytes.toString("utf8")).toBe(content);
+      await expect(fs.readFile(absolutePath)).resolves.toEqual(foreignBytes);
+      expect(
+        JSON.parse(await fs.readFile(path.join(workspaceDir, ownerRelativePath), "utf8")),
+      ).toMatchObject({
+        pendingContentSha256: contentSha256,
+        fileDev: expect.any(String),
+        fileIno: expect.any(String),
+      });
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("finishes an inode-owned empty event export after interruption", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-inode-owner-"));
+    const stateDir = path.join(fixtureRoot, "state");
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const event = {
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-05-18T12:00:00.000Z",
+      query: "recover inode-owned export",
+      resultCount: 0,
+      results: [],
+    };
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+      await fs.mkdir(workspaceDir);
+      await appendMemoryHostEvent(workspaceDir, event);
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(stateDir))
+        .digest("hex")
+        .slice(0, 32);
+      const workspaceHash = createHash("sha256")
+        .update(await fs.realpath(workspaceDir))
+        .digest("hex")
+        .slice(0, 32);
+      const exportDir = path.join(workspaceDir, "memory", "events", stateHash);
+      const exportPath = path.join(exportDir, "memory-host-events.jsonl");
+      const ownerPath = path.join(exportDir, ".openclaw-memory-host-events-owner.json");
+      const expectedContent = `${JSON.stringify(event)}\n`;
+      await fs.mkdir(exportDir, { recursive: true });
+      await fs.writeFile(exportPath, "", { mode: 0o600 });
+      const exportStat = await fs.stat(exportPath, { bigint: true });
+      await fs.writeFile(
+        ownerPath,
+        `${JSON.stringify({
+          schemaVersion: 3,
+          kind: "openclaw-memory-host-events-export",
+          stateHash,
+          workspaceHash,
+          pendingContentSha256: createHash("sha256").update(expectedContent).digest("hex"),
+          fileDev: String(exportStat.dev),
+          fileIno: String(exportStat.ino),
+        })}\n`,
+        "utf8",
+      );
+
+      const listed = await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+
+      expect(listed.some((artifact) => artifact.kind === "event-log")).toBe(true);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe(expectedContent);
+      const owner = JSON.parse(await fs.readFile(ownerPath, "utf8")) as {
+        contentSha256?: string;
+        fileDev?: string;
+        fileIno?: string;
+        pendingContentSha256?: string;
+      };
+      expect(owner).toMatchObject({
+        contentSha256: createHash("sha256").update(expectedContent).digest("hex"),
+        fileDev: expect.any(String),
+        fileIno: expect.any(String),
+      });
+      expect(owner.pendingContentSha256).toBeUndefined();
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not claim an empty export after exclusive-create interruption", async () => {
+    const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "memory-host-empty-export-"));
+    const stateDir = path.join(fixtureRoot, "state");
+    const workspaceDir = path.join(fixtureRoot, "workspace");
+    const event = {
+      type: "memory.recall.recorded" as const,
+      timestamp: "2026-05-18T12:00:00.000Z",
+      query: "leave empty export untouched",
+      resultCount: 0,
+      results: [],
+    };
+    try {
+      vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+      await fs.mkdir(workspaceDir);
+      await appendMemoryHostEvent(workspaceDir, event);
+      const stateHash = createHash("sha256")
+        .update(await fs.realpath(stateDir))
+        .digest("hex")
+        .slice(0, 32);
+      const workspaceHash = createHash("sha256")
+        .update(await fs.realpath(workspaceDir))
+        .digest("hex")
+        .slice(0, 32);
+      const exportDir = path.join(workspaceDir, "memory", "events", stateHash);
+      const exportPath = path.join(exportDir, "memory-host-events.jsonl");
+      const ownerPath = path.join(exportDir, ".openclaw-memory-host-events-owner.json");
+      const expectedContent = `${JSON.stringify(event)}\n`;
+      await fs.mkdir(exportDir, { recursive: true });
+      await fs.writeFile(exportPath, "", { mode: 0o600 });
+      await fs.writeFile(
+        ownerPath,
+        `${JSON.stringify({
+          schemaVersion: 3,
+          kind: "openclaw-memory-host-events-export",
+          stateHash,
+          workspaceHash,
+          pendingContentSha256: createHash("sha256").update(expectedContent).digest("hex"),
+        })}\n`,
+        "utf8",
+      );
+
+      const listed = await listMemoryHostPublicArtifacts({
+        cfg: { agents: { list: [{ id: "main", default: true, workspace: workspaceDir }] } },
+      });
+
+      expect(listed.some((artifact) => artifact.kind === "event-log")).toBe(false);
+      await expect(fs.readFile(exportPath, "utf8")).resolves.toBe("");
+    } finally {
+      await fs.rm(fixtureRoot, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/plugin-sdk/memory-host-event-export.ts b/src/plugin-sdk/memory-host-event-export.ts
new file mode 100644
index 00000000000..5636ed9f847
--- /dev/null
+++ b/src/plugin-sdk/memory-host-event-export.ts
@@ -0,0 +1,268 @@
+import type { FileHandle } from "node:fs/promises";
+import path from "node:path";
+import { sameFileIdentity, type FileIdentityStat } from "../infra/fs-safe-advanced.js";
+import { FsSafeError, root as createFsSafeRoot } from "../infra/fs-safe.js";
+import { syncDirectoryBestEffort } from "../infra/sqlite-snapshot.js";
+
+export type MemoryHostEventExportOwner = {
+  queueKey: string;
+  lockTarget: string;
+  relativePath: string;
+  ownerRelativePath: string;
+  stateHash: string;
+  workspaceHash: string;
+};
+
+type MemoryHostWorkspaceRoot = Awaited<ReturnType<typeof createFsSafeRoot>>;
+
+export function isMissingPathError(error: unknown): boolean {
+  const code = (error as { code?: unknown }).code;
+  return (
+    code === "ENOENT" ||
+    code === "ENOTDIR" ||
+    (error instanceof FsSafeError && code === "not-found")
+  );
+}
+
+export function isRejectedWorkspaceArtifactPath(error: unknown): boolean {
+  if (!(error instanceof FsSafeError)) {
+    return false;
+  }
+  return (
+    error.code === "hardlink" ||
+    error.code === "not-file" ||
+    error.code === "outside-workspace" ||
+    error.code === "path-alias" ||
+    error.code === "path-mismatch" ||
+    error.code === "symlink"
+  );
+}
+
+export function memoryHostEventExportOwnerContent(
+  owner: MemoryHostEventExportOwner,
+  content: {
+    currentSha256?: string;
+    pendingSha256?: string;
+    identity?: FileIdentityStat;
+  },
+): string {
+  return `${JSON.stringify({
+    schemaVersion: 3,
+    kind: "openclaw-memory-host-events-export",
+    stateHash: owner.stateHash,
+    workspaceHash: owner.workspaceHash,
+    ...(content.identity
+      ? { fileDev: String(content.identity.dev), fileIno: String(content.identity.ino) }
+      : {}),
+    ...(content.currentSha256 ? { contentSha256: content.currentSha256 } : {}),
+    ...(content.pendingSha256 ? { pendingContentSha256: content.pendingSha256 } : {}),
+  })}\n`;
+}
+
+async function writePinnedMemoryHostEventArtifact(
+  handle: FileHandle,
+  content: string,
+): Promise<void> {
+  const bytes = Buffer.from(content, "utf8");
+  let offset = 0;
+  while (offset < bytes.length) {
+    const result = await handle.write(bytes, offset, bytes.length - offset, offset);
+    if (result.bytesWritten === 0) {
+      throw new Error("event export write made no progress");
+    }
+    offset += result.bytesWritten;
+  }
+  await handle.truncate(bytes.length);
+  await handle.chmod(0o600);
+  await handle.sync();
+}
+
+export async function rewriteMemoryHostEventArtifactIfUnchanged(params: {
+  workspaceRoot: MemoryHostWorkspaceRoot;
+  relativePath: string;
+  expectedContent?: string;
+  expectedIdentity?: FileIdentityStat;
+  nextContent: string;
+}): Promise<boolean> {
+  let observed: Awaited<ReturnType<typeof params.workspaceRoot.open>>;
+  try {
+    observed = await params.workspaceRoot.open(params.relativePath);
+  } catch (error) {
+    if (isMissingPathError(error) || isRejectedWorkspaceArtifactPath(error)) {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    if (
+      params.expectedIdentity
+        ? !sameFileIdentity(params.expectedIdentity, observed.stat)
+        : (await observed.handle.readFile({ encoding: "utf8" })) !== params.expectedContent
+    ) {
+      return false;
+    }
+    let writable: Awaited<ReturnType<typeof params.workspaceRoot.openWritable>>;
+    try {
+      writable = await params.workspaceRoot.openWritable(params.relativePath, {
+        mode: 0o600,
+        writeMode: "update",
+      });
+    } catch (error) {
+      if (isMissingPathError(error) || isRejectedWorkspaceArtifactPath(error)) {
+        return false;
+      }
+      throw error;
+    }
+    try {
+      // The matching marker/content snapshot owns this generated artifact inode for
+      // the locked update. A distinct workspace file can take the path only by
+      // replacing that inode; direct writes still target the owned export itself.
+      if (!sameFileIdentity(observed.stat, writable.stat)) {
+        return false;
+      }
+      await writable.handle.writeFile(params.nextContent, { encoding: "utf8" });
+      await writable.handle.truncate(Buffer.byteLength(params.nextContent, "utf8"));
+      await writable.handle.chmod(0o600);
+      await writable.handle.sync();
+    } finally {
+      await writable.handle.close().catch(() => undefined);
+    }
+    let verified: Awaited<ReturnType<typeof params.workspaceRoot.open>>;
+    try {
+      verified = await params.workspaceRoot.open(params.relativePath);
+    } catch (error) {
+      if (isMissingPathError(error) || isRejectedWorkspaceArtifactPath(error)) {
+        return false;
+      }
+      throw error;
+    }
+    try {
+      return (
+        sameFileIdentity(observed.stat, verified.stat) &&
+        (await verified.handle.readFile({ encoding: "utf8" })) === params.nextContent
+      );
+    } finally {
+      await verified.handle.close().catch(() => undefined);
+    }
+  } finally {
+    await observed.handle.close().catch(() => undefined);
+  }
+}
+
+export async function isMemoryHostEventArtifactAtIdentity(params: {
+  workspaceRoot: MemoryHostWorkspaceRoot;
+  relativePath: string;
+  expectedIdentity: FileIdentityStat;
+  expectedContent?: string;
+}): Promise<boolean> {
+  let opened: Awaited<ReturnType<typeof params.workspaceRoot.open>>;
+  try {
+    opened = await params.workspaceRoot.open(params.relativePath);
+  } catch (error) {
+    if (isMissingPathError(error) || isRejectedWorkspaceArtifactPath(error)) {
+      return false;
+    }
+    throw error;
+  }
+  try {
+    if (!sameFileIdentity(params.expectedIdentity, opened.stat)) {
+      return false;
+    }
+    return (
+      params.expectedContent === undefined ||
+      (await opened.handle.readFile()).equals(Buffer.from(params.expectedContent, "utf8"))
+    );
+  } finally {
+    await opened.handle.close().catch(() => undefined);
+  }
+}
+
+export async function publishMemoryHostEventArtifact(params: {
+  workspaceRoot: MemoryHostWorkspaceRoot;
+  owner: MemoryHostEventExportOwner;
+  absolutePath: string;
+  expectedOwnerContent: string;
+  content: string;
+  contentSha256: string;
+}): Promise<FileIdentityStat | undefined> {
+  let writable: Awaited<ReturnType<typeof params.workspaceRoot.openWritable>>;
+  try {
+    writable = await params.workspaceRoot.openWritable(params.owner.relativePath, {
+      mode: 0o600,
+      writeMode: "replace",
+    });
+  } catch (error) {
+    if (isMissingPathError(error) || isRejectedWorkspaceArtifactPath(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+  try {
+    // `createdForWrite` is the exclusive-create proof. Keep its handle pinned
+    // through publication so a replacement path is never opened for mutation.
+    if (!writable.createdForWrite) {
+      return undefined;
+    }
+    const publishedIdentity = { dev: writable.stat.dev, ino: writable.stat.ino };
+    await syncDirectoryBestEffort(path.dirname(params.absolutePath));
+
+    const identityPendingOwnerContent = memoryHostEventExportOwnerContent(params.owner, {
+      pendingSha256: params.contentSha256,
+      identity: publishedIdentity,
+    });
+    if (
+      !(await rewriteMemoryHostEventArtifactIfUnchanged({
+        workspaceRoot: params.workspaceRoot,
+        relativePath: params.owner.ownerRelativePath,
+        expectedContent: params.expectedOwnerContent,
+        nextContent: identityPendingOwnerContent,
+      }))
+    ) {
+      return undefined;
+    }
+    await syncDirectoryBestEffort(path.dirname(params.absolutePath));
+
+    await writePinnedMemoryHostEventArtifact(writable.handle, params.content);
+    // Workspace actors can mutate this inode without replacing the path. Verify
+    // bytes before finalizing the marker so foreign content never gains ownership.
+    if (
+      !(await isMemoryHostEventArtifactAtIdentity({
+        workspaceRoot: params.workspaceRoot,
+        relativePath: params.owner.relativePath,
+        expectedIdentity: publishedIdentity,
+        expectedContent: params.content,
+      }))
+    ) {
+      return undefined;
+    }
+    await syncDirectoryBestEffort(path.dirname(params.absolutePath));
+
+    if (
+      !(await rewriteMemoryHostEventArtifactIfUnchanged({
+        workspaceRoot: params.workspaceRoot,
+        relativePath: params.owner.ownerRelativePath,
+        expectedContent: identityPendingOwnerContent,
+        nextContent: memoryHostEventExportOwnerContent(params.owner, {
+          currentSha256: params.contentSha256,
+          identity: publishedIdentity,
+        }),
+      }))
+    ) {
+      return undefined;
+    }
+    await syncDirectoryBestEffort(path.dirname(params.absolutePath));
+    if (
+      !(await isMemoryHostEventArtifactAtIdentity({
+        workspaceRoot: params.workspaceRoot,
+        relativePath: params.owner.relativePath,
+        expectedIdentity: publishedIdentity,
+        expectedContent: params.content,
+      }))
+    ) {
+      return undefined;
+    }
+    return publishedIdentity;
+  } finally {
+    await writable.handle.close().catch(() => undefined);
+  }
+}
diff --git a/src/plugin-sdk/memory-host-events.test.ts b/src/plugin-sdk/memory-host-events.test.ts
index 3f2dad57adb..ec35aaeeb20 100644
--- a/src/plugin-sdk/memory-host-events.test.ts
+++ b/src/plugin-sdk/memory-host-events.test.ts
@@ -3,13 +3,16 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  listStoredMemoryHostEvents,
+  setMaxMemoryHostEventsForTests,
+} from "../memory-host-sdk/event-store.js";
 import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import {
   appendMemoryHostEvent,
   readMemoryHostEventRecords,
   readMemoryHostEvents,
-  resolveMemoryHostEventLogPath,
 } from "./memory-host-events.js";
 import {
   createClaimableDedupe,
@@ -32,45 +35,51 @@ function createDedupe(root: string, overrides?: { ttlMs?: number }) {
 }
 
 afterEach(() => {
+  vi.restoreAllMocks();
+  setMaxMemoryHostEventsForTests(undefined);
   resetPluginStateStoreForTests();
 });
 
 describe("memory host event journal helpers", () => {
   it("appends and reads typed workspace events", async () => {
     const workspaceDir = await createTempDir("memory-host-events-");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: workspaceDir };
 
-    await appendMemoryHostEvent(workspaceDir, {
-      type: "memory.recall.recorded",
-      timestamp: "2026-04-05T12:00:00.000Z",
-      query: "glacier backup",
-      resultCount: 1,
-      results: [
-        {
-          path: "memory/2026-04-05.md",
-          startLine: 1,
-          endLine: 3,
-          score: 0.9,
-        },
-      ],
-    });
-    await appendMemoryHostEvent(workspaceDir, {
-      type: "memory.dream.completed",
-      timestamp: "2026-04-05T13:00:00.000Z",
-      phase: "light",
-      outcome: "completed",
-      lineCount: 4,
-      storageMode: "both",
-      inlinePath: path.join(workspaceDir, "memory", "2026-04-05.md"),
-      reportPath: path.join(workspaceDir, "memory", "dreaming", "light", "2026-04-05.md"),
-    });
-
-    const eventLogPath = resolveMemoryHostEventLogPath(workspaceDir);
-    await expect(fs.readFile(eventLogPath, "utf8")).resolves.toContain(
-      '"type":"memory.recall.recorded"',
+    await appendMemoryHostEvent(
+      workspaceDir,
+      {
+        type: "memory.recall.recorded",
+        timestamp: "2026-04-05T12:00:00.000Z",
+        query: "glacier backup",
+        resultCount: 1,
+        results: [
+          {
+            path: "memory/2026-04-05.md",
+            startLine: 1,
+            endLine: 3,
+            score: 0.9,
+          },
+        ],
+      },
+      { env },
+    );
+    await appendMemoryHostEvent(
+      workspaceDir,
+      {
+        type: "memory.dream.completed",
+        timestamp: "2026-04-05T11:00:00.000Z",
+        phase: "light",
+        outcome: "completed",
+        lineCount: 4,
+        storageMode: "both",
+        inlinePath: path.join(workspaceDir, "memory", "2026-04-05.md"),
+        reportPath: path.join(workspaceDir, "memory", "dreaming", "light", "2026-04-05.md"),
+      },
+      { env },
     );
 
-    const events = await readMemoryHostEvents({ workspaceDir });
-    const tail = await readMemoryHostEvents({ workspaceDir, limit: 1 });
+    const events = await readMemoryHostEvents({ workspaceDir, env });
+    const tail = await readMemoryHostEvents({ workspaceDir, limit: 1, env });
 
     expect(events).toHaveLength(2);
     expect(events[0]?.type).toBe("memory.recall.recorded");
@@ -83,62 +92,101 @@ describe("memory host event journal helpers", () => {
     expect(tail[0]?.type).toBe("memory.dream.completed");
   });
 
-  it("keeps legacy event readers stable when diagnostic records are present", async () => {
-    const workspaceDir = await createTempDir("memory-host-events-diagnostics-");
+  it("keeps journal retention timestamps in the current wall-clock domain", async () => {
+    const workspaceDir = await createTempDir("memory-host-events-created-at-");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: workspaceDir };
+    const now = Date.parse("2026-07-16T12:00:00.000Z");
+    vi.useFakeTimers();
+    vi.setSystemTime(now);
 
-    await appendMemoryHostEvent(workspaceDir, {
-      type: "memory.recall.skipped",
-      timestamp: "2026-04-05T12:00:00.000Z",
-      query: "durable memory",
-      reason: "non-short-term-memory-path",
-      eligibleResultCount: 0,
-      skippedResultCount: 1,
-      results: [
+    for (const query of ["first", "second"]) {
+      await appendMemoryHostEvent(
+        workspaceDir,
         {
-          path: "MEMORY.md",
-          startLine: 3,
-          endLine: 3,
-          score: 0.9,
-          reason: "non-short-term-memory-path",
+          type: "memory.recall.recorded",
+          timestamp: "2026-07-16T12:00:00.000Z",
+          query,
+          resultCount: 0,
+          results: [],
         },
-      ],
-    });
+        { env },
+      );
+    }
 
-    await appendMemoryHostEvent(workspaceDir, {
-      type: "memory.recall.recorded",
-      timestamp: "2026-04-05T12:05:00.000Z",
-      query: "daily memory",
-      resultCount: 1,
-      results: [
-        {
-          path: "memory/2026-04-05.md",
-          startLine: 1,
-          endLine: 3,
-          score: 0.95,
-        },
-      ],
-    });
-    await appendMemoryHostEvent(workspaceDir, {
-      type: "memory.recall.skipped",
-      timestamp: "2026-04-05T12:10:00.000Z",
-      query: "durable memory again",
-      reason: "non-short-term-memory-path",
-      eligibleResultCount: 1,
-      skippedResultCount: 1,
-      results: [
-        {
-          path: "MEMORY.md",
-          startLine: 4,
-          endLine: 4,
-          score: 0.8,
-          reason: "non-short-term-memory-path",
-        },
-      ],
-    });
+    expect(
+      listStoredMemoryHostEvents({ workspaceDir, env }).map((entry) => entry.createdAt),
+    ).toEqual([now, now + 1]);
+  });
 
-    const legacyEvents = await readMemoryHostEvents({ workspaceDir });
-    const legacyTail = await readMemoryHostEvents({ workspaceDir, limit: 1 });
-    const records = await readMemoryHostEventRecords({ workspaceDir });
+  it("keeps legacy event readers stable when diagnostic records are present", async () => {
+    const workspaceDir = await createTempDir("memory-host-events-diagnostics-");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: workspaceDir };
+
+    await appendMemoryHostEvent(
+      workspaceDir,
+      {
+        type: "memory.recall.skipped",
+        timestamp: "2026-04-05T12:00:00.000Z",
+        query: "durable memory",
+        reason: "non-short-term-memory-path",
+        eligibleResultCount: 0,
+        skippedResultCount: 1,
+        results: [
+          {
+            path: "MEMORY.md",
+            startLine: 3,
+            endLine: 3,
+            score: 0.9,
+            reason: "non-short-term-memory-path",
+          },
+        ],
+      },
+      { env },
+    );
+
+    await appendMemoryHostEvent(
+      workspaceDir,
+      {
+        type: "memory.recall.recorded",
+        timestamp: "2026-04-05T12:05:00.000Z",
+        query: "daily memory",
+        resultCount: 1,
+        results: [
+          {
+            path: "memory/2026-04-05.md",
+            startLine: 1,
+            endLine: 3,
+            score: 0.95,
+          },
+        ],
+      },
+      { env },
+    );
+    await appendMemoryHostEvent(
+      workspaceDir,
+      {
+        type: "memory.recall.skipped",
+        timestamp: "2026-04-05T12:10:00.000Z",
+        query: "durable memory again",
+        reason: "non-short-term-memory-path",
+        eligibleResultCount: 1,
+        skippedResultCount: 1,
+        results: [
+          {
+            path: "MEMORY.md",
+            startLine: 4,
+            endLine: 4,
+            score: 0.8,
+            reason: "non-short-term-memory-path",
+          },
+        ],
+      },
+      { env },
+    );
+
+    const legacyEvents = await readMemoryHostEvents({ workspaceDir, env });
+    const legacyTail = await readMemoryHostEvents({ workspaceDir, limit: 1, env });
+    const records = await readMemoryHostEventRecords({ workspaceDir, env });
 
     expect(legacyEvents.map((event) => event.type)).toEqual(["memory.recall.recorded"]);
     expect(legacyTail.map((event) => event.type)).toEqual(["memory.recall.recorded"]);
@@ -148,6 +196,105 @@ describe("memory host event journal helpers", () => {
       "memory.recall.skipped",
     ]);
   });
+
+  it("bounds oversized diagnostic detail without failing the parent operation", async () => {
+    const workspaceDir = await createTempDir("memory-host-events-bounded-");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: workspaceDir };
+    const results = Array.from({ length: 100 }, (_, index) => ({
+      path: `memory/${"wide-path-".repeat(100)}${index}.md`,
+      startLine: index + 1,
+      endLine: index + 2,
+      score: 0.9,
+    }));
+
+    await expect(
+      appendMemoryHostEvent(
+        workspaceDir,
+        {
+          type: "memory.recall.recorded",
+          timestamp: "2026-04-05T12:00:00.000Z",
+          query: "🔥".repeat(20_000),
+          resultCount: results.length,
+          results,
+        },
+        { env },
+      ),
+    ).resolves.toBeUndefined();
+
+    const [event] = await readMemoryHostEventRecords({ workspaceDir, env });
+    expect(event).toMatchObject({
+      type: "memory.recall.recorded",
+      resultCount: 100,
+      storageTruncated: true,
+    });
+    if (event?.type !== "memory.recall.recorded") {
+      throw new Error("expected bounded recall event");
+    }
+    expect(event.results).toHaveLength(10);
+    expect(Buffer.byteLength(JSON.stringify(event), "utf8")).toBeLessThanOrEqual(8 * 1024);
+  });
+
+  it("rotates old events without evicting the workspace sequence cursor", async () => {
+    const workspaceDir = await createTempDir("memory-host-events-rotation-");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: workspaceDir };
+    setMaxMemoryHostEventsForTests(3);
+    let clock = 1_000;
+    vi.spyOn(Date, "now").mockImplementation(() => clock--);
+
+    for (let index = 1; index <= 5; index += 1) {
+      await appendMemoryHostEvent(
+        workspaceDir,
+        {
+          type: "memory.recall.recorded",
+          timestamp: `2026-04-05T12:00:0${index}.000Z`,
+          query: `event-${index}`,
+          resultCount: 0,
+          results: [],
+        },
+        { env },
+      );
+    }
+
+    const events = await readMemoryHostEventRecords({ workspaceDir, env });
+    expect(
+      events.map((event) => (event.type === "memory.recall.recorded" ? event.query : "")),
+    ).toEqual(["event-3", "event-4", "event-5"]);
+  });
+
+  it("rotates events by namespace append order across workspaces", async () => {
+    const stateDir = await createTempDir("memory-host-events-shared-retention-");
+    const workspaceA = path.join(stateDir, "workspace-a");
+    const workspaceB = path.join(stateDir, "workspace-b");
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    setMaxMemoryHostEventsForTests(3);
+
+    const appendRecall = async (workspaceDir: string, query: string) => {
+      await appendMemoryHostEvent(
+        workspaceDir,
+        {
+          type: "memory.recall.recorded",
+          timestamp: "2026-04-05T12:00:00.000Z",
+          query,
+          resultCount: 0,
+          results: [],
+        },
+        { env },
+      );
+    };
+    await appendRecall(workspaceA, "a-1");
+    await appendRecall(workspaceA, "a-2");
+    await appendRecall(workspaceA, "a-3");
+    await appendRecall(workspaceB, "b-1");
+    await appendRecall(workspaceA, "a-4");
+
+    const workspaceBEvents = await readMemoryHostEventRecords({
+      workspaceDir: workspaceB,
+      env,
+    });
+    expect(
+      workspaceBEvents.map((event) => (event.type === "memory.recall.recorded" ? event.query : "")),
+    ).toEqual(["b-1"]);
+  });
 });
 
 describe("createPersistentDedupe", () => {
diff --git a/src/plugin-sdk/memory-host-events.ts b/src/plugin-sdk/memory-host-events.ts
index 09cccc28d2c..8cda8e2299b 100644
--- a/src/plugin-sdk/memory-host-events.ts
+++ b/src/plugin-sdk/memory-host-events.ts
@@ -1,8 +1,9 @@
 /**
- * Public SDK subpath for memory host event log types and helpers.
+ * Public SDK subpath for memory host event types and helpers.
  */
 export {
   appendMemoryHostEvent,
+  normalizeMemoryHostEventRecordForStorage,
   readMemoryHostEventRecords,
   readMemoryHostEvents,
   resolveMemoryHostEventLogPath,
diff --git a/src/plugin-sdk/plugin-state-test-runtime.ts b/src/plugin-sdk/plugin-state-test-runtime.ts
index fb3750b473e..69949122f6c 100644
--- a/src/plugin-sdk/plugin-state-test-runtime.ts
+++ b/src/plugin-sdk/plugin-state-test-runtime.ts
@@ -4,8 +4,11 @@
 export {
   createPluginStateKeyedStore as createPluginStateKeyedStoreForTests,
   createPluginStateSyncKeyedStore as createPluginStateSyncKeyedStoreForTests,
+  getPluginStateCapacity as getPluginStateCapacityForTests,
+  importPluginStateEntriesForDoctor as importPluginStateEntriesForDoctorForTests,
   resetPluginStateStoreForTests,
 } from "../plugin-state/plugin-state-store.js";
+export { setMaxMemoryHostEventsForTests } from "../memory-host-sdk/event-store.js";
 export {
   createPluginBlobStoreForTests,
   resetPluginBlobStoreForTests,
diff --git a/src/plugin-state/plugin-state-store.sqlite.ts b/src/plugin-state/plugin-state-store.sqlite.ts
index 6abc312c8b1..b078b4a54b7 100644
--- a/src/plugin-state/plugin-state-store.sqlite.ts
+++ b/src/plugin-state/plugin-state-store.sqlite.ts
@@ -222,6 +222,33 @@ function selectPluginStateEntries(
   ).rows;
 }
 
+function selectPluginStateEntriesInKeyRange(
+  db: DatabaseSync,
+  params: {
+    pluginId: string;
+    namespace: string;
+    keyStartInclusive: string;
+    keyEndExclusive: string;
+    limit: number;
+    order: "asc" | "desc";
+    now: number;
+  },
+): PluginStateRow[] {
+  return executeSqliteQuerySync(
+    db,
+    getPluginStateKysely(db)
+      .selectFrom("plugin_state_entries")
+      .select(["plugin_id", "namespace", "entry_key", "value_json", "created_at", "expires_at"])
+      .where("plugin_id", "=", params.pluginId)
+      .where("namespace", "=", params.namespace)
+      .where("entry_key", ">=", params.keyStartInclusive)
+      .where("entry_key", "<", params.keyEndExclusive)
+      .where((eb) => eb.or([eb("expires_at", "is", null), eb("expires_at", ">", params.now)]))
+      .orderBy("entry_key", params.order)
+      .limit(params.limit),
+  ).rows;
+}
+
 function deletePluginStateEntry(
   db: DatabaseSync,
   params: { pluginId: string; namespace: string; key: string },
@@ -268,6 +295,26 @@ function countLivePluginStateNamespaceEntries(
   return countRow(row);
 }
 
+function allocatePluginStateNamespaceCreatedAt(
+  db: DatabaseSync,
+  params: { pluginId: string; namespace: string; now: number },
+): number {
+  const row = executeSqliteQueryTakeFirstSync(
+    db,
+    getPluginStateKysely(db)
+      .selectFrom("plugin_state_entries")
+      .select((eb) => eb.fn.max<number | bigint>("created_at").as("max_created_at"))
+      .where("plugin_id", "=", params.pluginId)
+      .where("namespace", "=", params.namespace),
+  );
+  const previous = normalizeSqliteNumber(row?.max_created_at ?? null);
+  const next = previous === undefined ? params.now : Math.max(params.now, previous + 1);
+  if (!Number.isSafeInteger(next)) {
+    throw new RangeError("Plugin state namespace append order exhausted safe integer range");
+  }
+  return next;
+}
+
 function countLivePluginStateEntries(
   db: DatabaseSync,
   params: { pluginId: string; now: number },
@@ -380,6 +427,7 @@ function enforcePostRegisterLimits(params: {
   overflowPolicy: PluginStateOverflowPolicy;
   now: number;
   protectedKey: string;
+  enforcePluginLimit?: boolean;
 }): void {
   if (params.overflowPolicy === "reject-new") {
     return;
@@ -399,6 +447,10 @@ function enforcePostRegisterLimits(params: {
     });
   }
 
+  if (params.enforcePluginLimit === false) {
+    return;
+  }
+
   const pluginCount = countLivePluginStateEntries(params.store.db, {
     pluginId: params.pluginId,
     now: params.now,
@@ -408,7 +460,9 @@ function enforcePostRegisterLimits(params: {
     return;
   }
 
-  // Shed rows from the namespace that grew before failing the plugin write.
+  // Shed only rows from the namespace that grew. Sibling namespaces can hold
+  // durable state; if this namespace cannot cover the overflow, fail so the
+  // surrounding transaction rolls every insertion and deletion back.
   deleteOldestPluginStateNamespaceEntries(params.store.db, {
     pluginId: params.pluginId,
     namespace: params.namespace,
@@ -551,6 +605,141 @@ export function pluginStateRegister(params: {
   }
 }
 
+export function pluginStateRegisterSequencedJournalEntry(params: {
+  pluginId: string;
+  cursorNamespace: string;
+  cursorKey: string;
+  cursorMaxEntries: number;
+  journalNamespace: string;
+  journalMaxEntries: number;
+  initialSequence: number;
+  readCursorSequence: (valueJson: string) => number | undefined;
+  prepareEntry: (sequence: number) => {
+    cursorValueJson: string;
+    journalKey: string;
+    journalValueJson: string;
+  };
+  env?: NodeJS.ProcessEnv;
+}): number {
+  try {
+    return runWriteTransaction(
+      "register",
+      (store) => {
+        const now = Date.now();
+        deleteExpiredPluginStateNamespaceEntries(store.db, {
+          pluginId: params.pluginId,
+          namespace: params.cursorNamespace,
+          now,
+        });
+        deleteExpiredPluginStateNamespaceEntries(store.db, {
+          pluginId: params.pluginId,
+          namespace: params.journalNamespace,
+          now,
+        });
+        const cursor = selectPluginStateEntry(store.db, {
+          pluginId: params.pluginId,
+          namespace: params.cursorNamespace,
+          key: params.cursorKey,
+          now,
+        });
+        const cursorSequence = cursor ? params.readCursorSequence(cursor.value_json) : undefined;
+        const lastSequence = Math.max(params.initialSequence, cursorSequence ?? 0);
+        const sequence = lastSequence + 1;
+        if (!Number.isSafeInteger(sequence)) {
+          throw new RangeError("Plugin state journal sequence exhausted safe integer range");
+        }
+        const prepared = params.prepareEntry(sequence);
+        const existingJournalEntry = selectPluginStateEntry(store.db, {
+          pluginId: params.pluginId,
+          namespace: params.journalNamespace,
+          key: prepared.journalKey,
+          now,
+        });
+        if (existingJournalEntry) {
+          throw createPluginStateError({
+            code: "PLUGIN_STATE_WRITE_FAILED",
+            operation: "register",
+            message: "Plugin state journal sequence already exists.",
+            path: store.path,
+          });
+        }
+        if (!cursor) {
+          assertCanInsertPluginStateEntry({
+            store,
+            pluginId: params.pluginId,
+            namespace: params.cursorNamespace,
+            maxEntries: params.cursorMaxEntries,
+            overflowPolicy: "evict-oldest",
+            now,
+          });
+        }
+        assertCanInsertPluginStateEntry({
+          store,
+          pluginId: params.pluginId,
+          namespace: params.journalNamespace,
+          maxEntries: params.journalMaxEntries,
+          overflowPolicy: "evict-oldest",
+          now,
+        });
+        upsertPluginStateEntry(
+          store.db,
+          bindPluginStateEntry({
+            pluginId: params.pluginId,
+            namespace: params.cursorNamespace,
+            key: params.cursorKey,
+            valueJson: prepared.cursorValueJson,
+            createdAt: now,
+            expiresAt: null,
+          }),
+        );
+        enforcePostRegisterLimits({
+          store,
+          pluginId: params.pluginId,
+          namespace: params.cursorNamespace,
+          maxEntries: params.cursorMaxEntries,
+          overflowPolicy: "evict-oldest",
+          now,
+          protectedKey: params.cursorKey,
+          enforcePluginLimit: false,
+        });
+        upsertPluginStateEntry(
+          store.db,
+          bindPluginStateEntry({
+            pluginId: params.pluginId,
+            namespace: params.journalNamespace,
+            key: prepared.journalKey,
+            valueJson: prepared.journalValueJson,
+            createdAt: allocatePluginStateNamespaceCreatedAt(store.db, {
+              pluginId: params.pluginId,
+              namespace: params.journalNamespace,
+              now,
+            }),
+            expiresAt: null,
+          }),
+        );
+        enforcePostRegisterLimits({
+          store,
+          pluginId: params.pluginId,
+          namespace: params.journalNamespace,
+          maxEntries: params.journalMaxEntries,
+          overflowPolicy: "evict-oldest",
+          now,
+          protectedKey: prepared.journalKey,
+        });
+        return sequence;
+      },
+      envOptions(params.env),
+    );
+  } catch (error) {
+    throw wrapPluginStateError(
+      error,
+      "register",
+      "PLUGIN_STATE_WRITE_FAILED",
+      "Failed to register sequenced plugin state journal entry.",
+    );
+  }
+}
+
 export function pluginStateRegisterIfAbsent(params: {
   pluginId: string;
   namespace: string;
@@ -852,6 +1041,51 @@ export function pluginStateEntries(params: {
   }
 }
 
+/** Internal bounded key-range read for core owners with sortable plugin-state keys. */
+export function pluginStateEntriesInKeyRange(params: {
+  pluginId: string;
+  namespace: string;
+  keyStartInclusive: string;
+  keyEndExclusive: string;
+  limit: number;
+  order?: "asc" | "desc";
+  env?: NodeJS.ProcessEnv;
+}): PluginStateEntry<unknown>[] {
+  if (!Number.isSafeInteger(params.limit) || params.limit < 1) {
+    throw createPluginStateError({
+      code: "PLUGIN_STATE_INVALID_INPUT",
+      operation: "entries",
+      message: "Plugin state key-range limit must be a positive safe integer.",
+    });
+  }
+  if (params.keyStartInclusive >= params.keyEndExclusive) {
+    throw createPluginStateError({
+      code: "PLUGIN_STATE_INVALID_INPUT",
+      operation: "entries",
+      message: "Plugin state key range must have an increasing exclusive upper bound.",
+    });
+  }
+  try {
+    const { db } = openPluginStateDatabase("entries", envOptions(params.env));
+    return selectPluginStateEntriesInKeyRange(db, {
+      pluginId: params.pluginId,
+      namespace: params.namespace,
+      keyStartInclusive: params.keyStartInclusive,
+      keyEndExclusive: params.keyEndExclusive,
+      limit: params.limit,
+      order: params.order ?? "asc",
+      now: Date.now(),
+    }).map((row) => rowToEntry(row, "entries"));
+  } catch (error) {
+    throw wrapPluginStateError(
+      error,
+      "entries",
+      "PLUGIN_STATE_READ_FAILED",
+      "Failed to list plugin state entries by key range.",
+    );
+  }
+}
+
 export function pluginStateClear(params: {
   pluginId: string;
   namespace: string;
@@ -912,9 +1146,9 @@ function setMaxPluginStateEntriesPerPluginForTests(value?: number): void {
   maxPluginStateEntriesPerPluginForTests = value;
 }
 
-export function countPluginStateLiveEntries(pluginId: string): number {
+export function countPluginStateLiveEntries(pluginId: string, env?: NodeJS.ProcessEnv): number {
   try {
-    const { db } = openPluginStateDatabase("entries");
+    const { db } = openPluginStateDatabase("entries", envOptions(env));
     return countLivePluginStateEntries(db, { pluginId, now: Date.now() });
   } catch (error) {
     throw wrapPluginStateError(
@@ -926,6 +1160,16 @@ export function countPluginStateLiveEntries(pluginId: string): number {
   }
 }
 
+export function getPluginStateCapacity(
+  pluginId: string,
+  env?: NodeJS.ProcessEnv,
+): { liveEntries: number; maxEntries: number } {
+  return {
+    liveEntries: countPluginStateLiveEntries(pluginId, env),
+    maxEntries: resolveMaxPluginStateEntriesPerPlugin(),
+  };
+}
+
 function seedPluginStateDatabaseEntriesForTests(
   entries: readonly PluginStateSeedEntryForTests[],
 ): void {
diff --git a/src/plugin-state/plugin-state-store.test.ts b/src/plugin-state/plugin-state-store.test.ts
index 165456f8fcd..e2c43591bd2 100644
--- a/src/plugin-state/plugin-state-store.test.ts
+++ b/src/plugin-state/plugin-state-store.test.ts
@@ -15,6 +15,8 @@ import {
   createCorePluginStateSyncKeyedStore,
   createPluginStateKeyedStore,
   createPluginStateSyncKeyedStore,
+  pluginStateEntriesInKeyRange,
+  registerPluginStateSyncSequencedJournalEntry,
   resetPluginStateStoreForTests,
   sweepExpiredPluginStateEntries,
 } from "./plugin-state-store.js";
@@ -103,6 +105,29 @@ describe("plugin state keyed store", () => {
     });
   });
 
+  it("reads a bounded sortable key range without scanning sibling keys", async () => {
+    await withPluginStateTestState(async () => {
+      const store = createPluginStateSyncKeyedStore<{ count: number }>("memory-core", {
+        namespace: "events",
+        maxEntries: 10,
+      });
+      store.register("workspace:event:0001", { count: 1 });
+      store.register("workspace:event:0002", { count: 2 });
+      store.register("workspace:other:0003", { count: 3 });
+
+      expect(
+        pluginStateEntriesInKeyRange({
+          pluginId: "memory-core",
+          namespace: "events",
+          keyStartInclusive: "workspace:event:",
+          keyEndExclusive: "workspace:event;",
+          limit: 1,
+          order: "desc",
+        }),
+      ).toMatchObject([{ key: "workspace:event:0002", value: { count: 2 } }]);
+    });
+  });
+
   it("updates a key from the current stored value", async () => {
     await withPluginStateTestState(async () => {
       const store = createPluginStateSyncKeyedStore<{ count: number }>("discord", {
@@ -537,6 +562,74 @@ describe("plugin state keyed store", () => {
     });
   });
 
+  it("sheds sequenced journal rows without evicting durable sibling state", async () => {
+    await withPluginStateTestState(async () => {
+      const maxPluginEntries = 40;
+      setMaxPluginStateEntriesPerPluginForTests(maxPluginEntries);
+      seedPluginStateEntriesForTests([
+        ...Array.from({ length: maxPluginEntries - 3 }, (_, entryIndex) => ({
+          pluginId: "memory-core",
+          namespace: "durable-state",
+          key: `durable-${entryIndex}`,
+          value: { entryIndex },
+        })),
+        {
+          pluginId: "memory-core",
+          namespace: "memory-host.event-migration-checkpoints",
+          key: "generation",
+          value: { kind: "raw-checkpoint" },
+        },
+        {
+          pluginId: "memory-core",
+          namespace: "memory-host.event-cursors",
+          key: "workspace",
+          value: { kind: "cursor", lastSequence: 1 },
+        },
+        {
+          pluginId: "memory-core",
+          namespace: "memory-host.events",
+          key: "event-1",
+          value: { sequence: 1 },
+        },
+      ]);
+
+      expect(
+        registerPluginStateSyncSequencedJournalEntry({
+          pluginId: "memory-core",
+          cursorOptions: {
+            namespace: "memory-host.event-cursors",
+            maxEntries: 1_000,
+          },
+          cursorKey: "workspace",
+          journalOptions: { namespace: "memory-host.events", maxEntries: 10_000 },
+          initialSequence: 0,
+          journalKey: (sequence) => `event-${sequence}`,
+          journalValue: (sequence) => ({ sequence }),
+        }),
+      ).toBe(2);
+
+      const durable = createPluginStateKeyedStore("memory-core", {
+        namespace: "durable-state",
+        maxEntries: maxPluginEntries,
+      });
+      const checkpoints = createPluginStateKeyedStore("memory-core", {
+        namespace: "memory-host.event-migration-checkpoints",
+        maxEntries: 10_000,
+        overflowPolicy: "reject-new",
+      });
+      const journal = createPluginStateKeyedStore("memory-core", {
+        namespace: "memory-host.events",
+        maxEntries: 10_000,
+      });
+      await expect(durable.lookup("durable-0")).resolves.toEqual({ entryIndex: 0 });
+      await expect(checkpoints.lookup("generation")).resolves.toEqual({
+        kind: "raw-checkpoint",
+      });
+      await expect(journal.lookup("event-1")).resolves.toBeUndefined();
+      await expect(journal.lookup("event-2")).resolves.toEqual({ sequence: 2 });
+    });
+  });
+
   it("leaves room for Telegram sibling namespaces at their persistent budgets", async () => {
     await withPluginStateTestState(async () => {
       seedPluginStateEntriesForTests([
diff --git a/src/plugin-state/plugin-state-store.ts b/src/plugin-state/plugin-state-store.ts
index e9f7b0b434f..3cf3ed93fef 100644
--- a/src/plugin-state/plugin-state-store.ts
+++ b/src/plugin-state/plugin-state-store.ts
@@ -12,6 +12,7 @@ import {
   pluginStateLookup,
   pluginStateRegister,
   pluginStateRegisterIfAbsent,
+  pluginStateRegisterSequencedJournalEntry,
   pluginStateUpdate,
 } from "./plugin-state-store.sqlite.js";
 import type {
@@ -44,8 +45,10 @@ export type {
 export {
   closePluginStateDatabase,
   countPluginStateLiveEntries,
+  getPluginStateCapacity,
   isPluginStateDatabaseOpen,
   MAX_PLUGIN_STATE_ENTRIES_PER_PLUGIN,
+  pluginStateEntriesInKeyRange,
   resolveMaxPluginStateEntriesPerPlugin,
   sweepExpiredPluginStateEntries,
 } from "./plugin-state-store.sqlite.js";
@@ -62,6 +65,12 @@ type PreparedRegisterParams = {
   ttlMs?: number;
 };
 
+type PluginStateImportEntry = {
+  key: string;
+  value: unknown;
+  createdAt: number;
+};
+
 const namespaceOptionSignatures = new Map<string, StoreOptionSignature>();
 function invalidInput(
   message: string,
@@ -466,6 +475,121 @@ export function createPluginStateSyncKeyedStore<T>(
   return createSyncKeyedStoreForPluginId<T>(pluginId, options);
 }
 
+/** Atomically allocates a workspace sequence and appends one journal entry. */
+export function registerPluginStateSyncSequencedJournalEntry(params: {
+  pluginId: string;
+  cursorOptions: OpenKeyedStoreOptions;
+  cursorKey: string;
+  journalOptions: OpenKeyedStoreOptions;
+  initialSequence: number;
+  journalKey: (sequence: number) => string;
+  journalValue: (sequence: number) => unknown;
+}): number {
+  if (params.pluginId.startsWith("core:")) {
+    throw invalidInput("Plugin ids starting with 'core:' are reserved for core consumers.", "open");
+  }
+  if (!Number.isSafeInteger(params.initialSequence) || params.initialSequence < 0) {
+    throw invalidInput("plugin state initial journal sequence must be a safe non-negative integer");
+  }
+  const cursorNamespace = validateNamespace(params.cursorOptions.namespace);
+  const cursorMaxEntries = validateMaxEntries(params.cursorOptions.maxEntries);
+  const cursorOverflowPolicy = validateOverflowPolicy(params.cursorOptions.overflowPolicy);
+  const cursorDefaultTtlMs = validateOptionalTtlMs(params.cursorOptions.defaultTtlMs);
+  const journalNamespace = validateNamespace(params.journalOptions.namespace);
+  const journalMaxEntries = validateMaxEntries(params.journalOptions.maxEntries);
+  const journalOverflowPolicy = validateOverflowPolicy(params.journalOptions.overflowPolicy);
+  const journalDefaultTtlMs = validateOptionalTtlMs(params.journalOptions.defaultTtlMs);
+  if (
+    cursorOverflowPolicy !== "evict-oldest" ||
+    journalOverflowPolicy !== "evict-oldest" ||
+    cursorDefaultTtlMs !== undefined ||
+    journalDefaultTtlMs !== undefined
+  ) {
+    throw invalidInput("sequenced plugin state journals require non-expiring evict-oldest stores");
+  }
+  if (params.cursorOptions.env !== params.journalOptions.env) {
+    throw invalidInput("sequenced plugin state journal stores must share one environment");
+  }
+  const cursorKey = validateKey(params.cursorKey);
+  assertConsistentOptions(params.pluginId, cursorNamespace, {
+    maxEntries: cursorMaxEntries,
+    overflowPolicy: cursorOverflowPolicy,
+    defaultTtlMs: cursorDefaultTtlMs,
+  });
+  assertConsistentOptions(params.pluginId, journalNamespace, {
+    maxEntries: journalMaxEntries,
+    overflowPolicy: journalOverflowPolicy,
+    defaultTtlMs: journalDefaultTtlMs,
+  });
+  return pluginStateRegisterSequencedJournalEntry({
+    pluginId: params.pluginId,
+    cursorNamespace,
+    cursorKey,
+    cursorMaxEntries,
+    journalNamespace,
+    journalMaxEntries,
+    initialSequence: params.initialSequence,
+    readCursorSequence(valueJson) {
+      try {
+        const value = JSON.parse(valueJson) as { kind?: unknown; lastSequence?: unknown };
+        return value.kind === "cursor" && Number.isSafeInteger(value.lastSequence)
+          ? (value.lastSequence as number)
+          : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    prepareEntry(sequence) {
+      const cursor = prepareRegisterParams(cursorKey, { kind: "cursor", lastSequence: sequence });
+      const journal = prepareRegisterParams(
+        params.journalKey(sequence),
+        params.journalValue(sequence),
+      );
+      return {
+        cursorValueJson: cursor.valueJson,
+        journalKey: journal.key,
+        journalValueJson: journal.valueJson,
+      };
+    },
+    ...(params.cursorOptions.env ? { env: params.cursorOptions.env } : {}),
+  });
+}
+
+/** Doctor-only import that preserves source age for retention ordering. */
+export function importPluginStateEntriesForDoctor(
+  pluginId: string,
+  options: OpenKeyedStoreOptions,
+  entries: readonly PluginStateImportEntry[],
+): void {
+  if (pluginId.startsWith("core:")) {
+    throw invalidInput("Plugin ids starting with 'core:' are reserved for core consumers.", "open");
+  }
+  const namespace = validateNamespace(options.namespace);
+  const maxEntries = validateMaxEntries(options.maxEntries);
+  const overflowPolicy = validateOverflowPolicy(options.overflowPolicy);
+  const defaultTtlMs = validateOptionalTtlMs(options.defaultTtlMs);
+  const env = options.env;
+  assertConsistentOptions(pluginId, namespace, { maxEntries, overflowPolicy, defaultTtlMs });
+
+  for (const entry of entries) {
+    if (!Number.isSafeInteger(entry.createdAt)) {
+      throw invalidInput("plugin state import createdAt must be a safe integer", "register");
+    }
+    const prepared = prepareRegisterParams(entry.key, entry.value, defaultTtlMs);
+    pluginStateRegister({
+      pluginId,
+      namespace,
+      key: prepared.key,
+      valueJson: prepared.valueJson,
+      maxEntries,
+      overflowPolicy,
+      createdAtMs: entry.createdAt,
+      ...(env ? { env } : {}),
+      ...(prepared.ttlMs != null ? { ttlMs: prepared.ttlMs } : {}),
+    });
+  }
+}
+
 /** Opens a sync plugin-state namespace for a trusted core owner id. */
 export function createCorePluginStateSyncKeyedStore<T>(
   options: OpenKeyedStoreOptions & { ownerId: `core:${string}` },
diff --git a/src/plugins/doctor-contract-registry.ts b/src/plugins/doctor-contract-registry.ts
index 44c23e12398..13cf0e2686a 100644
--- a/src/plugins/doctor-contract-registry.ts
+++ b/src/plugins/doctor-contract-registry.ts
@@ -59,11 +59,20 @@ export type PluginDoctorStateMigrationDetection = {
 
 export type PluginDoctorStateMigrationContext = {
   openPluginStateKeyedStore: <T>(options: OpenKeyedStoreOptions) => PluginStateKeyedStore<T>;
+  /** Doctor-only batch import preserving source age for retention ordering. */
+  importPluginStateEntries?: (
+    options: OpenKeyedStoreOptions,
+    entries: readonly { key: string; value: unknown; createdAt: number }[],
+  ) => void;
+  /** Plugin-wide live-row capacity for import preflight. Older test hosts may omit it. */
+  getPluginStateCapacity?: () => { liveEntries: number; maxEntries: number };
 };
 
 export type PluginDoctorStateMigration = {
   id: string;
   label: string;
+  /** Import retired file state only during explicit `doctor --fix` repair. */
+  doctorOnly?: boolean;
   detectLegacyState: (params: {
     config: OpenClawConfig;
     env: NodeJS.ProcessEnv;
@@ -216,6 +225,7 @@ function coercePluginDoctorStateMigrations(value: unknown): PluginDoctorStateMig
   return value.filter(isPluginDoctorStateMigration).map((migration) => ({
     id: migration.id.trim(),
     label: migration.label.trim(),
+    doctorOnly: migration.doctorOnly === true ? true : undefined,
     detectLegacyState: migration.detectLegacyState,
     migrateLegacyState: migration.migrateLegacyState,
   }));
diff --git a/src/state/openclaw-agent-db.generated.d.ts b/src/state/openclaw-agent-db.generated.d.ts
index 2aa6b51ddcc..d27589adf05 100644
--- a/src/state/openclaw-agent-db.generated.d.ts
+++ b/src/state/openclaw-agent-db.generated.d.ts
@@ -10,6 +10,14 @@ export type Generated<T> =
     ? ColumnType<S, I | undefined, U>
     : ColumnType<T, T | undefined, T>;
 
+export interface AcpParentStreamEvents {
+  created_at: number;
+  event_json: string;
+  run_id: string;
+  seq: number;
+  session_id: string;
+}
+
 export interface AuthProfileState {
   state_json: string;
   state_key: string;
@@ -278,6 +286,7 @@ export interface TranscriptEvents {
 }
 
 export interface DB {
+  acp_parent_stream_events: AcpParentStreamEvents;
   auth_profile_state: AuthProfileState;
   auth_profile_store: AuthProfileStore;
   cache_entries: CacheEntries;
diff --git a/src/state/openclaw-agent-db.test.ts b/src/state/openclaw-agent-db.test.ts
index 217cd74329b..ea6c81156a9 100644
--- a/src/state/openclaw-agent-db.test.ts
+++ b/src/state/openclaw-agent-db.test.ts
@@ -513,8 +513,8 @@ describe("openclaw agent database", () => {
     expect(registered?.sizeBytes).toBeGreaterThan(0);
   });
 
-  it("folds additive heartbeat storage into schema version 11", () => {
-    expect(OPENCLAW_AGENT_SCHEMA_VERSION).toBe(11);
+  it("keeps additive heartbeat repair while upgrading schema version 11", () => {
+    expect(OPENCLAW_AGENT_SCHEMA_VERSION).toBe(12);
     const stateDir = createTempStateDir();
     const env = { OPENCLAW_STATE_DIR: stateDir };
     const opened = openOpenClawAgentDatabase({ agentId: "worker-1", env });
@@ -536,12 +536,12 @@ describe("openclaw agent database", () => {
         .prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name = ?")
         .get("heartbeat_outcomes"),
     ).toEqual({ name: "heartbeat_outcomes" });
-    expect(readSqliteNumberPragma(reopened.db, "user_version")).toBe(11);
+    expect(readSqliteNumberPragma(reopened.db, "user_version")).toBe(OPENCLAW_AGENT_SCHEMA_VERSION);
     expect(
       reopened.db
         .prepare("SELECT schema_version FROM schema_meta WHERE meta_key = 'primary'")
         .get(),
-    ).toEqual({ schema_version: 11 });
+    ).toEqual({ schema_version: OPENCLAW_AGENT_SCHEMA_VERSION });
   });
 
   it("upgrades version 10 with agent state intact and adds lease storage", () => {
@@ -589,6 +589,47 @@ describe("openclaw agent database", () => {
     ).toEqual({ name: "state_leases" });
   });
 
+  it("upgrades version 11 with agent state intact and adds ACP parent-stream storage", () => {
+    const stateDir = createTempStateDir();
+    const env = { OPENCLAW_STATE_DIR: stateDir };
+    const opened = openOpenClawAgentDatabase({ agentId: "worker-1", env });
+    const databasePath = opened.path;
+    opened.db
+      .prepare(
+        "INSERT INTO auth_profile_state (state_key, state_json, updated_at) VALUES (?, ?, ?)",
+      )
+      .run("last-good", '{"profile":"primary"}', 10);
+    closeOpenClawAgentDatabasesForTest();
+    closeOpenClawStateDatabaseForTest();
+
+    const { DatabaseSync } = requireNodeSqlite();
+    const legacy = new DatabaseSync(databasePath);
+    legacy.exec(`
+      DROP INDEX idx_agent_acp_parent_stream_run;
+      DROP TABLE acp_parent_stream_events;
+      PRAGMA user_version = 11;
+      UPDATE schema_meta SET schema_version = 11 WHERE meta_key = 'primary';
+    `);
+    legacy.close();
+
+    const migrated = openOpenClawAgentDatabase({ agentId: "worker-1", env });
+    expect(migrated.db.prepare("PRAGMA user_version").get()).toEqual({
+      user_version: OPENCLAW_AGENT_SCHEMA_VERSION,
+    });
+    expect(
+      migrated.db
+        .prepare("SELECT state_json FROM auth_profile_state WHERE state_key = ?")
+        .get("last-good"),
+    ).toEqual({ state_json: '{"profile":"primary"}' });
+    expect(
+      migrated.db
+        .prepare(
+          "SELECT name FROM sqlite_schema WHERE type = 'table' AND name = 'acp_parent_stream_events'",
+        )
+        .get(),
+    ).toEqual({ name: "acp_parent_stream_events" });
+  });
+
   it("migrates version 8 tables to STRICT without losing agent state", () => {
     const stateDir = createTempStateDir();
     const env = { OPENCLAW_STATE_DIR: stateDir };
diff --git a/src/state/openclaw-agent-db.ts b/src/state/openclaw-agent-db.ts
index f69702dad4c..8f12922b308 100644
--- a/src/state/openclaw-agent-db.ts
+++ b/src/state/openclaw-agent-db.ts
@@ -83,6 +83,7 @@ export { resolveOpenClawAgentSqlitePath } from "./openclaw-agent-db.paths.js";
  * per pathname, protected with private file modes, and registered in the shared
  * OpenClaw state database for discovery and maintenance.
  */
+// v12 = session-owned ACP parent-stream events.
 // v11 = agent-scoped runtime leases, durable delivery operations, canonical
 // external conversation addresses, and bounded per-session heartbeat outcome context.
 // v10 = materialized active transcript paths.
@@ -93,7 +94,7 @@ export { resolveOpenClawAgentSqlitePath } from "./openclaw-agent-db.paths.js";
 // The v4 session/transcript flip and main's v2 memory-identity
 // change is folded in structure-gated (migrateMemoryIndexSourcesIdentity), so
 // v2 main DBs and pre-merge v4 flip DBs both converge on this schema.
-export const OPENCLAW_AGENT_SCHEMA_VERSION = 11;
+export const OPENCLAW_AGENT_SCHEMA_VERSION = 12;
 const OPENCLAW_AGENT_DB_DIR_MODE = 0o700;
 const OPENCLAW_AGENT_DB_FILE_MODE = 0o600;
 const OPENCLAW_AGENT_DB_SLOW_OPEN_MS = 1_000;
diff --git a/src/state/openclaw-agent-schema.generated.ts b/src/state/openclaw-agent-schema.generated.ts
index 3f4692b4f19..0796f5fa95f 100644
--- a/src/state/openclaw-agent-schema.generated.ts
+++ b/src/state/openclaw-agent-schema.generated.ts
@@ -222,6 +222,19 @@ CREATE INDEX IF NOT EXISTS idx_agent_trajectory_runtime_run
   ON trajectory_runtime_events(session_id, run_id, seq)
   WHERE run_id IS NOT NULL;
 
+CREATE TABLE IF NOT EXISTS acp_parent_stream_events (
+  session_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  event_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (session_id, run_id, seq),
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_agent_acp_parent_stream_run
+  ON acp_parent_stream_events(run_id, seq);
+
 CREATE TABLE IF NOT EXISTS transcript_event_identities (
   session_id TEXT NOT NULL,
   event_id TEXT NOT NULL,
diff --git a/src/state/openclaw-agent-schema.sql b/src/state/openclaw-agent-schema.sql
index a46b1697100..1df4c9b2df5 100644
--- a/src/state/openclaw-agent-schema.sql
+++ b/src/state/openclaw-agent-schema.sql
@@ -217,6 +217,19 @@ CREATE INDEX IF NOT EXISTS idx_agent_trajectory_runtime_run
   ON trajectory_runtime_events(session_id, run_id, seq)
   WHERE run_id IS NOT NULL;
 
+CREATE TABLE IF NOT EXISTS acp_parent_stream_events (
+  session_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  event_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY (session_id, run_id, seq),
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_agent_acp_parent_stream_run
+  ON acp_parent_stream_events(run_id, seq);
+
 CREATE TABLE IF NOT EXISTS transcript_event_identities (
   session_id TEXT NOT NULL,
   event_id TEXT NOT NULL,
diff --git a/src/state/openclaw-state-db.generated.d.ts b/src/state/openclaw-state-db.generated.d.ts
index 7c5fc0ad667..0f755917944 100644
--- a/src/state/openclaw-state-db.generated.d.ts
+++ b/src/state/openclaw-state-db.generated.d.ts
@@ -501,6 +501,7 @@ export interface DiagnosticEvents {
   event_key: string;
   payload_json: string;
   scope: string;
+  sequence: Generated<number>;
 }
 
 export interface DiagnosticStabilityBundles {
diff --git a/src/state/openclaw-state-db.test.ts b/src/state/openclaw-state-db.test.ts
index 1d54472345e..9c7ce90d9ab 100644
--- a/src/state/openclaw-state-db.test.ts
+++ b/src/state/openclaw-state-db.test.ts
@@ -2336,6 +2336,56 @@ describe("openclaw state database", () => {
     );
   });
 
+  it("backfills diagnostic event sequences in legacy creation order", () => {
+    const stateDir = createTempStateDir();
+    const options = { env: { OPENCLAW_STATE_DIR: stateDir } };
+    const databasePath = openOpenClawStateDatabase(options).path;
+    closeOpenClawStateDatabaseForTest();
+
+    const { DatabaseSync } = requireNodeSqlite();
+    const legacyDb = new DatabaseSync(databasePath);
+    legacyDb.exec(`
+      DROP INDEX idx_diagnostic_events_scope_sequence;
+      ALTER TABLE diagnostic_events DROP COLUMN sequence;
+      CREATE INDEX idx_diagnostic_events_scope_created
+        ON diagnostic_events(scope, created_at, event_key);
+      INSERT INTO diagnostic_events (scope, event_key, payload_json, created_at) VALUES
+        ('alpha', 'late', '{}', 20),
+        ('alpha', 'tie-first', '{}', 10),
+        ('alpha', 'tie-second', '{}', 10),
+        ('beta', 'only', '{}', 30);
+    `);
+    legacyDb.close();
+
+    const reopened = openOpenClawStateDatabase(options);
+    const rows = reopened.db
+      .prepare(
+        `SELECT scope, event_key, sequence
+           FROM diagnostic_events
+          ORDER BY scope, sequence`,
+      )
+      .all();
+    expect(rows).toEqual([
+      { scope: "alpha", event_key: "tie-first", sequence: 1 },
+      { scope: "alpha", event_key: "tie-second", sequence: 2 },
+      { scope: "alpha", event_key: "late", sequence: 3 },
+      { scope: "beta", event_key: "only", sequence: 1 },
+    ]);
+    const indexes = reopened.db.prepare("PRAGMA index_list(diagnostic_events)").all() as Array<{
+      name?: unknown;
+    }>;
+    expect(indexes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "idx_diagnostic_events_scope_sequence" }),
+      ]),
+    );
+    expect(indexes).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "idx_diagnostic_events_scope_created" }),
+      ]),
+    );
+  });
+
   it("adds relay origins to existing APNs registration tables", () => {
     const stateDir = createTempStateDir();
     const options = { env: { OPENCLAW_STATE_DIR: stateDir } };
diff --git a/src/state/openclaw-state-db.ts b/src/state/openclaw-state-db.ts
index bbe873981a8..f41892ac3db 100644
--- a/src/state/openclaw-state-db.ts
+++ b/src/state/openclaw-state-db.ts
@@ -94,6 +94,7 @@ const OPENCLAW_STATE_CANONICAL_UNIQUE_INDEXES = [
 ] as const satisfies readonly CanonicalSqliteUniqueIndex[];
 const OPENCLAW_STATE_MAINTENANCE_SCHEMA_COMPATIBILITY = {
   allowedColumnDefinitions: {
+    "diagnostic_events.sequence": ["sequence INTEGER NOT NULL DEFAULT 0"],
     "commitments.attempts": ["attempts INTEGER NOT NULL DEFAULT 0"],
     "commitments.confidence": ["confidence REAL NOT NULL DEFAULT 0"],
     "commitments.created_at_ms": ["created_at_ms INTEGER NOT NULL DEFAULT 0"],
@@ -1446,6 +1447,33 @@ function backfillDeliveryQueueEntriesFromEntryJson(db: DatabaseSync): void {
 // The caller owns the state.schema.ensure transaction so every probe, DDL
 // change, and backfill observes one authoritative schema across processes.
 function ensureAdditiveStateColumns(db: DatabaseSync): void {
+  const addedDiagnosticEventSequence = ensureColumn(
+    db,
+    "diagnostic_events",
+    "sequence INTEGER NOT NULL DEFAULT 0",
+  );
+  if (addedDiagnosticEventSequence) {
+    // Preserve the legacy (created_at, rowid) order before the new sequence
+    // index becomes authoritative, including stable ties within each scope.
+    db.exec(`
+      WITH ranked AS (
+        SELECT
+          rowid AS event_rowid,
+          ROW_NUMBER() OVER (
+            PARTITION BY scope
+            ORDER BY created_at ASC, rowid ASC
+          ) AS sequence
+        FROM diagnostic_events
+      )
+      UPDATE diagnostic_events
+      SET sequence = (
+        SELECT ranked.sequence
+        FROM ranked
+        WHERE ranked.event_rowid = diagnostic_events.rowid
+      );
+    `);
+  }
+  db.exec("DROP INDEX IF EXISTS idx_diagnostic_events_scope_created;");
   ensureColumn(db, "worktrees", "provisioned_paths_json TEXT");
   ensureColumn(db, "node_host_config", "gateway_context_path TEXT");
   ensureColumn(db, "node_host_config", "installed_apps_sharing INTEGER NOT NULL DEFAULT 0");
diff --git a/src/state/openclaw-state-lease.ts b/src/state/openclaw-state-lease.ts
index 43cfb8cf15a..310bf2bd894 100644
--- a/src/state/openclaw-state-lease.ts
+++ b/src/state/openclaw-state-lease.ts
@@ -18,13 +18,16 @@ import type { DB as OpenClawStateKyselyDatabase } from "./openclaw-state-db.gene
 import {
   openOpenClawStateDatabase,
   runOpenClawStateWriteTransaction,
+  type OpenClawStateDatabaseOptions,
 } from "./openclaw-state-db.js";
 
 type LeaseDatabase = Pick<OpenClawStateKyselyDatabase, "state_leases">;
 type AgentLeaseDatabase = Pick<OpenClawAgentKyselyDatabase, "state_leases">;
 type LeaseKysely = ReturnType<typeof getNodeSqliteKysely<LeaseDatabase>>;
 
-type OpenClawStateLeaseDatabase = { scope: "shared" } | { scope: "agent"; agentId: string };
+type OpenClawStateLeaseDatabase =
+  | { scope: "shared"; options?: OpenClawStateDatabaseOptions }
+  | { scope: "agent"; agentId: string };
 
 type OpenClawStateLeaseOptions = {
   scope: string;
@@ -175,11 +178,11 @@ function withLeaseWriteTransaction<T>(
   busyTimeoutMs = LEASE_DB_BUSY_TIMEOUT_MS,
 ): T {
   if (database.scope === "shared") {
-    const stateDatabase = openOpenClawStateDatabase();
+    const stateDatabase = openOpenClawStateDatabase(database.options);
     const run = () =>
       runOpenClawStateWriteTransaction(
         ({ db }) => operation(db, getNodeSqliteKysely<LeaseDatabase>(db)),
-        {},
+        database.options,
         { operationLabel, busyTimeoutMs },
       );
     return withBusyTimeout(stateDatabase.db, busyTimeoutMs, run);
@@ -200,7 +203,7 @@ function withLeaseRead<T>(
 ): T {
   const sqlite =
     database.scope === "shared"
-      ? openOpenClawStateDatabase().db
+      ? openOpenClawStateDatabase(database.options).db
       : openOpenClawAgentDatabase({ agentId: database.agentId }).db;
   return operation(sqlite, getNodeSqliteKysely<LeaseDatabase>(sqlite));
 }
diff --git a/src/state/openclaw-state-schema.generated.ts b/src/state/openclaw-state-schema.generated.ts
index 966ee121629..ddbd5be2e03 100644
--- a/src/state/openclaw-state-schema.generated.ts
+++ b/src/state/openclaw-state-schema.generated.ts
@@ -27,11 +27,12 @@ CREATE TABLE IF NOT EXISTS diagnostic_events (
   event_key TEXT NOT NULL,
   payload_json TEXT NOT NULL,
   created_at INTEGER NOT NULL,
+  sequence INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY (scope, event_key)
 ) STRICT;
 
-CREATE INDEX IF NOT EXISTS idx_diagnostic_events_scope_created
-  ON diagnostic_events(scope, created_at, event_key);
+CREATE INDEX IF NOT EXISTS idx_diagnostic_events_scope_sequence
+  ON diagnostic_events(scope, sequence, event_key);
 
 CREATE TABLE IF NOT EXISTS skill_usage (
   skill_file TEXT NOT NULL PRIMARY KEY,
diff --git a/src/state/openclaw-state-schema.sql b/src/state/openclaw-state-schema.sql
index bf7b2548c7f..e7f1d957890 100644
--- a/src/state/openclaw-state-schema.sql
+++ b/src/state/openclaw-state-schema.sql
@@ -22,11 +22,12 @@ CREATE TABLE IF NOT EXISTS diagnostic_events (
   event_key TEXT NOT NULL,
   payload_json TEXT NOT NULL,
   created_at INTEGER NOT NULL,
+  sequence INTEGER NOT NULL DEFAULT 0,
   PRIMARY KEY (scope, event_key)
 ) STRICT;
 
-CREATE INDEX IF NOT EXISTS idx_diagnostic_events_scope_created
-  ON diagnostic_events(scope, created_at, event_key);
+CREATE INDEX IF NOT EXISTS idx_diagnostic_events_scope_sequence
+  ON diagnostic_events(scope, sequence, event_key);
 
 CREATE TABLE IF NOT EXISTS skill_usage (
   skill_file TEXT NOT NULL PRIMARY KEY,
diff --git a/src/system-agent/audit.test-support.ts b/src/system-agent/audit.test-support.ts
new file mode 100644
index 00000000000..6ea2a4ca58c
--- /dev/null
+++ b/src/system-agent/audit.test-support.ts
@@ -0,0 +1,14 @@
+import { createSqliteAuditRecordStore } from "../infra/sqlite-audit-record-store.js";
+import {
+  SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+  SYSTEM_AGENT_AUDIT_SCOPE,
+  type SystemAgentAuditEntry,
+} from "./audit.js";
+
+export function listSystemAgentAuditEntriesForTests(params?: { env?: NodeJS.ProcessEnv }) {
+  return createSqliteAuditRecordStore<SystemAgentAuditEntry>({
+    scope: SYSTEM_AGENT_AUDIT_SCOPE,
+    maxEntries: SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+    ...(params?.env ? { env: params.env } : {}),
+  }).entries();
+}
diff --git a/src/system-agent/audit.test.ts b/src/system-agent/audit.test.ts
index 6a14181393a..3c816133a7f 100644
--- a/src/system-agent/audit.test.ts
+++ b/src/system-agent/audit.test.ts
@@ -1,13 +1,15 @@
-// OpenClaw audit tests cover filesystem-backed rescue audit scenarios.
-import fs from "node:fs/promises";
+// OpenClaw audit tests cover SQLite-backed rescue audit scenarios.
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import { withTempDir } from "../test-helpers/temp-dir.js";
-import { appendSystemAgentAuditEntry, resolveSystemAgentAuditPath } from "./audit.js";
+import { appendSystemAgentAuditEntry, SYSTEM_AGENT_AUDIT_STORE_LABEL } from "./audit.js";
+import { listSystemAgentAuditEntriesForTests } from "./audit.test-support.js";
 
 describe("OpenClaw audit log", () => {
   const previousStateDir = process.env.OPENCLAW_STATE_DIR;
 
   afterEach(() => {
+    resetPluginStateStoreForTests();
     if (previousStateDir === undefined) {
       delete process.env.OPENCLAW_STATE_DIR;
     } else {
@@ -15,21 +17,25 @@ describe("OpenClaw audit log", () => {
     }
   });
 
-  it("writes jsonl records under the OpenClaw audit dir", async () => {
+  it("writes records into shared SQLite state", async () => {
     await withTempDir({ prefix: "openclaw-audit-" }, async (tempDir) => {
       vi.stubEnv("OPENCLAW_STATE_DIR", tempDir);
 
-      const auditPath = await appendSystemAgentAuditEntry({
+      const auditStore = await appendSystemAgentAuditEntry({
         operation: "config.setDefaultModel",
         summary: "Set default model to openai/gpt-5.2",
         configHashBefore: "before",
         configHashAfter: "after",
       });
 
-      expect(auditPath).toBe(resolveSystemAgentAuditPath());
-      const lines = (await fs.readFile(auditPath, "utf8")).trim().split("\n");
-      expect(lines).toHaveLength(1);
-      const entry = JSON.parse(lines[0] ?? "{}") as Record<string, unknown>;
+      expect(auditStore).toBe(SYSTEM_AGENT_AUDIT_STORE_LABEL);
+      const records = listSystemAgentAuditEntriesForTests();
+      expect(records).toHaveLength(1);
+      const entry = records[0]?.value;
+      expect(entry).toBeDefined();
+      if (!entry) {
+        throw new Error("expected persisted system-agent audit entry");
+      }
       expect(entry.operation).toBe("config.setDefaultModel");
       expect(entry.summary).toBe("Set default model to openai/gpt-5.2");
       expect(entry.configHashBefore).toBe("before");
diff --git a/src/system-agent/audit.ts b/src/system-agent/audit.ts
index effa5d6c474..eb23820d55e 100644
--- a/src/system-agent/audit.ts
+++ b/src/system-agent/audit.ts
@@ -1,16 +1,15 @@
-// OpenClaw audit helpers append JSONL records for approved local-state changes.
-import fs from "node:fs/promises";
-import path from "node:path";
-import { resolveStateDir } from "../config/paths.js";
-import { appendRegularFile } from "../infra/fs-safe.js";
+// OpenClaw audit helpers persist approved local-state changes.
+import { randomUUID } from "node:crypto";
+import { createSqliteAuditRecordStore } from "../infra/sqlite-audit-record-store.js";
+import { redactSecrets } from "../logging/redact.js";
 
 /**
  * Append-only audit log helpers for OpenClaw writes.
  *
  * Discovery and read-only commands stay quiet; persistent operations append a
- * JSONL entry under the state directory with config hashes and redacted details.
+ * SQLite entry under the shared state directory with config hashes and redacted details.
  */
-type SystemAgentAuditEntry = {
+export type SystemAgentAuditEntry = {
   timestamp: string;
   operation: string;
   summary: string;
@@ -20,30 +19,32 @@ type SystemAgentAuditEntry = {
   details?: Record<string, unknown>;
 };
 
-/** Resolve the JSONL audit path for OpenClaw persistent operations. */
-export function resolveSystemAgentAuditPath(
-  env: NodeJS.ProcessEnv = process.env,
-  stateDir = resolveStateDir(env),
-): string {
-  return path.join(stateDir, "audit", "system-agent.jsonl");
+export const SYSTEM_AGENT_AUDIT_SCOPE = "system-agent-audit";
+export const SYSTEM_AGENT_AUDIT_MAX_ENTRIES = 50_000;
+export const SYSTEM_AGENT_AUDIT_STORE_LABEL =
+  "SQLite diagnostic_events/system-agent-audit state (latest 50000 rows)";
+
+function openSystemAgentAuditStore(env?: NodeJS.ProcessEnv) {
+  return createSqliteAuditRecordStore<SystemAgentAuditEntry>({
+    scope: SYSTEM_AGENT_AUDIT_SCOPE,
+    maxEntries: SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+    ...(env ? { env } : {}),
+  });
 }
 
-/** Append one OpenClaw audit entry and return the file path written. */
+/** Append one OpenClaw audit entry and return its SQLite owner label. */
 export async function appendSystemAgentAuditEntry(
   entry: Omit<SystemAgentAuditEntry, "timestamp">,
-  opts: { env?: NodeJS.ProcessEnv; auditPath?: string } = {},
+  opts: { env?: NodeJS.ProcessEnv } = {},
 ): Promise<string> {
-  const auditPath = opts.auditPath ?? resolveSystemAgentAuditPath(opts.env);
-  await fs.mkdir(path.dirname(auditPath), { recursive: true });
-  const line = JSON.stringify({
+  const record = redactSecrets({
     timestamp: new Date().toISOString(),
     ...entry,
   } satisfies SystemAgentAuditEntry);
-  // Audit writes reject symlinked parents so approval records cannot be redirected silently.
-  await appendRegularFile({
-    filePath: auditPath,
-    content: `${line}\n`,
-    rejectSymlinkParents: true,
-  });
-  return auditPath;
+  openSystemAgentAuditStore(opts.env).register(
+    `${record.timestamp}:${randomUUID()}`,
+    record,
+    Date.parse(record.timestamp),
+  );
+  return SYSTEM_AGENT_AUDIT_STORE_LABEL;
 }
diff --git a/src/system-agent/operations-execute.ts b/src/system-agent/operations-execute.ts
index 33f147c41b0..37b979c490d 100644
--- a/src/system-agent/operations-execute.ts
+++ b/src/system-agent/operations-execute.ts
@@ -5,7 +5,7 @@ import type { RuntimeEnv } from "../runtime.js";
 import { resolveUserPath, shortenHomePath } from "../utils.js";
 import { t } from "../wizard/i18n/index.js";
 import { isReservedSystemAgentId } from "./agent-id.js";
-import { resolveSystemAgentAuditPath } from "./audit.js";
+import { SYSTEM_AGENT_AUDIT_STORE_LABEL } from "./audit.js";
 import {
   CONFIG_GET_OUTPUT_MAX_CHARS,
   CONFIG_SCHEMA_CHILDREN_MAX,
@@ -108,7 +108,7 @@ export async function executeSystemAgentOperation(
       return { applied: false };
     }
     case "audit":
-      runtime.log(`Audit log: ${resolveSystemAgentAuditPath()}`);
+      runtime.log(`Audit state: ${SYSTEM_AGENT_AUDIT_STORE_LABEL}`);
       runtime.log("Only applied writes/actions are recorded; discovery stays quiet.");
       return { applied: false };
     case "config-validate": {
diff --git a/src/system-agent/operations.setup.test.ts b/src/system-agent/operations.setup.test.ts
index 6eb5fd6a9aa..55b6de9ea06 100644
--- a/src/system-agent/operations.setup.test.ts
+++ b/src/system-agent/operations.setup.test.ts
@@ -3,19 +3,17 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import { captureEnv, setTestEnvValue } from "../test-utils/env.js";
+import { listSystemAgentAuditEntriesForTests } from "./audit.test-support.js";
 import { SystemAgentInferenceUnavailableError } from "./inference-error.js";
 import { executeSystemAgentOperation, isPersistentSystemAgentOperation } from "./operations.js";
 import { createSystemAgentTestRuntime } from "./system-agent.test-helpers.js";
 
 type TestConfig = Record<string, unknown>;
 
-function parseLastJsonLine(raw: string): unknown {
-  const lastLine = raw.trim().split("\n").at(-1);
-  if (!lastLine) {
-    throw new Error("Expected audit log to contain at least one JSON line");
-  }
-  return JSON.parse(lastLine) as unknown;
+function readLastAuditEntry(): unknown {
+  return listSystemAgentAuditEntriesForTests().at(-1)?.value;
 }
 
 function requireRecord(value: unknown, label: string): Record<string, unknown> {
@@ -172,6 +170,7 @@ describe("parseSystemAgentOperation", () => {
   });
 
   afterEach(() => {
+    resetPluginStateStoreForTests();
     stateDirSnapshot?.restore();
     vi.unstubAllEnvs();
   });
@@ -232,8 +231,7 @@ describe("parseSystemAgentOperation", () => {
       { commit: expect.any(Function) },
     );
     expect(lines.join("\n")).toContain("Default model: openai/gpt-5.5 (verified and kept)");
-    const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-    const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim());
+    const audit = readLastAuditEntry();
     expectAuditRecord(
       audit,
       {
@@ -556,9 +554,7 @@ describe("parseSystemAgentOperation", () => {
     expect(persisted.channels).toEqual({ telegram: { enabled: true } });
     expect(lines.join("\n")).toContain("Default model: openai/gpt-5.5");
 
-    const audit = parseLastJsonLine(
-      await fs.readFile(path.join(tempDir, "audit", "system-agent.jsonl"), "utf8"),
-    );
+    const audit = readLastAuditEntry();
     expectAuditRecord(
       audit,
       {
diff --git a/src/system-agent/operations.test.ts b/src/system-agent/operations.test.ts
index 2f0a508b996..ba5fce87bd0 100644
--- a/src/system-agent/operations.test.ts
+++ b/src/system-agent/operations.test.ts
@@ -3,8 +3,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.js";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { captureEnv, setTestEnvValue } from "../test-utils/env.js";
+import { listSystemAgentAuditEntriesForTests } from "./audit.test-support.js";
 import {
   describeSystemAgentPersistentOperation,
   executeSystemAgentOperation,
@@ -38,6 +40,10 @@ function expectAuditRecord(
   expectRecordFields(requireRecord(auditRecord.details, "audit details"), detailFields);
 }
 
+function readLastAuditEntry(): unknown {
+  return listSystemAgentAuditEntriesForTests().at(-1)?.value;
+}
+
 function requireFirstMockCall(mock: unknown, label: string): unknown[] {
   const call = (mock as { mock?: { calls?: unknown[][] } }).mock?.calls?.[0];
   if (!call) {
@@ -181,6 +187,7 @@ describe("parseSystemAgentOperation", () => {
   });
 
   afterEach(() => {
+    resetPluginStateStoreForTests();
     stateDirSnapshot?.restore();
     vi.unstubAllEnvs();
   });
@@ -624,8 +631,7 @@ describe("parseSystemAgentOperation", () => {
       cliOptions: {},
     });
     expect(lines.join("\n")).toContain("[openclaw] done: config.set");
-    const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-    const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim());
+    const audit = readLastAuditEntry();
     expectAuditRecord(
       audit,
       { operation: "config.set", summary: "Set config gateway.port" },
@@ -637,7 +643,7 @@ describe("parseSystemAgentOperation", () => {
     );
   });
 
-  it("reports an audit failure without claiming the committed operation failed", async () => {
+  it("records SQLite audit state despite a retired audit-directory symlink", async () => {
     const tempDir = opTempDirs.make("openclaw-audit-warning-");
     setTestEnvValue("OPENCLAW_STATE_DIR", tempDir);
     const redirectedAuditDir = path.join(tempDir, "redirected-audit");
@@ -654,9 +660,7 @@ describe("parseSystemAgentOperation", () => {
 
     expect(result.applied).toBe(true);
     expect(runConfigSet).toHaveBeenCalledOnce();
-    expect(lines.join("\n")).toContain(
-      "Set config gateway.port, but OpenClaw could not record its audit entry:",
-    );
+    expect(readLastAuditEntry()).toMatchObject({ operation: "config.set" });
     expect(lines.join("\n")).toContain("[openclaw] done: config.set");
   });
 
@@ -691,8 +695,7 @@ describe("parseSystemAgentOperation", () => {
       },
     });
     expect(lines.join("\n")).toContain("[openclaw] done: config.setRef");
-    const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-    const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim());
+    const audit = readLastAuditEntry();
     expectAuditRecord(
       audit,
       {
@@ -938,8 +941,7 @@ describe("parseSystemAgentOperation", () => {
     expect(installCall[0]).toBe("clawhub:openclaw-demo");
     expectRuntimeArg(installCall[1]);
     expect(lines.join("\n")).toContain("[openclaw] done: plugin.install");
-    const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-    const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim());
+    const audit = readLastAuditEntry();
     expectAuditRecord(
       audit,
       {
diff --git a/src/system-agent/rescue-channel.live.test.ts b/src/system-agent/rescue-channel.live.test.ts
index ab43fd616f2..3a022e09188 100644
--- a/src/system-agent/rescue-channel.live.test.ts
+++ b/src/system-agent/rescue-channel.live.test.ts
@@ -5,8 +5,10 @@ import { afterEach, describe, expect, it } from "vitest";
 import type { CommandContext } from "../auto-reply/reply/commands-types.js";
 import { clearConfigCache } from "../config/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { resetPluginStateStoreForTests } from "../plugin-state/plugin-state-store.js";
 import { withTempDir } from "../test-helpers/temp-dir.js";
 import { deleteTestEnvValue, setTestEnvValue } from "../test-utils/env.js";
+import { listSystemAgentAuditEntriesForTests } from "./audit.test-support.js";
 import { runSystemAgentRescueMessage } from "./rescue-message.js";
 
 const originalStateDir = process.env.OPENCLAW_STATE_DIR;
@@ -53,6 +55,7 @@ async function runRescue(params: {
 
 describeLive("OpenClaw live rescue channel smoke", () => {
   afterEach(() => {
+    resetPluginStateStoreForTests();
     clearConfigCache();
     if (originalStateDir === undefined) {
       deleteTestEnvValue("OPENCLAW_STATE_DIR");
@@ -105,11 +108,11 @@ describeLive("OpenClaw live rescue channel smoke", () => {
         throw new Error("expected default model object");
       }
       expect(defaultModel.primary).toBe("openai/gpt-5.5");
-      const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-      const auditLines = (await fs.readFile(auditPath, "utf8")).trim().split("\n");
-      expect(auditLines.some((line) => line.includes('"operation":"config.setDefaultModel"'))).toBe(
-        true,
-      );
+      expect(
+        listSystemAgentAuditEntriesForTests().some(
+          (entry) => entry.value.operation === "config.setDefaultModel",
+        ),
+      ).toBe(true);
     });
   });
 });
diff --git a/src/system-agent/rescue-message.test.ts b/src/system-agent/rescue-message.test.ts
index 29b225dcf77..acb09d8ceba 100644
--- a/src/system-agent/rescue-message.test.ts
+++ b/src/system-agent/rescue-message.test.ts
@@ -11,6 +11,7 @@ import {
 } from "../plugin-state/plugin-state-store.js";
 import type { RuntimeEnv } from "../runtime.js";
 import { withEnvAsync } from "../test-utils/env.js";
+import { listSystemAgentAuditEntriesForTests } from "./audit.test-support.js";
 import { extractSystemAgentRescueMessage, runSystemAgentRescueMessage } from "./rescue-message.js";
 
 let tempRoot = "";
@@ -18,6 +19,10 @@ let tempDirId = 0;
 
 type TestConfig = Record<string, unknown>;
 
+function readLastAuditEntry(): Record<string, unknown> {
+  return (listSystemAgentAuditEntriesForTests().at(-1)?.value ?? {}) as Record<string, unknown>;
+}
+
 const mockConfig = vi.hoisted(() => {
   const state = {
     path: "/tmp/openclaw.json",
@@ -531,7 +536,7 @@ describe("OpenClaw rescue message", () => {
   });
 
   it("queues and applies persistent writes through conversational approval", async () => {
-    await withRescueStateDir("models-", async (tempDir) => {
+    await withRescueStateDir("models-", async () => {
       const cfg: OpenClawConfig = { systemAgent: { rescue: { enabled: true } } };
       const deps = {
         verifyInferenceConfig: vi.fn(async () => ({
@@ -552,8 +557,7 @@ describe("OpenClaw rescue message", () => {
       };
       const model = currentConfig.agents?.defaults?.model;
       expect(typeof model === "string" ? model : model?.primary).toBe("openai/gpt-5.2");
-      const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-      const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim()) as {
+      const audit = readLastAuditEntry() as {
         details?: { rescue?: boolean; channel?: string; accountId?: string; senderId?: string };
       };
       expect(audit.details?.rescue).toBe(true);
@@ -564,7 +568,7 @@ describe("OpenClaw rescue message", () => {
   });
 
   it("queues and applies gateway restart through conversational approval", async () => {
-    await withRescueStateDir("gateway-", async (tempDir) => {
+    await withRescueStateDir("gateway-", async () => {
       const cfg: OpenClawConfig = { systemAgent: { rescue: { enabled: true } } };
       const deps = { runGatewayRestart: vi.fn(async () => {}) };
 
@@ -576,8 +580,7 @@ describe("OpenClaw rescue message", () => {
       );
 
       expect(deps.runGatewayRestart).toHaveBeenCalledTimes(1);
-      const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-      const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim()) as {
+      const audit = readLastAuditEntry() as {
         operation?: string;
         details?: { rescue?: boolean; channel?: string; senderId?: string };
       };
@@ -658,7 +661,7 @@ describe("OpenClaw rescue message", () => {
   });
 
   it("queues and applies agent creation through conversational approval", async () => {
-    await withRescueStateDir("agent-", async (tempDir) => {
+    await withRescueStateDir("agent-", async () => {
       const cfg: OpenClawConfig = { systemAgent: { rescue: { enabled: true } } };
       const deps = { runAgentsAdd: vi.fn(async () => {}) };
 
@@ -687,8 +690,7 @@ describe("OpenClaw rescue message", () => {
       });
       expect(agentRuntime).toBeTypeOf("object");
       expect(agentOptions).toEqual({ hasFlags: true });
-      const auditPath = path.join(tempDir, "audit", "system-agent.jsonl");
-      const audit = JSON.parse((await fs.readFile(auditPath, "utf8")).trim()) as {
+      const audit = readLastAuditEntry() as {
         operation?: string;
         details?: {
           rescue?: boolean;
diff --git a/test/e2e/qa-lab/runtime/system-agent-first-run-docker-client.ts b/test/e2e/qa-lab/runtime/system-agent-first-run-docker-client.ts
index 6f81120bf1d..c7af1d0c475 100644
--- a/test/e2e/qa-lab/runtime/system-agent-first-run-docker-client.ts
+++ b/test/e2e/qa-lab/runtime/system-agent-first-run-docker-client.ts
@@ -7,7 +7,13 @@ import path from "node:path";
 import { shouldStartOnboardingForFreshInstall } from "../../../../dist/cli/run-main.js";
 import { clearConfigCache } from "../../../../dist/config/config.js";
 import type { OpenClawConfig } from "../../../../dist/config/types.openclaw.js";
+import { createSqliteAuditRecordStore } from "../../../../dist/infra/sqlite-audit-record-store.js";
 import type { RuntimeEnv } from "../../../../dist/runtime.js";
+import {
+  SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+  SYSTEM_AGENT_AUDIT_SCOPE,
+  type SystemAgentAuditEntry,
+} from "../../../../dist/system-agent/audit.js";
 import {
   activateSetupInference,
   verifySetupInference,
@@ -367,10 +373,15 @@ async function main() {
     "OpenClaw persisted an unrelated ambient credential",
   );
 
-  const auditPath = path.join(stateDir, "audit", "system-agent.jsonl");
-  const audit = (await fs.readFile(auditPath, "utf8")).trim();
+  const audit = createSqliteAuditRecordStore<SystemAgentAuditEntry>({
+    scope: SYSTEM_AGENT_AUDIT_SCOPE,
+    maxEntries: SYSTEM_AGENT_AUDIT_MAX_ENTRIES,
+  }).entries();
   for (const operation of spec.auditOperations) {
-    assert(audit.includes(`"operation":"${operation}"`), `${operation} audit entry missing`);
+    assert(
+      audit.some((entry) => entry.value.operation === operation),
+      `${operation} audit entry missing`,
+    );
   }
 
   console.log("OpenClaw first-run Docker E2E passed");
diff --git a/test/scripts/check-database-first-legacy-stores.test.ts b/test/scripts/check-database-first-legacy-stores.test.ts
index ec9e4eaee2e..546c9c3db29 100644
--- a/test/scripts/check-database-first-legacy-stores.test.ts
+++ b/test/scripts/check-database-first-legacy-stores.test.ts
@@ -315,6 +315,23 @@ describe("check-database-first-legacy-stores", () => {
     expect(violations).toEqual([{ kind: "legacy store filesystem write", line: 4 }]);
   });
 
+  it("flags runtime writes to retired core audit JSONL stores", () => {
+    const violations = collectDatabaseFirstLegacyStoreViolations(
+      `
+        import { promises as fs } from "node:fs";
+        import path from "node:path";
+        await fs.appendFile(path.join(stateDir, "logs", "config-audit.jsonl"), "{}\\n");
+        await fs.appendFile(path.join(stateDir, "audit", "system-agent.jsonl"), "{}\\n");
+      `,
+      "src/infra/audit-writer.ts",
+    );
+
+    expect(violations).toEqual([
+      { kind: "legacy store filesystem write", line: 4 },
+      { kind: "legacy store filesystem write", line: 5 },
+    ]);
+  });
+
   it("flags runtime writes to retired managed-image record JSON", () => {
     const violations = collectDatabaseFirstLegacyStoreViolations(
       `
diff --git a/test/scripts/test-projects.test.ts b/test/scripts/test-projects.test.ts
index 4db953b568c..d9078baa2b1 100644
--- a/test/scripts/test-projects.test.ts
+++ b/test/scripts/test-projects.test.ts
@@ -2868,7 +2868,7 @@ describe("scripts/test-projects changed-target routing", () => {
         includePatterns: expect.arrayContaining(["src/plugin-sdk/access-groups.test.ts"]),
       }),
       expect.objectContaining({
-        config: "test/vitest/vitest.unit-fast-isolated.config.ts",
+        config: "test/vitest/vitest.unit-fast-fake-timers.config.ts",
         includePatterns: ["src/plugin-sdk/memory-host-events.test.ts"],
       }),
       expect.objectContaining({
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 453b2e308db..7fa3ca1c8c1 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -334,6 +334,8 @@ function buildDockerE2eHarnessEntries(): Record<string, string> {
     "commitments/runtime.test-support": "src/commitments/runtime.test-support.ts",
     "commitments/store": "src/commitments/store.ts",
     "config/config": "src/config/config.ts",
+    "infra/sqlite-audit-record-store": "src/infra/sqlite-audit-record-store.ts",
+    "system-agent/audit": "src/system-agent/audit.ts",
     "system-agent/system-agent": "src/system-agent/system-agent.ts",
     "system-agent/rescue-message": "src/system-agent/rescue-message.ts",
     "system-agent/setup-inference": "src/system-agent/setup-inference.ts",

From 4a96c9da31080bc6c49fbd5306efee6ea112c866 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:46:40 +0100
Subject: [PATCH 36/76] feat(ui): link Get the apps from the mobile pairing
 dialog (#110622)

---
 ui/src/app/app-host.ts             |  4 ++++
 ui/src/i18n/locales/en.ts          |  2 ++
 ui/src/pages/nodes/view-pairing.ts |  5 +++++
 ui/src/styles/components.css       | 26 ++++++++++++++++++++++++++
 4 files changed, 37 insertions(+)

diff --git a/ui/src/app/app-host.ts b/ui/src/app/app-host.ts
index 7edec7e11f1..82eafaacd2c 100644
--- a/ui/src/app/app-host.ts
+++ b/ui/src/app/app-host.ts
@@ -1509,6 +1509,10 @@ class OpenClawShell extends OpenClawLightDomElement {
             context.overlays.closeDevicePairSetup();
             this.navigate("nodes");
           },
+          onGetApps: () => {
+            context.overlays.closeDevicePairSetup();
+            this.navigate("apps");
+          },
         })}
         ${onboarding && activeRoute !== "custodian"
           ? html`<openclaw-onboarding-memory-import
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 100bbccb321..0c5f2ce47f1 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -283,6 +283,8 @@ export const en: TranslationMap = {
       adminRequired: "Administrator access is required to create setup codes.",
       title: "OpenClaw mobile",
       subtitle: "Scan this QR code in the mobile app to connect a new phone.",
+      noApp: "Don't have the app yet?",
+      getApps: "Get the apps",
       generating: "Creating a secure setup code…",
       accessTitle: "Mobile access",
       fullAccess: "Full access (recommended)",
diff --git a/ui/src/pages/nodes/view-pairing.ts b/ui/src/pages/nodes/view-pairing.ts
index 8b0d3f68f25..27c17c4e558 100644
--- a/ui/src/pages/nodes/view-pairing.ts
+++ b/ui/src/pages/nodes/view-pairing.ts
@@ -20,6 +20,7 @@ type DevicePairSetupProps = {
   onClose: () => void;
   onCopy: (setupCode: string) => void;
   onManageDevices: () => void;
+  onGetApps: () => void;
 };
 
 export function renderDevicePairSetup(props: DevicePairSetupProps) {
@@ -40,6 +41,10 @@ export function renderDevicePairSetup(props: DevicePairSetupProps) {
           <div>
             <h2>${title}</h2>
             <p>${description}</p>
+            <p class="device-pair-setup__get-apps">
+              ${t("nodes.pairing.noApp")}
+              <button type="button" @click=${props.onGetApps}>${t("nodes.pairing.getApps")}</button>
+            </p>
           </div>
           <button
             class="btn btn--icon btn--ghost device-pair-setup__close"
diff --git a/ui/src/styles/components.css b/ui/src/styles/components.css
index 729a1ed9d4f..d992600efee 100644
--- a/ui/src/styles/components.css
+++ b/ui/src/styles/components.css
@@ -4672,6 +4672,32 @@ td.data-table-key-col {
   line-height: 1.5;
 }
 
+.device-pair-setup__header p.device-pair-setup__get-apps {
+  margin-top: 2px;
+  font-size: 13px;
+}
+
+.device-pair-setup__get-apps button {
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--text);
+  font: inherit;
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.device-pair-setup__get-apps button:hover {
+  color: var(--text-strong);
+}
+
+.device-pair-setup__get-apps button:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+  border-radius: 4px;
+}
+
 .device-pair-setup__phone {
   display: grid;
   width: 44px;

From 347ee45895033b461649b1bcd2035b23fd221d5b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:46:53 +0100
Subject: [PATCH 37/76] fix(secrets): surface degradation in logs and doctor
 (#109792)

* fix(secrets): surface degraded owners safely

* fix(secrets): preserve degradation ownership across reloads

* fix(secrets): require cold ownership for source recovery

* refactor(secrets): keep assignment provenance internal

* test(secrets): use provider error contract

* fix(secrets): attribute provider failures to active co-owners

* test(secrets): clarify provider failure fixture

* fix(secrets): redact doctor degradation reasons

* test(secrets): align reload harness with runtime state

* test(secrets): cover atomic source publication

* fix(secrets): preserve web owner degradation context

* fix(secrets): retain active web degradation co-owners

* fix(secrets): keep web provider error internal

* refactor(secrets): unify reload degradation state

* refactor(config): remove obsolete source snapshot setter
---
 docs/cli/doctor.md                            |   2 +-
 docs/gateway/secrets.md                       |   6 +-
 src/commands/doctor-gateway-health.test.ts    |  21 +-
 src/commands/doctor-gateway-health.ts         |   6 +-
 src/commands/status.summary.test.ts           |   4 +-
 src/commands/status.summary.ts                |  22 +-
 src/config/runtime-snapshot.ts                |  16 -
 src/gateway/config-reload.test.ts             |  20 +-
 src/gateway/config-reload.ts                  |  23 +-
 src/gateway/server-aux-handlers.test.ts       |  14 +-
 src/gateway/server-aux-handlers.ts            |   3 +
 src/gateway/server-reload-handlers.test.ts    | 406 +++++++++-
 src/gateway/server-reload-handlers.ts         | 186 ++++-
 .../server-startup-config.secrets.test.ts     | 730 ++++++++++++++++-
 src/gateway/server-startup-config.ts          | 171 +++-
 src/secrets/resolve-errors.ts                 |  10 +-
 src/secrets/runtime-assignment-provenance.ts  |  17 +
 src/secrets/runtime-auth-collectors.ts        |  15 +-
 .../runtime-auth-refresh-failure.test.ts      |  78 +-
 .../runtime-degradation-attribution.test.ts   | 737 ++++++++++++++++++
 src/secrets/runtime-degraded-state.test.ts    |  23 +
 src/secrets/runtime-degraded-state.ts         | 111 +++
 src/secrets/runtime-fast-path.ts              |   1 +
 src/secrets/runtime-owner-assignments.ts      | 262 ++++++-
 src/secrets/runtime-shared.ts                 |  59 +-
 src/secrets/runtime-state.test.ts             |  19 +-
 src/secrets/runtime-state.ts                  |  92 ++-
 src/secrets/runtime-web-tools.shared.ts       | 185 ++++-
 src/secrets/runtime-web-tools.test.ts         | 196 ++++-
 src/secrets/runtime-web-tools.ts              | 229 ++++--
 src/secrets/runtime.auth.integration.test.ts  |   2 +
 src/secrets/runtime.fast-path.test.ts         |   2 +
 src/secrets/runtime.test.ts                   | 100 +--
 src/secrets/runtime.ts                        |  56 +-
 34 files changed, 3395 insertions(+), 429 deletions(-)
 create mode 100644 src/secrets/runtime-assignment-provenance.ts
 create mode 100644 src/secrets/runtime-degradation-attribution.test.ts

diff --git a/docs/cli/doctor.md b/docs/cli/doctor.md
index ce5aedd3ec7..9093c60e7f0 100644
--- a/docs/cli/doctor.md
+++ b/docs/cli/doctor.md
@@ -10,7 +10,7 @@ title: "Doctor"
 
 Health checks and quick fixes for the gateway, channels, plugins, skills, model routing, local state, and config migrations. Use it whenever something is not behaving as expected and you want one command to explain what is wrong.
 
-When Gateway status reports SecretRef owners isolated during cold startup, doctor prints a **Secret owners unavailable** warning with every owner and affected config path.
+When Gateway status reports SecretRef owners isolated during cold startup, doctor prints a **Secret runtime degradation** warning with every cold owner, affected config path, redacted reason, and the `openclaw secrets reload` retry command.
 
 Related:
 
diff --git a/docs/gateway/secrets.md b/docs/gateway/secrets.md
index 086a8839963..eb96615d560 100644
--- a/docs/gateway/secrets.md
+++ b/docs/gateway/secrets.md
@@ -21,7 +21,7 @@ Plaintext credentials remain agent-readable if they sit in files the agent can i
 ## Runtime model
 
 - Secrets resolve into an in-memory runtime snapshot, eagerly during activation, not lazily on request paths.
-- Cold Gateway startup isolates unavailable SecretRefs to a known non-Gateway owner when that owner supports isolation. Today this covers model providers and the built-in TTS capability. The Gateway starts, records that owner as configured-unavailable, and emits a redacted `SECRETS_OWNER_UNAVAILABLE` warning. Gateway ingress auth, structurally invalid refs or resolved values, and refs whose runtime owner is not yet mapped still fail startup.
+- Cold Gateway startup isolates unavailable SecretRefs to a known non-Gateway owner when that owner supports isolation. Today this covers model providers, the built-in TTS capability, web search and fetch providers, and webhook routes. The Gateway starts, records that owner as configured-unavailable, and emits a redacted `SECRETS_OWNER_UNAVAILABLE` warning. Gateway ingress auth, structurally invalid refs or resolved values, and refs whose runtime owner is not yet mapped still fail startup.
 - Reload is an atomic swap: full success, or keep the last-known-good snapshot.
 - Policy violations (for example an OAuth-mode auth profile combined with SecretRef input) fail activation before the runtime swap.
 - Runtime requests read only the active in-memory snapshot. Model-provider SecretRef credentials pass through auth storage and stream options as process-local sentinels until egress. Outbound delivery paths (Discord reply/thread delivery, Telegram action sends) also read that snapshot and do not re-resolve refs per send.
@@ -29,7 +29,7 @@ Plaintext credentials remain agent-readable if they sit in files the agent can i
 This keeps secret-provider outages off hot request paths.
 
 <Note>
-Target policy for the SecretRef ownership-isolation migration: failures isolate to the smallest known owner. Only unavailable Gateway ingress protection, structurally invalid config, or unknown ownership will block startup; other affected capabilities, accounts, or routes will become configured-unavailable with typed redacted diagnostics and no implicit credential fallback. Reload will retain last-known-good only for an unchanged ref and provider, while a changed unresolved ref will make that owner cold. Doctor and status will list every degraded owner. This migration is not fully implemented; the current activation rules on this page remain in effect.
+Target policy for the SecretRef ownership-isolation migration: failures isolate to the smallest known owner. Only unavailable Gateway ingress protection, structurally invalid config, or unknown ownership will block startup; other affected capabilities, accounts, or routes will become configured-unavailable with typed redacted diagnostics and no implicit credential fallback. Reload will retain last-known-good only for an unchanged ref and provider, while a changed unresolved ref will make that owner cold. Doctor and structured Gateway warnings will identify degraded owners. This migration is not fully implemented; the current activation rules on this page remain in effect.
 </Note>
 
 ## Egress-time injection (sentinels)
@@ -617,6 +617,8 @@ Behavior:
 - Recovered: emitted once after the next successful activation.
 - Repeated failures while already degraded log warnings but do not re-emit the event.
 - Startup fail-fast never emits a degraded event, because runtime never became active.
+- Startup and reload failures emit a structured `SECRETS_DEGRADED` warning for each affected owner. The warning includes the owner kind and id, a redacted reason, `cold` or `stale` state, and the `openclaw secrets reload` retry hint. It never includes resolved values or SecretRef ids.
+- `openclaw doctor` lists owners isolated during cold startup with their affected config paths, redacted reason, and retry guidance.
 
 ## Command-path resolution
 
diff --git a/src/commands/doctor-gateway-health.test.ts b/src/commands/doctor-gateway-health.test.ts
index 35b56c9e34f..3db07dacdb3 100644
--- a/src/commands/doctor-gateway-health.test.ts
+++ b/src/commands/doctor-gateway-health.test.ts
@@ -120,14 +120,21 @@ describe("checkGatewayHealth", () => {
             ownerId: "discord:ops",
             state: "unavailable",
             paths: ["channels.discord.accounts.ops.token"],
-            reason: "secret reference was not found",
+            reason: "secret reference was not found (env:default:PRIVATE_REF_ID)",
           },
           {
             ownerKind: "capability",
             ownerId: "tts",
             state: "unavailable",
             paths: ["messages.tts.providers.elevenlabs.apiKey"],
-            reason: "secret provider failed",
+            reason: "secret provider policy denied resolution",
+          },
+          {
+            ownerKind: "capability",
+            ownerId: "web-fetch:firecrawl",
+            state: "unavailable",
+            paths: ["plugins.entries.firecrawl.config.webFetch.apiKey"],
+            reason: "resolved secret value was invalid",
           },
         ],
       })
@@ -138,10 +145,14 @@ describe("checkGatewayHealth", () => {
 
     expect(note).toHaveBeenCalledWith(
       [
-        "- account:discord:ops (channels.discord.accounts.ops.token): secret reference was not found",
-        "- capability:tts (messages.tts.providers.elevenlabs.apiKey): secret provider failed",
+        "- cold account:discord:ops (channels.discord.accounts.ops.token): secret resolution failed",
+        "  Retry: openclaw secrets reload",
+        "- cold capability:tts (messages.tts.providers.elevenlabs.apiKey): secret provider policy denied resolution",
+        "  Retry: openclaw secrets reload",
+        "- cold capability:web-fetch:firecrawl (plugins.entries.firecrawl.config.webFetch.apiKey): resolved secret value was invalid",
+        "  Retry: openclaw secrets reload",
       ].join("\n"),
-      "Secret owners unavailable",
+      "Secret runtime degradation",
     );
   });
 
diff --git a/src/commands/doctor-gateway-health.ts b/src/commands/doctor-gateway-health.ts
index 6d386dbbfe8..2695b1dc6f5 100644
--- a/src/commands/doctor-gateway-health.ts
+++ b/src/commands/doctor-gateway-health.ts
@@ -16,6 +16,7 @@ import type {
 import { collectChannelStatusIssues } from "../infra/channels-status-issues.js";
 import { formatErrorMessage } from "../infra/errors.js";
 import type { RuntimeEnv } from "../runtime.js";
+import { redactSecretDegradationReason } from "../secrets/runtime-degraded-state.js";
 import { VERSION } from "../version.js";
 import {
   GATEWAY_HEALTH_CREDENTIALS_REQUIRED_MESSAGE,
@@ -91,10 +92,11 @@ export async function checkGatewayHealth(params: {
         status.degradedSecretOwners
           .map(
             (owner) =>
-              `- ${owner.ownerKind}:${owner.ownerId} (${owner.paths.join(", ")}): ${owner.reason}`,
+              `- cold ${owner.ownerKind}:${owner.ownerId} (${owner.paths.join(", ")}): ${redactSecretDegradationReason(owner.reason)}` +
+              "\n  Retry: openclaw secrets reload",
           )
           .join("\n"),
-        "Secret owners unavailable",
+        "Secret runtime degradation",
       );
     }
     if (status.degradedPlugins && status.degradedPlugins.length > 0) {
diff --git a/src/commands/status.summary.test.ts b/src/commands/status.summary.test.ts
index 2242f922cf2..32e0ca51dc0 100644
--- a/src/commands/status.summary.test.ts
+++ b/src/commands/status.summary.test.ts
@@ -286,7 +286,7 @@ describe("getStatusSummary", () => {
         state: "unavailable",
         paths: ["channels.discord.accounts.ops.token"],
         refKeys: ["env:default:PRIVATE_REF_ID"],
-        reason: "secret reference was not found",
+        reason: "provider SecretRef is unresolved (env:default:PRIVATE_REF_ID)",
       },
     ]);
 
@@ -298,7 +298,7 @@ describe("getStatusSummary", () => {
         ownerId: "discord:ops",
         state: "unavailable",
         paths: ["channels.discord.accounts.ops.token"],
-        reason: "secret reference was not found",
+        reason: "secret resolution failed",
       },
     ]);
     expect(JSON.stringify(summary.degradedSecretOwners)).not.toContain("PRIVATE_REF_ID");
diff --git a/src/commands/status.summary.ts b/src/commands/status.summary.ts
index 14daa693ad1..a92c05e0db4 100644
--- a/src/commands/status.summary.ts
+++ b/src/commands/status.summary.ts
@@ -21,7 +21,10 @@ import {
   toPublicPluginVerificationDiagnostic,
 } from "../plugins/runtime-degraded-state.js";
 import { parseAgentSessionKey } from "../routing/session-key.js";
-import { listActiveDegradedSecretOwners } from "../secrets/runtime-degraded-state.js";
+import {
+  listActiveDegradedSecretOwners,
+  redactSecretDegradationReason,
+} from "../secrets/runtime-degraded-state.js";
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
 import { createLazyRuntimeSurface } from "../shared/lazy-runtime.js";
 import {
@@ -570,13 +573,16 @@ export async function getStatusSummary(
     channelSummary,
     queuedSystemEvents,
     degradedSecretOwners: listActiveDegradedSecretOwners().map(
-      ({ ownerKind, ownerId, state, paths: ownerPaths, reason }) => ({
-        ownerKind,
-        ownerId,
-        state,
-        paths: ownerPaths,
-        reason,
-      }),
+      ({ ownerKind, ownerId, state, paths: ownerPaths, reason }) => {
+        const redactedReason: string = redactSecretDegradationReason(reason);
+        return {
+          ownerKind,
+          ownerId,
+          state,
+          paths: ownerPaths,
+          reason: redactedReason,
+        };
+      },
     ),
     degradedPlugins: listActiveDegradedPlugins().map(({ pluginId, state, diagnostic }) => ({
       pluginId,
diff --git a/src/config/runtime-snapshot.ts b/src/config/runtime-snapshot.ts
index 9917a108983..4aadd1385c4 100644
--- a/src/config/runtime-snapshot.ts
+++ b/src/config/runtime-snapshot.ts
@@ -178,22 +178,6 @@ export function setAppliedRuntimeConfigSnapshot(
   runtimeConfigAppliedHash = hashRuntimeConfigValue(sourceConfig);
 }
 
-/** Publish a newer canonical source without changing the active runtime object. */
-export function setRuntimeConfigSourceSnapshotIfCurrent(params: {
-  expectedRevision: number;
-  sourceConfig: OpenClawConfig;
-}): boolean {
-  if (
-    !runtimeConfigSnapshot ||
-    !runtimeConfigSnapshotMetadata ||
-    runtimeConfigSnapshotMetadata.revision !== params.expectedRevision
-  ) {
-    return false;
-  }
-  setRuntimeConfigSnapshot(runtimeConfigSnapshot, params.sourceConfig);
-  return true;
-}
-
 export function resetConfigRuntimeState(): void {
   runtimeConfigSnapshot = null;
   runtimeConfigSourceSnapshot = null;
diff --git a/src/gateway/config-reload.test.ts b/src/gateway/config-reload.test.ts
index e58b90d96f2..ebd106db069 100644
--- a/src/gateway/config-reload.test.ts
+++ b/src/gateway/config-reload.test.ts
@@ -667,7 +667,7 @@ function createReloaderHarness(
       nextConfig: OpenClawConfig,
       ownership: GatewayConfigReloadTransactionOwnership,
       sourceConfig: OpenClawConfig,
-    ) => Promise<() => Promise<void>>;
+    ) => Promise<{ rollback: () => Promise<void>; commit?: () => void }>;
     onConfigApplied?: (plan: GatewayReloadPlan, nextConfig: OpenClawConfig) => void | Promise<void>;
     onConfigRevisionApplied?: (hash: string) => void;
     onConfigChange?: (plan: GatewayReloadPlan, nextConfig: OpenClawConfig) => void | Promise<void>;
@@ -703,7 +703,7 @@ function createReloaderHarness(
   const onConfigAccepted = vi.fn(options.onConfigAccepted ?? (async () => {}));
   const onConfigRevisionApplied = vi.fn(options.onConfigRevisionApplied ?? (() => {}));
   const onEffectiveConfigUnchanged = vi.fn(
-    options.onEffectiveConfigUnchanged ?? (async () => async () => {}),
+    options.onEffectiveConfigUnchanged ?? (async () => ({ rollback: async () => {} })),
   );
   const onNoopConfigCommit = vi.fn(
     options.onNoopConfigCommit ??
@@ -3021,6 +3021,8 @@ describe("startGatewayConfigReloader", () => {
       ...initialConfig,
       logging: { level: "debug" as const },
     } satisfies OpenClawConfig;
+    const publicationEvents: string[] = [];
+    let publicationId = 0;
     const rollbackSource = vi.fn(async () => {});
     let emitSupersedingChange = () => {};
     const harness = createReloaderHarness(
@@ -3032,7 +3034,18 @@ describe("startGatewayConfigReloader", () => {
           queueMicrotask(emitSupersedingChange);
           return rollback;
         },
-        onEffectiveConfigUnchanged: async () => rollbackSource,
+        onEffectiveConfigUnchanged: async () => {
+          const id = publicationId++;
+          return {
+            rollback: async () => {
+              publicationEvents.push(`rollback:${id}`);
+              await rollbackSource();
+            },
+            commit: () => {
+              publicationEvents.push(`commit:${id}`);
+            },
+          };
+        },
       },
     );
     emitSupersedingChange = () => {
@@ -3063,6 +3076,7 @@ describe("startGatewayConfigReloader", () => {
       initialConfig,
     ]);
     expect(rollbackSource).toHaveBeenCalledOnce();
+    expect(publicationEvents).toEqual(["rollback:0", "commit:1"]);
 
     await harness.reloader.stop();
   });
diff --git a/src/gateway/config-reload.ts b/src/gateway/config-reload.ts
index ef206629577..e3a86c7c127 100644
--- a/src/gateway/config-reload.ts
+++ b/src/gateway/config-reload.ts
@@ -175,7 +175,11 @@ export function startGatewayConfigReloader(opts: {
     nextConfig: OpenClawConfig,
     ownership: GatewayConfigReloadTransactionOwnership,
     sourceConfig: OpenClawConfig,
-  ) => Promise<() => Promise<void>>;
+  ) => Promise<{
+    rollback: () => Promise<void>;
+    /** Runs only when this exact source publication can no longer roll back. */
+    commit?: () => void;
+  }>;
   onNoopConfigCommit: (
     plan: GatewayReloadPlan,
     nextConfig: OpenClawConfig,
@@ -497,16 +501,27 @@ export function startGatewayConfigReloader(opts: {
       }
     };
     if (changedPaths.length === 0) {
+      let publishedSource: { rollback: () => Promise<void>; commit?: () => void } | undefined;
       let publishedSourceRollback: (() => Promise<void>) | undefined;
+      let publishedSourceRolledBack = false;
       const publishSource = opts.onEffectiveConfigUnchanged
-        ? async () =>
-            (publishedSourceRollback ??= await opts.onEffectiveConfigUnchanged!(
+        ? async () => {
+            publishedSource ??= await opts.onEffectiveConfigUnchanged!(
               nextConfig,
               ownership,
               nextSourceConfig,
-            ))
+            );
+            publishedSourceRollback ??= async () => {
+              publishedSourceRolledBack = true;
+              await publishedSource?.rollback();
+            };
+            return publishedSourceRollback;
+          }
         : undefined;
       await commitReloadBaseline(publishSource ? { publishSource } : {});
+      if (!publishedSourceRolledBack) {
+        publishedSource?.commit?.();
+      }
       opts.onConfigRevisionApplied?.(nextConfigRevisionHash);
       return;
     }
diff --git a/src/gateway/server-aux-handlers.test.ts b/src/gateway/server-aux-handlers.test.ts
index 3338ec57d61..b135f0d4f35 100644
--- a/src/gateway/server-aux-handlers.test.ts
+++ b/src/gateway/server-aux-handlers.test.ts
@@ -413,8 +413,18 @@ describe("gateway aux handlers", () => {
       canonicalConfig,
     ]);
     expect(activateRuntimeSecrets.mock.calls.map(([, activation]) => activation)).toEqual([
-      { reason: "reload", activate: false },
-      { reason: "reload", activate: false },
+      {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
+      },
+      {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
+      },
     ]);
     expect(activatePreparedSnapshotIfCurrent).toHaveBeenCalledTimes(2);
     expect(getActiveSecretsRuntimeSnapshot()?.sourceConfig).toEqual(canonicalConfig);
diff --git a/src/gateway/server-aux-handlers.ts b/src/gateway/server-aux-handlers.ts
index f3b4d5d5ee2..26b8cdb0f95 100644
--- a/src/gateway/server-aux-handlers.ts
+++ b/src/gateway/server-aux-handlers.ts
@@ -264,6 +264,9 @@ export function createGatewayAuxHandlers(params: {
                     {
                       reason: "reload",
                       activate: false,
+                      publishFailureAsDegraded: true,
+                      canPublishFailureAsDegraded: () =>
+                        getActiveSecretsRuntimeSnapshotRevision() === previousSnapshotRevision,
                     },
                   );
                   const plan = buildReloadPlan(
diff --git a/src/gateway/server-reload-handlers.test.ts b/src/gateway/server-reload-handlers.test.ts
index 266cfd49124..2024e7a2379 100644
--- a/src/gateway/server-reload-handlers.test.ts
+++ b/src/gateway/server-reload-handlers.test.ts
@@ -40,7 +40,10 @@ import {
   tryBeginGatewaySuspendAdmission,
 } from "../process/gateway-work-admission.js";
 import { CommandLane } from "../process/lanes.js";
+import { resolveAuthProfileSecretOwnerId } from "../secrets/runtime-auth-profile-owner.js";
+import { listActiveDegradedSecretOwners } from "../secrets/runtime-degraded-state.js";
 import { createEmptyRuntimeWebToolsMetadata } from "../secrets/runtime-fast-path.js";
+import { classifySecretOwnerDegradationState } from "../secrets/runtime-owner-assignments.js";
 import {
   activateSecretsRuntimeSnapshot,
   clearSecretsRuntimeSnapshot,
@@ -420,6 +423,14 @@ function createManagedRestartSequenceHarness(
     },
   } as OpenClawConfig;
   setRuntimeConfigSnapshot(initialConfig, initialConfig);
+  activateSecretsRuntimeSnapshot({
+    sourceConfig: initialConfig,
+    config: initialConfig,
+    authStores: [],
+    authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+    warnings: [],
+    webTools: createEmptyRuntimeWebToolsMetadata(),
+  });
   const deferredConfig = {
     gateway: {
       port: 18790,
@@ -3880,7 +3891,7 @@ describe("gateway Gmail hot reload handlers", () => {
       gateway: { reload: { debounceMs: 0 } },
       messages: { visibleReplies: "message_tool" },
     };
-    const activateRuntimeSecrets = vi.fn(async (config: OpenClawConfig) => ({
+    const activateRuntimeSecrets = vi.fn(async (config: OpenClawConfig, _params: unknown) => ({
       sourceConfig: config,
       config,
       authStores: [],
@@ -3977,6 +3988,9 @@ describe("gateway Gmail hot reload handlers", () => {
     expect(activateRuntimeSecrets).toHaveBeenCalledWith(nextConfig, {
       reason: "reload",
       activate: false,
+      publishFailureAsDegraded: true,
+      canPublishFailureAsDegraded: expect.any(Function),
+      includeAuthStoreRefs: undefined,
     });
     expect(getActiveSecretsRuntimeSnapshot()?.sourceConfig).toEqual(nextConfig);
     expect(acceptTerminalConfig).toHaveBeenCalledWith({
@@ -3987,6 +4001,380 @@ describe("gateway Gmail hot reload handlers", () => {
     await reloader.stop();
   });
 
+  it("refreshes owner refs when only the resolved source snapshot changes", async () => {
+    vi.useFakeTimers();
+    const authAgentDir = "/tmp/openclaw-source-only-auth-owner";
+    const authProfileId = "openai:source-only";
+    const authOwnerId = resolveAuthProfileSecretOwnerId({
+      agentDir: authAgentDir,
+      profileId: authProfileId,
+    });
+    const firstRef = { source: "env" as const, provider: "default", id: "TTS_FIRST" };
+    const secondRef = { source: "env" as const, provider: "default", id: "TTS_SECOND" };
+    const thirdRef = { source: "env" as const, provider: "default", id: "TTS_THIRD" };
+    const fourthRef = { source: "env" as const, provider: "default", id: "TTS_FOURTH" };
+    const sourceConfig = (ref: typeof firstRef): OpenClawConfig => ({
+      gateway: { reload: { debounceMs: 0 } },
+      messages: { tts: { providers: { elevenlabs: { apiKey: ref } } } },
+    });
+    const runtimeConfig: OpenClawConfig = {
+      gateway: { reload: { debounceMs: 0 } },
+      messages: { tts: { providers: { elevenlabs: { apiKey: String(42) } } } },
+    };
+    const initialSourceConfig = sourceConfig(firstRef);
+    const nextSourceConfig = sourceConfig(secondRef);
+    activateSecretsRuntimeSnapshot({
+      sourceConfig: initialSourceConfig,
+      config: runtimeConfig,
+      authStores: [
+        {
+          agentDir: authAgentDir,
+          store: {
+            version: 1,
+            profiles: {
+              [authProfileId]: {
+                type: "api_key",
+                provider: "openai",
+                key: String(42),
+                keyRef: { source: "env", provider: "default", id: "AUTH_FIRST" },
+              },
+            },
+          },
+        },
+      ],
+      authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+      warnings: [],
+      degradedOwners: [
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          state: "unavailable",
+          paths: ["messages.tts.providers.elevenlabs.apiKey"],
+          refKeys: ["env:default:TTS_FIRST"],
+          reason: "secret reference was not found",
+        },
+        {
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          state: "unavailable",
+          paths: [`${authAgentDir}.auth-profiles.${authProfileId}.key`],
+          refKeys: ["env:default:AUTH_FIRST"],
+          reason: "secret provider failed",
+        },
+      ],
+      secretOwners: [
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_FIRST"],
+        },
+        {
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          refKeys: ["env:default:AUTH_FIRST"],
+        },
+      ],
+      webTools: createEmptyRuntimeWebToolsMetadata(),
+    });
+    const writeListenerRef: { current: ((event: ConfigWriteNotification) => void) | null } = {
+      current: null,
+    };
+    const activateRuntimeSecrets = vi.fn(async (config: OpenClawConfig, _params: unknown) => ({
+      sourceConfig: config,
+      config: runtimeConfig,
+      authStores: [
+        {
+          agentDir: authAgentDir,
+          store: {
+            version: 1,
+            profiles: {
+              [authProfileId]: {
+                type: "api_key" as const,
+                provider: "openai",
+                key: String(42),
+                keyRef: { source: "env" as const, provider: "default", id: "AUTH_SECOND" },
+              },
+            },
+          },
+        },
+      ],
+      authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+      warnings: [],
+      secretOwners: [
+        {
+          ownerKind: "capability" as const,
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_SECOND"],
+        },
+        {
+          ownerKind: "account" as const,
+          ownerId: authOwnerId,
+          refKeys: ["env:default:AUTH_SECOND"],
+        },
+      ],
+      webTools: createEmptyRuntimeWebToolsMetadata(),
+    }));
+    const reloader = startManagedGatewayConfigReloader({
+      minimalTestGateway: false,
+      initialConfig: runtimeConfig,
+      initialCompareConfig: runtimeConfig,
+      initialInternalWriteHash: null,
+      watchPath: "/tmp/openclaw.json",
+      readSnapshot: vi.fn(async () => ({
+        path: "/tmp/openclaw.json",
+        exists: true,
+        raw: "{}",
+        parsed: nextSourceConfig,
+        sourceConfig: nextSourceConfig,
+        resolved: runtimeConfig,
+        valid: true,
+        runtimeConfig,
+        config: runtimeConfig,
+        issues: [],
+        warnings: [],
+        legacyIssues: [],
+        hash: "same-runtime-next-source",
+      })) as never,
+      promoteSnapshot: vi.fn(async () => true) as never,
+      subscribeToWrites: ((listener: (event: ConfigWriteNotification) => void) => {
+        writeListenerRef.current = listener;
+        return () => {
+          if (writeListenerRef.current === listener) {
+            writeListenerRef.current = null;
+          }
+        };
+      }) as never,
+      prepareConfigCandidate: ({ runtimeConfig: candidateRuntime }) => ({
+        runtimeConfig: candidateRuntime,
+        compareConfig: candidateRuntime,
+      }),
+      deps: {} as never,
+      broadcast: vi.fn(),
+      getState: () => ({
+        hooksConfig: {} as never,
+        hookClientIpConfig: {} as never,
+        heartbeatRunner: { stop: vi.fn(), updateConfig: vi.fn() } as never,
+        cronState: {
+          cron: { start: vi.fn(async () => {}), stop: vi.fn() },
+          storePath: "/tmp/cron.json",
+          cronEnabled: false,
+        } as never,
+        channelHealthMonitor: null,
+      }),
+      setState: vi.fn(),
+      startChannel: vi.fn(async () => {}),
+      stopChannel: vi.fn(async () => {}),
+      reloadPlugins: vi.fn(async () => ({
+        restartChannels: new Set<ChannelKind>(),
+        activeChannels: new Set<ChannelKind>(),
+      })),
+      logHooks: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+      logChannels: { info: vi.fn(), error: vi.fn() },
+      logCron: { error: vi.fn() },
+      logReload: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+      channelManager: {} as never,
+      activateRuntimeSecrets: activateRuntimeSecrets as never,
+      resolveSharedGatewaySessionGenerationForConfig: () => undefined,
+      sharedGatewaySessionGenerationState: { current: undefined, required: null },
+      clients: [],
+      reconcileTerminalSessions: vi.fn(),
+      commitTerminalConfig: vi.fn(),
+      acceptTerminalConfig: vi.fn(),
+    });
+
+    try {
+      const listener = writeListenerRef.current;
+      if (!listener) {
+        throw new Error("Expected config write listener to be registered");
+      }
+      const unrelatedSourceConfig = {
+        ...initialSourceConfig,
+        logging: { level: "info" as const },
+      };
+      listener({
+        configPath: "/tmp/openclaw.json",
+        sourceConfig: unrelatedSourceConfig,
+        runtimeConfig,
+        persistedHash: "same-secrets-new-source",
+        revision: 1,
+        fingerprint: "same-runtime",
+        sourceFingerprint: "same-secrets-new-source",
+        writtenAtMs: Date.now(),
+      });
+      await vi.runAllTimersAsync();
+
+      expect(activateRuntimeSecrets).not.toHaveBeenCalled();
+      expect(getActiveSecretsRuntimeSnapshot()?.sourceConfig).toEqual(unrelatedSourceConfig);
+      expect(getActiveSecretsRuntimeSnapshot()?.secretOwners).toEqual([
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_FIRST"],
+        },
+        {
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          refKeys: ["env:default:AUTH_FIRST"],
+        },
+      ]);
+
+      listener({
+        configPath: "/tmp/openclaw.json",
+        sourceConfig: nextSourceConfig,
+        runtimeConfig,
+        persistedHash: "same-runtime-next-source",
+        revision: 2,
+        fingerprint: "same-runtime",
+        sourceFingerprint: "next-source",
+        writtenAtMs: Date.now(),
+      });
+      await vi.runAllTimersAsync();
+
+      expect(activateRuntimeSecrets.mock.calls[0]?.[1]).toMatchObject({
+        activate: false,
+        includeAuthStoreRefs: true,
+        publishFailureAsDegraded: true,
+      });
+      expect(listActiveDegradedSecretOwners()).toEqual([]);
+      expect(getActiveSecretsRuntimeSnapshot()?.secretOwners).toEqual([
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_SECOND"],
+        },
+        {
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          refKeys: ["env:default:AUTH_SECOND"],
+        },
+      ]);
+      expect(
+        getActiveSecretsRuntimeSnapshot()?.authStores[0]?.store.profiles[authProfileId],
+      ).toMatchObject({
+        key: String(42),
+        keyRef: { source: "env", provider: "default", id: "AUTH_SECOND" },
+      });
+      expect(
+        classifySecretOwnerDegradationState({
+          ownerKind: "capability",
+          ownerId: "tts",
+          refs: [secondRef],
+          config: nextSourceConfig,
+        }),
+      ).toBe("stale");
+
+      activateRuntimeSecrets.mockImplementationOnce(async (config: OpenClawConfig) => ({
+        sourceConfig: config,
+        config: { ...runtimeConfig, logging: { level: "debug" } },
+        authStores: [],
+        authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+        warnings: [],
+        secretOwners: [
+          {
+            ownerKind: "capability" as const,
+            ownerId: "tts",
+            refKeys: ["env:default:TTS_THIRD"],
+          },
+        ],
+        webTools: createEmptyRuntimeWebToolsMetadata(),
+      }));
+      listener({
+        configPath: "/tmp/openclaw.json",
+        sourceConfig: sourceConfig(thirdRef),
+        runtimeConfig,
+        persistedHash: "changed-second-resolution",
+        revision: 2,
+        fingerprint: "same-runtime",
+        sourceFingerprint: "changed-second-resolution",
+        writtenAtMs: Date.now(),
+      });
+      await vi.runAllTimersAsync();
+
+      expect(getActiveSecretsRuntimeSnapshot()?.secretOwners).toEqual([
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_SECOND"],
+        },
+        {
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          refKeys: ["env:default:AUTH_SECOND"],
+        },
+      ]);
+
+      let releasePreparation = () => {};
+      let markPreparationStarted: (() => void) | undefined;
+      const preparationStarted = new Promise<void>((resolve) => {
+        markPreparationStarted = resolve;
+      });
+      const preparationGate = new Promise<void>((resolve) => {
+        releasePreparation = resolve;
+      });
+      activateRuntimeSecrets.mockImplementationOnce(async (config: OpenClawConfig) => {
+        markPreparationStarted?.();
+        await preparationGate;
+        return {
+          sourceConfig: config,
+          config: runtimeConfig,
+          authStores: [],
+          authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+          warnings: [],
+          secretOwners: [
+            {
+              ownerKind: "capability" as const,
+              ownerId: "tts",
+              refKeys: ["env:default:TTS_THIRD"],
+            },
+          ],
+          webTools: createEmptyRuntimeWebToolsMetadata(),
+        };
+      });
+      listener({
+        configPath: "/tmp/openclaw.json",
+        sourceConfig: sourceConfig(thirdRef),
+        runtimeConfig,
+        persistedHash: "superseded-source-owner",
+        revision: 3,
+        fingerprint: "same-runtime",
+        sourceFingerprint: "superseded-source-owner",
+        writtenAtMs: Date.now(),
+      });
+      await vi.advanceTimersByTimeAsync(0);
+      await preparationStarted;
+
+      const concurrentSourceConfig = sourceConfig(fourthRef);
+      activateSecretsRuntimeSnapshot({
+        sourceConfig: concurrentSourceConfig,
+        config: runtimeConfig,
+        authStores: [],
+        authStoreCredentialsRevision: getRuntimeAuthProfileStoreCredentialsRevision(),
+        warnings: [],
+        secretOwners: [
+          {
+            ownerKind: "capability",
+            ownerId: "tts",
+            refKeys: ["env:default:TTS_FOURTH"],
+          },
+        ],
+        webTools: createEmptyRuntimeWebToolsMetadata(),
+      });
+      releasePreparation();
+      await vi.runAllTimersAsync();
+
+      expect(getActiveSecretsRuntimeSnapshot()?.sourceConfig).toEqual(concurrentSourceConfig);
+      expect(getActiveSecretsRuntimeSnapshot()?.secretOwners).toEqual([
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          refKeys: ["env:default:TTS_FOURTH"],
+        },
+      ]);
+    } finally {
+      await reloader.stop();
+    }
+  });
+
   it("rejects ownerless irreversible plans but applies safe hot plans", async () => {
     vi.useFakeTimers();
     const initialConfig: OpenClawConfig = {
@@ -4408,10 +4796,14 @@ describe("gateway Gmail hot reload handlers", () => {
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(1, harness.deferredConfig, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(2, harness.invalidConfig, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       expect(harness.terminalPolicy.isEnabled()).toBe(false);
       expect(harness.promoteSnapshot.mock.calls.map(([snapshot]) => snapshot.hash)).not.toContain(
@@ -4435,11 +4827,15 @@ describe("gateway Gmail hot reload handlers", () => {
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(3, acceptedWithLogging, {
         reason: "reload",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
         includeAuthStoreRefs: undefined,
       });
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(4, acceptedWithLogging, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       const deferredPlan = buildGatewayReloadPlan(
         diffConfigPaths(harness.initialConfig, harness.deferredConfig),
@@ -4588,6 +4984,8 @@ describe("gateway Gmail hot reload handlers", () => {
         {
           reason: "restart-check",
           activate: false,
+          publishFailureAsDegraded: true,
+          canPublishFailureAsDegraded: expect.any(Function),
         },
       );
       expect(harness.requestRecoveryRestart).not.toHaveBeenCalled();
@@ -4692,6 +5090,8 @@ describe("gateway Gmail hot reload handlers", () => {
       expect(harness.activateRuntimeSecrets).toHaveBeenCalledWith(harness.deferredConfig, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       await vi.advanceTimersByTimeAsync(500);
       expect(harness.requestRecoveryRestart.mock.calls).toEqual([
@@ -4739,6 +5139,8 @@ describe("gateway Gmail hot reload handlers", () => {
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(3, harness.deferredConfig, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       expect(harness.requestRecoveryRestart).not.toHaveBeenCalled();
       expect(harness.promoteSnapshot.mock.calls.map(([snapshot]) => snapshot.hash)).not.toContain(
@@ -4773,6 +5175,8 @@ describe("gateway Gmail hot reload handlers", () => {
       expect(harness.activateRuntimeSecrets).toHaveBeenNthCalledWith(2, harness.replacementConfig, {
         reason: "restart-check",
         activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: expect.any(Function),
       });
       expect(harness.requestRecoveryRestart).not.toHaveBeenCalled();
 
diff --git a/src/gateway/server-reload-handlers.ts b/src/gateway/server-reload-handlers.ts
index 182e9364935..5a2c1e5aaa7 100644
--- a/src/gateway/server-reload-handlers.ts
+++ b/src/gateway/server-reload-handlers.ts
@@ -14,11 +14,7 @@ import { getChannelPlugin } from "../channels/plugins/index.js";
 import type { CliDeps } from "../cli/deps.types.js";
 import { isRestartEnabled } from "../config/commands.flags.js";
 import { getConfigValueAtPath } from "../config/config-paths.js";
-import {
-  getRuntimeConfigSnapshotMetadata,
-  getRuntimeConfigSourceSnapshot,
-  setRuntimeConfigAppliedHash,
-} from "../config/config.js";
+import { getRuntimeConfigSourceSnapshot, setRuntimeConfigAppliedHash } from "../config/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isSecretRef } from "../config/types.secrets.js";
 import { isTruthyEnvValue } from "../infra/env.js";
@@ -43,7 +39,7 @@ import {
   clearSecretsRuntimeSnapshot,
   getActiveSecretsRuntimeSnapshot,
   getActiveSecretsRuntimeSnapshotRevision,
-  setSecretsRuntimeSourceSnapshotIfCurrent,
+  hasSameSecretReloadContract,
   type PreparedSecretsRuntimeSnapshot,
 } from "../secrets/runtime-state.js";
 import { getInspectableActiveTaskRestartBlockers } from "../tasks/task-registry.maintenance.js";
@@ -84,7 +80,10 @@ import {
   type SharedGatewaySessionGenerationOwnership,
   type SharedGatewaySessionGenerationState,
 } from "./server-shared-auth-generation.js";
-import type { ActivateRuntimeSecrets } from "./server-startup-config.js";
+import {
+  publishRuntimeSecretsRecovery,
+  type ActivateRuntimeSecrets,
+} from "./server-startup-config.js";
 import { resolveHookClientIpConfig } from "./server/hook-client-ip-config.js";
 import type { HookClientIpConfig } from "./server/hooks-request-handler.js";
 
@@ -117,13 +116,18 @@ async function activateSecretsRuntimeSnapshotIfCurrent(
   options?: {
     canActivate?: () => boolean;
     onActivated?: () => void;
+    runtimeSourceConfig?: OpenClawConfig;
   },
 ): Promise<boolean> {
   const runtime = await import("../secrets/runtime.js");
   if (options?.canActivate && !options.canActivate()) {
     return false;
   }
-  if (!runtime.activateSecretsRuntimeSnapshotIfCurrent(snapshot, expectedRevision)) {
+  if (
+    !runtime.activateSecretsRuntimeSnapshotIfCurrent(snapshot, expectedRevision, {
+      runtimeSourceConfig: options?.runtimeSourceConfig,
+    })
+  ) {
     return false;
   }
   options?.onActivated?.();
@@ -134,10 +138,14 @@ async function restoreSecretsRuntimeSnapshotIfCurrent(
   snapshot: PreparedSecretsRuntimeSnapshot,
   expectedRevision: number,
   ownedSnapshot: PreparedSecretsRuntimeSnapshot,
-  options?: { onActivated?: () => void },
+  options?: { onActivated?: () => void; runtimeSourceConfig?: OpenClawConfig },
 ): Promise<boolean> {
   const runtime = await import("../secrets/runtime.js");
-  if (!runtime.restoreSecretsRuntimeSnapshotIfCurrent(snapshot, expectedRevision, ownedSnapshot)) {
+  if (
+    !runtime.restoreSecretsRuntimeSnapshotIfCurrent(snapshot, expectedRevision, ownedSnapshot, {
+      runtimeSourceConfig: options?.runtimeSourceConfig,
+    })
+  ) {
     return false;
   }
   options?.onActivated?.();
@@ -1732,6 +1740,8 @@ export function startManagedGatewayConfigReloader(
           {
             reason: "restart-check",
             activate: false,
+            publishFailureAsDegraded: true,
+            canPublishFailureAsDegraded: transactionOwnership.isCurrent,
             ...(transactionOwnership.runtimeEnv
               ? { env: transactionOwnership.runtimeEnv.env }
               : {}),
@@ -1799,6 +1809,8 @@ export function startManagedGatewayConfigReloader(
             {
               reason: "restart-check",
               activate: false,
+              publishFailureAsDegraded: true,
+              canPublishFailureAsDegraded: transactionOwnership.isCurrent,
               ...(transactionOwnership.runtimeEnv
                 ? { env: transactionOwnership.runtimeEnv.env }
                 : {}),
@@ -1866,6 +1878,8 @@ export function startManagedGatewayConfigReloader(
             {
               reason: "restart-check",
               activate: false,
+              publishFailureAsDegraded: true,
+              canPublishFailureAsDegraded: transactionOwnership.isCurrent,
               ...(transactionOwnership.runtimeEnv
                 ? { env: transactionOwnership.runtimeEnv.env }
                 : {}),
@@ -1948,42 +1962,140 @@ export function startManagedGatewayConfigReloader(
       if (!transactionOwnership.isCurrent()) {
         throw new GatewayConfigReloadSupersededError();
       }
-      const metadata = getRuntimeConfigSnapshotMetadata();
       const previousRuntimeSourceConfig = getRuntimeConfigSourceSnapshot();
-      const previousSecretsSourceConfig = getActiveSecretsRuntimeSnapshot()?.sourceConfig;
+      const previousSecretsSnapshot = getActiveSecretsRuntimeSnapshot();
       const previousSecretsRevision = getActiveSecretsRuntimeSnapshotRevision();
+      const nextSecretsSourceConfig = prepareRuntimeCandidate(
+        nextConfig,
+        sourceConfig,
+        transactionOwnership,
+      );
       if (
-        !metadata ||
-        !previousRuntimeSourceConfig ||
-        !setSecretsRuntimeSourceSnapshotIfCurrent({
-          expectedSecretsRevision: previousSecretsRevision,
-          expectedRuntimeConfigRevision: metadata.revision,
-          runtimeSourceConfig: sourceConfig,
-          secretsSourceConfig: prepareRuntimeCandidate(
-            nextConfig,
-            sourceConfig,
-            transactionOwnership,
-          ),
-        }) ||
-        !transactionOwnership.isCurrent()
+        previousRuntimeSourceConfig &&
+        previousSecretsSnapshot &&
+        hasSameSecretReloadContract(previousSecretsSnapshot.sourceConfig, nextSecretsSourceConfig)
       ) {
+        const sourceOnlySnapshot = {
+          ...previousSecretsSnapshot,
+          sourceConfig: nextSecretsSourceConfig,
+          warnings: [],
+        };
+        if (!isDeepStrictEqual(sourceOnlySnapshot.config, nextConfig)) {
+          throw new GatewayConfigReloadSupersededError();
+        }
+        const activateIfCurrent = params.activateRuntimeSecrets.activatePreparedSnapshotIfCurrent;
+        const activated = activateIfCurrent
+          ? await activateIfCurrent(
+              sourceOnlySnapshot,
+              previousSecretsRevision,
+              {
+                reason: "reload",
+                activate: true,
+                publishRecovery: false,
+                runtimeSourceConfig: sourceConfig,
+              },
+              undefined,
+              transactionOwnership.isCurrent,
+            )
+          : (await activateSecretsRuntimeSnapshotIfCurrent(
+                sourceOnlySnapshot,
+                previousSecretsRevision,
+                {
+                  canActivate: transactionOwnership.isCurrent,
+                  runtimeSourceConfig: sourceConfig,
+                },
+              ))
+            ? sourceOnlySnapshot
+            : null;
+        if (!activated) {
+          throw new GatewayConfigReloadSupersededError();
+        }
+        const committedSecretsRevision = getActiveSecretsRuntimeSnapshotRevision();
+        const rollbackPublishedSource = async () => {
+          if (
+            !(await restoreSecretsRuntimeSnapshotIfCurrent(
+              previousSecretsSnapshot,
+              committedSecretsRevision,
+              activated,
+              { runtimeSourceConfig: previousRuntimeSourceConfig },
+            ))
+          ) {
+            throw new GatewayConfigReloadSupersededError();
+          }
+        };
+        if (!transactionOwnership.isCurrent()) {
+          await rollbackPublishedSource();
+          throw new GatewayConfigReloadSupersededError();
+        }
+        return {
+          rollback: rollbackPublishedSource,
+          commit: () =>
+            publishRuntimeSecretsRecovery(params.activateRuntimeSecrets, activated, {
+              sourceOnly: true,
+            }),
+        };
+      }
+      const preparedSecrets = await params.activateRuntimeSecrets(nextSecretsSourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: transactionOwnership.isCurrent,
+        ...(transactionOwnership.runtimeEnv ? { env: transactionOwnership.runtimeEnv.env } : {}),
+        includeAuthStoreRefs: true,
+      });
+      if (!transactionOwnership.isCurrent()) {
+        throw new GatewayConfigReloadSupersededError();
+      }
+      if (!isDeepStrictEqual(preparedSecrets.config, nextConfig)) {
+        throw new GatewayConfigReloadSupersededError();
+      }
+      if (!previousRuntimeSourceConfig || !previousSecretsSnapshot) {
+        throw new GatewayConfigReloadSupersededError();
+      }
+      const activateIfCurrent = params.activateRuntimeSecrets.activatePreparedSnapshotIfCurrent;
+      const activated = activateIfCurrent
+        ? await activateIfCurrent(
+            preparedSecrets,
+            previousSecretsRevision,
+            {
+              reason: "reload",
+              activate: true,
+              publishRecovery: false,
+              runtimeSourceConfig: sourceConfig,
+            },
+            undefined,
+            transactionOwnership.isCurrent,
+          )
+        : (await activateSecretsRuntimeSnapshotIfCurrent(preparedSecrets, previousSecretsRevision, {
+              canActivate: transactionOwnership.isCurrent,
+              runtimeSourceConfig: sourceConfig,
+            }))
+          ? preparedSecrets
+          : null;
+      if (!activated) {
         throw new GatewayConfigReloadSupersededError();
       }
-      const committedMetadata = getRuntimeConfigSnapshotMetadata();
       const committedSecretsRevision = getActiveSecretsRuntimeSnapshotRevision();
-      return async () => {
+      const rollbackPublishedSource = async () => {
         if (
-          !committedMetadata ||
-          !setSecretsRuntimeSourceSnapshotIfCurrent({
-            expectedSecretsRevision: committedSecretsRevision,
-            expectedRuntimeConfigRevision: committedMetadata.revision,
-            runtimeSourceConfig: previousRuntimeSourceConfig,
-            secretsSourceConfig: previousSecretsSourceConfig ?? previousRuntimeSourceConfig,
-          })
+          !(await restoreSecretsRuntimeSnapshotIfCurrent(
+            previousSecretsSnapshot,
+            committedSecretsRevision,
+            activated,
+            { runtimeSourceConfig: previousRuntimeSourceConfig },
+          ))
         ) {
           throw new GatewayConfigReloadSupersededError();
         }
       };
+      if (!transactionOwnership.isCurrent()) {
+        await rollbackPublishedSource();
+        throw new GatewayConfigReloadSupersededError();
+      }
+      return {
+        rollback: rollbackPublishedSource,
+        commit: () => publishRuntimeSecretsRecovery(params.activateRuntimeSecrets, activated),
+      };
     },
     onNoopConfigCommit: async (plan, nextConfig, transactionOwnership, sourceConfig) => {
       for (;;) {
@@ -1996,6 +2108,8 @@ export function startManagedGatewayConfigReloader(
           {
             reason: "reload",
             activate: false,
+            publishFailureAsDegraded: true,
+            canPublishFailureAsDegraded: transactionOwnership.isCurrent,
             ...(transactionOwnership.runtimeEnv
               ? { env: transactionOwnership.runtimeEnv.env }
               : {}),
@@ -2048,6 +2162,8 @@ export function startManagedGatewayConfigReloader(
           {
             reason: "reload",
             activate: false,
+            publishFailureAsDegraded: true,
+            canPublishFailureAsDegraded: transactionOwnership.isCurrent,
             ...(transactionOwnership.runtimeEnv
               ? { env: transactionOwnership.runtimeEnv.env }
               : {}),
@@ -2083,6 +2199,8 @@ export function startManagedGatewayConfigReloader(
                 {
                   reason: "restart-check",
                   activate: false,
+                  publishFailureAsDegraded: true,
+                  canPublishFailureAsDegraded: transactionOwnership.isCurrent,
                   ...(transactionOwnership.runtimeEnv
                     ? { env: transactionOwnership.runtimeEnv.env }
                     : {}),
diff --git a/src/gateway/server-startup-config.secrets.test.ts b/src/gateway/server-startup-config.secrets.test.ts
index 6211f9a5b25..0c671f848fc 100644
--- a/src/gateway/server-startup-config.secrets.test.ts
+++ b/src/gateway/server-startup-config.secrets.test.ts
@@ -13,6 +13,8 @@ import {
 } from "../agents/auth-profiles/runtime-snapshots.js";
 import type { ConfigFileSnapshot, OpenClawConfig } from "../config/types.js";
 import { measureDiagnosticsTimelineSpan } from "../infra/diagnostics-timeline.js";
+import { providerResolutionError, refResolutionError } from "../secrets/resolve-errors.js";
+import { associateSecretResolutionErrorOwners } from "../secrets/runtime-degraded-state.js";
 import {
   activateSecretsRuntimeSnapshotState,
   clearSecretsRuntimeSnapshot,
@@ -23,6 +25,7 @@ import type { PreparedSecretsRuntimeSnapshot, SecretResolverWarning } from "../s
 import {
   createRuntimeSecretsActivator,
   prepareGatewayStartupConfig,
+  publishRuntimeSecretsRecovery,
 } from "./server-startup-config.js";
 import { buildTestConfigSnapshot } from "./test-helpers.config-snapshots.js";
 
@@ -44,7 +47,7 @@ type GatewayStartupSecretsRuntimeMock = {
 
 type GatewayStartupLogMock = {
   info: ReturnType<typeof vi.fn<(message: string) => void>>;
-  warn: ReturnType<typeof vi.fn<(message: string) => void>>;
+  warn: ReturnType<typeof vi.fn<(message: string, meta?: Record<string, unknown>) => void>>;
   error: ReturnType<typeof vi.fn<(message: string) => void>>;
 };
 
@@ -184,7 +187,7 @@ function runtimeSecretsActivatorOptionsForTest() {
 function mockLogSecretsForTest(): GatewayStartupLogMock {
   return {
     info: vi.fn<(message: string) => void>(),
-    warn: vi.fn<(message: string) => void>(),
+    warn: vi.fn<(message: string, meta?: Record<string, unknown>) => void>(),
     error: vi.fn<(message: string) => void>(),
   };
 }
@@ -643,27 +646,89 @@ describe("gateway startup config secret preflight", () => {
   });
 
   it("wraps startup secret activation failures without emitting reload state events", async () => {
-    const error = new Error('Environment variable "OPENAI_API_KEY" is missing or empty.');
+    const error = refResolutionError({
+      code: "SECRET_REF_NOT_FOUND",
+      source: "env",
+      provider: "default",
+      refId: "PRIVATE_STARTUP_AUTH_REF",
+      message: 'Environment variable "PRIVATE_STARTUP_AUTH_REF" is missing or empty.',
+    });
+    associateSecretResolutionErrorOwners(error, [
+      {
+        ownerKind: "gateway",
+        ownerId: "auth",
+        state: "unavailable",
+        paths: ["gateway.auth.token"],
+        refKeys: ["env:default:PRIVATE_STARTUP_AUTH_REF"],
+        reason: "secret reference was not found",
+        degradationState: "cold",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
     const prepareRuntimeSecretsSnapshot = vi.fn(async () => {
       throw error;
     });
     const emitStateEvent = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
     const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
       emitStateEvent,
+      logSecrets,
       prepareRuntimeSecretsSnapshot,
     });
 
-    await expect(
-      activateRuntimeSecrets(gatewayTokenConfig({}), {
-        reason: "startup",
-        activate: false,
-      }),
-    ).rejects.toThrow(
-      'Startup failed: required secrets are unavailable. Error: Environment variable "OPENAI_API_KEY" is missing or empty.',
+    const startupFailure = await activateRuntimeSecrets(gatewayTokenConfig({}), {
+      reason: "startup",
+      activate: false,
+    }).then(
+      () => null,
+      (caught: unknown) => caught,
+    );
+    expect(startupFailure).toBeInstanceOf(Error);
+    expect(String(startupFailure)).toBe("Error: Startup failed: required secrets are unavailable.");
+    expect((startupFailure as Error).cause).toBeUndefined();
+    expect(String(startupFailure)).not.toContain("PRIVATE_STARTUP_AUTH_REF");
+    expect(logSecrets.warn).toHaveBeenCalledWith(
+      "[SECRETS_DEGRADED] cold gateway:auth: secret reference was not found. " +
+        "Retry: openclaw secrets reload.",
+      {
+        event: "secrets.degraded",
+        ownerKind: "gateway",
+        ownerId: "auth",
+        reason: "secret reference was not found",
+        state: "cold",
+        retryHint: "openclaw secrets reload",
+      },
     );
+    expect(JSON.stringify(logSecrets.warn.mock.calls)).not.toContain("PRIVATE_STARTUP_AUTH_REF");
     expect(emitStateEvent).not.toHaveBeenCalled();
   });
 
+  it("preserves diagnostics for unclassified startup activation failures", async () => {
+    const error = new Error("secret provider transport failed");
+    const logSecrets = mockLogSecretsForTest();
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      logSecrets,
+      prepareRuntimeSecretsSnapshot: vi.fn(async () => {
+        throw error;
+      }),
+    });
+
+    const startupFailure = await activateRuntimeSecrets(gatewayTokenConfig({}), {
+      reason: "startup",
+      activate: false,
+    }).then(
+      () => null,
+      (caught: unknown) => caught,
+    );
+    expect(String(startupFailure)).toContain("secret provider transport failed");
+    expect((startupFailure as Error).cause).toBe(error);
+    expect(logSecrets.warn).not.toHaveBeenCalledWith(
+      expect.stringContaining("SECRETS_DEGRADED"),
+      expect.anything(),
+    );
+  });
+
   it("allows cold startup snapshots with isolated SecretRef owners", async () => {
     const sourceConfig = gatewayTokenConfig({
       messages: {
@@ -680,12 +745,22 @@ describe("gateway startup config secret preflight", () => {
       code: "SECRETS_OWNER_UNAVAILABLE",
       path: "messages.tts.providers.elevenlabs.apiKey",
       message:
-        "Secret owner capability:tts is configured-unavailable; paths: messages.tts.providers.elevenlabs.apiKey; reason: secret reference was not found.",
+        "Secret owner capability:tts is configured-unavailable; paths: messages.tts.providers.elevenlabs.apiKey; reason: secret provider policy denied resolution.",
     };
     const prepareRuntimeSecretsSnapshot = vi.fn(async () => ({
       ...preparedSnapshot(sourceConfig),
       config: structuredClone(sourceConfig),
       warnings: [warning],
+      degradedOwners: [
+        {
+          ownerKind: "capability" as const,
+          ownerId: "tts",
+          state: "unavailable" as const,
+          paths: ["messages.tts.providers.elevenlabs.apiKey"],
+          refKeys: ["env:default:ELEVENLABS_API_KEY"],
+          reason: "secret provider policy denied resolution",
+        },
+      ],
     }));
     const emitStateEvent = vi.fn();
     const logSecrets = mockLogSecretsForTest();
@@ -707,12 +782,26 @@ describe("gateway startup config secret preflight", () => {
       expect.objectContaining({ allowUnavailableSecretOwners: true }),
     );
     expect(logSecrets.warn).toHaveBeenCalledWith(`[${warning.code}] ${warning.message}`);
+    expect(logSecrets.warn).toHaveBeenCalledWith(
+      "[SECRETS_DEGRADED] cold capability:tts: secret provider policy denied resolution. " +
+        "Retry: openclaw secrets reload.",
+      {
+        event: "secrets.degraded",
+        ownerKind: "capability",
+        ownerId: "tts",
+        reason: "secret provider policy denied resolution",
+        state: "cold",
+        retryHint: "openclaw secrets reload",
+      },
+    );
+    expect(JSON.stringify(logSecrets.warn.mock.calls)).not.toContain("ELEVENLABS_API_KEY");
     expect(emitStateEvent).not.toHaveBeenCalled();
   });
 
   it.each(["reload", "restart-check"] as const)(
-    "keeps unavailable SecretRef owners fail-closed during %s",
+    "does not classify untyped %s errors as secret degradation",
     async (reason) => {
+      activateSecretsRuntimeSnapshotForTest(preparedSnapshot(gatewayTokenConfig({})));
       const missingSecretError = new Error(
         'Environment variable "ELEVENLABS_API_KEY" is missing or empty.',
       );
@@ -720,15 +809,20 @@ describe("gateway startup config secret preflight", () => {
         throw missingSecretError;
       });
       const activateRuntimeSecretsSnapshot = vi.fn();
+      const emitStateEvent = vi.fn();
+      const logSecrets = mockLogSecretsForTest();
       const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
         prepareRuntimeSecretsSnapshot,
         activateRuntimeSecretsSnapshot,
+        emitStateEvent,
+        logSecrets,
       });
 
       await expect(
         activateRuntimeSecrets(gatewayTokenConfig({}), {
           reason,
-          activate: true,
+          activate: false,
+          publishFailureAsDegraded: true,
         }),
       ).rejects.toThrow(missingSecretError.message);
 
@@ -736,15 +830,257 @@ describe("gateway startup config secret preflight", () => {
         expect.objectContaining({ allowUnavailableSecretOwners: false }),
       );
       expect(activateRuntimeSecretsSnapshot).not.toHaveBeenCalled();
+      expect(logSecrets.warn).not.toHaveBeenCalledWith(
+        expect.stringContaining("SECRETS_DEGRADED"),
+        expect.anything(),
+      );
+      expect(emitStateEvent).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["reload", "restart-check"] as const)(
+    "publishes the owner when a resolved secret value is invalid during %s",
+    async (reason) => {
+      activateSecretsRuntimeSnapshotForTest(preparedSnapshot(gatewayTokenConfig({})));
+      const invalidSecretError = new Error(
+        "messages.tts.providers.elevenlabs.apiKey resolved to a non-string or empty value.",
+      );
+      associateSecretResolutionErrorOwners(invalidSecretError, [
+        {
+          ownerKind: "capability",
+          ownerId: "tts",
+          state: "unavailable",
+          paths: ["messages.tts.providers.elevenlabs.apiKey"],
+          refKeys: ["file:ttsfile:/private/value"],
+          reason: "resolved secret value was invalid",
+          degradationState: "stale",
+          failureMatched: true,
+          source: "config",
+        },
+      ]);
+      const prepareRuntimeSecretsSnapshot = vi.fn(async () => {
+        throw invalidSecretError;
+      });
+      const emitStateEvent = vi.fn();
+      const logSecrets = mockLogSecretsForTest();
+      const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+        prepareRuntimeSecretsSnapshot,
+        emitStateEvent,
+        logSecrets,
+      });
+
+      await expect(
+        activateRuntimeSecrets(gatewayTokenConfig({}), {
+          reason,
+          activate: false,
+          publishFailureAsDegraded: true,
+        }),
+      ).rejects.toThrow(invalidSecretError.message);
+
+      expect(logSecrets.warn).toHaveBeenCalledWith(
+        "[SECRETS_DEGRADED] stale capability:tts: resolved secret value was invalid. " +
+          "Retry: openclaw secrets reload.",
+        {
+          event: "secrets.degraded",
+          ownerKind: "capability",
+          ownerId: "tts",
+          reason: "resolved secret value was invalid",
+          state: "stale",
+          retryHint: "openclaw secrets reload",
+        },
+      );
+      expect(JSON.stringify(logSecrets.warn.mock.calls)).not.toContain("/private/value");
+      expect(emitStateEvent).toHaveBeenCalledWith(
+        "SECRETS_RELOADER_DEGRADED",
+        "Secret resolution failed; runtime remains on the last-known-good snapshot.",
+        expect.anything(),
+      );
     },
   );
 
+  it("does not publish typed degradation after reload ownership expires", async () => {
+    activateSecretsRuntimeSnapshotForTest(preparedSnapshot(gatewayTokenConfig({})));
+    const failure = refResolutionError({
+      code: "SECRET_REF_NOT_FOUND",
+      source: "env",
+      provider: "default",
+      refId: "EXPIRED_RELOAD_REF",
+      message: "expired reload fixture",
+    });
+    associateSecretResolutionErrorOwners(failure, [
+      {
+        ownerKind: "capability",
+        ownerId: "tts",
+        state: "unavailable",
+        paths: ["messages.tts.providers.elevenlabs.apiKey"],
+        refKeys: ["env:default:EXPIRED_RELOAD_REF"],
+        reason: "secret reference was not found",
+        degradationState: "stale",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
+    const emitStateEvent = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      prepareRuntimeSecretsSnapshot: vi.fn(async () => {
+        throw failure;
+      }),
+      emitStateEvent,
+      logSecrets,
+    });
+
+    await expect(
+      activateRuntimeSecrets(gatewayTokenConfig({}), {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+        canPublishFailureAsDegraded: () => false,
+      }),
+    ).rejects.toThrow(failure.message);
+
+    expect(logSecrets.warn).not.toHaveBeenCalled();
+    expect(emitStateEvent).not.toHaveBeenCalled();
+  });
+
+  it("publishes a redacted unknown-owner warning for an unmapped typed reload failure", async () => {
+    activateSecretsRuntimeSnapshotForTest(preparedSnapshot(gatewayTokenConfig({})));
+    const missingSecretError = refResolutionError({
+      code: "SECRET_REF_NOT_FOUND",
+      source: "env",
+      provider: "default",
+      refId: "PRIVATE_UNMAPPED_REF",
+      message: 'Environment variable "PRIVATE_UNMAPPED_REF" is missing or empty.',
+    });
+    const prepareRuntimeSecretsSnapshot = vi.fn(async () => {
+      throw missingSecretError;
+    });
+    const emitStateEvent = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      prepareRuntimeSecretsSnapshot,
+      emitStateEvent,
+      logSecrets,
+    });
+
+    await expect(
+      activateRuntimeSecrets(gatewayTokenConfig({}), {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+
+    expect(logSecrets.warn).toHaveBeenCalledWith(
+      "[SECRETS_DEGRADED] cold unknown:unmapped: secret reference was not found. " +
+        "Retry: openclaw secrets reload.",
+      {
+        event: "secrets.degraded",
+        ownerKind: "unknown",
+        ownerId: "unmapped",
+        reason: "secret reference was not found",
+        state: "cold",
+        retryHint: "openclaw secrets reload",
+      },
+    );
+    expect(JSON.stringify(logSecrets.warn.mock.calls)).not.toContain("PRIVATE_UNMAPPED_REF");
+    expect(emitStateEvent).toHaveBeenCalledWith(
+      "SECRETS_RELOADER_DEGRADED",
+      "Secret resolution failed; runtime remains on the last-known-good snapshot.",
+      expect.anything(),
+    );
+  });
+
+  it("preserves invalid provider diagnostics instead of reporting runtime degradation", async () => {
+    const invalidProviderError = providerResolutionError({
+      code: "SECRET_PROVIDER_INVALID",
+      source: "env",
+      provider: "missing",
+      message: 'Secret provider "missing" is not configured.',
+    });
+    const emitStateEvent = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      prepareRuntimeSecretsSnapshot: vi.fn(async () => {
+        throw invalidProviderError;
+      }),
+      emitStateEvent,
+      logSecrets,
+    });
+
+    await expect(
+      activateRuntimeSecrets(gatewayTokenConfig({}), {
+        reason: "startup",
+        activate: false,
+      }),
+    ).rejects.toThrow('Secret provider "missing" is not configured.');
+
+    expect(logSecrets.warn).not.toHaveBeenCalled();
+    expect(emitStateEvent).not.toHaveBeenCalled();
+  });
+
+  it("does not publish a rejected candidate-only preflight as active degradation", async () => {
+    let shouldFail = true;
+    const prepareRuntimeSecretsSnapshot = vi.fn(async ({ config }) => {
+      if (shouldFail) {
+        throw new Error("candidate secret resolution failed");
+      }
+      return preparedSnapshot(config);
+    });
+    const emitStateEvent = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      prepareRuntimeSecretsSnapshot,
+      emitStateEvent,
+      logSecrets,
+    });
+
+    await expect(
+      activateRuntimeSecrets(gatewayTokenConfig({}), {
+        reason: "reload",
+        activate: false,
+      }),
+    ).rejects.toThrow("candidate secret resolution failed");
+
+    expect(emitStateEvent).not.toHaveBeenCalled();
+    expect(logSecrets.warn).not.toHaveBeenCalledWith(
+      expect.stringContaining("SECRETS_DEGRADED"),
+      expect.anything(),
+    );
+
+    shouldFail = false;
+    await expect(
+      activateRuntimeSecrets(gatewayTokenConfig({}), {
+        reason: "reload",
+        activate: false,
+      }),
+    ).resolves.toBeDefined();
+    expect(emitStateEvent).not.toHaveBeenCalled();
+    expect(logSecrets.info).not.toHaveBeenCalledWith(
+      expect.stringContaining("SECRETS_RELOADER_RECOVERED"),
+    );
+  });
+
   it("enables cold-start owner isolation during non-activating startup preparation", async () => {
-    const prepareRuntimeSecretsSnapshot = vi.fn(async ({ config }) => preparedSnapshot(config));
+    const prepareRuntimeSecretsSnapshot = vi.fn(async ({ config }) => ({
+      ...preparedSnapshot(config),
+      degradedOwners: [
+        {
+          ownerKind: "capability" as const,
+          ownerId: "tts",
+          state: "unavailable" as const,
+          paths: ["messages.tts.providers.elevenlabs.apiKey"],
+          refKeys: ["env:default:ELEVENLABS_API_KEY"],
+          reason: "secret reference was not found",
+        },
+      ],
+    }));
     const activateRuntimeSecretsSnapshot = vi.fn();
+    const logSecrets = mockLogSecretsForTest();
     const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
       prepareRuntimeSecretsSnapshot,
       activateRuntimeSecretsSnapshot,
+      logSecrets,
     });
 
     await activateRuntimeSecrets(gatewayTokenConfig({}), {
@@ -756,6 +1092,10 @@ describe("gateway startup config secret preflight", () => {
       expect.objectContaining({ allowUnavailableSecretOwners: true }),
     );
     expect(activateRuntimeSecretsSnapshot).not.toHaveBeenCalled();
+    expect(logSecrets.warn).not.toHaveBeenCalledWith(
+      expect.stringContaining("SECRETS_DEGRADED"),
+      expect.anything(),
+    );
   });
 
   it("does not enable cold-start degradation while a runtime snapshot is active", async () => {
@@ -867,6 +1207,22 @@ describe("gateway startup config secret preflight", () => {
         },
       },
     });
+    const activeSnapshot = preparedSnapshot(sourceConfig);
+    activeSnapshot.config.models!.providers!.openai!.apiKey = "test-api-key";
+    activateSecretsRuntimeSnapshotForTest(activeSnapshot);
+    associateSecretResolutionErrorOwners(missingSecretError, [
+      {
+        ownerKind: "provider",
+        ownerId: "openai",
+        state: "unavailable",
+        paths: ["models.providers.openai.apiKey"],
+        refKeys: ["env:default:OPENAI_API_KEY"],
+        reason: "secret reference was not found",
+        degradationState: "stale",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
     const prepareRuntimeSecretsSnapshot = vi.fn(async ({ config }) => {
       if (!shouldResolve) {
         throw missingSecretError;
@@ -879,39 +1235,373 @@ describe("gateway startup config secret preflight", () => {
       logSecrets,
       emitStateEvent,
       prepareRuntimeSecretsSnapshot,
+      activateRuntimeSecretsSnapshot: activateSecretsRuntimeSnapshotForTest,
     });
 
     await expect(
       activateRuntimeSecrets(sourceConfig, {
         reason: "reload",
-        activate: true,
+        activate: false,
+        publishFailureAsDegraded: true,
       }),
     ).rejects.toThrow(missingSecretError.message);
     await expect(
       activateRuntimeSecrets(sourceConfig, {
         reason: "reload",
-        activate: true,
+        activate: false,
+        publishFailureAsDegraded: true,
       }),
     ).rejects.toThrow(missingSecretError.message);
     shouldResolve = true;
+    const activeRevision = getActiveSecretsRuntimeSnapshotRevision();
+    const prepared = await activateRuntimeSecrets(sourceConfig, {
+      reason: "restart-check",
+      activate: false,
+    });
+    expect(emitStateEvent).toHaveBeenCalledTimes(1);
+
     await expect(
-      activateRuntimeSecrets(sourceConfig, {
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(prepared, activeRevision, {
         reason: "reload",
         activate: true,
       }),
     ).resolves.toMatchObject({ config: sourceConfig });
-
     expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
       "SECRETS_RELOADER_DEGRADED",
       "SECRETS_RELOADER_RECOVERED",
     ]);
-    expect(logSecrets.error).toHaveBeenCalledTimes(1);
+    expect(emitStateEvent.mock.calls[0]?.[1]).toBe(
+      "Secret resolution failed; runtime remains on the last-known-good snapshot.",
+    );
+    expect(logSecrets.error).not.toHaveBeenCalled();
+    expect(logSecrets.warn).toHaveBeenCalledTimes(2);
     expect(logSecrets.warn).toHaveBeenCalledWith(
-      `[SECRETS_RELOADER_DEGRADED] Error: ${missingSecretError.message}`,
+      "[SECRETS_DEGRADED] stale provider:openai: secret reference was not found. " +
+        "Retry: openclaw secrets reload.",
+      {
+        event: "secrets.degraded",
+        ownerKind: "provider",
+        ownerId: "openai",
+        reason: "secret reference was not found",
+        state: "stale",
+        retryHint: "openclaw secrets reload",
+      },
     );
+    expect(JSON.stringify(logSecrets.warn.mock.calls)).not.toContain("OPENAI_API_KEY");
     expect(logSecrets.info).toHaveBeenCalledWith(
       "[SECRETS_RELOADER_RECOVERED] Secret resolution recovered; runtime remained on last-known-good during the outage.",
     );
+
+    shouldResolve = false;
+    await expect(
+      activateRuntimeSecrets(sourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+    shouldResolve = true;
+    const sourceOnlyRevision = getActiveSecretsRuntimeSnapshotRevision();
+    const sourceOnly = await activateRuntimeSecrets(sourceConfig, {
+      reason: "reload",
+      activate: false,
+      publishFailureAsDegraded: true,
+    });
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(sourceOnly, sourceOnlyRevision, {
+        reason: "reload",
+        activate: true,
+        publishRecovery: false,
+      }),
+    ).resolves.toMatchObject({ config: sourceConfig });
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+    ]);
+    shouldResolve = false;
+    await expect(
+      activateRuntimeSecrets(sourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, sourceOnly);
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+    ]);
+    shouldResolve = true;
+    const newerRevision = getActiveSecretsRuntimeSnapshotRevision();
+    const newerPrepared = await activateRuntimeSecrets(sourceConfig, {
+      reason: "reload",
+      activate: false,
+    });
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(newerPrepared, newerRevision, {
+        reason: "reload",
+        activate: true,
+      }),
+    ).resolves.toMatchObject({ config: sourceConfig });
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+    ]);
+
+    const changedSourceConfig: OpenClawConfig = structuredClone(sourceConfig);
+    changedSourceConfig.models!.providers!.openai!.apiKey = {
+      source: "env",
+      provider: "default",
+      id: "OPENAI_API_KEY_NEXT",
+    };
+    associateSecretResolutionErrorOwners(missingSecretError, [
+      {
+        ownerKind: "provider",
+        ownerId: "openai",
+        state: "unavailable",
+        paths: ["models.providers.openai.apiKey"],
+        refKeys: ["env:default:OPENAI_API_KEY_NEXT"],
+        reason: "secret reference was not found",
+        degradationState: "cold",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
+    shouldResolve = false;
+    await expect(
+      activateRuntimeSecrets(changedSourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+    const revertedSnapshot = getActiveSecretsRuntimeSnapshot()!;
+    const revertedRevision = getActiveSecretsRuntimeSnapshotRevision();
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        revertedSnapshot,
+        revertedRevision,
+        {
+          reason: "reload",
+          activate: true,
+          publishRecovery: false,
+        },
+      ),
+    ).resolves.toMatchObject({ sourceConfig });
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, revertedSnapshot, { sourceOnly: true });
+    expect(emitStateEvent.mock.calls.map((call) => call[0]).slice(-2)).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+    ]);
+
+    const unrelatedChangedSourceConfig = structuredClone(sourceConfig);
+    unrelatedChangedSourceConfig.messages = {
+      tts: {
+        providers: {
+          elevenlabs: {
+            apiKey: { source: "env", provider: "default", id: "UNRELATED_TTS_KEY" },
+          },
+        },
+      },
+    };
+    associateSecretResolutionErrorOwners(missingSecretError, [
+      {
+        ownerKind: "provider",
+        ownerId: "openai",
+        state: "unavailable",
+        paths: ["models.providers.openai.apiKey"],
+        refKeys: ["env:default:OPENAI_API_KEY"],
+        reason: "secret reference was not found",
+        degradationState: "stale",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
+    await expect(
+      activateRuntimeSecrets(unrelatedChangedSourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+    const unrelatedRevertedSnapshot = getActiveSecretsRuntimeSnapshot()!;
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        unrelatedRevertedSnapshot,
+        getActiveSecretsRuntimeSnapshotRevision(),
+        { reason: "reload", activate: true, publishRecovery: false },
+      ),
+    ).resolves.toMatchObject({ sourceConfig });
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, unrelatedRevertedSnapshot, {
+      sourceOnly: true,
+    });
+    expect(emitStateEvent.mock.calls.map((call) => call[0]).slice(-2)).toEqual([
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+    ]);
+
+    await expect(
+      activateRuntimeSecrets(sourceConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toThrow(missingSecretError.message);
+    const unchangedSnapshot = getActiveSecretsRuntimeSnapshot()!;
+    const unchangedRevision = getActiveSecretsRuntimeSnapshotRevision();
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        unchangedSnapshot,
+        unchangedRevision,
+        {
+          reason: "reload",
+          activate: true,
+          publishRecovery: false,
+        },
+      ),
+    ).resolves.toMatchObject({ sourceConfig });
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, unchangedSnapshot, { sourceOnly: true });
+    expect(emitStateEvent.mock.calls.map((call) => call[0]).slice(-2)).toEqual([
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+    ]);
+  });
+
+  it("does not recover auth-store degradation from a config-only source reversion", async () => {
+    const stableConfig = gatewayTokenConfig({
+      models: {
+        providers: {
+          openai: {
+            baseUrl: "https://api.openai.com/v1",
+            apiKey: { source: "env", provider: "default", id: "OPENAI_STABLE" },
+            models: [],
+          },
+        },
+      },
+    });
+    const changedConfig = structuredClone(stableConfig);
+    changedConfig.models!.providers!.openai!.apiKey = {
+      source: "env",
+      provider: "default",
+      id: "OPENAI_CHANGED",
+    };
+    const configFailure = new Error("config secret failed");
+    associateSecretResolutionErrorOwners(configFailure, [
+      {
+        ownerKind: "provider",
+        ownerId: "openai",
+        state: "unavailable",
+        paths: ["models.providers.openai.apiKey"],
+        refKeys: ["env:default:OPENAI_CHANGED"],
+        reason: "secret reference was not found",
+        degradationState: "cold",
+        failureMatched: true,
+        source: "config",
+      },
+    ]);
+    const authStoreFailure = new Error("auth store secret failed");
+    associateSecretResolutionErrorOwners(authStoreFailure, [
+      {
+        ownerKind: "account",
+        ownerId: "auth-profile-owner",
+        state: "unavailable",
+        paths: ["/tmp/agent.auth-profiles.openai:default.key"],
+        refKeys: ["env:default:AUTH_PROFILE_KEY"],
+        reason: "secret reference was not found",
+        degradationState: "stale",
+        failureMatched: true,
+        source: "auth-store",
+      },
+    ]);
+    const emitStateEvent = vi.fn();
+    let nextFailure = configFailure;
+    const activateRuntimeSecrets = runtimeSecretsActivatorForTest({
+      emitStateEvent,
+      prepareRuntimeSecretsSnapshot: vi.fn(async () => {
+        throw nextFailure;
+      }),
+      activateRuntimeSecretsSnapshot: activateSecretsRuntimeSnapshotForTest,
+    });
+    activateSecretsRuntimeSnapshotForTest(preparedSnapshot(stableConfig));
+
+    await expect(
+      activateRuntimeSecrets(changedConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toBe(configFailure);
+    nextFailure = authStoreFailure;
+    await expect(
+      activateRuntimeSecrets(changedConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toBe(authStoreFailure);
+
+    const revertedSnapshot = preparedSnapshot(stableConfig);
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        revertedSnapshot,
+        getActiveSecretsRuntimeSnapshotRevision(),
+        { reason: "reload", activate: true, publishRecovery: false },
+      ),
+    ).resolves.toBe(revertedSnapshot);
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, revertedSnapshot, { sourceOnly: true });
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual(["SECRETS_RELOADER_DEGRADED"]);
+
+    const fullyResolvedSnapshot = preparedSnapshot(stableConfig);
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        fullyResolvedSnapshot,
+        getActiveSecretsRuntimeSnapshotRevision(),
+        { reason: "reload", activate: true, publishRecovery: false },
+      ),
+    ).resolves.toBe(fullyResolvedSnapshot);
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, fullyResolvedSnapshot);
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+    ]);
+
+    nextFailure = authStoreFailure;
+    await expect(
+      activateRuntimeSecrets(changedConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toBe(authStoreFailure);
+    nextFailure = configFailure;
+    await expect(
+      activateRuntimeSecrets(changedConfig, {
+        reason: "reload",
+        activate: false,
+        publishFailureAsDegraded: true,
+      }),
+    ).rejects.toBe(configFailure);
+
+    const secondRevertedSnapshot = preparedSnapshot(stableConfig);
+    await expect(
+      activateRuntimeSecrets.activatePreparedSnapshotIfCurrent?.(
+        secondRevertedSnapshot,
+        getActiveSecretsRuntimeSnapshotRevision(),
+        { reason: "reload", activate: true, publishRecovery: false },
+      ),
+    ).resolves.toBe(secondRevertedSnapshot);
+    publishRuntimeSecretsRecovery(activateRuntimeSecrets, secondRevertedSnapshot, {
+      sourceOnly: true,
+    });
+    expect(emitStateEvent.mock.calls.map((call) => call[0])).toEqual([
+      "SECRETS_RELOADER_DEGRADED",
+      "SECRETS_RELOADER_RECOVERED",
+      "SECRETS_RELOADER_DEGRADED",
+    ]);
   });
 
   it.each(KNOWN_WEAK_GATEWAY_TOKEN_PLACEHOLDERS)(
diff --git a/src/gateway/server-startup-config.ts b/src/gateway/server-startup-config.ts
index b22e112616a..c2a56b5dd5f 100644
--- a/src/gateway/server-startup-config.ts
+++ b/src/gateway/server-startup-config.ts
@@ -20,6 +20,13 @@ import type { ConfigFileSnapshot, OpenClawConfig } from "../config/types.opencla
 import { measureDiagnosticsTimelineSpan } from "../infra/diagnostics-timeline.js";
 import type { PluginManifestRegistry } from "../plugins/manifest-registry.js";
 import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
+import {
+  classifySecretResolutionErrorDegradations,
+  listSecretResolutionErrorOwners,
+  redactSecretDegradationReason,
+  SECRET_DEGRADATION_RETRY_HINT,
+  type SecretDegradation,
+} from "../secrets/runtime-degraded-state.js";
 import { prepareSecretsRuntimeFastPathSnapshot } from "../secrets/runtime-fast-path.js";
 import {
   GATEWAY_AUTH_SURFACE_PATHS,
@@ -30,6 +37,7 @@ import {
   graftActiveSecretsRuntimeAuthState,
   getActiveSecretsRuntimeSnapshot,
   getActiveSecretsRuntimeSnapshotRevision,
+  hasSameSecretReloadContract,
   hasCurrentAuthStoreCredentialsRevision,
 } from "../secrets/runtime-state.js";
 import { createLazyPromise } from "../shared/lazy-runtime.js";
@@ -48,7 +56,7 @@ import {
 
 type GatewayStartupLog = {
   info: (message: string) => void;
-  warn: (message: string) => void;
+  warn: (message: string, meta?: Record<string, unknown>) => void;
   error?: (message: string) => void;
 };
 
@@ -63,8 +71,16 @@ type PreparedRuntimeSecretsSnapshot = Awaited<ReturnType<PrepareRuntimeSecretsSn
 type RuntimeSecretsActivationParams = {
   reason: "startup" | "reload" | "restart-check";
   activate: boolean;
+  /** This preparation belongs to a live reload; publish failure against the active snapshot. */
+  publishFailureAsDegraded?: boolean;
+  /** Reject warning publication after a speculative reload loses transaction ownership. */
+  canPublishFailureAsDegraded?: () => boolean;
   env?: NodeJS.ProcessEnv;
   includeAuthStoreRefs?: boolean;
+  /** Raw config source paired with an otherwise fully activated prepared snapshot. */
+  runtimeSourceConfig?: OpenClawConfig;
+  /** Defer recovery until a larger transaction can no longer roll activation back. */
+  publishRecovery?: boolean;
 };
 
 /** Gateway startup hook that prepares secrets and optionally activates the prepared snapshot. */
@@ -85,6 +101,20 @@ export type ActivateRuntimeSecrets = ((
   ) => Promise<PreparedRuntimeSecretsSnapshot | null>;
 };
 
+const runtimeSecretsRecoveryPublishers = new WeakMap<
+  ActivateRuntimeSecrets,
+  (snapshot: PreparedRuntimeSecretsSnapshot, options?: { sourceOnly?: boolean }) => void
+>();
+
+/** Publishes recovery after a prepared source-only snapshot wins its commit CAS. */
+export function publishRuntimeSecretsRecovery(
+  activateRuntimeSecrets: ActivateRuntimeSecrets,
+  snapshot: PreparedRuntimeSecretsSnapshot,
+  options?: { sourceOnly?: boolean },
+): void {
+  runtimeSecretsRecoveryPublishers.get(activateRuntimeSecrets)?.(snapshot, options);
+}
+
 type GatewayStartupConfigOverrides = {
   auth?: GatewayAuthConfig;
   tailscale?: GatewayTailscaleConfig;
@@ -96,6 +126,22 @@ type GatewayStartupConfigMeasure = <T>(
   options?: { omitErrorMessage?: boolean },
 ) => Promise<T>;
 
+function logSecretDegradation(log: GatewayStartupLog, degradation: SecretDegradation): void {
+  const reason = redactSecretDegradationReason(degradation.reason);
+  log.warn(
+    `[SECRETS_DEGRADED] ${degradation.state} ${degradation.kind}:${degradation.id}: ` +
+      `${reason}. Retry: ${degradation.retryHint}.`,
+    {
+      event: "secrets.degraded",
+      ownerKind: degradation.kind,
+      ownerId: degradation.id,
+      reason,
+      state: degradation.state,
+      retryHint: degradation.retryHint,
+    },
+  );
+}
+
 /** Config snapshot plus optional plugin metadata loaded before Gateway startup auth. */
 export type GatewayStartupConfigSnapshotLoadResult = {
   snapshot: ConfigFileSnapshot;
@@ -185,7 +231,11 @@ export function createRuntimeSecretsActivator(params: {
   pluginMetadataSnapshot?: Pick<PluginMetadataSnapshot, "plugins" | "manifestRegistry">;
   channelAutostartSuppression?: ChannelAutostartSuppression | null;
 }): ActivateRuntimeSecrets {
-  let secretsDegraded = false;
+  let degradationGeneration = 0;
+  let activeDegradationGeneration: number | null = null;
+  let activeDegradationConfig: OpenClawConfig | null = null;
+  let activeDegradationSupportsSourceOnlyRecovery = false;
+  const deferredRecoveryGenerations = new WeakMap<object, number>();
   let secretsActivationTail: Promise<void> = Promise.resolve();
   const loadSecretsRuntime = createLazyPromise(() => import("../secrets/runtime.js"), {
     cacheRejections: true,
@@ -213,6 +263,22 @@ export function createRuntimeSecretsActivator(params: {
     return (await loadSecretsRuntime()).activateSecretsRuntimeSnapshot;
   };
 
+  const publishRecovery = (config: OpenClawConfig, expectedGeneration?: number) => {
+    if (
+      activeDegradationGeneration === null ||
+      (expectedGeneration !== undefined && activeDegradationGeneration !== expectedGeneration)
+    ) {
+      return;
+    }
+    const recoveredMessage =
+      "Secret resolution recovered; runtime remained on last-known-good during the outage.";
+    params.logSecrets.info(`[SECRETS_RELOADER_RECOVERED] ${recoveredMessage}`);
+    params.emitStateEvent("SECRETS_RELOADER_RECOVERED", recoveredMessage, config);
+    activeDegradationGeneration = null;
+    activeDegradationConfig = null;
+    activeDegradationSupportsSourceOnlyRecovery = false;
+  };
+
   const finishPreparedSnapshot = async (
     prepared: PreparedRuntimeSecretsSnapshot,
     activationParams: RuntimeSecretsActivationParams,
@@ -234,13 +300,28 @@ export function createRuntimeSecretsActivator(params: {
     for (const warning of prepared.warnings) {
       params.logSecrets.warn(`[${warning.code}] ${warning.message}`);
     }
-    if (secretsDegraded) {
-      const recoveredMessage =
-        "Secret resolution recovered; runtime remained on last-known-good during the outage.";
-      params.logSecrets.info(`[SECRETS_RELOADER_RECOVERED] ${recoveredMessage}`);
-      params.emitStateEvent("SECRETS_RELOADER_RECOVERED", recoveredMessage, prepared.config);
+    if (
+      activationParams.reason === "startup" &&
+      activationParams.activate &&
+      (prepared.degradedOwners?.length ?? 0) > 0
+    ) {
+      for (const owner of prepared.degradedOwners ?? []) {
+        logSecretDegradation(params.logSecrets, {
+          kind: owner.ownerKind,
+          id: owner.ownerId,
+          reason: owner.reason,
+          state: "cold",
+          retryHint: SECRET_DEGRADATION_RETRY_HINT,
+        });
+      }
+    }
+    if (activationParams.activate && activeDegradationGeneration !== null) {
+      if (activationParams.publishRecovery === false) {
+        deferredRecoveryGenerations.set(prepared, activeDegradationGeneration);
+      } else {
+        publishRecovery(prepared.config);
+      }
     }
-    secretsDegraded = false;
     return prepared;
   };
 
@@ -249,22 +330,46 @@ export function createRuntimeSecretsActivator(params: {
     activationParams: RuntimeSecretsActivationParams,
     eventConfig: OpenClawConfig,
   ): never => {
-    const details = String(err);
-    if (!secretsDegraded) {
-      params.logSecrets.error?.(`[SECRETS_RELOADER_DEGRADED] ${details}`);
+    const mayPublishReloadDegradation =
+      (activationParams.activate || activationParams.publishFailureAsDegraded === true) &&
+      (activationParams.canPublishFailureAsDegraded?.() ?? true);
+    const degradations = classifySecretResolutionErrorDegradations(err);
+    if (
+      degradations.length > 0 &&
+      (activationParams.reason === "startup" || mayPublishReloadDegradation)
+    ) {
+      for (const degradation of degradations) {
+        logSecretDegradation(params.logSecrets, degradation);
+      }
       if (activationParams.reason !== "startup") {
-        params.emitStateEvent(
-          "SECRETS_RELOADER_DEGRADED",
-          `Secret resolution failed; runtime remains on last-known-good snapshot. ${details}`,
-          eventConfig,
+        const wasDegraded = activeDegradationGeneration !== null;
+        if (!wasDegraded) {
+          params.emitStateEvent(
+            "SECRETS_RELOADER_DEGRADED",
+            "Secret resolution failed; runtime remains on the last-known-good snapshot.",
+            eventConfig,
+          );
+        }
+        const failedOwners = listSecretResolutionErrorOwners(err).filter(
+          (owner) => owner.failureMatched,
         );
+        const currentFailureSupportsSourceOnlyRecovery =
+          failedOwners.length > 0 &&
+          failedOwners.every(
+            (owner) => owner.source === "config" && owner.degradationState === "cold",
+          );
+        activeDegradationSupportsSourceOnlyRecovery = wasDegraded
+          ? activeDegradationSupportsSourceOnlyRecovery && currentFailureSupportsSourceOnlyRecovery
+          : currentFailureSupportsSourceOnlyRecovery;
+        activeDegradationGeneration = ++degradationGeneration;
+        activeDegradationConfig = structuredClone(eventConfig);
       }
-    } else {
-      params.logSecrets.warn(`[SECRETS_RELOADER_DEGRADED] ${details}`);
     }
-    secretsDegraded = true;
     if (activationParams.reason === "startup") {
-      throw new Error(`Startup failed: required secrets are unavailable. ${details}`, {
+      if (degradations.length > 0) {
+        throw new Error("Startup failed: required secrets are unavailable.");
+      }
+      throw new Error(`Startup failed: required secrets are unavailable. ${String(err)}`, {
         cause: err,
       });
     }
@@ -273,6 +378,7 @@ export function createRuntimeSecretsActivator(params: {
 
   const activateRuntimeSecrets = (async (config, activationParams) =>
     await runWithSecretsActivationLock(async () => {
+      let activationSourceConfig = config;
       try {
         const { sourceConfig, assignmentConfig } = resolveGatewayStartupSecretProjection({
           config,
@@ -280,6 +386,7 @@ export function createRuntimeSecretsActivator(params: {
           channelAutostartSuppression: params.channelAutostartSuppression,
           ...(activationParams.env ? { env: activationParams.env } : {}),
         });
+        activationSourceConfig = sourceConfig;
         const startupPreflight =
           activationParams.reason === "startup" || activationParams.reason === "restart-check";
         if (
@@ -358,7 +465,7 @@ export function createRuntimeSecretsActivator(params: {
         }
         return await finishPreparedSnapshot(prepared, activationParams);
       } catch (err) {
-        return handleSecretsActivationError(err, activationParams, config);
+        return handleSecretsActivationError(err, activationParams, activationSourceConfig);
       }
     })) as ActivateRuntimeSecrets;
 
@@ -380,8 +487,17 @@ export function createRuntimeSecretsActivator(params: {
   ) => {
     // Resolve the lazy activator before entering the compare-and-activate
     // section so no await separates revision ownership from state publication.
+    const runtimeSourceConfig = activationParams.runtimeSourceConfig;
     const activateRuntimeSecretsSnapshot = activationParams.activate
-      ? await loadActivateRuntimeSecretsSnapshot()
+      ? runtimeSourceConfig
+        ? (
+            (runtime) => (preparedSnapshot: PreparedRuntimeSecretsSnapshot) =>
+              runtime.activateSecretsRuntimeSnapshotWithSource(
+                preparedSnapshot,
+                runtimeSourceConfig,
+              )
+          )(await loadSecretsRuntime())
+        : await loadActivateRuntimeSecretsSnapshot()
       : undefined;
     return await runWithSecretsActivationLock(async () => {
       if (
@@ -418,6 +534,19 @@ export function createRuntimeSecretsActivator(params: {
     });
   };
 
+  runtimeSecretsRecoveryPublishers.set(activateRuntimeSecrets, (snapshot, options) => {
+    const expectedGeneration = deferredRecoveryGenerations.get(snapshot);
+    deferredRecoveryGenerations.delete(snapshot);
+    const sourceOnlyContractRecovered =
+      options?.sourceOnly !== true ||
+      (activeDegradationSupportsSourceOnlyRecovery &&
+        activeDegradationConfig !== null &&
+        !hasSameSecretReloadContract(activeDegradationConfig, snapshot.sourceConfig));
+    if (expectedGeneration !== undefined && sourceOnlyContractRecovered) {
+      publishRecovery(snapshot.config, expectedGeneration);
+    }
+  });
+
   return activateRuntimeSecrets;
 }
 
diff --git a/src/secrets/resolve-errors.ts b/src/secrets/resolve-errors.ts
index 9b11931a7e0..46abc5a6dc4 100644
--- a/src/secrets/resolve-errors.ts
+++ b/src/secrets/resolve-errors.ts
@@ -10,6 +10,12 @@ type SecretRefResolutionCode =
 
 type SecretProviderResolutionCode = "SECRET_PROVIDER_INVALID" | "SECRET_PROVIDER_UNAVAILABLE";
 
+export type SecretResolutionFailureReason =
+  | "secret provider failed"
+  | "secret provider policy denied resolution"
+  | "secret provider response violated its contract"
+  | "secret reference was not found";
+
 /** Error for failures that affect an entire configured secret provider. */
 class SecretProviderResolutionError extends Error {
   readonly scope = "provider" as const;
@@ -73,7 +79,9 @@ export function isSecretResolutionError(
 }
 
 /** Redacted reason suitable for warnings and status output. */
-export function describeSecretResolutionError(value: unknown): string | undefined {
+export function describeSecretResolutionError(
+  value: unknown,
+): SecretResolutionFailureReason | undefined {
   if (value instanceof SecretProviderResolutionError) {
     return value.code === "SECRET_PROVIDER_UNAVAILABLE" ? "secret provider failed" : undefined;
   }
diff --git a/src/secrets/runtime-assignment-provenance.ts b/src/secrets/runtime-assignment-provenance.ts
new file mode 100644
index 00000000000..574494f6f5f
--- /dev/null
+++ b/src/secrets/runtime-assignment-provenance.ts
@@ -0,0 +1,17 @@
+/** Internal provenance for assignments collected outside openclaw.json. */
+import type { SecretAssignment } from "./runtime-shared.js";
+
+type SecretAssignmentSource = "auth-store" | "config";
+
+const assignmentSources = new WeakMap<SecretAssignment, SecretAssignmentSource>();
+
+export function setSecretAssignmentSource(
+  assignment: SecretAssignment,
+  source: SecretAssignmentSource,
+): void {
+  assignmentSources.set(assignment, source);
+}
+
+export function getSecretAssignmentSource(assignment: SecretAssignment): SecretAssignmentSource {
+  return assignmentSources.get(assignment) ?? "config";
+}
diff --git a/src/secrets/runtime-auth-collectors.ts b/src/secrets/runtime-auth-collectors.ts
index 5b25ae76d5f..13ae10af460 100644
--- a/src/secrets/runtime-auth-collectors.ts
+++ b/src/secrets/runtime-auth-collectors.ts
@@ -4,6 +4,7 @@ import { assertNoOAuthSecretRefPolicyViolations } from "../agents/auth-profiles/
 import type { AuthProfileCredential, AuthProfileStore } from "../agents/auth-profiles/types.js";
 import type { ProviderAuthAliasLookupParams } from "../agents/provider-auth-aliases.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";
+import { setSecretAssignmentSource } from "./runtime-assignment-provenance.js";
 import { resolveAuthProfileSecretOwnerId } from "./runtime-auth-profile-owner.js";
 import {
   collectRuntimeSecretInputAssignment,
@@ -25,6 +26,16 @@ type TokenCredentialLike = AuthProfileCredential & {
   tokenRef?: unknown;
 };
 
+function collectAuthStoreSecretInputAssignment(
+  params: Parameters<typeof collectRuntimeSecretInputAssignment>[0],
+): void {
+  const previousCount = params.context.assignments.length;
+  collectRuntimeSecretInputAssignment(params);
+  for (const assignment of params.context.assignments.slice(previousCount)) {
+    setSecretAssignmentSource(assignment, "auth-store");
+  }
+}
+
 function collectApiKeyProfileAssignment(params: {
   profile: ApiKeyCredentialLike;
   profileId: string;
@@ -67,7 +78,7 @@ function collectApiKeyProfileAssignment(params: {
     provider: params.profile.provider,
     profileId: params.profileId,
   });
-  collectRuntimeSecretInputAssignment({
+  collectAuthStoreSecretInputAssignment({
     value: resolvedKeyRef,
     path: `${params.agentDir}.auth-profiles.${params.profileId}.key`,
     expected: "string",
@@ -129,7 +140,7 @@ function collectTokenProfileAssignment(params: {
     provider: params.profile.provider,
     profileId: params.profileId,
   });
-  collectRuntimeSecretInputAssignment({
+  collectAuthStoreSecretInputAssignment({
     value: resolvedTokenRef,
     path: `${params.agentDir}.auth-profiles.${params.profileId}.token`,
     expected: "string",
diff --git a/src/secrets/runtime-auth-refresh-failure.test.ts b/src/secrets/runtime-auth-refresh-failure.test.ts
index a45c27c7154..380338ece33 100644
--- a/src/secrets/runtime-auth-refresh-failure.test.ts
+++ b/src/secrets/runtime-auth-refresh-failure.test.ts
@@ -1,7 +1,9 @@
-/** Tests secrets runtime refresh failure handling for auth-profile stores. */
+/** Tests secrets runtime refresh handling for auth-profile stores. */
+import fs from "node:fs/promises";
 import os from "node:os";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { withTempHome } from "../config/home-env.test-harness.js";
+import { resolveAuthProfileSecretOwnerId } from "./runtime-auth-profile-owner.js";
 import {
   beginSecretsRuntimeIsolationForTest,
   createOpenAIFileRuntimeConfig,
@@ -13,10 +15,12 @@ import {
   OPENAI_FILE_KEY_REF,
   type SecretsRuntimeEnvSnapshot,
 } from "./runtime-auth.integration.test-helpers.js";
+import { listSecretResolutionErrorOwners } from "./runtime-degraded-state.js";
 import {
   activateSecretsRuntimeSnapshot,
   getActiveSecretsRuntimeSnapshot,
   prepareSecretsRuntimeSnapshot,
+  refreshActiveProviderAuthRuntimeSnapshot,
 } from "./runtime.js";
 
 vi.unmock("../version.js");
@@ -93,4 +97,76 @@ describe("secrets runtime snapshot auth refresh failure", () => {
       );
     });
   });
+
+  it("classifies a changed auth-profile ref as stale after a successful refresh", async () => {
+    if (os.platform() === "win32") {
+      return;
+    }
+    await withTempHome("openclaw-secrets-runtime-refresh-owner-", async (home) => {
+      const { secretFile, agentDir } = await createOpenAIFileRuntimeFixture(home);
+      const firstRef = { source: "file" as const, provider: "default", id: "/accounts/first" };
+      const secondRef = { source: "file" as const, provider: "default", id: "/accounts/second" };
+      let activeRef = firstRef;
+      const loadAuthStore = () =>
+        loadAuthStoreWithProfiles({
+          "openai:default": {
+            type: "api_key",
+            provider: "openai",
+            keyRef: activeRef,
+          },
+        });
+      const writeSecrets = async (includeSecond: boolean) => {
+        await fs.writeFile(
+          secretFile,
+          `${JSON.stringify({
+            providers: { openai: { apiKey: "test-api-key" } },
+            accounts: {
+              first: "first-fixture",
+              ...(includeSecond ? { second: "second-fixture" } : {}),
+            },
+          })}\n`,
+          { encoding: "utf8", mode: 0o600 },
+        );
+      };
+
+      await writeSecrets(true);
+      const prepared = await prepareSecretsRuntimeSnapshot({
+        config: createOpenAIFileRuntimeConfig(secretFile),
+        agentDirs: [agentDir],
+        loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+        loadAuthStore,
+      });
+      prepared.secretOwners = [
+        ...(prepared.secretOwners ?? []),
+        {
+          ownerKind: "account",
+          ownerId: "discord:ops",
+          refKeys: ["env:default:DISCORD_BOT_TOKEN"],
+        },
+      ];
+      activateSecretsRuntimeSnapshot(prepared);
+
+      activeRef = secondRef;
+      await expect(refreshActiveProviderAuthRuntimeSnapshot()).resolves.toBe(true);
+      expect(expectActiveSecretsRuntimeSnapshot().secretOwners).toContainEqual({
+        ownerKind: "account",
+        ownerId: "discord:ops",
+        refKeys: ["env:default:DISCORD_BOT_TOKEN"],
+      });
+      await writeSecrets(false);
+
+      const error = await refreshActiveProviderAuthRuntimeSnapshot().catch(
+        (cause: unknown) => cause,
+      );
+      expect(listSecretResolutionErrorOwners(error)).toContainEqual(
+        expect.objectContaining({
+          ownerKind: "account",
+          ownerId: resolveAuthProfileSecretOwnerId({ agentDir, profileId: "openai:default" }),
+          degradationState: "stale",
+          failureMatched: true,
+          source: "auth-store",
+        }),
+      );
+    });
+  });
 });
diff --git a/src/secrets/runtime-degradation-attribution.test.ts b/src/secrets/runtime-degradation-attribution.test.ts
new file mode 100644
index 00000000000..8767c62082e
--- /dev/null
+++ b/src/secrets/runtime-degradation-attribution.test.ts
@@ -0,0 +1,737 @@
+/** Tests degraded-owner attribution during runtime SecretRef preparation. */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../test/helpers/temp-dir.ts";
+import type { SecretRef } from "../config/types.secrets.js";
+import { resolveAuthProfileSecretOwnerId } from "./runtime-auth-profile-owner.js";
+import { listSecretResolutionErrorOwners } from "./runtime-degraded-state.js";
+import { activateSecretsRuntimeSnapshotState } from "./runtime-state.js";
+import { asConfig, setupSecretsRuntimeSnapshotTestHooks } from "./runtime.test-support.ts";
+
+const EMPTY_LOADABLE_PLUGIN_ORIGINS = new Map();
+const { prepareSecretsRuntimeSnapshot } = setupSecretsRuntimeSnapshotTestHooks();
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+
+const TTS_REF = {
+  source: "env",
+  provider: "default",
+  id: "ELEVENLABS_API_KEY",
+} as const;
+
+describe("secrets runtime degraded-owner attribution", () => {
+  it("fails closed for missing TTS SecretRefs outside cold-start isolation", async () => {
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({
+        models: {
+          providers: {
+            example: {
+              apiKey: { source: "env", provider: "default", id: "CURRENT_PROVIDER_REF" },
+              baseUrl: "https://example.invalid/v1",
+              models: [],
+            },
+          },
+        },
+        messages: {
+          tts: {
+            providers: {
+              elevenlabs: { apiKey: TTS_REF },
+            },
+          },
+        },
+      }),
+      env: { CURRENT_PROVIDER_REF: "resolved" },
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).then(
+      () => undefined,
+      (failure: unknown) => failure,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(String(error)).toContain(
+      'Environment variable "ELEVENLABS_API_KEY" is missing or empty.',
+    );
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({
+        ownerKind: "capability",
+        ownerId: "tts",
+        paths: ["messages.tts.providers.elevenlabs.apiKey"],
+        reason: "secret reference was not found",
+        degradationState: "cold",
+        failureMatched: true,
+      }),
+    ]);
+  });
+
+  it.each([
+    ["CURRENT_REF", "stale"],
+    ["CHANGED_REF", "cold"],
+  ] as const)("classifies unresolved reload ref %s", async (candidateId, expectedState) => {
+    const config = (ref: SecretRef) =>
+      asConfig({ messages: { tts: { providers: { elevenlabs: { apiKey: ref } } } } });
+    const ref = (id: string): SecretRef => ({ source: "env", provider: "default", id });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config: config(ref("CURRENT_REF")),
+      env: { CURRENT_REF: "resolved" },
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: config(ref(candidateId)),
+      env: {},
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({
+        ownerKind: "capability",
+        ownerId: "tts",
+        degradationState: expectedState,
+      }),
+    ]);
+  });
+
+  it.each([
+    ["explicit", "WEB_TOOL_REF", "stale"],
+    ["explicit", "CHANGED_WEB_TOOL_REF", "cold"],
+    ["auto", "WEB_TOOL_REF", "stale"],
+  ] as const)("classifies %s web tool ref %s", async (mode, candidateId, expectedState) => {
+    const config = (id: string) =>
+      asConfig({
+        tools: {
+          web: { search: mode === "explicit" ? { provider: "gemini" } : { enabled: true } },
+        },
+        plugins: {
+          entries: {
+            ...(mode === "auto"
+              ? {
+                  brave: {
+                    config: {
+                      webSearch: {
+                        apiKey: { source: "env", provider: "default", id: "EARLIER_REF" },
+                      },
+                    },
+                  },
+                }
+              : {}),
+            google: {
+              config: {
+                webSearch: { apiKey: { source: "env", provider: "default", id } },
+              },
+            },
+          },
+        },
+      });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config: config("WEB_TOOL_REF"),
+      env: { WEB_TOOL_REF: "resolved" },
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: config(candidateId),
+      env: {},
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    const owners = listSecretResolutionErrorOwners(error);
+    expect(owners).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "web-search:gemini",
+          degradationState: expectedState,
+          failureMatched: true,
+        }),
+      ]),
+    );
+    if (mode === "auto") {
+      expect(owners).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            ownerId: "web-search:brave",
+            degradationState: "cold",
+          }),
+        ]),
+      );
+    }
+  });
+
+  it("attributes provider failures by source and provider before matching ref ids", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-secret-provider-owner-match-");
+    const healthyPath = path.join(root, "healthy.json");
+    await fs.writeFile(healthyPath, JSON.stringify({ shared: "healthy" }), "utf8");
+    await fs.chmod(healthyPath, 0o600);
+    const sharedId = "/shared";
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({
+        secrets: {
+          providers: {
+            missing: {
+              source: "file",
+              path: path.join(root, "missing.json"),
+              mode: "json",
+            },
+            healthy: { source: "file", path: healthyPath, mode: "json" },
+          },
+        },
+        models: {
+          providers: {
+            example: {
+              apiKey: { source: "file", provider: "missing", id: sharedId },
+              baseUrl: "https://example.invalid/v1",
+              models: [],
+            },
+          },
+        },
+        messages: {
+          tts: {
+            providers: {
+              elevenlabs: {
+                apiKey: { source: "file", provider: "healthy", id: sharedId },
+              },
+            },
+          },
+        },
+      }),
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({ ownerKind: "provider", ownerId: "example" }),
+    ]);
+  });
+
+  it("includes active co-owners using another ref from a failed provider", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-secret-provider-active-co-owner-");
+    const provider = "missing";
+    const apiKeyRef = { source: "file" as const, provider, id: "/candidate" };
+    const activeRef = { source: "file" as const, provider, id: "/active" };
+    const config = asConfig({
+      secrets: {
+        providers: {
+          [provider]: {
+            source: "file",
+            path: path.join(root, "missing.json"),
+            mode: "json",
+          },
+        },
+      },
+      models: {
+        providers: {
+          example: {
+            apiKey: apiKeyRef,
+            baseUrl: "https://example.invalid/v1",
+            models: [],
+          },
+        },
+      },
+    });
+    const agentDir = path.join(root, "agent");
+    const profileId = "openai:provider-failure";
+    const accountOwnerId = resolveAuthProfileSecretOwnerId({
+      agentDir,
+      profileId,
+    });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({}),
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    active.sourceConfig = config;
+    active.config = config;
+    active.authStores = [
+      {
+        agentDir,
+        store: {
+          version: 1,
+          profiles: {
+            [profileId]: {
+              type: "api_key",
+              provider: "openai",
+              key: "dummy",
+              keyRef: activeRef,
+            },
+          },
+        },
+      },
+    ];
+    active.secretOwners = [
+      {
+        ownerKind: "account",
+        ownerId: accountOwnerId,
+        refKeys: ["file:missing:/active"],
+      },
+    ];
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config,
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ ownerKind: "provider", ownerId: "example" }),
+        expect.objectContaining({
+          ownerKind: "account",
+          ownerId: accountOwnerId,
+          degradationState: "stale",
+          source: "auth-store",
+          failureMatched: true,
+        }),
+      ]),
+    );
+  });
+
+  it("includes active web-tool co-owners when strict resolution fails first", async () => {
+    const sharedRef = { source: "env" as const, provider: "default", id: "SHARED_API_KEY" };
+    const authAgentDir = "/tmp/shared-secret-co-owner";
+    const authProfileId = "openai:shared";
+    const authOwnerId = resolveAuthProfileSecretOwnerId({
+      agentDir: authAgentDir,
+      profileId: authProfileId,
+    });
+    const config = asConfig({
+      models: {
+        providers: {
+          example: {
+            apiKey: sharedRef,
+            baseUrl: "https://example.invalid/v1",
+            models: [],
+          },
+        },
+      },
+      tools: { web: { search: { provider: "gemini" } } },
+      plugins: {
+        entries: {
+          google: { config: { webSearch: { apiKey: sharedRef } } },
+        },
+      },
+    });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config,
+      env: { SHARED_API_KEY: "dummy" },
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    active.authStores = [
+      {
+        agentDir: authAgentDir,
+        store: {
+          version: 1,
+          profiles: {
+            [authProfileId]: {
+              type: "api_key",
+              provider: "openai",
+              key: "dummy",
+              keyRef: sharedRef,
+            },
+          },
+        },
+      },
+    ];
+    active.secretOwners?.push({
+      ownerKind: "account",
+      ownerId: authOwnerId,
+      refKeys: ["env:default:SHARED_API_KEY"],
+    });
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config,
+      env: {},
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ ownerKind: "provider", ownerId: "example" }),
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "web-search:gemini",
+          degradationState: "stale",
+          failureMatched: true,
+        }),
+        expect.objectContaining({
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          source: "auth-store",
+          failureMatched: true,
+        }),
+      ]),
+    );
+  });
+
+  it("includes active web-tool co-owners when a shared resolved value is invalid", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-invalid-web-co-owner-");
+    const secretsPath = path.join(root, "secrets.json");
+    await fs.writeFile(secretsPath, JSON.stringify({ shared: "dummy" }), "utf8");
+    await fs.chmod(secretsPath, 0o600);
+    const sharedRef = { source: "file" as const, provider: "shared", id: "/shared" };
+    const config = asConfig({
+      secrets: {
+        providers: {
+          shared: { source: "file", path: secretsPath, mode: "json" },
+        },
+      },
+      models: {
+        providers: {
+          example: {
+            apiKey: sharedRef,
+            baseUrl: "https://example.invalid/v1",
+            models: [],
+          },
+        },
+      },
+      tools: { web: { search: { provider: "gemini" } } },
+      plugins: {
+        entries: {
+          google: { config: { webSearch: { apiKey: sharedRef } } },
+        },
+      },
+    });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config,
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+    await fs.writeFile(secretsPath, JSON.stringify({ shared: { invalid: true } }), "utf8");
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config,
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ ownerKind: "provider", ownerId: "example" }),
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "web-search:gemini",
+          reason: "resolved secret value was invalid",
+          degradationState: "stale",
+          failureMatched: true,
+          source: "config",
+        }),
+      ]),
+    );
+  });
+
+  it("includes later active web-tool co-owners when web resolution fails first", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-invalid-web-sibling-");
+    const secretsPath = path.join(root, "secrets.json");
+    await fs.writeFile(secretsPath, JSON.stringify({ shared: "dummy" }), "utf8");
+    await fs.chmod(secretsPath, 0o600);
+    const sharedRef = { source: "file" as const, provider: "shared", id: "/shared" };
+    const config = asConfig({
+      secrets: {
+        providers: {
+          shared: { source: "file", path: secretsPath, mode: "json" },
+        },
+      },
+      tools: {
+        web: {
+          search: { provider: "gemini" },
+          fetch: { provider: "firecrawl" },
+        },
+      },
+      plugins: {
+        entries: {
+          google: { config: { webSearch: { apiKey: sharedRef } } },
+          firecrawl: { config: { webFetch: { apiKey: sharedRef } } },
+        },
+      },
+    });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config,
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+    await fs.writeFile(secretsPath, JSON.stringify({ shared: { invalid: true } }), "utf8");
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config,
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "web-search:gemini",
+          reason: "resolved secret value was invalid",
+          degradationState: "stale",
+          failureMatched: true,
+        }),
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "web-fetch:firecrawl",
+          reason: "resolved secret value was invalid",
+          degradationState: "stale",
+          failureMatched: true,
+        }),
+      ]),
+    );
+  });
+
+  it("keeps TTS SecretRefs that resolve to non-strings fail-closed", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-tts-secretref-object-");
+    const secretsPath = path.join(root, "secrets.json");
+    await fs.writeFile(
+      secretsPath,
+      JSON.stringify(
+        {
+          providers: {
+            elevenlabs: {
+              apiKey: { value: "not-a-string" },
+            },
+          },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+    await fs.chmod(secretsPath, 0o600);
+    const ref = {
+      source: "file" as const,
+      provider: "ttsfile",
+      id: "/providers/elevenlabs/apiKey",
+    };
+    const config = asConfig({
+      secrets: {
+        providers: {
+          ttsfile: {
+            source: "file",
+            path: secretsPath,
+            mode: "json",
+          },
+        },
+      },
+      messages: {
+        tts: { providers: { elevenlabs: { apiKey: ref } } },
+      },
+    });
+    const authAgentDir = "/tmp/invalid-value-auth-co-owner";
+    const authProfileId = "openai:invalid-value";
+    const authOwnerId = resolveAuthProfileSecretOwnerId({
+      agentDir: authAgentDir,
+      profileId: authProfileId,
+    });
+    const active = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({}),
+      includeAuthStoreRefs: false,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    });
+    active.sourceConfig = config;
+    active.config = config;
+    active.authStores = [
+      {
+        agentDir: authAgentDir,
+        store: {
+          version: 1,
+          profiles: {
+            [authProfileId]: {
+              type: "api_key",
+              provider: "openai",
+              key: "dummy",
+              keyRef: ref,
+            },
+          },
+        },
+      },
+    ];
+    active.secretOwners = [
+      {
+        ownerKind: "account",
+        ownerId: authOwnerId,
+        refKeys: ["file:ttsfile:/providers/elevenlabs/apiKey"],
+      },
+    ];
+    activateSecretsRuntimeSnapshotState({
+      snapshot: active,
+      refreshContext: null,
+      refreshHandler: null,
+    });
+
+    const error = await prepareSecretsRuntimeSnapshot({
+      config,
+      env: {},
+      includeAuthStoreRefs: false,
+      allowUnavailableSecretOwners: true,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(error).toBeInstanceOf(Error);
+    expect(String(error)).toContain(
+      "messages.tts.providers.elevenlabs.apiKey resolved to a non-string or empty value.",
+    );
+    expect(listSecretResolutionErrorOwners(error)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "tts",
+          paths: ["messages.tts.providers.elevenlabs.apiKey"],
+          reason: "resolved secret value was invalid",
+          degradationState: "cold",
+          failureMatched: true,
+        }),
+        expect.objectContaining({
+          ownerKind: "account",
+          ownerId: authOwnerId,
+          reason: "resolved secret value was invalid",
+          source: "auth-store",
+          failureMatched: true,
+        }),
+      ]),
+    );
+  });
+
+  it("reports every cold-start owner sharing an invalid resolved value", async () => {
+    if (process.platform === "win32") {
+      return;
+    }
+    const root = tempDirs.make("openclaw-shared-invalid-secretref-");
+    const secretsPath = path.join(root, "secrets.json");
+    await fs.writeFile(secretsPath, JSON.stringify({ shared: { invalid: true } }), "utf8");
+    await fs.chmod(secretsPath, 0o600);
+    const sharedRef = { source: "file" as const, provider: "shared", id: "/shared" };
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({
+        secrets: {
+          providers: {
+            shared: { source: "file", path: secretsPath, mode: "json" },
+          },
+        },
+        models: {
+          providers: {
+            example: {
+              apiKey: sharedRef,
+              baseUrl: "https://example.invalid/v1",
+              models: [],
+            },
+          },
+        },
+        messages: {
+          tts: { providers: { elevenlabs: { apiKey: sharedRef } } },
+        },
+        skills: {
+          entries: {
+            healthy: {
+              apiKey: { source: "env", provider: "default", id: "HEALTHY_SKILL_KEY" },
+            },
+          },
+        },
+      }),
+      env: { HEALTHY_SKILL_KEY: "healthy-skill-key" },
+      includeAuthStoreRefs: false,
+      allowUnavailableSecretOwners: true,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(error).toBeInstanceOf(Error);
+    const owners = listSecretResolutionErrorOwners(error);
+    expect(owners).toHaveLength(2);
+    expect(owners).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          ownerKind: "provider",
+          ownerId: "example",
+          reason: "resolved secret value was invalid",
+          failureMatched: true,
+        }),
+        expect.objectContaining({
+          ownerKind: "capability",
+          ownerId: "tts",
+          reason: "resolved secret value was invalid",
+          failureMatched: true,
+        }),
+      ]),
+    );
+    expect(owners).not.toContainEqual(expect.objectContaining({ ownerId: "skill:healthy" }));
+  });
+
+  it("still fails required gateway auth SecretRefs when env is missing", async () => {
+    const error = await prepareSecretsRuntimeSnapshot({
+      config: asConfig({
+        gateway: {
+          auth: {
+            mode: "token",
+            token: { source: "env", provider: "default", id: "GATEWAY_TOKEN_REF" },
+          },
+        },
+      }),
+      env: {},
+      includeAuthStoreRefs: false,
+      allowUnavailableSecretOwners: true,
+      loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
+    }).catch((failure: unknown) => failure);
+
+    expect(String(error)).toContain(
+      'Environment variable "GATEWAY_TOKEN_REF" is missing or empty.',
+    );
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({
+        ownerKind: "gateway",
+        ownerId: "ingress-auth",
+        degradationState: "cold",
+        failureMatched: true,
+      }),
+    ]);
+  });
+});
diff --git a/src/secrets/runtime-degraded-state.test.ts b/src/secrets/runtime-degraded-state.test.ts
index 152647ececa..1e53ebc9ac4 100644
--- a/src/secrets/runtime-degraded-state.test.ts
+++ b/src/secrets/runtime-degraded-state.test.ts
@@ -1,9 +1,11 @@
 /** Tests for process-local SecretRef degraded-owner state. */
 import { afterEach, describe, expect, it } from "vitest";
 import {
+  associateSecretResolutionErrorOwners,
   assertSecretOwnerAvailable,
   clearActiveCredentialDegradedOwner,
   listActiveDegradedSecretOwners,
+  listSecretResolutionErrorOwners,
   SecretSurfaceUnavailableError,
   setActiveCredentialDegradedOwner,
   setActiveDegradedSecretOwners,
@@ -37,6 +39,27 @@ describe("runtime degraded SecretRef owners", () => {
     );
     expect(() => assertSecretOwnerAvailable("provider", "anthropic")).not.toThrow();
   });
+  it("records strict resolution owner metadata without exposing mutable state", () => {
+    const error = new Error("private provider details");
+    const owner = {
+      ownerKind: "provider" as const,
+      ownerId: "openai",
+      state: "unavailable" as const,
+      paths: ["models.providers.openai.apiKey"],
+      refKeys: ["env:default:OPENAI_API_KEY"],
+      reason: "secret provider failed",
+      degradationState: "stale" as const,
+      failureMatched: true,
+      source: "config" as const,
+    };
+    associateSecretResolutionErrorOwners(error, [owner]);
+
+    const recorded = listSecretResolutionErrorOwners(error);
+    recorded[0]?.paths.push("mutated");
+    expect(listSecretResolutionErrorOwners(error)[0]?.paths).toEqual([
+      "models.providers.openai.apiKey",
+    ]);
+  });
 
   it("merges runtime-discovered credential owners and clears them independently", () => {
     setActiveDegradedSecretOwners([
diff --git a/src/secrets/runtime-degraded-state.ts b/src/secrets/runtime-degraded-state.ts
index 134504f9476..6ff951c4a1d 100644
--- a/src/secrets/runtime-degraded-state.ts
+++ b/src/secrets/runtime-degraded-state.ts
@@ -1,4 +1,16 @@
 /** Process-local registry for SecretRef owners isolated during cold startup. */
+import {
+  describeSecretResolutionError,
+  isSecretResolutionError,
+  type SecretResolutionFailureReason,
+} from "./resolve-errors.js";
+
+export type SecretDegradationReason =
+  | SecretResolutionFailureReason
+  | "resolved secret value was invalid"
+  | "secret reference is not allowed for this provider"
+  | "secret reference was not materialized by the active runtime"
+  | "secret resolution failed";
 
 export type SecretOwnerKind =
   | "account"
@@ -19,6 +31,76 @@ export type DegradedSecretOwner = {
   reason: string;
 };
 
+/** SecretRef identities resolved for one owner in an active runtime snapshot. */
+export type SecretOwnerRefState = Pick<DegradedSecretOwner, "ownerKind" | "ownerId" | "refKeys">;
+
+/** One owner from an atomic resolution attempt, including whether it caused the failure. */
+type SecretResolutionErrorOwner = DegradedSecretOwner & {
+  degradationState: "cold" | "stale";
+  failureMatched: boolean;
+  source: "auth-store" | "config";
+};
+
+export const SECRET_DEGRADATION_RETRY_HINT = "openclaw secrets reload" as const;
+
+/** Redacted owner details for one structured degradation warning. */
+export type SecretDegradation = {
+  kind: SecretOwnerKind;
+  id: string;
+  reason: string;
+  state: "cold" | "stale";
+  retryHint: typeof SECRET_DEGRADATION_RETRY_HINT;
+};
+
+/** Maps a typed resolution failure to redacted owner warnings when attribution is safe. */
+export function classifySecretResolutionErrorDegradations(error: unknown): SecretDegradation[] {
+  const degradations = listSecretResolutionErrorOwners(error).flatMap((owner) =>
+    owner.failureMatched
+      ? [
+          {
+            kind: owner.ownerKind,
+            id: owner.ownerId,
+            reason: owner.reason,
+            state: owner.degradationState,
+            retryHint: SECRET_DEGRADATION_RETRY_HINT,
+          },
+        ]
+      : [],
+  );
+  if (degradations.length > 0 || !isSecretResolutionError(error)) {
+    return degradations;
+  }
+  const reason = describeSecretResolutionError(error);
+  return reason
+    ? [
+        {
+          kind: "unknown",
+          id: "unmapped",
+          reason,
+          state: "cold",
+          retryHint: SECRET_DEGRADATION_RETRY_HINT,
+        },
+      ]
+    : [];
+}
+
+/** Preserves known failure classes while dropping any embedded SecretRef identity. */
+export function redactSecretDegradationReason(reason: string): SecretDegradationReason {
+  switch (reason) {
+    case "secret provider failed":
+    case "secret provider policy denied resolution":
+    case "secret provider response violated its contract":
+    case "secret reference is not allowed for this provider":
+    case "secret reference was not found":
+    case "secret reference was not materialized by the active runtime":
+    case "resolved secret value was invalid":
+    case "secret resolution failed":
+      return reason;
+    default:
+      return "secret resolution failed";
+  }
+}
+
 const SECRET_SURFACE_UNAVAILABLE_ERROR_CODE = "SECRET_SURFACE_UNAVAILABLE";
 
 /** Runtime error returned when a request targets an isolated SecretRef owner. */
@@ -40,6 +122,7 @@ export class SecretSurfaceUnavailableError extends Error {
 }
 
 let activeDegradedOwners: DegradedSecretOwner[] = [];
+const resolutionErrorOwners = new WeakMap<object, SecretResolutionErrorOwner[]>();
 const activeCredentialDegradedOwners = new Map<string, DegradedSecretOwner>();
 
 function ownerKey(ownerKind: DegradedSecretOwner["ownerKind"], ownerId: string): string {
@@ -54,6 +137,15 @@ function cloneOwner(owner: DegradedSecretOwner): DegradedSecretOwner {
   };
 }
 
+function cloneResolutionErrorOwner(owner: SecretResolutionErrorOwner): SecretResolutionErrorOwner {
+  return {
+    ...cloneOwner(owner),
+    degradationState: owner.degradationState,
+    failureMatched: owner.failureMatched,
+    source: owner.source,
+  };
+}
+
 /** Publishes the degraded-owner snapshot at the same edge as runtime config activation. */
 export function setActiveDegradedSecretOwners(owners: readonly DegradedSecretOwner[]): void {
   activeDegradedOwners = owners.map(cloneOwner);
@@ -81,6 +173,25 @@ export function listActiveDegradedSecretOwners(): DegradedSecretOwner[] {
   ];
 }
 
+/** Associates a strict activation failure with the owners it prevented from refreshing. */
+export function associateSecretResolutionErrorOwners(
+  error: unknown,
+  owners: readonly SecretResolutionErrorOwner[],
+): void {
+  if ((typeof error !== "object" && typeof error !== "function") || error === null) {
+    return;
+  }
+  resolutionErrorOwners.set(error, owners.map(cloneResolutionErrorOwner));
+}
+
+/** Returns owner metadata recorded for a strict activation failure. */
+export function listSecretResolutionErrorOwners(error: unknown): SecretResolutionErrorOwner[] {
+  if ((typeof error !== "object" && typeof error !== "function") || error === null) {
+    return [];
+  }
+  return (resolutionErrorOwners.get(error) ?? []).map(cloneResolutionErrorOwner);
+}
+
 /** Returns one active degraded owner, if present. */
 export function findActiveDegradedSecretOwner(
   ownerKind: DegradedSecretOwner["ownerKind"],
diff --git a/src/secrets/runtime-fast-path.ts b/src/secrets/runtime-fast-path.ts
index eb354d8fb2b..c0ee96b4e05 100644
--- a/src/secrets/runtime-fast-path.ts
+++ b/src/secrets/runtime-fast-path.ts
@@ -276,6 +276,7 @@ export function prepareSecretsRuntimeFastPathSnapshot(params: {
     authStoreCredentialsRevision,
     warnings: [],
     degradedOwners: [],
+    secretOwners: [],
     webTools: createEmptyRuntimeWebToolsMetadata(),
   };
   return {
diff --git a/src/secrets/runtime-owner-assignments.ts b/src/secrets/runtime-owner-assignments.ts
index d034772cc4c..ee9e658a2d3 100644
--- a/src/secrets/runtime-owner-assignments.ts
+++ b/src/secrets/runtime-owner-assignments.ts
@@ -1,4 +1,7 @@
 /** Resolves SecretRef assignments atomically by owning runtime surface. */
+import { isDeepStrictEqual } from "node:util";
+import type { OpenClawConfig } from "../config/types.openclaw.js";
+import type { SecretRef } from "../config/types.secrets.js";
 import { toErrorObject } from "../infra/errors.js";
 import { registerSecretValueForRedaction } from "../logging/secret-redaction-registry.js";
 import { secretRefKey } from "./ref-contract.js";
@@ -8,16 +11,58 @@ import {
   isSecretResolutionError,
 } from "./resolve-errors.js";
 import { resolveSecretRefValues, resolveSecretRefValuesSettledByProvider } from "./resolve.js";
-import type { DegradedSecretOwner } from "./runtime-degraded-state.js";
+import { getSecretAssignmentSource } from "./runtime-assignment-provenance.js";
+import { resolveAuthProfileSecretOwnerId } from "./runtime-auth-profile-owner.js";
+import type {
+  DegradedSecretOwner,
+  SecretDegradationReason,
+  SecretOwnerRefState,
+} from "./runtime-degraded-state.js";
+import { associateSecretResolutionErrorOwners } from "./runtime-degraded-state.js";
 import {
   applyResolvedAssignments,
+  getSecretAssignmentValidationFailures,
   pushWarning,
   type ResolverContext,
   type SecretAssignment,
 } from "./runtime-shared.js";
+import {
+  getActiveSecretsRuntimeSnapshot,
+  hasSameSecretProviderDefinition,
+} from "./runtime-state.js";
 
 type SecretResolutionOptions = Parameters<typeof resolveSecretRefValues>[1];
 
+/** Classifies whether an unresolved owner has an unchanged active SecretRef snapshot. */
+export function classifySecretOwnerDegradationState(params: {
+  ownerKind: DegradedSecretOwner["ownerKind"];
+  ownerId: string;
+  refs: SecretRef[];
+  config: OpenClawConfig;
+}): "cold" | "stale" {
+  const active = getActiveSecretsRuntimeSnapshot();
+  if (
+    !active ||
+    active.degradedOwners?.some(
+      (entry) => entry.ownerKind === params.ownerKind && entry.ownerId === params.ownerId,
+    )
+  ) {
+    return "cold";
+  }
+  const activeOwner = active.secretOwners?.find(
+    (entry) => entry.ownerKind === params.ownerKind && entry.ownerId === params.ownerId,
+  );
+  const refKeys = params.refs.map(secretRefKey).toSorted();
+  const providerDefinitionsMatch = params.refs.every((ref) =>
+    hasSameSecretProviderDefinition(ref, [active.sourceConfig, params.config]),
+  );
+  return activeOwner &&
+    isDeepStrictEqual(activeOwner.refKeys.toSorted(), refKeys) &&
+    providerDefinitionsMatch
+    ? "stale"
+    : "cold";
+}
+
 function registerResolvedValuesForRedaction(resolved: ReadonlyMap<string, unknown>): void {
   for (const value of resolved.values()) {
     if (typeof value === "string") {
@@ -27,7 +72,7 @@ function registerResolvedValuesForRedaction(resolved: ReadonlyMap<string, unknow
 }
 
 function assignmentOwnerKey(assignment: SecretAssignment): string {
-  return `${assignment.ownerKind}\0${assignment.ownerId}`;
+  return `${getSecretAssignmentSource(assignment)}\0${assignment.ownerKind}\0${assignment.ownerId}`;
 }
 
 function groupAssignmentsByOwner(assignments: SecretAssignment[]): SecretAssignment[][] {
@@ -53,7 +98,26 @@ function groupAssignmentsByOwner(assignments: SecretAssignment[]): SecretAssignm
   return [...groups.values()];
 }
 
-function createDegradedOwner(assignments: SecretAssignment[], reason: string): DegradedSecretOwner {
+/** Captures every typed owner/ref relationship for later reload classification. */
+export function listSecretAssignmentOwners(assignments: SecretAssignment[]): SecretOwnerRefState[] {
+  return groupAssignmentsByOwner(assignments).flatMap((ownerAssignments) => {
+    const owner = ownerAssignments[0];
+    return !owner || owner.ownerKind === "unknown"
+      ? []
+      : [
+          {
+            ownerKind: owner.ownerKind,
+            ownerId: owner.ownerId,
+            refKeys: ownerAssignments.map((assignment) => secretRefKey(assignment.ref)).toSorted(),
+          },
+        ];
+  });
+}
+
+function createDegradedOwner(
+  assignments: SecretAssignment[],
+  reason: SecretDegradationReason,
+): DegradedSecretOwner {
   const owner = assignments[0]!;
   if (owner.ownerKind === "unknown") {
     throw new Error(`Secret assignment ${owner.path} has no runtime owner.`);
@@ -68,6 +132,140 @@ function createDegradedOwner(assignments: SecretAssignment[], reason: string): D
   };
 }
 
+function associateAssignmentFailureOwners(params: {
+  assignments: SecretAssignment[];
+  error: unknown;
+  config: OpenClawConfig;
+}): void {
+  const validationFailures = getSecretAssignmentValidationFailures(params.error);
+  const validationFailureRefKeys = new Set(validationFailures.map((failure) => failure.refKey));
+  const validationFailureOwnerKeys = new Set(
+    validationFailures.flatMap((failure) =>
+      params.assignments
+        .filter(
+          (assignment) =>
+            assignment.ownerKind === failure.ownerKind &&
+            assignment.ownerId === failure.ownerId &&
+            assignment.expected === failure.expected &&
+            secretRefKey(assignment.ref) === failure.refKey,
+        )
+        .map(assignmentOwnerKey),
+    ),
+  );
+  const reason =
+    validationFailures.length > 0
+      ? "resolved secret value was invalid"
+      : describeSecretResolutionError(params.error);
+  if (!reason) {
+    return;
+  }
+  const owners = groupAssignmentsByOwner(params.assignments).flatMap((assignments) => {
+    if (assignments[0]?.ownerKind === "unknown") {
+      return [];
+    }
+    const failureMatched = assignments.some((assignment) =>
+      validationFailures.length > 0
+        ? validationFailureOwnerKeys.has(assignmentOwnerKey(assignment))
+        : assignmentMatchesResolutionFailure(assignment, params.error),
+    );
+    if (!failureMatched) {
+      return [];
+    }
+    const degradedOwner = createDegradedOwner(assignments, reason);
+    return [
+      {
+        ...degradedOwner,
+        degradationState: classifySecretOwnerDegradationState({
+          ownerKind: degradedOwner.ownerKind,
+          ownerId: degradedOwner.ownerId,
+          refs: assignments.map((assignment) => assignment.ref),
+          config: params.config,
+        }),
+        failureMatched,
+        source: getSecretAssignmentSource(assignments[0]!),
+      },
+    ];
+  });
+  const failureRefs = new Map(
+    validationFailures.length > 0
+      ? params.assignments
+          .filter((assignment) => validationFailureRefKeys.has(secretRefKey(assignment.ref)))
+          .map((assignment) => [secretRefKey(assignment.ref), assignment.ref] as const)
+      : params.assignments
+          .filter((assignment) => assignmentMatchesResolutionFailure(assignment, params.error))
+          .map((assignment) => [secretRefKey(assignment.ref), assignment.ref] as const),
+  );
+  const providerFailure =
+    validationFailures.length === 0 && isProviderScopedSecretResolutionError(params.error)
+      ? params.error
+      : null;
+  const providerRefPrefix = providerFailure
+    ? `${providerFailure.source}:${providerFailure.provider}:`
+    : null;
+  const ownerKeys = new Set(
+    owners.map((owner) => `${owner.source}\0${owner.ownerKind}\0${owner.ownerId}`),
+  );
+  const collectedOwnerKeys = new Set(params.assignments.map(assignmentOwnerKey));
+  const activeSnapshot = getActiveSecretsRuntimeSnapshot();
+  const activeAuthOwnerIds = new Set(
+    (activeSnapshot?.authStores ?? []).flatMap(({ agentDir, store }) =>
+      Object.keys(store.profiles).map((profileId) =>
+        resolveAuthProfileSecretOwnerId({ agentDir, profileId }),
+      ),
+    ),
+  );
+  const activeCoOwners = (activeSnapshot?.secretOwners ?? []).flatMap((owner) => {
+    const source =
+      owner.ownerKind === "account" && activeAuthOwnerIds.has(owner.ownerId)
+        ? ("auth-store" as const)
+        : ("config" as const);
+    const ownerKey = `${source}\0${owner.ownerKind}\0${owner.ownerId}`;
+    // Current assignments are authoritative. Retain active co-owners only for runtime surfaces
+    // that strict assignment validation prevented this preparation from reaching.
+    if (ownerKeys.has(ownerKey) || collectedOwnerKeys.has(ownerKey)) {
+      return [];
+    }
+    const refs = owner.refKeys.flatMap((refKey) => {
+      const ref = failureRefs.get(refKey);
+      if (ref) {
+        return [ref];
+      }
+      if (!providerFailure || !providerRefPrefix || !refKey.startsWith(providerRefPrefix)) {
+        return [];
+      }
+      return [
+        {
+          source: providerFailure.source,
+          provider: providerFailure.provider,
+          id: refKey.slice(providerRefPrefix.length),
+        },
+      ];
+    });
+    if (refs.length === 0) {
+      return [];
+    }
+    return [
+      {
+        ownerKind: owner.ownerKind,
+        ownerId: owner.ownerId,
+        state: "unavailable" as const,
+        paths: [],
+        refKeys: [...owner.refKeys],
+        reason,
+        degradationState: classifySecretOwnerDegradationState({
+          ownerKind: owner.ownerKind,
+          ownerId: owner.ownerId,
+          refs,
+          config: params.config,
+        }),
+        failureMatched: true,
+        source,
+      },
+    ];
+  });
+  associateSecretResolutionErrorOwners(params.error, [...owners, ...activeCoOwners]);
+}
+
 /** Emits the canonical warning for one isolated runtime secret owner. */
 export function warnDegradedSecretOwner(
   context: ResolverContext,
@@ -86,25 +284,39 @@ async function resolveStrictAssignments(params: {
   assignments: SecretAssignment[];
   options: SecretResolutionOptions;
 }): Promise<void> {
-  const resolved = await resolveSecretRefValues(
-    params.assignments.map((assignment) => assignment.ref),
-    params.options,
-  );
-  registerResolvedValuesForRedaction(resolved);
-  applyResolvedAssignments({ assignments: params.assignments, resolved });
+  try {
+    const resolved = await resolveSecretRefValues(
+      params.assignments.map((assignment) => assignment.ref),
+      params.options,
+    );
+    registerResolvedValuesForRedaction(resolved);
+    applyResolvedAssignments({ assignments: params.assignments, resolved });
+  } catch (error) {
+    associateAssignmentFailureOwners({
+      assignments: params.assignments,
+      error,
+      config: params.options.config,
+    });
+    throw error;
+  }
 }
 
 function assignmentMatchesResolutionFailure(assignment: SecretAssignment, error: unknown): boolean {
   if (!isSecretResolutionError(error)) {
     return false;
   }
+  // Provider failures affect every ref under that exact source/provider pair. Ref failures
+  // additionally require the id, so equal ids under sibling providers never share attribution.
   if (assignment.ref.source !== error.source || assignment.ref.provider !== error.provider) {
     return false;
   }
   return isProviderScopedSecretResolutionError(error) || assignment.ref.id.trim() === error.refId;
 }
 
-function assertOwnerCanBeIsolated(assignments: SecretAssignment[], error: unknown): string {
+function assertOwnerCanBeIsolated(
+  assignments: SecretAssignment[],
+  error: unknown,
+): SecretDegradationReason {
   const owner = assignments[0]!;
   const reason = describeSecretResolutionError(error);
   if (
@@ -138,8 +350,13 @@ export async function resolveAndApplySecretAssignments(params: {
     );
     registerResolvedValuesForRedaction(resolution.resolved);
 
-    const failedOwners = new Map<SecretAssignment[], string>();
+    const failedOwners = new Map<SecretAssignment[], SecretDegradationReason>();
     for (const failure of resolution.failures) {
+      associateAssignmentFailureOwners({
+        assignments: pendingOwners.flat(),
+        error: failure.error,
+        config: params.options.config,
+      });
       const matchingOwners = pendingOwners.filter((assignments) =>
         assignments.some((assignment) =>
           assignmentMatchesResolutionFailure(assignment, failure.error),
@@ -155,6 +372,28 @@ export async function resolveAndApplySecretAssignments(params: {
       }
     }
 
+    const readyAssignments = pendingOwners
+      .filter(
+        (assignments) =>
+          !failedOwners.has(assignments) &&
+          assignments.every((assignment) => resolution.resolved.has(secretRefKey(assignment.ref))),
+      )
+      .flat();
+    if (readyAssignments.length > 0) {
+      // Validate the whole ready set so owners sharing one invalid ref are all reported.
+      // Failure association filters by validated owner keys; unrelated owners stay healthy.
+      try {
+        applyResolvedAssignments({ assignments: readyAssignments, resolved: resolution.resolved });
+      } catch (error) {
+        associateAssignmentFailureOwners({
+          assignments: readyAssignments,
+          error,
+          config: params.options.config,
+        });
+        throw error;
+      }
+    }
+
     const nextPendingOwners: SecretAssignment[][] = [];
     for (const assignments of pendingOwners) {
       const failureReason = failedOwners.get(assignments);
@@ -172,7 +411,6 @@ export async function resolveAndApplySecretAssignments(params: {
       if (
         assignments.every((assignment) => resolution.resolved.has(secretRefKey(assignment.ref)))
       ) {
-        applyResolvedAssignments({ assignments, resolved: resolution.resolved });
         continue;
       }
       nextPendingOwners.push(assignments);
diff --git a/src/secrets/runtime-shared.ts b/src/secrets/runtime-shared.ts
index 1ebbaf31c1c..44be57b598c 100644
--- a/src/secrets/runtime-shared.ts
+++ b/src/secrets/runtime-shared.ts
@@ -38,6 +38,33 @@ export type SecretAssignment = {
   apply: (value: unknown) => void;
 };
 
+type SecretAssignmentValidationFailure = Pick<
+  SecretAssignment,
+  "ownerKind" | "ownerId" | "expected"
+> & {
+  refKey: string;
+};
+
+class SecretAssignmentValidationError extends Error {
+  readonly failures: SecretAssignmentValidationFailure[];
+
+  constructor(params: { failures: SecretAssignmentValidationFailure[]; error: Error }) {
+    super(params.error.message, { cause: params.error });
+    this.name = "SecretAssignmentValidationError";
+    this.failures = params.failures.map((failure) => ({ ...failure }));
+  }
+}
+
+/** Returns every assignment whose resolved value failed its target shape contract. */
+export function getSecretAssignmentValidationFailures(
+  error: unknown,
+): SecretAssignmentValidationFailure[] {
+  if (!(error instanceof SecretAssignmentValidationError)) {
+    return [];
+  }
+  return error.failures.map((failure) => ({ ...failure }));
+}
+
 export type SecretAssignmentOwner = Pick<
   SecretAssignment,
   "ownerKind" | "ownerId" | "requiredForGateway" | "disposition"
@@ -172,22 +199,38 @@ export function applyResolvedAssignments(params: {
   resolved: Map<string, unknown>;
 }): void {
   const values: unknown[] = [];
+  const failures: SecretAssignmentValidationFailure[] = [];
+  let firstValidationError: Error | undefined;
   for (const assignment of params.assignments) {
     const key = secretRefKey(assignment.ref);
     if (!params.resolved.has(key)) {
       throw new Error(`Secret reference "${key}" resolved to no value.`);
     }
     const value = params.resolved.get(key);
-    assertExpectedResolvedSecretValue({
-      value,
-      expected: assignment.expected,
-      errorMessage:
-        assignment.expected === "string"
-          ? `${assignment.path} resolved to a non-string or empty value.`
-          : `${assignment.path} resolved to an unsupported value type.`,
-    });
+    try {
+      assertExpectedResolvedSecretValue({
+        value,
+        expected: assignment.expected,
+        errorMessage:
+          assignment.expected === "string"
+            ? `${assignment.path} resolved to a non-string or empty value.`
+            : `${assignment.path} resolved to an unsupported value type.`,
+      });
+    } catch (error) {
+      const validationError = error instanceof Error ? error : new Error(String(error));
+      firstValidationError ??= validationError;
+      failures.push({
+        ownerKind: assignment.ownerKind,
+        ownerId: assignment.ownerId,
+        expected: assignment.expected,
+        refKey: key,
+      });
+    }
     values.push(value);
   }
+  if (firstValidationError) {
+    throw new SecretAssignmentValidationError({ error: firstValidationError, failures });
+  }
   for (const [index, assignment] of params.assignments.entries()) {
     assignment.apply(values[index]);
   }
diff --git a/src/secrets/runtime-state.test.ts b/src/secrets/runtime-state.test.ts
index 6c8e5cf24a2..18c19cd59fc 100644
--- a/src/secrets/runtime-state.test.ts
+++ b/src/secrets/runtime-state.test.ts
@@ -16,10 +16,7 @@ import {
   saveAuthProfileStore,
 } from "../agents/auth-profiles/store.js";
 import type { AuthProfileStore } from "../agents/auth-profiles/types.js";
-import {
-  getRuntimeConfigSnapshotMetadata,
-  getRuntimeConfigSourceSnapshot,
-} from "../config/runtime-snapshot.js";
+import { getRuntimeConfigSourceSnapshot } from "../config/runtime-snapshot.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SecretRef } from "../config/types.secrets.js";
 import { closeOpenClawAgentDatabasesForTest } from "../state/openclaw-agent-db.js";
@@ -32,7 +29,6 @@ import {
   getActiveSecretsRuntimeSnapshot,
   getActiveSecretsRuntimeSnapshotRevision,
   restoreSecretsRuntimeSnapshotStateIfCurrent,
-  setSecretsRuntimeSourceSnapshotIfCurrent,
   type PreparedSecretsRuntimeSnapshot,
 } from "./runtime-state.js";
 
@@ -102,10 +98,6 @@ describe("secrets runtime state", () => {
       refreshContext: null,
       refreshHandler: null,
     });
-    const metadata = getRuntimeConfigSnapshotMetadata();
-    if (!metadata) {
-      throw new Error("expected runtime config metadata");
-    }
     const rawSourceConfig = { gateway: { port: 19_030 } } satisfies OpenClawConfig;
     const secretsSourceConfig = {
       ...rawSourceConfig,
@@ -113,11 +105,12 @@ describe("secrets runtime state", () => {
     } satisfies OpenClawConfig;
 
     expect(
-      setSecretsRuntimeSourceSnapshotIfCurrent({
-        expectedSecretsRevision: getActiveSecretsRuntimeSnapshotRevision(),
-        expectedRuntimeConfigRevision: metadata.revision,
+      activateSecretsRuntimeSnapshotStateIfCurrent({
+        snapshot: { ...snapshot, sourceConfig: secretsSourceConfig },
+        expectedRevision: getActiveSecretsRuntimeSnapshotRevision(),
+        refreshContext: null,
+        refreshHandler: null,
         runtimeSourceConfig: rawSourceConfig,
-        secretsSourceConfig,
       }),
     ).toBe(true);
 
diff --git a/src/secrets/runtime-state.ts b/src/secrets/runtime-state.ts
index 766df94c251..e27e75c130a 100644
--- a/src/secrets/runtime-state.ts
+++ b/src/secrets/runtime-state.ts
@@ -18,7 +18,6 @@ import type {
 } from "../agents/auth-profiles/types.js";
 import {
   clearRuntimeConfigSnapshot,
-  setRuntimeConfigSourceSnapshotIfCurrent,
   setRuntimeConfigSnapshot,
   setRuntimeConfigSnapshotRefreshHandler,
   type RuntimeConfigSnapshotRefreshHandler,
@@ -31,6 +30,7 @@ import { isRecord } from "../utils.js";
 import {
   setActiveDegradedSecretOwners,
   type DegradedSecretOwner,
+  type SecretOwnerRefState,
 } from "./runtime-degraded-state.js";
 import type { SecretResolverWarning } from "./runtime-shared.js";
 import {
@@ -47,9 +47,54 @@ export type PreparedSecretsRuntimeSnapshot = {
   authStoreCredentialsRevision: number;
   warnings: SecretResolverWarning[];
   degradedOwners?: DegradedSecretOwner[];
+  secretOwners?: SecretOwnerRefState[];
   webTools: RuntimeWebToolsMetadata;
 };
 
+type LocatedSecretRef = {
+  path: Array<string | number>;
+  ref: SecretRef;
+};
+
+function listLocatedSecretRefs(
+  value: unknown,
+  path: Array<string | number> = [],
+  refs: LocatedSecretRef[] = [],
+): LocatedSecretRef[] {
+  if (isSecretRef(value)) {
+    refs.push({ path, ref: value });
+    return refs;
+  }
+  if (Array.isArray(value)) {
+    for (const [index, entry] of value.entries()) {
+      listLocatedSecretRefs(entry, [...path, index], refs);
+    }
+    return refs;
+  }
+  if (isRecord(value)) {
+    for (const key of Object.keys(value).toSorted()) {
+      listLocatedSecretRefs(value[key], [...path, key], refs);
+    }
+  }
+  return refs;
+}
+
+/** Whether two configs resolve the same SecretRefs through the same provider contracts. */
+export function hasSameSecretReloadContract(left: OpenClawConfig, right: OpenClawConfig): boolean {
+  return isDeepStrictEqual(
+    {
+      refs: listLocatedSecretRefs(left),
+      defaults: left.secrets?.defaults,
+      providers: left.secrets?.providers,
+    },
+    {
+      refs: listLocatedSecretRefs(right),
+      defaults: right.secrets?.defaults,
+      providers: right.secrets?.providers,
+    },
+  );
+}
+
 /** Context needed to refresh active secrets runtime snapshots without losing plugin origin data. */
 export type SecretsRuntimeRefreshContext = {
   env: Record<string, string | undefined>;
@@ -141,6 +186,11 @@ function cloneSnapshot(snapshot: PreparedSecretsRuntimeSnapshot): PreparedSecret
       refKeys: [...owner.refKeys],
       reason: owner.reason,
     })),
+    secretOwners: (snapshot.secretOwners ?? []).map((owner) => ({
+      ownerKind: owner.ownerKind,
+      ownerId: owner.ownerId,
+      refKeys: [...owner.refKeys],
+    })),
     webTools: structuredClone(snapshot.webTools),
   };
 }
@@ -281,7 +331,10 @@ function mergeRollbackValue(previous: unknown, candidate: unknown, current: unkn
   return merged;
 }
 
-function hasSameSecretProviderDefinition(ref: SecretRef, configs: OpenClawConfig[]): boolean {
+export function hasSameSecretProviderDefinition(
+  ref: SecretRef,
+  configs: OpenClawConfig[],
+): boolean {
   const definition = configs[0]?.secrets?.providers?.[ref.provider];
   if (
     !configs.every((config) =>
@@ -790,6 +843,7 @@ export function activateSecretsRuntimeSnapshotState(params: {
   snapshot: PreparedSecretsRuntimeSnapshot;
   refreshContext: SecretsRuntimeRefreshContext | null;
   refreshHandler: RuntimeConfigSnapshotRefreshHandler | null;
+  runtimeSourceConfig?: OpenClawConfig;
   mergeLiveAuthBookkeeping?: boolean;
   preserveActivationLineage?: boolean;
 }): void {
@@ -812,7 +866,7 @@ export function activateSecretsRuntimeSnapshotState(params: {
   const nextRefreshContext = params.refreshContext
     ? cloneSecretsRuntimeRefreshContext(params.refreshContext)
     : null;
-  setRuntimeConfigSnapshot(next.config, next.sourceConfig);
+  setRuntimeConfigSnapshot(next.config, params.runtimeSourceConfig ?? next.sourceConfig);
   replaceRuntimeAuthProfileStoreSnapshots(next.authStores);
   next.authStoreCredentialsRevision = getRuntimeAuthProfileStoreCredentialsRevision();
   const previousLineageStartRevision = activeSnapshotLineageStartRevision;
@@ -956,38 +1010,6 @@ export function getActiveSecretsRuntimeSnapshotRevision(): number {
   return activeSnapshotRevision;
 }
 
-/** Advance canonical source ownership without replacing resolved runtime or auth bytes. */
-export function setSecretsRuntimeSourceSnapshotIfCurrent(params: {
-  expectedSecretsRevision: number;
-  expectedRuntimeConfigRevision: number;
-  runtimeSourceConfig: OpenClawConfig;
-  secretsSourceConfig: OpenClawConfig;
-}): boolean {
-  if (activeSnapshotRevision !== params.expectedSecretsRevision) {
-    return false;
-  }
-  const nextRuntimeSourceConfig = structuredClone(params.runtimeSourceConfig);
-  const nextSecretsSourceConfig = structuredClone(params.secretsSourceConfig);
-  const currentAuthStores = structuredClone(listRuntimeAuthProfileStoreSnapshots());
-  const nextAuthMutations = captureAuthStoreMutationLineage(currentAuthStores, currentAuthStores);
-  if (
-    !setRuntimeConfigSourceSnapshotIfCurrent({
-      expectedRevision: params.expectedRuntimeConfigRevision,
-      sourceConfig: nextRuntimeSourceConfig,
-    })
-  ) {
-    return false;
-  }
-  if (activeSnapshot) {
-    activeSnapshot.sourceConfig = nextSecretsSourceConfig;
-    activeSnapshotRevision += 1;
-    activeSnapshotLineageStartRevision = activeSnapshotRevision;
-    activeSnapshotLineageAuthStores = currentAuthStores;
-    activeSnapshotLineageAuthMutations = nextAuthMutations;
-  }
-  return true;
-}
-
 // Hot-path readers only need the config pair for availability decisions.
 // Return the active references and keep full snapshot clone isolation on
 // getActiveSecretsRuntimeSnapshot() for callers that need mutable data.
diff --git a/src/secrets/runtime-web-tools.shared.ts b/src/secrets/runtime-web-tools.shared.ts
index 8ce80c8f94a..6a553ad58f8 100644
--- a/src/secrets/runtime-web-tools.shared.ts
+++ b/src/secrets/runtime-web-tools.shared.ts
@@ -1,9 +1,10 @@
 /** Shared helpers for web-tool secret metadata resolution. */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
-import { resolveSecretInputRef } from "../config/types.secrets.js";
+import { resolveSecretInputRef, type SecretRef } from "../config/types.secrets.js";
 import { createLazyRuntimeNamedExport } from "../shared/lazy-runtime.js";
 import { setPathExistingStrict } from "./path-utils.js";
+import type { SecretDegradationReason } from "./runtime-degraded-state.js";
 import type {
   ResolverContext,
   SecretDefaults,
@@ -28,20 +29,44 @@ export type SecretResolutionResult<TSource extends string> = {
   value?: string;
   source: TSource;
   secretRefConfigured: boolean;
+  secretRef?: SecretRef;
   secretRefKey?: string;
-  unresolvedRefReason?: string;
+  unresolvedRefReason?: SecretDegradationReason;
   fallbackEnvVar?: string;
 };
 
+export type RuntimeWebSecretOwner = {
+  providerId: string;
+  path: string;
+  ref: SecretRef;
+  refKey: string;
+  reason?: SecretDegradationReason;
+};
+
+export type RuntimeWebUnavailableProvider = RuntimeWebSecretOwner & {
+  reason: SecretDegradationReason;
+};
+
 export type RuntimeWebProviderSelectionResult = {
-  unavailableProvider?: {
-    providerId: string;
-    path: string;
-    refKey: string;
-    reason: string;
-  };
+  secretOwners: RuntimeWebSecretOwner[];
+  unavailableProviders: RuntimeWebUnavailableProvider[];
 };
 
+/** Carries typed web-provider ownership through strict reload failures. */
+class RuntimeWebProviderUnavailableError extends Error {
+  readonly unavailableProviders: RuntimeWebUnavailableProvider[];
+
+  constructor(
+    code: RuntimeWebWarningCode,
+    reason: SecretDegradationReason,
+    unavailableProviders: RuntimeWebUnavailableProvider[],
+  ) {
+    super(`[${code}] ${reason}`);
+    this.name = "RuntimeWebProviderUnavailableError";
+    this.unavailableProviders = unavailableProviders;
+  }
+}
+
 /**
  * Metadata fields shared by runtime web search and fetch provider selection.
  */
@@ -80,11 +105,11 @@ type RuntimeWebProviderSelectionParams<
   allowKeylessAutoSelect: boolean;
   /** Defer keyless providers until credential-bearing auto-detect candidates are exhausted. */
   deferKeylessFallback: boolean;
-  /** Keep cold-start preparation alive when an explicit provider ref cannot resolve. */
-  allowUnavailableExplicitProvider?: boolean;
+  /** Keep cold-start preparation alive when no configured provider ref can resolve. */
+  allowUnavailableProviders?: boolean;
+  onUnavailableProviders?: (error: RuntimeWebProviderUnavailableError) => void;
   noFallbackCode: RuntimeWebWarningCode;
   autoDetectSelectedCode: RuntimeWebWarningCode;
-  /** Reads the primary credential location for a provider from source config. */
   readConfiguredCredential: (params: {
     provider: TProvider;
     config: OpenClawConfig;
@@ -95,13 +120,12 @@ type RuntimeWebProviderSelectionParams<
     config: OpenClawConfig;
     toolConfig: TToolConfig;
   }) => { path: string; value: unknown } | undefined;
-  /** Resolves inline/env/SecretRef credentials and reports the winning source. */
   resolveSecretInput: (params: {
+    providerId: string;
     value: unknown;
     path: string;
     envVars: string[];
   }) => Promise<SecretResolutionResult<TSource>>;
-  /** Writes the selected credential into the resolved runtime config snapshot. */
   setResolvedCredential: (params: {
     resolvedConfig: OpenClawConfig;
     provider: TProvider;
@@ -404,20 +428,22 @@ export async function resolveRuntimeWebProviderSelection<
     params.metadata.providerSource = "configured";
   }
 
-  let unavailableProvider: RuntimeWebProviderSelectionResult["unavailableProvider"];
+  const unavailableProviders: RuntimeWebUnavailableProvider[] = [];
+  let selectedProvider: string | undefined;
+  let selectedPath: string | undefined;
+  let selectedResolution: SecretResolutionResult<TSource> | undefined;
   if (params.enabled) {
     const candidates = params.configuredProvider
       ? params.providers.filter((provider) => provider.id === params.configuredProvider)
       : params.providers;
-    const unresolvedWithoutFallback: Array<{
+    type UnresolvedProvider = {
       provider: string;
       path: string;
+      ref?: SecretRef;
       refKey?: string;
-      reason: string;
-    }> = [];
-
-    let selectedProvider: string | undefined;
-    let selectedResolution: SecretResolutionResult<TSource> | undefined;
+      reason: SecretDegradationReason;
+    };
+    const unresolvedWithoutFallback: UnresolvedProvider[] = [];
     let keylessFallbackProvider: TProvider | undefined;
 
     for (const provider of candidates) {
@@ -438,11 +464,14 @@ export async function resolveRuntimeWebProviderSelection<
         config: params.sourceConfig,
         toolConfig: params.toolConfig,
       });
-      const resolution = await params.resolveSecretInput({
-        value,
-        path,
-        envVars: getProviderEnvVars(provider),
-      });
+      const resolveSecretInput = (input: unknown, inputPath: string) =>
+        params.resolveSecretInput({
+          providerId: provider.id,
+          value: input,
+          path: inputPath,
+          envVars: getProviderEnvVars(provider),
+        });
+      const resolution = await resolveSecretInput(value, path);
       let selectedCandidatePath = path;
       let selectedCandidateResolution = resolution;
 
@@ -454,11 +483,7 @@ export async function resolveRuntimeWebProviderSelection<
         });
         if (fallback?.value !== undefined) {
           selectedCandidatePath = fallback.path;
-          selectedCandidateResolution = await params.resolveSecretInput({
-            value: fallback.value,
-            path: fallback.path,
-            envVars: getProviderEnvVars(provider),
-          });
+          selectedCandidateResolution = await resolveSecretInput(fallback.value, fallback.path);
         }
       } else if (resolution.source === "env" && !resolution.secretRefConfigured) {
         const fallback = params.readConfiguredCredentialFallback?.({
@@ -470,11 +495,7 @@ export async function resolveRuntimeWebProviderSelection<
           fallback?.value !== undefined &&
           params.hasConfiguredSecretRef(fallback.value, params.defaults)
         ) {
-          const fallbackResolution = await params.resolveSecretInput({
-            value: fallback.value,
-            path: fallback.path,
-            envVars: getProviderEnvVars(provider),
-          });
+          const fallbackResolution = await resolveSecretInput(fallback.value, fallback.path);
           if (fallbackResolution.source === "secretRef" && fallbackResolution.value) {
             // Preserve transcript/config bytes for env-selected providers while materializing refs.
             setResolvedCredentialPath({
@@ -494,6 +515,7 @@ export async function resolveRuntimeWebProviderSelection<
         unresolvedWithoutFallback.push({
           provider: provider.id,
           path: selectedCandidatePath,
+          ref: selectedCandidateResolution.secretRef,
           refKey: selectedCandidateResolution.secretRefKey,
           reason: selectedCandidateResolution.unresolvedRefReason,
         });
@@ -513,6 +535,7 @@ export async function resolveRuntimeWebProviderSelection<
 
       if (params.configuredProvider) {
         selectedProvider = provider.id;
+        selectedPath = selectedCandidatePath;
         selectedResolution = selectedCandidateResolution;
         if (selectedCandidateResolution.value) {
           setResolvedCredentialPath({
@@ -531,6 +554,7 @@ export async function resolveRuntimeWebProviderSelection<
 
       if (isKeyless) {
         selectedProvider = provider.id;
+        selectedPath = selectedCandidatePath;
         selectedResolution = selectedCandidateResolution;
         if (selectedCandidateResolution.value) {
           setResolvedCredentialPath({
@@ -549,6 +573,7 @@ export async function resolveRuntimeWebProviderSelection<
 
       if (selectedCandidateResolution.value) {
         selectedProvider = provider.id;
+        selectedPath = selectedCandidatePath;
         selectedResolution = selectedCandidateResolution;
         setResolvedCredentialPath({
           resolvedConfig: params.resolvedConfig,
@@ -572,7 +597,10 @@ export async function resolveRuntimeWebProviderSelection<
       };
     }
 
-    const failUnresolvedNoFallback = (unresolved: { path: string; reason: string }) => {
+    const recordUnresolvedNoFallback = (unresolved: {
+      path: string;
+      reason: SecretDegradationReason;
+    }) => {
       const diagnostic: RuntimeWebDiagnostic = {
         code: params.noFallbackCode,
         message: unresolved.reason,
@@ -585,6 +613,34 @@ export async function resolveRuntimeWebProviderSelection<
         path: unresolved.path,
         message: unresolved.reason,
       });
+    };
+    const failUnresolvedNoFallback = (
+      unresolved: UnresolvedProvider,
+      related: UnresolvedProvider[] = [unresolved],
+    ): never => {
+      recordUnresolvedNoFallback(unresolved);
+      const relatedUnavailableProviders = related.flatMap((entry) =>
+        entry.ref && entry.refKey
+          ? [
+              {
+                providerId: entry.provider,
+                path: entry.path,
+                ref: entry.ref,
+                refKey: entry.refKey,
+                reason: entry.reason,
+              },
+            ]
+          : [],
+      );
+      if (relatedUnavailableProviders.length > 0) {
+        const error = new RuntimeWebProviderUnavailableError(
+          params.noFallbackCode,
+          unresolved.reason,
+          relatedUnavailableProviders,
+        );
+        params.onUnavailableProviders?.(error);
+        throw error;
+      }
       throw new Error(`[${params.noFallbackCode}] ${unresolved.reason}`);
     };
 
@@ -592,22 +648,50 @@ export async function resolveRuntimeWebProviderSelection<
       const unresolved = unresolvedWithoutFallback[0];
       if (unresolved) {
         const refKey = unresolved.refKey;
-        if (params.allowUnavailableExplicitProvider && refKey) {
-          unavailableProvider = {
+        const ref = unresolved.ref;
+        if (refKey && ref) {
+          const unavailable = {
             providerId: params.configuredProvider,
             path: unresolved.path,
+            ref,
             refKey,
             reason: unresolved.reason,
           };
+          if (params.allowUnavailableProviders) {
+            unavailableProviders.push(unavailable);
+          } else {
+            failUnresolvedNoFallback(unresolved);
+          }
         } else {
           failUnresolvedNoFallback(unresolved);
         }
       }
     } else {
       if (!selectedProvider && unresolvedWithoutFallback.length > 0) {
-        failUnresolvedNoFallback(
-          expectDefined(unresolvedWithoutFallback[0], "unresolved without fallback entry at 0"),
+        const firstUnresolved = expectDefined(
+          unresolvedWithoutFallback[0],
+          "unresolved without fallback entry at 0",
+        );
+        if (!params.allowUnavailableProviders) {
+          failUnresolvedNoFallback(firstUnresolved, unresolvedWithoutFallback);
+        }
+        const unavailable = unresolvedWithoutFallback.flatMap((entry) =>
+          entry.ref && entry.refKey
+            ? [
+                {
+                  providerId: entry.provider,
+                  path: entry.path,
+                  ref: entry.ref,
+                  refKey: entry.refKey,
+                  reason: entry.reason,
+                },
+              ]
+            : [],
         );
+        if (unavailable.length !== unresolvedWithoutFallback.length) {
+          failUnresolvedNoFallback(firstUnresolved, unresolvedWithoutFallback);
+        }
+        unavailableProviders.push(...unavailable);
       }
 
       if (selectedProvider) {
@@ -628,14 +712,14 @@ export async function resolveRuntimeWebProviderSelection<
       }
     }
 
-    if (selectedProvider && !unavailableProvider) {
+    if (selectedProvider && unavailableProviders.length === 0) {
       params.metadata.selectedProvider = selectedProvider;
       params.metadata.selectedProviderKeySource = selectedResolution?.source;
       if (!params.configuredProvider) {
         params.metadata.providerSource = "auto-detect";
       }
       const provider = params.providers.find((entry) => entry.id === selectedProvider);
-      if (provider && params.mergeRuntimeMetadata && !unavailableProvider) {
+      if (provider && params.mergeRuntimeMetadata) {
         await params.mergeRuntimeMetadata({
           provider,
           metadata: params.metadata,
@@ -667,5 +751,20 @@ export async function resolveRuntimeWebProviderSelection<
     });
   }
 
-  return unavailableProvider ? { unavailableProvider } : {};
+  const selectedSecretOwner =
+    selectedProvider &&
+    selectedPath &&
+    selectedResolution?.secretRef &&
+    selectedResolution.secretRefKey
+      ? {
+          providerId: selectedProvider,
+          path: selectedPath,
+          ref: selectedResolution.secretRef,
+          refKey: selectedResolution.secretRefKey,
+        }
+      : undefined;
+  return {
+    secretOwners: selectedSecretOwner ? [selectedSecretOwner] : unavailableProviders,
+    unavailableProviders,
+  };
 }
diff --git a/src/secrets/runtime-web-tools.test.ts b/src/secrets/runtime-web-tools.test.ts
index 8ad35e5c34b..45622b20ee9 100644
--- a/src/secrets/runtime-web-tools.test.ts
+++ b/src/secrets/runtime-web-tools.test.ts
@@ -5,6 +5,7 @@ import type {
   PluginWebFetchProviderEntry,
   PluginWebSearchProviderEntry,
 } from "../plugins/types.js";
+import { listSecretResolutionErrorOwners } from "./runtime-degraded-state.js";
 
 type ProviderUnderTest = "brave" | "gemini" | "grok" | "kimi" | "perplexity" | "duckduckgo";
 
@@ -899,37 +900,44 @@ describe("runtime web tools resolution", () => {
     );
   });
 
-  it("keeps unresolved auto-detected providers strict during cold-start isolation", async () => {
-    await expect(
-      runRuntimeWebTools({
-        config: asConfig({
-          tools: {
-            web: {
-              search: {
-                enabled: true,
-              },
+  it("isolates unresolved auto-detected providers during cold start", async () => {
+    const { metadata, degradedOwners } = await runRuntimeWebTools({
+      config: asConfig({
+        tools: {
+          web: {
+            search: {
+              enabled: true,
             },
           },
-          plugins: {
-            entries: {
-              google: {
-                enabled: true,
-                config: {
-                  webSearch: {
-                    apiKey: {
-                      source: "env",
-                      provider: "default",
-                      id: "MISSING_GEMINI_API_KEY_REF",
-                    },
+        },
+        plugins: {
+          entries: {
+            google: {
+              enabled: true,
+              config: {
+                webSearch: {
+                  apiKey: {
+                    source: "env",
+                    provider: "default",
+                    id: "MISSING_GEMINI_API_KEY_REF",
                   },
                 },
               },
             },
           },
-        }),
-        allowUnavailableSecretOwners: true,
+        },
       }),
-    ).rejects.toThrow("[WEB_SEARCH_KEY_UNRESOLVED_NO_FALLBACK]");
+      allowUnavailableSecretOwners: true,
+    });
+
+    expect(metadata.search.selectedProvider).toBeUndefined();
+    expect(degradedOwners).toMatchObject([
+      {
+        ownerKind: "capability",
+        ownerId: "web-search:gemini",
+        reason: "secret reference was not found",
+      },
+    ]);
   });
 
   it("auto-detects Gemini from the Google model provider key after env fallbacks", async () => {
@@ -1513,15 +1521,20 @@ describe("runtime web tools resolution", () => {
     expect(firstMockArg(resolvePluginWebFetchProvidersMock).sandboxed).toBe(true);
   });
 
-  it("isolates an explicit web fetch provider instead of using env after its ref fails", async () => {
+  it("isolates an explicit web fetch provider when its ref is unavailable", async () => {
     const { metadata, resolvedConfig, context, degradedOwners } = await runRuntimeWebTools({
       config: asConfig({
+        secrets: {
+          providers: {
+            default: { source: "file", path: "/missing/firecrawl-secrets.json" },
+          },
+        },
         plugins: {
           entries: {
             firecrawl: {
               config: {
                 webFetch: {
-                  apiKey: { source: "env", provider: "default", id: "MISSING_FIRECRAWL_REF" },
+                  apiKey: { source: "file", provider: "default", id: "/firecrawl/apiKey" },
                 },
               },
             },
@@ -1550,23 +1563,137 @@ describe("runtime web tools resolution", () => {
           | { webFetch?: { apiKey?: unknown } }
           | undefined
       )?.webFetch?.apiKey,
-    ).toEqual({ source: "env", provider: "default", id: "MISSING_FIRECRAWL_REF" });
+    ).toEqual({ source: "file", provider: "default", id: "/firecrawl/apiKey" });
     expect(degradedOwners).toContainEqual(
       expect.objectContaining({
         ownerKind: "capability",
         ownerId: "web-fetch:firecrawl",
         state: "unavailable",
         paths: ["plugins.entries.firecrawl.config.webFetch.apiKey"],
-        reason: expect.stringContaining("MISSING_FIRECRAWL_REF"),
+        reason: "secret provider failed",
       }),
     );
-    expect(degradedOwners[0]?.refKeys).toEqual(["env:default:MISSING_FIRECRAWL_REF"]);
+    expect(degradedOwners[0]?.refKeys).toEqual(["file:default:/firecrawl/apiKey"]);
+    expect(degradedOwners[0]?.reason).not.toContain("/missing/firecrawl-secrets.json");
     expectDiagnostic(context.warnings, {
       code: "SECRETS_OWNER_UNAVAILABLE",
       path: "plugins.entries.firecrawl.config.webFetch.apiKey",
     });
   });
 
+  it("fails fast on an invalid resolved value without exposing its ref", async () => {
+    const refId = "FIRECRAWL_API_KEY";
+    const resolveSpy = vi
+      .spyOn(secretResolve, "resolveSecretRefValues")
+      .mockResolvedValue(new Map([[`env:default:${refId}`, { value: "fixture-api-key" }]]));
+    restoreResolveSecretRefValuesSpy = () => resolveSpy.mockRestore();
+
+    const error = await runRuntimeWebTools({
+      config: asConfig({
+        plugins: {
+          entries: {
+            firecrawl: {
+              config: {
+                webFetch: {
+                  apiKey: { source: "env", provider: "default", id: refId },
+                },
+              },
+            },
+          },
+        },
+        tools: { web: { fetch: { provider: "firecrawl" } } },
+      }),
+      allowUnavailableSecretOwners: true,
+    }).then(
+      () => undefined,
+      (caught: unknown) => caught,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    const message = error instanceof Error ? error.message : String(error);
+    expect(message).toBe(
+      "plugins.entries.firecrawl.config.webFetch.apiKey resolved to a non-string or empty value.",
+    );
+    expect(message).not.toContain(refId);
+    expect(message).not.toContain("fixture-api-key");
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({
+        ownerKind: "capability",
+        ownerId: "web-fetch:firecrawl",
+        reason: "resolved secret value was invalid",
+        degradationState: "cold",
+        failureMatched: true,
+        source: "config",
+      }),
+    ]);
+  });
+
+  it("attributes an invalid legacy x_search value to the Grok capability", async () => {
+    const refId = "X_SEARCH_KEY_REF";
+    const resolveSpy = vi
+      .spyOn(secretResolve, "resolveSecretRefValues")
+      .mockResolvedValue(new Map([[`env:default:${refId}`, { value: "fixture-api-key" }]]));
+    restoreResolveSecretRefValuesSpy = () => resolveSpy.mockRestore();
+
+    const error = await runRuntimeWebTools({
+      config: asConfig({
+        tools: {
+          web: {
+            x_search: {
+              apiKey: { source: "env", provider: "default", id: refId },
+            },
+          },
+        },
+      }),
+    }).catch((caught: unknown) => caught);
+
+    expect(listSecretResolutionErrorOwners(error)).toEqual([
+      expect.objectContaining({
+        ownerKind: "capability",
+        ownerId: "web-search:grok",
+        reason: "resolved secret value was invalid",
+        failureMatched: true,
+      }),
+    ]);
+  });
+
+  it("preserves a denied-provider reason without exposing its ref", async () => {
+    const refId = "FIRECRAWL_API_KEY";
+    const { degradedOwners } = await runRuntimeWebTools({
+      config: asConfig({
+        secrets: {
+          providers: {
+            default: { source: "env", allowlist: ["OTHER_API_KEY"] },
+          },
+        },
+        plugins: {
+          entries: {
+            firecrawl: {
+              config: {
+                webFetch: {
+                  apiKey: { source: "env", provider: "default", id: refId },
+                },
+              },
+            },
+          },
+        },
+        tools: { web: { fetch: { provider: "firecrawl" } } },
+      }),
+      env: { [refId]: "fixture-api-key" },
+      allowUnavailableSecretOwners: true,
+    });
+
+    expect(degradedOwners).toMatchObject([
+      {
+        ownerKind: "capability",
+        ownerId: "web-fetch:firecrawl",
+        reason: "secret provider policy denied resolution",
+      },
+    ]);
+    expect(degradedOwners[0]?.reason).not.toContain(refId);
+    expect(degradedOwners[0]?.reason).not.toContain("fixture-api-key");
+  });
+
   it("resolves web fetch fallback SecretRefs with provider env var allowlist", async () => {
     const { metadata, resolvedConfig } = await runRuntimeWebTools({
       config: asConfig({
@@ -1674,7 +1801,7 @@ describe("runtime web tools resolution", () => {
           firecrawl: {
             config: {
               webFetch: {
-                apiKey: { source: "env", provider: "default", id: "MISSING_FIRECRAWL_REF" },
+                apiKey: { source: "env", provider: "default", id: "FIRECRAWL_API_KEY" },
               },
             },
           },
@@ -1741,13 +1868,12 @@ describe("runtime web tools resolution", () => {
         sourceConfig,
         resolvedConfig,
         context,
+        allowUnavailableSecretOwners: true,
       }),
-    ).rejects.toThrow("[WEB_FETCH_PROVIDER_KEY_UNRESOLVED_NO_FALLBACK]");
-    expectDiagnostic(context.warnings, {
-      code: "WEB_FETCH_PROVIDER_KEY_UNRESOLVED_NO_FALLBACK",
-      path: "plugins.entries.firecrawl.config.webFetch.apiKey",
-      messageIncludes: 'SecretRef env var "AWS_SECRET_ACCESS_KEY" is not allowed.',
-    });
+    ).rejects.toThrow(
+      "plugins.entries.firecrawl.config.webFetch.apiKey SecretRef is not allowed for this provider.",
+    );
+    expect(context.warnings).toEqual([]);
   });
 
   it("keeps web fetch provider discovery bundled-only during runtime secret resolution", async () => {
diff --git a/src/secrets/runtime-web-tools.ts b/src/secrets/runtime-web-tools.ts
index 15a968717a8..b7ae64018e6 100644
--- a/src/secrets/runtime-web-tools.ts
+++ b/src/secrets/runtime-web-tools.ts
@@ -19,11 +19,20 @@ import { sortWebSearchProvidersForAutoDetect } from "../plugins/web-search-provi
 import { createLazyRuntimeSurface } from "../shared/lazy-runtime.js";
 import { normalizeSecretInput } from "../utils/normalize-secret-input.js";
 import { secretRefKey } from "./ref-contract.js";
+import { describeSecretResolutionError } from "./resolve-errors.js";
 import { resolveSecretRefValues } from "./resolve.js";
-import type { DegradedSecretOwner } from "./runtime-degraded-state.js";
-import { warnDegradedSecretOwner } from "./runtime-owner-assignments.js";
+import {
+  associateSecretResolutionErrorOwners,
+  type DegradedSecretOwner,
+  type SecretOwnerRefState,
+} from "./runtime-degraded-state.js";
+import {
+  classifySecretOwnerDegradationState,
+  warnDegradedSecretOwner,
+} from "./runtime-owner-assignments.js";
 import { hasCredentialBearingObjectValue } from "./runtime-secret-scan.js";
 import type { ResolverContext, SecretDefaults } from "./runtime-shared.js";
+import { getActiveSecretsRuntimeSnapshot } from "./runtime-state.js";
 import { runtimeWebSecretOwnerId } from "./runtime-web-secret-owner.js";
 import {
   ensureObject,
@@ -32,6 +41,8 @@ import {
   resolveRuntimeWebProviderSurface,
   resolveRuntimeWebProviderSelection,
   type RuntimeWebProviderSelectionResult,
+  type RuntimeWebSecretOwner,
+  type RuntimeWebUnavailableProvider,
   type SecretResolutionResult,
 } from "./runtime-web-tools.shared.js";
 import type {
@@ -40,6 +51,7 @@ import type {
   RuntimeWebSearchMetadata,
   RuntimeWebToolsMetadata,
 } from "./runtime-web-tools.types.js";
+import { isExpectedResolvedSecretValue } from "./secret-value.js";
 
 const loadRuntimeWebToolsFallbackProviders = createLazyRuntimeSurface(
   () => import("./runtime-web-tools-fallback.runtime.js"),
@@ -67,28 +79,109 @@ type SecretResolutionSource =
 type ResolvedRuntimeWebTools = {
   metadata: RuntimeWebToolsMetadata;
   degradedOwners: DegradedSecretOwner[];
+  secretOwners: SecretOwnerRefState[];
 };
 
-function collectUnavailableWebProvider(params: {
+function createUnavailableWebProviderOwner(params: {
+  kind: "search" | "fetch";
+  unavailable: RuntimeWebUnavailableProvider;
+}): DegradedSecretOwner {
+  return {
+    ownerKind: "capability",
+    ownerId: runtimeWebSecretOwnerId(params.kind, params.unavailable.providerId),
+    state: "unavailable",
+    paths: [params.unavailable.path],
+    refKeys: [params.unavailable.refKey],
+    reason: params.unavailable.reason,
+  };
+}
+
+function collectUnavailableWebProviders(params: {
   kind: "search" | "fetch";
   result: RuntimeWebProviderSelectionResult;
   context: ResolverContext;
   degradedOwners: DegradedSecretOwner[];
 }): void {
-  const unavailable = params.result.unavailableProvider;
-  if (!unavailable) {
-    return;
+  for (const unavailable of params.result.unavailableProviders) {
+    const owner = createUnavailableWebProviderOwner({ kind: params.kind, unavailable });
+    params.degradedOwners.push(owner);
+    warnDegradedSecretOwner(params.context, owner);
   }
-  const owner: DegradedSecretOwner = {
+}
+
+function toWebSecretOwnerRefState(
+  kind: "search" | "fetch",
+  owner: RuntimeWebSecretOwner,
+): SecretOwnerRefState {
+  return {
     ownerKind: "capability",
-    ownerId: runtimeWebSecretOwnerId(params.kind, unavailable.providerId),
-    state: "unavailable",
-    paths: [unavailable.path],
-    refKeys: [unavailable.refKey],
-    reason: unavailable.reason,
+    ownerId: runtimeWebSecretOwnerId(kind, owner.providerId),
+    refKeys: [owner.refKey],
   };
-  params.degradedOwners.push(owner);
-  warnDegradedSecretOwner(params.context, owner);
+}
+
+function associateWebProviderResolutionError(params: {
+  kind: "search" | "fetch";
+  config: OpenClawConfig;
+  error: unknown;
+  unavailableProviders: RuntimeWebUnavailableProvider[];
+}): void {
+  const failureByRefKey = new Map(
+    params.unavailableProviders.map((unavailable) => [unavailable.refKey, unavailable] as const),
+  );
+  const owners = params.unavailableProviders.map((unavailable) => {
+    const owner = createUnavailableWebProviderOwner({ kind: params.kind, unavailable });
+    return {
+      ...owner,
+      degradationState: classifySecretOwnerDegradationState({
+        ownerKind: owner.ownerKind,
+        ownerId: owner.ownerId,
+        refs: [unavailable.ref],
+        config: params.config,
+      }),
+      failureMatched: true,
+      source: "config" as const,
+    };
+  });
+  const ownerIds = new Set(owners.map((owner) => owner.ownerId));
+  const activeCoOwners = (getActiveSecretsRuntimeSnapshot()?.secretOwners ?? []).flatMap(
+    (owner) => {
+      if (
+        owner.ownerKind !== "capability" ||
+        ownerIds.has(owner.ownerId) ||
+        (!owner.ownerId.startsWith("web-search:") && !owner.ownerId.startsWith("web-fetch:"))
+      ) {
+        return [];
+      }
+      const matches = owner.refKeys.flatMap((refKey) => {
+        const unavailable = failureByRefKey.get(refKey);
+        return unavailable ? [unavailable] : [];
+      });
+      const firstMatch = matches[0];
+      if (!firstMatch) {
+        return [];
+      }
+      return [
+        {
+          ownerKind: owner.ownerKind,
+          ownerId: owner.ownerId,
+          state: "unavailable" as const,
+          paths: [],
+          refKeys: [...owner.refKeys],
+          reason: firstMatch.reason,
+          degradationState: classifySecretOwnerDegradationState({
+            ownerKind: owner.ownerKind,
+            ownerId: owner.ownerId,
+            refs: matches.map((match) => match.ref),
+            config: params.config,
+          }),
+          failureMatched: true,
+          source: "config" as const,
+        },
+      ];
+    },
+  );
+  associateSecretResolutionErrorOwners(params.error, [...owners, ...activeCoOwners]);
 }
 
 function needsRuntimeWebFetchProviderDiscovery(params: {
@@ -226,21 +319,9 @@ function readNonEmptyEnvValue(
   return {};
 }
 
-function buildUnresolvedReason(params: {
-  path: string;
-  kind: "unresolved" | "non-string" | "empty";
-  refLabel: string;
-}): string {
-  if (params.kind === "non-string") {
-    return `${params.path} SecretRef resolved to a non-string value.`;
-  }
-  if (params.kind === "empty") {
-    return `${params.path} SecretRef resolved to an empty value.`;
-  }
-  return `${params.path} SecretRef is unresolved (${params.refLabel}).`;
-}
-
 async function resolveSecretInputWithEnvFallback(params: {
+  kind: "search" | "fetch";
+  providerId: string;
   sourceConfig: OpenClawConfig;
   context: ResolverContext;
   defaults: SecretDefaults | undefined;
@@ -278,16 +359,15 @@ async function resolveSecretInputWithEnvFallback(params: {
     };
   }
 
-  const refLabel = `${ref.source}:${ref.provider}:${ref.id}`;
   let resolvedFromRef: string | undefined;
-  let unresolvedRefReason: string | undefined;
+  let unresolvedRefReason: SecretResolutionResult<SecretResolutionSource>["unresolvedRefReason"];
 
   if (
     params.restrictEnvRefsToEnvVars === true &&
     ref.source === "env" &&
     !params.envVars.includes(ref.id)
   ) {
-    unresolvedRefReason = `${params.path} SecretRef env var "${ref.id}" is not allowed.`;
+    throw new Error(`${params.path} SecretRef is not allowed for this provider.`);
   } else {
     try {
       const resolved = await resolveSecretRefValues([ref], {
@@ -297,28 +377,33 @@ async function resolveSecretInputWithEnvFallback(params: {
         manifestRegistry: params.context.manifestRegistry,
       });
       const resolvedValue = resolved.get(secretRefKey(ref));
-      if (typeof resolvedValue !== "string") {
-        unresolvedRefReason = buildUnresolvedReason({
-          path: params.path,
-          kind: "non-string",
-          refLabel,
+      if (!isExpectedResolvedSecretValue(resolvedValue, "string")) {
+        const error = new Error(`${params.path} resolved to a non-string or empty value.`);
+        associateWebProviderResolutionError({
+          kind: params.kind,
+          config: params.sourceConfig,
+          error,
+          unavailableProviders: [
+            {
+              providerId: params.providerId,
+              path: params.path,
+              ref,
+              refKey: secretRefKey(ref),
+              reason: "resolved secret value was invalid",
+            },
+          ],
         });
-      } else {
-        resolvedFromRef = normalizeSecretInput(resolvedValue);
-        if (!resolvedFromRef) {
-          unresolvedRefReason = buildUnresolvedReason({
-            path: params.path,
-            kind: "empty",
-            refLabel,
-          });
-        }
+        throw error;
       }
-    } catch {
-      unresolvedRefReason = buildUnresolvedReason({
-        path: params.path,
-        kind: "unresolved",
-        refLabel,
-      });
+      resolvedFromRef = normalizeSecretInput(resolvedValue);
+    } catch (error) {
+      const reason = describeSecretResolutionError(error);
+      if (!reason) {
+        // Invalid provider config or resolved values are structural failures. They must fail
+        // activation before publishing an owner degradation that could imply retryability.
+        throw error;
+      }
+      unresolvedRefReason = reason;
     }
   }
 
@@ -327,12 +412,14 @@ async function resolveSecretInputWithEnvFallback(params: {
       value: resolvedFromRef,
       source: "secretRef",
       secretRefConfigured: true,
+      secretRef: ref,
       secretRefKey: secretRefKey(ref),
     };
   }
 
   return {
     source: "missing",
+    secretRef: ref,
     secretRefKey: secretRefKey(ref),
     unresolvedRefReason,
     secretRefConfigured: true,
@@ -540,9 +627,11 @@ export async function resolveRuntimeWebTools(params: {
   const defaults = params.sourceConfig.secrets?.defaults;
   const diagnostics: RuntimeWebDiagnostic[] = [];
   const degradedOwners: DegradedSecretOwner[] = [];
+  const secretOwners: SecretOwnerRefState[] = [];
   const finish = (metadata: RuntimeWebToolsMetadata): ResolvedRuntimeWebTools => ({
     metadata,
     degradedOwners,
+    secretOwners,
   });
   const env = { ...process.env, ...params.context.env };
 
@@ -583,6 +672,8 @@ export async function resolveRuntimeWebTools(params: {
     const legacyXSearchSourceRecord = legacyXSearchSource as Record<string, unknown>;
     const legacyXSearchResolvedRecord = legacyXSearchResolved as Record<string, unknown>;
     const resolution = await resolveSecretInputWithEnvFallback({
+      kind: "search",
+      providerId: "grok",
       sourceConfig: params.sourceConfig,
       context: params.context,
       defaults,
@@ -695,7 +786,14 @@ export async function resolveRuntimeWebTools(params: {
       defaults,
       allowKeylessAutoSelect: false,
       deferKeylessFallback: true,
-      allowUnavailableExplicitProvider: params.allowUnavailableSecretOwners,
+      allowUnavailableProviders: params.allowUnavailableSecretOwners,
+      onUnavailableProviders: (error) =>
+        associateWebProviderResolutionError({
+          kind: "search",
+          config: params.sourceConfig,
+          error,
+          unavailableProviders: error.unavailableProviders,
+        }),
       noFallbackCode: "WEB_SEARCH_KEY_UNRESOLVED_NO_FALLBACK",
       autoDetectSelectedCode: "WEB_SEARCH_AUTODETECT_SELECTED",
       readConfiguredCredential: ({ provider, config, toolConfig }) =>
@@ -710,8 +808,10 @@ export async function resolveRuntimeWebTools(params: {
           config,
           search: toolConfig,
         }),
-      resolveSecretInput: ({ value, path, envVars }) =>
+      resolveSecretInput: ({ providerId, value, path, envVars }) =>
         resolveSecretInputWithEnvFallback({
+          kind: "search",
+          providerId,
           sourceConfig: params.sourceConfig,
           context: params.context,
           defaults,
@@ -748,7 +848,10 @@ export async function resolveRuntimeWebTools(params: {
         );
       },
     });
-    collectUnavailableWebProvider({
+    for (const owner of searchSelection.secretOwners) {
+      secretOwners.push(toWebSecretOwnerRefState("search", owner));
+    }
+    collectUnavailableWebProviders({
       kind: "search",
       result: searchSelection,
       context: params.context,
@@ -814,7 +917,14 @@ export async function resolveRuntimeWebTools(params: {
       defaults,
       allowKeylessAutoSelect: true,
       deferKeylessFallback: false,
-      allowUnavailableExplicitProvider: params.allowUnavailableSecretOwners,
+      allowUnavailableProviders: params.allowUnavailableSecretOwners,
+      onUnavailableProviders: (error) =>
+        associateWebProviderResolutionError({
+          kind: "fetch",
+          config: params.sourceConfig,
+          error,
+          unavailableProviders: error.unavailableProviders,
+        }),
       noFallbackCode: "WEB_FETCH_PROVIDER_KEY_UNRESOLVED_NO_FALLBACK",
       autoDetectSelectedCode: "WEB_FETCH_AUTODETECT_SELECTED",
       readConfiguredCredential: ({ provider, config, toolConfig }) =>
@@ -829,8 +939,10 @@ export async function resolveRuntimeWebTools(params: {
           config,
           fetch: toolConfig,
         }),
-      resolveSecretInput: ({ value, path, envVars }) =>
+      resolveSecretInput: ({ providerId, value, path, envVars }) =>
         resolveSecretInputWithEnvFallback({
+          kind: "fetch",
+          providerId,
           sourceConfig: params.sourceConfig,
           context: params.context,
           defaults,
@@ -868,7 +980,10 @@ export async function resolveRuntimeWebTools(params: {
         );
       },
     });
-    collectUnavailableWebProvider({
+    for (const owner of fetchSelection.secretOwners) {
+      secretOwners.push(toWebSecretOwnerRefState("fetch", owner));
+    }
+    collectUnavailableWebProviders({
       kind: "fetch",
       result: fetchSelection,
       context: params.context,
diff --git a/src/secrets/runtime.auth.integration.test.ts b/src/secrets/runtime.auth.integration.test.ts
index fe29873d4ff..3931a103451 100644
--- a/src/secrets/runtime.auth.integration.test.ts
+++ b/src/secrets/runtime.auth.integration.test.ts
@@ -64,10 +64,12 @@ vi.mock("./runtime-prepare.runtime.js", () => ({
       diagnostics: [],
     },
     degradedOwners: [],
+    secretOwners: [],
   }),
 }));
 
 vi.mock("./runtime-owner-assignments.js", () => ({
+  listSecretAssignmentOwners: () => [],
   resolveAndApplySecretAssignments: async () => [],
 }));
 
diff --git a/src/secrets/runtime.fast-path.test.ts b/src/secrets/runtime.fast-path.test.ts
index 89f0be0ffe6..2d948b07bbf 100644
--- a/src/secrets/runtime.fast-path.test.ts
+++ b/src/secrets/runtime.fast-path.test.ts
@@ -22,6 +22,7 @@ const { resolveRuntimeWebToolsMock, runtimePrepareImportMock } = vi.hoisted(() =
       diagnostics: [],
     },
     degradedOwners: [],
+    secretOwners: [],
   })),
   runtimePrepareImportMock: vi.fn(),
 }));
@@ -44,6 +45,7 @@ vi.mock("./runtime-prepare.runtime.js", () => {
 });
 
 vi.mock("./runtime-owner-assignments.js", () => ({
+  listSecretAssignmentOwners: () => [],
   resolveAndApplySecretAssignments: async () => [],
 }));
 
diff --git a/src/secrets/runtime.test.ts b/src/secrets/runtime.test.ts
index d24071f1441..6f6088e5550 100644
--- a/src/secrets/runtime.test.ts
+++ b/src/secrets/runtime.test.ts
@@ -390,6 +390,7 @@ describe("secrets runtime snapshot", () => {
       }),
       env: {},
       includeAuthStoreRefs: false,
+      allowUnavailableSecretOwners: true,
       loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
     });
 
@@ -476,27 +477,6 @@ describe("secrets runtime snapshot", () => {
     ).rejects.toThrow('Environment variable "CODEX_APP_SERVER_TOKEN" is missing or empty.');
   });
 
-  it("fails closed for missing TTS SecretRefs outside cold-start isolation", async () => {
-    await expect(
-      prepareSecretsRuntimeSnapshot({
-        config: asConfig({
-          messages: {
-            tts: {
-              providers: {
-                elevenlabs: {
-                  apiKey: TTS_REF,
-                },
-              },
-            },
-          },
-        }),
-        env: {},
-        includeAuthStoreRefs: false,
-        loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
-      }),
-    ).rejects.toThrow('Environment variable "ELEVENLABS_API_KEY" is missing or empty.');
-  });
-
   it("isolates the TTS owner when its SecretRef is missing during cold startup", async () => {
     const snapshot = await prepareSecretsRuntimeSnapshot({
       config: asConfig({
@@ -755,84 +735,6 @@ describe("secrets runtime snapshot", () => {
     ).rejects.toThrow('Secret provider "missing" is not configured');
   });
 
-  it("keeps TTS SecretRefs that resolve to non-strings fail-closed", async () => {
-    if (process.platform === "win32") {
-      return;
-    }
-    const root = tempDirs.make("openclaw-tts-secretref-object-");
-    const secretsPath = path.join(root, "secrets.json");
-    await fs.writeFile(
-      secretsPath,
-      JSON.stringify(
-        {
-          providers: {
-            elevenlabs: {
-              apiKey: { value: "not-a-string" },
-            },
-          },
-        },
-        null,
-        2,
-      ),
-      "utf8",
-    );
-    await fs.chmod(secretsPath, 0o600);
-
-    await expect(
-      prepareSecretsRuntimeSnapshot({
-        config: asConfig({
-          secrets: {
-            providers: {
-              ttsfile: {
-                source: "file",
-                path: secretsPath,
-                mode: "json",
-              },
-            },
-          },
-          messages: {
-            tts: {
-              providers: {
-                elevenlabs: {
-                  apiKey: {
-                    source: "file",
-                    provider: "ttsfile",
-                    id: "/providers/elevenlabs/apiKey",
-                  },
-                },
-              },
-            },
-          },
-        }),
-        env: {},
-        includeAuthStoreRefs: false,
-        allowUnavailableSecretOwners: true,
-        loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
-      }),
-    ).rejects.toThrow(
-      "messages.tts.providers.elevenlabs.apiKey resolved to a non-string or empty value.",
-    );
-  });
-
-  it("still fails required gateway auth SecretRefs when env is missing", async () => {
-    await expect(
-      prepareSecretsRuntimeSnapshot({
-        config: asConfig({
-          gateway: {
-            auth: {
-              mode: "token",
-              token: { source: "env", provider: "default", id: "GATEWAY_TOKEN_REF" },
-            },
-          },
-        }),
-        env: {},
-        includeAuthStoreRefs: false,
-        allowUnavailableSecretOwners: true,
-        loadablePluginOrigins: EMPTY_LOADABLE_PLUGIN_ORIGINS,
-      }),
-    ).rejects.toThrow('Environment variable "GATEWAY_TOKEN_REF" is missing or empty.');
-  });
-
   it("isolates an unavailable model provider without applying another credential source", async () => {
     const ref = { source: "env", provider: "default", id: "MISSING_PROVIDER_KEY" } as const;
     const snapshot = await prepareSecretsRuntimeSnapshot({
diff --git a/src/secrets/runtime.ts b/src/secrets/runtime.ts
index 6bcd3336627..5dcccd7299c 100644
--- a/src/secrets/runtime.ts
+++ b/src/secrets/runtime.ts
@@ -20,6 +20,7 @@ import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot
 import type { PluginOrigin } from "../plugins/plugin-origin.types.js";
 import { createLazyRuntimeModule } from "../shared/lazy-runtime.js";
 import { isRecord, resolveUserPath } from "../utils.js";
+import { resolveAuthProfileSecretOwnerId } from "./runtime-auth-profile-owner.js";
 import {
   canUseSecretsRuntimeFastPath,
   collectCandidateAgentDirs,
@@ -178,6 +179,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
       authStoreCredentialsRevision,
       warnings: [],
       degradedOwners: [],
+      secretOwners: [],
       webTools: createEmptyRuntimeWebToolsMetadata(),
     };
     setPreparedSecretsRuntimeSnapshotRefreshContext(snapshot, {
@@ -198,7 +200,8 @@ export async function prepareSecretsRuntimeSnapshot(params: {
     createResolverContext,
     resolveRuntimeWebTools,
   } = await loadRuntimePrepareHelpers();
-  const { resolveAndApplySecretAssignments } = await loadRuntimeOwnerAssignmentHelpers();
+  const { listSecretAssignmentOwners, resolveAndApplySecretAssignments } =
+    await loadRuntimeOwnerAssignmentHelpers();
   const manifestRegistry =
     params.manifestRegistry ?? params.pluginMetadataSnapshot?.manifestRegistry;
   const loadablePluginOrigins =
@@ -257,6 +260,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
           },
         })
       : [];
+  const assignmentSecretOwners = listSecretAssignmentOwners(context.assignments);
 
   const webTools = includeConfigRefs
     ? await resolveRuntimeWebTools({
@@ -268,6 +272,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
     : {
         metadata: createEmptyRuntimeWebToolsMetadata(),
         degradedOwners: [],
+        secretOwners: [],
       };
   const snapshot = {
     sourceConfig,
@@ -276,6 +281,7 @@ export async function prepareSecretsRuntimeSnapshot(params: {
     authStoreCredentialsRevision,
     warnings: context.warnings,
     degradedOwners: [...degradedOwners, ...webTools.degradedOwners],
+    secretOwners: [...assignmentSecretOwners, ...webTools.secretOwners],
     webTools: webTools.metadata,
   };
   setPreparedSecretsRuntimeSnapshotRefreshContext(snapshot, {
@@ -295,16 +301,28 @@ export function activateSecretsRuntimeSnapshot(snapshot: PreparedSecretsRuntimeS
   activateSecretsRuntimeSnapshotState(createSecretsRuntimeSnapshotActivation(snapshot));
 }
 
+/** Activates resolved runtime bytes while retaining the distinct raw config source. */
+export function activateSecretsRuntimeSnapshotWithSource(
+  snapshot: PreparedSecretsRuntimeSnapshot,
+  runtimeSourceConfig: OpenClawConfig,
+): void {
+  activateSecretsRuntimeSnapshotState({
+    ...createSecretsRuntimeSnapshotActivation(snapshot),
+    runtimeSourceConfig,
+  });
+}
+
 /** Compare-and-activate boundary for snapshots prepared from process-wide runtime state. */
 export function activateSecretsRuntimeSnapshotIfCurrent(
   snapshot: PreparedSecretsRuntimeSnapshot,
   expectedRevision: number,
-  options?: { preserveActivationLineage?: boolean },
+  options?: { preserveActivationLineage?: boolean; runtimeSourceConfig?: OpenClawConfig },
 ): boolean {
   return activateSecretsRuntimeSnapshotStateIfCurrent({
     ...createSecretsRuntimeSnapshotActivation(snapshot),
     expectedRevision,
     preserveActivationLineage: options?.preserveActivationLineage,
+    runtimeSourceConfig: options?.runtimeSourceConfig,
   });
 }
 
@@ -313,11 +331,13 @@ export function restoreSecretsRuntimeSnapshotIfCurrent(
   snapshot: PreparedSecretsRuntimeSnapshot,
   expectedRevision: number,
   ownedSnapshot: PreparedSecretsRuntimeSnapshot,
+  options?: { runtimeSourceConfig?: OpenClawConfig },
 ): boolean {
   return restoreSecretsRuntimeSnapshotStateIfCurrent({
     ...createSecretsRuntimeSnapshotActivation(snapshot),
     expectedRevision,
     ownedSnapshot,
+    runtimeSourceConfig: options?.runtimeSourceConfig,
   });
 }
 
@@ -474,6 +494,37 @@ function selectProviderAuthConfig(config: OpenClawConfig): OpenClawConfig {
   };
 }
 
+function listAuthProfileSecretOwnerIds(
+  authStores: PreparedSecretsRuntimeSnapshot["authStores"],
+): Set<string> {
+  return new Set(
+    authStores.flatMap(({ agentDir, store }) =>
+      Object.keys(store.profiles).map((profileId) =>
+        resolveAuthProfileSecretOwnerId({ agentDir, profileId }),
+      ),
+    ),
+  );
+}
+
+function mergeProviderAuthSecretOwners(
+  active: PreparedSecretsRuntimeSnapshot,
+  candidate: PreparedSecretsRuntimeSnapshot,
+): PreparedSecretsRuntimeSnapshot["secretOwners"] {
+  const activeAuthProfileOwnerIds = listAuthProfileSecretOwnerIds(active.authStores);
+  const isActiveProviderAuthOwner = (owner: NonNullable<typeof active.secretOwners>[number]) =>
+    owner.ownerKind === "provider" ||
+    (owner.ownerKind === "account" && activeAuthProfileOwnerIds.has(owner.ownerId));
+  const isCandidateProviderAuthOwner = (
+    owner: NonNullable<typeof candidate.secretOwners>[number],
+  ) => owner.ownerKind === "provider" || owner.ownerKind === "account";
+  // This refresh publishes provider and account state only. Keep transport-owned refs pinned
+  // to their active snapshot so later failures compare against the values actually in use.
+  return [
+    ...(active.secretOwners ?? []).filter((owner) => !isActiveProviderAuthOwner(owner)),
+    ...(candidate.secretOwners ?? []).filter(isCandidateProviderAuthOwner),
+  ];
+}
+
 function createSecretsRuntimeSnapshotActivation(snapshot: PreparedSecretsRuntimeSnapshot) {
   const refreshContext =
     getPreparedSecretsRuntimeSnapshotRefreshContext(snapshot) ??
@@ -531,6 +582,7 @@ export async function refreshActiveProviderAuthRuntimeSnapshot(): Promise<boolea
       config,
       authStores: candidate.snapshot.authStores,
       authStoreCredentialsRevision: candidate.snapshot.authStoreCredentialsRevision,
+      secretOwners: mergeProviderAuthSecretOwners(activeSnapshot, candidate.snapshot),
     };
     // The pinned config read and revision claim are synchronous: preserve gateway-owned
     // runtime mutations while preventing a concurrently prepared secrets snapshot from winning.

From f57a8753da4cbf563a7dad7c6b0a9fcf0bca4983 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:56:16 +0100
Subject: [PATCH 38/76] fix(ui): cap sidebar child sessions with show-more,
 drop Subagent prefix in tree (#110604)

* fix(ui): cap sidebar child sessions at four with show-more, drop Subagent prefix in tree

* test(ui): split child-session cap cases under the max-lines budget
---
 ui/src/components/app-sidebar-session-list.ts |  33 +++-
 .../app-sidebar-session-navigation.ts         |  12 +-
 ui/src/components/app-sidebar.test.ts         |   1 +
 ui/src/i18n/locales/en.ts                     |   1 +
 ui/src/lib/session-display.test.ts            |  28 ++++
 ui/src/lib/session-display.ts                 |  13 +-
 ui/src/styles/layout.css                      |  16 ++
 .../app-sidebar-cases/child-sessions-cap.ts   | 141 ++++++++++++++++++
 8 files changed, 242 insertions(+), 3 deletions(-)
 create mode 100644 ui/src/test-helpers/app-sidebar-cases/child-sessions-cap.ts

diff --git a/ui/src/components/app-sidebar-session-list.ts b/ui/src/components/app-sidebar-session-list.ts
index 4ad1a52552a..e3b2919c8a7 100644
--- a/ui/src/components/app-sidebar-session-list.ts
+++ b/ui/src/components/app-sidebar-session-list.ts
@@ -27,6 +27,8 @@ import { icons } from "./icons.ts";
 import { renderSessionRowBadges } from "./session-row-badges.ts";
 import "./elapsed-time.ts";
 
+const SIDEBAR_VISIBLE_CHILD_SESSION_LIMIT = 4;
+
 /** Session-list presentation and catalog renderer wiring. */
 export abstract class AppSidebarSessionListElement extends AppSidebarMenusElement {
   @state() protected catalogProjectGrouping = loadStoredSidebarCatalogGrouping();
@@ -242,6 +244,22 @@ export abstract class AppSidebarSessionListElement extends AppSidebarMenusElemen
 
   private renderSessionTree(session: SidebarRecentSession): TemplateResult {
     const expanded = this.isSessionChildrenExpanded(session);
+    const showAllChildren = this.fullyShownChildSessionKeys.has(session.key);
+    // The cap hides quiet children only: the active branch and any branch with
+    // live runs (runningChildCount is transitive) must stay visible, or an
+    // auto-expanded parent would omit its own selection or a running session.
+    const visibleChildren = showAllChildren
+      ? session.children
+      : session.children.filter(
+          (child, index) =>
+            index < SIDEBAR_VISIBLE_CHILD_SESSION_LIMIT ||
+            child.visuallyActive ||
+            child.containsActiveDescendant ||
+            child.hasActiveRun ||
+            child.status === "running" ||
+            child.runningChildCount > 0,
+        );
+    const hiddenChildCount = session.children.length - visibleChildren.length;
     return html`<div class="sidebar-session-tree" data-session-tree=${session.key}>
       ${this.renderRecentSession(session)}
       ${expanded
@@ -249,7 +267,20 @@ export abstract class AppSidebarSessionListElement extends AppSidebarMenusElemen
             class="sidebar-session-tree__children"
             aria-label=${t("sessionsView.childSessions")}
           >
-            ${session.children.map((child) => this.renderSessionTree(child))}
+            ${visibleChildren.map((child) => this.renderSessionTree(child))}
+            ${hiddenChildCount > 0
+              ? html`<button
+                  class="sidebar-session-tree__show-more"
+                  type="button"
+                  data-show-more-children=${session.key}
+                  aria-label=${t("sessionsView.showMoreChildren", {
+                    count: String(hiddenChildCount),
+                  })}
+                  @click=${() => this.showAllSessionChildren(session.key)}
+                >
+                  ${t("sessionsView.showMoreChildren", { count: String(hiddenChildCount) })}
+                </button>`
+              : nothing}
             ${session.loadingChildren && session.children.length === 0
               ? html`<span class="sidebar-session-tree__loading">${t("common.loading")}</span>`
               : nothing}
diff --git a/ui/src/components/app-sidebar-session-navigation.ts b/ui/src/components/app-sidebar-session-navigation.ts
index 0374d02d2f4..abdae9f2dbb 100644
--- a/ui/src/components/app-sidebar-session-navigation.ts
+++ b/ui/src/components/app-sidebar-session-navigation.ts
@@ -53,6 +53,7 @@ export abstract class AppSidebarSessionNavigationElement extends AppSidebarSessi
   @state() protected selectedSessionKeys: ReadonlySet<string> = new Set();
   @state() protected expandedChildSessionKeys: ReadonlySet<string> = new Set();
   @state() protected collapsedActiveChildSessionKeys: ReadonlySet<string> = new Set();
+  @state() protected fullyShownChildSessionKeys: ReadonlySet<string> = new Set();
   @state() protected sessionSortMode: SidebarSessionSortMode = "created";
   @state() protected sessionsGrouping: SidebarSessionsGrouping =
     loadStoredSidebarSessionsGrouping();
@@ -162,7 +163,9 @@ export abstract class AppSidebarSessionNavigationElement extends AppSidebarSessi
       }
       return {
         key: row.key,
-        label: resolveSessionDisplayName(row.key, row),
+        label: resolveSessionDisplayName(row.key, row, {
+          includeSubagentPrefix: !isChild,
+        }),
         meta: formatSidebarTimestamp(row.updatedAt),
         subtitle: resolveSessionWorkSubtitle(row),
         href: `${pathForRoute("chat", context?.basePath ?? "")}${searchForSession(row.key)}`,
@@ -618,8 +621,10 @@ export abstract class AppSidebarSessionNavigationElement extends AppSidebarSessi
   protected toggleSessionChildren(session: SidebarRecentSession) {
     const next = new Set(this.expandedChildSessionKeys);
     const collapsedActive = new Set(this.collapsedActiveChildSessionKeys);
+    const fullyShown = new Set(this.fullyShownChildSessionKeys);
     if (this.isSessionChildrenExpanded(session)) {
       next.delete(session.key);
+      fullyShown.delete(session.key);
       if (session.containsActiveDescendant) {
         collapsedActive.add(session.key);
       }
@@ -643,6 +648,11 @@ export abstract class AppSidebarSessionNavigationElement extends AppSidebarSessi
     }
     this.expandedChildSessionKeys = next;
     this.collapsedActiveChildSessionKeys = collapsedActive;
+    this.fullyShownChildSessionKeys = fullyShown;
+  }
+
+  protected showAllSessionChildren(sessionKey: string) {
+    this.fullyShownChildSessionKeys = new Set(this.fullyShownChildSessionKeys).add(sessionKey);
   }
 
   private projectSessionTree(
diff --git a/ui/src/components/app-sidebar.test.ts b/ui/src/components/app-sidebar.test.ts
index 29291737c6b..8583d3d859e 100644
--- a/ui/src/components/app-sidebar.test.ts
+++ b/ui/src/components/app-sidebar.test.ts
@@ -8,6 +8,7 @@ import "../test-helpers/app-sidebar-cases/catalog-live-events.ts";
 import "../test-helpers/app-sidebar-cases/catalog-live.ts";
 import "../test-helpers/app-sidebar-cases/catalog-live-state.ts";
 import "../test-helpers/app-sidebar-cases/catalog-pages.ts";
+import "../test-helpers/app-sidebar-cases/child-sessions-cap.ts";
 import "../test-helpers/app-sidebar-cases/child-sessions.ts";
 import "../test-helpers/app-sidebar-cases/group-mutations.ts";
 import "../test-helpers/app-sidebar-cases/interactions.ts";
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 0c5f2ce47f1..6cc9715ca73 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -627,6 +627,7 @@ export const en: TranslationMap = {
     showChildSessions: "Show {count} child sessions for {session}",
     hideChildSessions: "Hide {count} child sessions for {session}",
     childSessions: "Child sessions",
+    showMoreChildren: "Show {count} more",
     archived: "Archived",
     pinned: "Pinned",
     unread: "Unread",
diff --git a/ui/src/lib/session-display.test.ts b/ui/src/lib/session-display.test.ts
index 34152566f22..ab6efbda714 100644
--- a/ui/src/lib/session-display.test.ts
+++ b/ui/src/lib/session-display.test.ts
@@ -77,6 +77,34 @@ describe("resolveSessionDisplayName", () => {
       "node-fleet-…8b2e",
     );
   });
+
+  it("can omit only the subagent prefix while preserving its untitled fallback", () => {
+    const key = "agent:main:subagent:worker";
+    expect(resolveSessionDisplayName(key, { label: "Research sources" })).toBe(
+      "Subagent: Research sources",
+    );
+    expect(
+      resolveSessionDisplayName(
+        key,
+        { label: "Subagent: Research sources" },
+        {
+          includeSubagentPrefix: false,
+        },
+      ),
+    ).toBe("Research sources");
+    expect(resolveSessionDisplayName(key, undefined, { includeSubagentPrefix: false })).toBe(
+      "Subagent:",
+    );
+    expect(
+      resolveSessionDisplayName(
+        "agent:main:cron:daily",
+        { label: "Daily" },
+        {
+          includeSubagentPrefix: false,
+        },
+      ),
+    ).toBe("Cron: Daily");
+  });
 });
 
 describe("resolveSessionWorkSubtitle", () => {
diff --git a/ui/src/lib/session-display.ts b/ui/src/lib/session-display.ts
index 4826b2d1b1d..c58a4c91f87 100644
--- a/ui/src/lib/session-display.ts
+++ b/ui/src/lib/session-display.ts
@@ -92,6 +92,10 @@ type SessionDisplayRow = {
   derivedTitle?: string;
 } & SessionWorktreeDisplayRow;
 
+type SessionDisplayOptions = {
+  includeSubagentPrefix?: boolean;
+};
+
 function capitalize(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
@@ -169,7 +173,11 @@ function parseSessionKey(key: string): SessionKeyInfo {
   return { prefix: "", fallbackName: key };
 }
 
-export function resolveSessionDisplayName(key: string, row?: SessionDisplayRow): string {
+export function resolveSessionDisplayName(
+  key: string,
+  row?: SessionDisplayRow,
+  options: SessionDisplayOptions = {},
+): string {
   const label = normalizeOptionalString(row?.label) ?? "";
   const displayName = normalizeOptionalString(row?.displayName) ?? "";
   const derivedTitle = normalizeOptionalString(row?.derivedTitle) ?? "";
@@ -180,6 +188,9 @@ export function resolveSessionDisplayName(key: string, row?: SessionDisplayRow):
       return name;
     }
     const prefixPattern = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\s*`, "i");
+    if (prefix === "Subagent:" && options.includeSubagentPrefix === false) {
+      return name.replace(prefixPattern, "").trim() || fallbackName;
+    }
     return prefixPattern.test(name) ? name : `${prefix} ${name}`;
   };
 
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index b976dc66f60..996e6cf42cc 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -1505,6 +1505,22 @@ html.openclaw-native-macos
   font-size: 11px;
 }
 
+.sidebar-session-tree__show-more {
+  min-height: 28px;
+  padding: 6px 8px;
+  border: 0;
+  background: transparent;
+  color: var(--muted);
+  font-size: 11px;
+  font-weight: 400;
+  text-align: left;
+}
+
+.sidebar-session-tree__show-more:hover,
+.sidebar-session-tree__show-more:focus-visible {
+  color: var(--text);
+}
+
 .sidebar-recent-sessions__group[data-session-section^="catalog:"] > .sidebar-recent-sessions__list {
   gap: 8px;
 }
diff --git a/ui/src/test-helpers/app-sidebar-cases/child-sessions-cap.ts b/ui/src/test-helpers/app-sidebar-cases/child-sessions-cap.ts
new file mode 100644
index 00000000000..362fb14093d
--- /dev/null
+++ b/ui/src/test-helpers/app-sidebar-cases/child-sessions-cap.ts
@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import type { GatewayBrowserClient } from "../../api/gateway.ts";
+import { createGateway, createSessionsHarness, mountSidebar } from "../app-sidebar.ts";
+import { waitForFast } from "../wait-for.ts";
+import "../../components/app-sidebar.ts";
+
+describe("AppSidebar child session cap", () => {
+  it("caps visible children until requested and resets the cap after collapse", async () => {
+    const gateway = createGateway({} as GatewayBrowserClient);
+    const childKeys = Array.from(
+      { length: 6 },
+      (_, index) => `agent:main:subagent:child-${index + 1}`,
+    );
+    const harness = createSessionsHarness("main", ["agent:main:parent"]);
+    harness.list.mockResolvedValue({
+      ts: 100_000,
+      path: "",
+      count: childKeys.length,
+      defaults: { modelProvider: null, model: null, contextTokens: null },
+      sessions: childKeys.map((key, index) => ({
+        key,
+        spawnedBy: "agent:main:parent",
+        kind: "direct" as const,
+        label: `Subagent: Child ${index + 1}`,
+        updatedAt: index + 1,
+      })),
+    });
+    const { sidebar } = await mountSidebar(gateway, harness.sessions);
+    harness.publishList({
+      result: {
+        ts: 2,
+        path: "",
+        count: 1,
+        defaults: { modelProvider: null, model: null, contextTokens: null },
+        sessions: [
+          {
+            key: "agent:main:parent",
+            kind: "direct",
+            label: "Parent task",
+            updatedAt: 1,
+            childSessions: childKeys,
+          },
+        ],
+      },
+    });
+    await sidebar.updateComplete;
+
+    const toggle = sidebar.querySelector<HTMLButtonElement>("[data-child-session-toggle]");
+    toggle?.click();
+    await waitForFast(() =>
+      expect(sidebar.querySelectorAll(".sidebar-recent-session--child")).toHaveLength(4),
+    );
+    const showMore = sidebar.querySelector<HTMLButtonElement>("[data-show-more-children]");
+    expect(showMore?.textContent?.trim()).toBe("Show 2 more");
+    expect(showMore?.getAttribute("aria-label")).toBe("Show 2 more");
+    expect(sidebar.textContent).not.toContain("Subagent:");
+
+    showMore?.click();
+    await waitForFast(() =>
+      expect(sidebar.querySelectorAll(".sidebar-recent-session--child")).toHaveLength(6),
+    );
+    expect(sidebar.querySelector("[data-show-more-children]")).toBeNull();
+
+    toggle?.click();
+    await sidebar.updateComplete;
+    toggle?.click();
+    await waitForFast(() =>
+      expect(sidebar.querySelectorAll(".sidebar-recent-session--child")).toHaveLength(4),
+    );
+    expect(sidebar.querySelector("[data-show-more-children]")?.textContent).toContain(
+      "Show 2 more",
+    );
+  });
+
+  it("keeps live children visible past the cap", async () => {
+    const gateway = createGateway({} as GatewayBrowserClient);
+    const childKeys = Array.from(
+      { length: 6 },
+      (_, index) => `agent:main:subagent:child-${index + 1}`,
+    );
+    const harness = createSessionsHarness("main", ["agent:main:parent"]);
+    harness.list.mockResolvedValue({
+      ts: 100_000,
+      path: "",
+      count: childKeys.length,
+      defaults: { modelProvider: null, model: null, contextTokens: null },
+      sessions: [
+        ...childKeys.map((key, index) => ({
+          key,
+          spawnedBy: "agent:main:parent",
+          kind: "direct" as const,
+          label: `Subagent: Child ${index + 1}`,
+          updatedAt: index + 1,
+        })),
+        // Quiet child beyond the cap with a RUNNING grandchild: the branch
+        // must bypass the cap via the transitive runningChildCount.
+        {
+          key: "agent:main:subagent:grandchild",
+          spawnedBy: "agent:main:subagent:child-6",
+          kind: "direct" as const,
+          label: "Subagent: Grandchild run",
+          updatedAt: 10,
+          status: "running" as const,
+          hasActiveRun: true,
+        },
+      ],
+    });
+    const { sidebar } = await mountSidebar(gateway, harness.sessions);
+    harness.publishList({
+      result: {
+        ts: 2,
+        path: "",
+        count: 1,
+        defaults: { modelProvider: null, model: null, contextTokens: null },
+        sessions: [
+          {
+            key: "agent:main:parent",
+            kind: "direct",
+            label: "Parent task",
+            updatedAt: 1,
+            childSessions: childKeys,
+          },
+        ],
+      },
+    });
+    await sidebar.updateComplete;
+
+    sidebar
+      .querySelector<HTMLButtonElement>('[data-child-session-toggle="agent:main:parent"]')
+      ?.click();
+    await waitForFast(() =>
+      expect(
+        sidebar.querySelector('[data-session-key="agent:main:subagent:child-6"]'),
+      ).not.toBeNull(),
+    );
+    expect(sidebar.querySelector('[data-session-key="agent:main:subagent:child-5"]')).toBeNull();
+    expect(sidebar.querySelector("[data-show-more-children]")?.textContent?.trim()).toBe(
+      "Show 1 more",
+    );
+  });
+});

From 31314920ced79a9fca0612709743140e11473a99 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 11:57:36 +0100
Subject: [PATCH 39/76] improve(ui): plugins hub hierarchy, settings section
 spacing, and grid-aligned secret inputs (#110482)

* improve(ui): align settings section headers, dedupe plugin row status pills, clean hub tab strip

* improve(ui): hub tabs as page nav, one-row plugins toolbar, honest section spacing, inset secret-input reveal
---
 ui/src/components/plugins-hub-tabs.ts  |  8 +--
 ui/src/components/sessions-hub-tabs.ts |  6 +-
 ui/src/components/settings-ui.ts       | 39 +++++++++++++
 ui/src/pages/connection/view.ts        | 30 +---------
 ui/src/pages/plugins/view.ts           | 34 +++++++----
 ui/src/styles/plugins.css              | 69 +++++++++++++++++++---
 ui/src/styles/settings.css             | 79 +++++++++++++++++++++++---
 7 files changed, 205 insertions(+), 60 deletions(-)

diff --git a/ui/src/components/plugins-hub-tabs.ts b/ui/src/components/plugins-hub-tabs.ts
index 9689a4bc225..1c1ab451f7f 100644
--- a/ui/src/components/plugins-hub-tabs.ts
+++ b/ui/src/components/plugins-hub-tabs.ts
@@ -72,13 +72,13 @@ function reclaimFocus(tab: PluginsHubTab, element: Element | undefined) {
 /**
  * Every hub page marks its main content container with
  * id="plugins-hub-panel" so aria-controls stays valid on each route.
- * Styled through the settings design language's segmented control
- * (ui/src/styles/settings.css) while keeping tablist semantics.
+ * Styled as page-level navigation (.hub-tabs in ui/src/styles/plugins.css),
+ * deliberately distinct from segmented filter pills, keeping tablist semantics.
  */
 export function renderPluginsHubTabs(props: PluginsHubTabsProps) {
   return html`
     <wa-tab-group
-      class="settings-segmented plugins-hub-tabs plugins-tabs"
+      class="hub-tabs plugins-hub-tabs plugins-tabs"
       aria-label=${t("pluginsPage.hubTablistLabel")}
       .active=${props.active}
       activation="manual"
@@ -94,7 +94,7 @@ export function renderPluginsHubTabs(props: PluginsHubTabsProps) {
             id=${`plugins-tab-${tab}`}
             panel=${tab}
             aria-controls="plugins-hub-panel"
-            class="settings-segmented__btn ${selected ? "settings-segmented__btn--active" : ""}"
+            class="hub-tab"
             ?active=${selected}
             @click=${(event: MouseEvent) => {
               // Trusted pointer clicks carry a click count. Keyboard and AT
diff --git a/ui/src/components/sessions-hub-tabs.ts b/ui/src/components/sessions-hub-tabs.ts
index 0e147730144..40d44f2e749 100644
--- a/ui/src/components/sessions-hub-tabs.ts
+++ b/ui/src/components/sessions-hub-tabs.ts
@@ -29,12 +29,12 @@ function hubTabLabel(tab: SessionsHubTab): string {
 /**
  * Every hub page marks its main content container with
  * id="sessions-hub-panel" so aria-controls stays valid on each route.
- * Styled through the settings design language's segmented control.
+ * Styled as page-level navigation (.hub-tabs in ui/src/styles/plugins.css).
  */
 export function renderSessionsHubTabs(props: SessionsHubTabsProps) {
   return html`
     <wa-tab-group
-      class="settings-segmented plugins-hub-tabs sessions-hub-tabs"
+      class="hub-tabs plugins-hub-tabs sessions-hub-tabs"
       aria-label=${t("sessionsPage.hubTablistLabel")}
       .active=${props.active}
       activation="manual"
@@ -49,7 +49,7 @@ export function renderSessionsHubTabs(props: SessionsHubTabsProps) {
             id=${`sessions-tab-${tab}`}
             panel=${tab}
             aria-controls="sessions-hub-panel"
-            class="settings-segmented__btn ${selected ? "settings-segmented__btn--active" : ""}"
+            class="hub-tab"
             ?active=${selected}
           >
             ${hubTabLabel(tab)}
diff --git a/ui/src/components/settings-ui.ts b/ui/src/components/settings-ui.ts
index 986b8e0d8a5..fdb7154c81e 100644
--- a/ui/src/components/settings-ui.ts
+++ b/ui/src/components/settings-ui.ts
@@ -7,6 +7,7 @@ import "@awesome.me/webawesome/dist/components/radio-group/radio-group.js";
 import "@awesome.me/webawesome/dist/components/switch/switch.js";
 import { html, nothing, type TemplateResult } from "lit";
 import { icons } from "./icons.ts";
+import "./tooltip.ts";
 
 type SettingsStatusKind = "ok" | "warn" | "danger" | "accent" | "muted";
 
@@ -259,3 +260,41 @@ export function renderSettingsValue(value: unknown, options: { mono?: boolean }
 export function renderSettingsEmpty(message: unknown): TemplateResult {
   return html`<div class="settings-empty">${message}</div>`;
 }
+
+/** Secret text input with an inset reveal toggle — one field, no trailing
+ * button, so secret rows line up with plain input rows in the same group. */
+export function renderSettingsSecretInput(props: {
+  value: string;
+  placeholder?: string;
+  visible: boolean;
+  showLabel: string;
+  hideLabel: string;
+  toggleLabel: string;
+  onInput: (next: string) => void;
+  onToggle: () => void;
+}): TemplateResult {
+  return html`
+    <span class="settings-secret">
+      <input
+        class="settings-input"
+        type=${props.visible ? "text" : "password"}
+        autocomplete="off"
+        spellcheck="false"
+        .value=${props.value}
+        placeholder=${props.placeholder ?? ""}
+        @input=${(e: Event) => props.onInput((e.target as HTMLInputElement).value)}
+      />
+      <openclaw-tooltip .content=${props.visible ? props.hideLabel : props.showLabel}>
+        <button
+          type="button"
+          class="settings-secret__toggle"
+          aria-label=${props.toggleLabel}
+          aria-pressed=${props.visible}
+          @click=${props.onToggle}
+        >
+          ${props.visible ? icons.eye : icons.eyeOff}
+        </button>
+      </openclaw-tooltip>
+    </span>
+  `;
+}
diff --git a/ui/src/pages/connection/view.ts b/ui/src/pages/connection/view.ts
index 3884f5ee330..ac700147342 100644
--- a/ui/src/pages/connection/view.ts
+++ b/ui/src/pages/connection/view.ts
@@ -2,11 +2,10 @@
 import { html } from "lit";
 import type { GatewayHelloOk } from "../../api/gateway.ts";
 import { resolveGatewayTokenForUrlEdit, type UiSettings } from "../../app/settings.ts";
-import "../../components/tooltip.ts";
-import { icons } from "../../components/icons.ts";
 import {
   renderSettingsPage,
   renderSettingsRow,
+  renderSettingsSecretInput,
   renderSettingsSection,
   renderSettingsStatus,
   renderSettingsValue,
@@ -43,31 +42,8 @@ function renderSecretRow(params: {
   onInput: (next: string) => void;
   onToggle: () => void;
 }) {
-  return renderSettingsRow({
-    title: params.label,
-    control: html`
-      <input
-        class="settings-input"
-        type=${params.visible ? "text" : "password"}
-        autocomplete="off"
-        spellcheck="false"
-        .value=${params.value}
-        @input=${(e: Event) => params.onInput((e.target as HTMLInputElement).value)}
-        placeholder=${params.placeholder}
-      />
-      <openclaw-tooltip .content=${params.visible ? params.hideLabel : params.showLabel}>
-        <button
-          type="button"
-          class="btn btn--icon ${params.visible ? "active" : ""}"
-          aria-label=${params.toggleLabel}
-          aria-pressed=${params.visible}
-          @click=${params.onToggle}
-        >
-          ${params.visible ? icons.eye : icons.eyeOff}
-        </button>
-      </openclaw-tooltip>
-    `,
-  });
+  const { label, ...secret } = params;
+  return renderSettingsRow({ title: label, control: renderSettingsSecretInput(secret) });
 }
 
 export function renderConnection(props: ConnectionProps) {
diff --git a/ui/src/pages/plugins/view.ts b/ui/src/pages/plugins/view.ts
index 6b6119dc163..586d35193d6 100644
--- a/ui/src/pages/plugins/view.ts
+++ b/ui/src/pages/plugins/view.ts
@@ -341,6 +341,12 @@ function stateStatus(plugin: PluginCatalogItem) {
   return renderSettingsStatus({ kind, label: stateLabel(plugin) });
 }
 
+/** Rows pair the status with an Enable/Disable button that already implies the
+ * healthy states, so only the error status earns a pill next to the actions. */
+function rowStateStatus(plugin: PluginCatalogItem) {
+  return plugin.state === "error" ? stateStatus(plugin) : nothing;
+}
+
 function originLabel(origin: string): string {
   switch (origin) {
     case "bundled":
@@ -614,7 +620,7 @@ function renderInstalledRow(plugin: PluginCatalogItem, props: PluginsViewProps):
         ])}
       </div>
       <div class="settings-row__control">
-        ${stateStatus(plugin)} ${renderCatalogActions(plugin, props, busy, key)}
+        ${rowStateStatus(plugin)} ${renderCatalogActions(plugin, props, busy, key)}
       </div>
       ${plugin.error
         ? html`<div class="plugins-row-message plugins-row-message--error" role="alert">
@@ -697,10 +703,6 @@ function renderMcpRow(server: McpServerSummary, props: PluginsViewProps): Templa
         ])}
       </div>
       <div class="settings-row__control">
-        ${renderSettingsStatus({
-          kind: server.enabled ? "ok" : "muted",
-          label: server.enabled ? t("pluginsPage.enabled") : t("pluginsPage.disabled"),
-        })}
         ${renderToggleButton(props, props.mcpBusy, {
           enabled: server.enabled,
           onToggle: (enabled) => props.onMcpToggle(server.name, enabled),
@@ -766,7 +768,6 @@ function renderInstalled(props: PluginsViewProps) {
   const groups = groupInstalledByCategory(plugins);
   const filtered = Boolean(props.query || props.installedFilter !== "all");
   return html`
-    ${renderInstalledFilter(props)}
     ${groups.length === 0
       ? renderEmpty(
           filtered ? t("pluginsPage.noInstalledMatchTitle") : t("pluginsPage.noInstalledTitle"),
@@ -821,7 +822,7 @@ function renderCatalogRow(plugin: PluginCatalogItem, props: PluginsViewProps): T
         ${renderMetaLine([plugin.origin ? originLabel(plugin.origin) : nothing])}
       </div>
       <div class="settings-row__control">
-        ${plugin.installed ? stateStatus(plugin) : nothing}
+        ${plugin.installed ? rowStateStatus(plugin) : nothing}
         ${renderCatalogActions(plugin, props, busy, key)}
       </div>
       ${plugin.error
@@ -966,7 +967,7 @@ function renderClawHubResult(item: PluginSearchResult, props: PluginsViewProps):
       </div>
       <div class="settings-row__control">
         ${installed
-          ? html`${stateStatus(installed)}${renderCatalogActions(installed, props, busy, key)}`
+          ? html`${rowStateStatus(installed)}${renderCatalogActions(installed, props, busy, key)}`
           : renderInstallButton(props, busy, key, pkg.displayName, {
               source: "clawhub",
               packageName: pkg.name,
@@ -1258,6 +1259,14 @@ function renderActivePanel(props: PluginsViewProps) {
 
 export function renderPlugins(props: PluginsViewProps) {
   const canShowCatalog = Boolean(props.result);
+  const panelState =
+    props.loading && !canShowCatalog
+      ? "loading"
+      : props.error && !canShowCatalog
+        ? "error"
+        : !props.connected && !canShowCatalog
+          ? "offline"
+          : "content";
   return renderSettingsPage(
     html`
       <div class="plugins-toolbar">
@@ -1273,6 +1282,9 @@ export function renderPlugins(props: PluginsViewProps) {
           @input=${(event: Event) =>
             props.onQueryChange((event.currentTarget as HTMLInputElement).value)}
         />
+        ${props.activeTab === "installed" && panelState === "content"
+          ? renderInstalledFilter(props)
+          : nothing}
         <button
           type="button"
           class="btn btn--sm btn--icon plugins-refresh"
@@ -1316,11 +1328,11 @@ export function renderPlugins(props: PluginsViewProps) {
         active
         aria-labelledby=${`plugins-tab-${props.activeTab}`}
       >
-        ${props.loading && !canShowCatalog
+        ${panelState === "loading"
           ? html`<div class="plugins-search-state" role="status">${t("pluginsPage.loading")}</div>`
-          : props.error && !canShowCatalog
+          : panelState === "error"
             ? nothing
-            : !props.connected && !canShowCatalog
+            : panelState === "offline"
               ? renderEmpty(t("pluginsPage.offlineTitle"), t("pluginsPage.offlineBody"))
               : renderActivePanel(props)}
       </wa-tab-panel>
diff --git a/ui/src/styles/plugins.css b/ui/src/styles/plugins.css
index befc57c78c0..302cb25d01f 100644
--- a/ui/src/styles/plugins.css
+++ b/ui/src/styles/plugins.css
@@ -15,6 +15,60 @@
   padding: var(--space-3) var(--space-4) 0;
 }
 
+/* ---------- hub tabs ---------- */
+
+/* Hub tab strips (plugins + sessions hubs) are page-level navigation, not
+   filters: quiet text tabs on a hairline track with an accent indicator, so
+   they read differently from the segmented filter pills inside the pages.
+   Track/indicator come from wa-tab-group's shadow machinery. */
+wa-tab-group.hub-tabs {
+  --track-color: color-mix(in srgb, var(--border) 60%, transparent);
+  --indicator-color: var(--accent);
+}
+
+wa-tab-group.hub-tabs::part(body) {
+  display: none;
+}
+
+wa-tab-group.hub-tabs::part(tabs) {
+  gap: var(--space-2);
+}
+
+wa-tab.hub-tab {
+  font-size: var(--control-ui-text-sm);
+  font-weight: 550;
+  color: var(--muted);
+  transition: color var(--duration-normal) var(--ease-out);
+}
+
+/* Neutralize wa-tab's stock 1em padding; keep a slim nav-tab hit area. */
+wa-tab.hub-tab::part(base) {
+  padding: var(--space-1) var(--space-2) var(--space-2);
+  gap: 6px;
+  font: inherit;
+  color: inherit;
+}
+
+wa-tab.hub-tab:hover {
+  color: var(--text);
+}
+
+wa-tab.hub-tab[active] {
+  color: var(--text-strong);
+}
+
+wa-tab.hub-tab:focus-visible {
+  outline: none;
+  border-radius: var(--radius-sm);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 22%, transparent);
+}
+
+/* Web Awesome also draws its stock focus ring on the inner base part;
+   without this reset both rings render at once. */
+wa-tab.hub-tab:focus-visible::part(base) {
+  outline: none;
+}
+
 /* ---------- toolbar ---------- */
 
 .plugins-toolbar {
@@ -113,17 +167,18 @@
 
 /* ---------- panel + notices ---------- */
 
-/* Sections inside the tabpanel keep the settings-page rhythm. */
+/* Sections inside the tabpanel keep the settings-page rhythm. wa-tab-panel's
+   shadow slot (part=base) owns the slotted children's layout, so the column
+   flex + gap must live on the part — host-level gap never reaches them. */
 .plugins-panel {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-7);
   min-width: 0;
 }
 
-/* Keep the installed-state filter shrink-to-fit inside the panel column. */
-.plugins-panel > .settings-segmented {
-  align-self: flex-start;
+.plugins-panel::part(base) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8);
+  min-width: 0;
 }
 
 .plugins-readonly {
diff --git a/ui/src/styles/settings.css b/ui/src/styles/settings.css
index a83563ae05c..36bfaaa5977 100644
--- a/ui/src/styles/settings.css
+++ b/ui/src/styles/settings.css
@@ -66,6 +66,9 @@
 
 /* ── Page ── */
 
+/* Section separation stays generous (--space-8) so group surfaces read as
+   distinct blocks; headings bind to their own group via the tighter
+   .settings-section gap. */
 .settings-page {
   width: 100%;
   max-width: 760px;
@@ -73,7 +76,7 @@
   padding: var(--space-3) var(--space-4) var(--space-8);
   display: flex;
   flex-direction: column;
-  gap: var(--space-7);
+  gap: var(--space-8);
 }
 
 /* Table/list-heavy pages (sessions, automations, plugins) need more width. */
@@ -96,26 +99,28 @@
   min-width: 0;
 }
 
+/* Header and description indent to var(--space-4) so the eyebrow label lines
+   up with the row content inside the group surface below it. */
 .settings-section__header {
   display: flex;
-  align-items: baseline;
+  align-items: center;
   justify-content: space-between;
   gap: var(--space-3);
-  padding: 0 var(--space-1);
+  padding: 0 var(--space-4);
 }
 
 .settings-section__heading {
   margin: 0;
-  font-size: var(--control-ui-text-sm);
+  font-size: var(--control-ui-text-xs);
   font-weight: 600;
-  letter-spacing: 0.02em;
+  letter-spacing: 0.06em;
   color: var(--muted-strong);
   text-transform: uppercase;
 }
 
 .settings-section__desc {
   margin: calc(-1 * var(--space-2)) 0 0;
-  padding: 0 var(--space-1);
+  padding: 0 var(--space-4);
   font-size: var(--control-ui-text-sm);
   line-height: 1.5;
   color: var(--muted);
@@ -424,12 +429,70 @@ wa-radio-group.settings-segmented::part(radios) {
   transition: border-color var(--duration-fast) var(--ease-out);
 }
 
-.settings-row:not(.settings-row--stacked) .settings-row__control > .settings-select,
-.settings-row:not(.settings-row--stacked) .settings-row__control > .settings-input {
+.settings-row:not(.settings-row--stacked) .settings-row__control > .settings-select {
   width: auto;
   min-width: min(220px, 100%);
 }
 
+/* Lone value inputs share one width so stacked rows in a group read as a
+   grid instead of ragged right-aligned fields. A percentage guard cannot work
+   here (the shrink-to-fit control resolves 100% circularly); the fixed width
+   shrinks via flex because .settings-input/.settings-secret set min-width: 0. */
+.settings-row:not(.settings-row--stacked) .settings-row__control > .settings-input,
+.settings-row:not(.settings-row--stacked) .settings-row__control > .settings-secret {
+  width: 340px;
+}
+
+/* ── Secret input (inset reveal toggle; no trailing button) ── */
+
+.settings-secret {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.settings-secret > .settings-input {
+  width: 100%;
+  padding-right: 36px;
+}
+
+.settings-secret__toggle {
+  position: absolute;
+  right: 5px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+  transition: color var(--duration-fast) var(--ease-out);
+}
+
+.settings-secret__toggle:hover {
+  color: var(--text);
+}
+
+.settings-secret__toggle:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 22%, transparent);
+}
+
+.settings-secret__toggle svg {
+  width: 16px;
+  height: 16px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2px;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
 .settings-input::placeholder {
   color: var(--muted);
 }

From 0ac69b9fe8073e65a8dbbb0587b3a26d3eb60628 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:09:22 +0100
Subject: [PATCH 40/76] fix(zalo): prevent webhook message loss after
 acknowledgment (#110630)

* fix(zalo): adopt durable ingress drain with ack gated on raw-envelope append

OA webhooks acked before detached processing behind a 5-minute in-memory
guard, and Zalo does not retry (silent loss). Raw webhook JSON now appends
durably (event_id = Bot API message.message_id, lane per chat.id) before the
200; failed appends answer 400/500 so nothing acks unpersisted. Dispatch runs
through the core drain with serialized admissions across append backoff,
deferred claims held through shutdown until adoption, retry/dead-letter
classification, and 30d/20k tombstones replacing the deleted 5min/5k guard
after its parity test. Webhook and polling transports stay mutually
exclusive; no twin scenario exists across the four received-event types.

Autoreview scanner false-positive on deleted-line token field references; full
manual review performed (ack ordering, dual-transport exclusivity, eleven-test
matrix). Part of the #109657 fleet program (wave 3).

* refactor(zalo): keep webhook runtime exports private

* test(zalo): use managed temp directories
---
 docs/channels/zalo.md                         |  15 +-
 extensions/zalo/src/monitor.lifecycle.test.ts |  50 ++-
 ...nitor.reply-once.lifecycle.test-support.ts |  11 +-
 extensions/zalo/src/monitor.ts                | 127 +++---
 extensions/zalo/src/monitor.webhook.test.ts   | 411 ++++--------------
 extensions/zalo/src/monitor.webhook.ts        | 138 ++----
 .../monitor-mocks-test-support.ts             |  42 +-
 .../zalo/src/webhook-spool.test-support.ts    |  75 ++++
 extensions/zalo/src/webhook-spool.test.ts     | 367 ++++++++++++++++
 extensions/zalo/src/webhook-spool.ts          | 364 ++++++++++++++++
 10 files changed, 1083 insertions(+), 517 deletions(-)
 create mode 100644 extensions/zalo/src/webhook-spool.test-support.ts
 create mode 100644 extensions/zalo/src/webhook-spool.test.ts
 create mode 100644 extensions/zalo/src/webhook-spool.ts

diff --git a/docs/channels/zalo.md b/docs/channels/zalo.md
index 57a1d10f21b..94c278f2b51 100644
--- a/docs/channels/zalo.md
+++ b/docs/channels/zalo.md
@@ -60,13 +60,13 @@ This page covers **Zalo Bot Creator / Marketplace bots**. **Zalo Official Accoun
 
 ## Limits
 
-| Limit                          | Value                                                                         |
-| ------------------------------ | ----------------------------------------------------------------------------- |
-| Outbound text chunk size       | 2000 characters (Zalo API limit)                                              |
-| Media size (inbound/outbound)  | `channels.zalo.mediaMaxMb`, default `5` MB                                    |
-| Webhook request body           | 1 MB, 30s read timeout                                                        |
-| Webhook rate limit             | 120 requests / 60s per path+client IP, then HTTP 429                          |
-| Webhook duplicate-event window | 5 minutes (keyed on path + account + event name + chat + sender + message id) |
+| Limit                         | Value                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------ |
+| Outbound text chunk size      | 2000 characters (Zalo API limit)                                         |
+| Media size (inbound/outbound) | `channels.zalo.mediaMaxMb`, default `5` MB                               |
+| Webhook request body          | 1 MB, 30s read timeout                                                   |
+| Webhook rate limit            | 120 requests / 60s per path+client IP, then HTTP 429                     |
+| Webhook replay tombstones     | 30 days, up to 20,000 completed events per account (keyed by message id) |
 
 ## Access control
 
@@ -97,6 +97,7 @@ Group chats are supported by the plugin (`chatTypes: ["direct", "group"]`) and g
   - Zalo sends events with an `X-Bot-Api-Secret-Token` header, checked with a constant-time comparison.
   - Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL's path).
   - Requests must use `Content-Type: application/json` (or a `+json` media type).
+  - HTTP 200 is returned only after the raw event is durably stored; storage failures return HTTP 500.
   - getUpdates polling and webhook are mutually exclusive per Zalo API docs.
 
 ## Supported message types
diff --git a/extensions/zalo/src/monitor.lifecycle.test.ts b/extensions/zalo/src/monitor.lifecycle.test.ts
index 98745ff2b44..a078b9e08f3 100644
--- a/extensions/zalo/src/monitor.lifecycle.test.ts
+++ b/extensions/zalo/src/monitor.lifecycle.test.ts
@@ -1,17 +1,26 @@
 // Zalo tests cover monitor.lifecycle plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createPluginRuntimeMock } from "openclaw/plugin-sdk/channel-test-helpers";
+import {
+  closeOpenClawStateDatabaseForTest,
+  createChannelIngressQueueForTests,
+} from "openclaw/plugin-sdk/plugin-state-test-runtime";
 import {
   createEmptyPluginRegistry,
   createRuntimeEnv,
   setActivePluginRegistry,
 } from "openclaw/plugin-sdk/plugin-test-runtime";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig } from "../runtime-api.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js";
 import type { ResolvedZaloAccount } from "./accounts.js";
 
 const getWebhookInfoMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
 const deleteWebhookMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
 const getUpdatesMock = vi.fn(() => new Promise(() => {}));
 const setWebhookMock = vi.fn(async () => ({ ok: true, result: { url: "" } }));
+const getZaloRuntimeMock = vi.hoisted(() => vi.fn());
 
 vi.mock("./api.js", async () => {
   const actual = await vi.importActual<typeof import("./api.js")>("./api.js");
@@ -25,11 +34,7 @@ vi.mock("./api.js", async () => {
 });
 
 vi.mock("./runtime.js", () => ({
-  getZaloRuntime: () => ({
-    logging: {
-      shouldLogVerbose: () => false,
-    },
-  }),
+  getZaloRuntime: getZaloRuntimeMock,
 }));
 
 const TEST_ACCOUNT = {
@@ -38,6 +43,8 @@ const TEST_ACCOUNT = {
 } as unknown as ResolvedZaloAccount;
 
 const TEST_CONFIG = {} as OpenClawConfig;
+let testStateDir: string | undefined;
+let previousStateDir: string | undefined;
 
 async function settleLifecycleWork(): Promise<void> {
   for (let i = 0; i < 6; i += 1) {
@@ -70,11 +77,37 @@ async function startLifecycleMonitor(
 }
 
 describe("monitorZaloProvider lifecycle", () => {
-  afterEach(() => {
+  beforeEach(async () => {
+    const createdDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-zalo-monitor-"));
+    testStateDir = await fs.realpath(createdDir);
+    previousStateDir = process.env.OPENCLAW_STATE_DIR;
+    process.env.OPENCLAW_STATE_DIR = testStateDir;
+    const core = createPluginRuntimeMock();
+    core.state.openChannelIngressQueue = (<T>(options: { accountId?: string }) =>
+      createChannelIngressQueueForTests<T>({
+        channelId: "zalo",
+        accountId: options.accountId ?? "default",
+        stateDir: testStateDir,
+      })) as PluginRuntime["state"]["openChannelIngressQueue"];
+    getZaloRuntimeMock.mockReturnValue(core);
+  });
+
+  afterEach(async () => {
     vi.clearAllMocks();
     getUpdatesMock.mockReset();
     getUpdatesMock.mockImplementation(() => new Promise(() => {}));
     setActivePluginRegistry(createEmptyPluginRegistry());
+    closeOpenClawStateDatabaseForTest();
+    if (testStateDir) {
+      await fs.rm(testStateDir, { recursive: true, force: true });
+      testStateDir = undefined;
+    }
+    if (previousStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousStateDir;
+      previousStateDir = undefined;
+    }
   });
 
   it("stays alive in polling mode until abort", async () => {
@@ -184,6 +217,7 @@ describe("monitorZaloProvider lifecycle", () => {
       resolveSetWebhookCalled = resolve;
     });
     setWebhookMock.mockImplementationOnce(async () => {
+      expect(registry.httpRoutes).toHaveLength(2);
       resolveSetWebhookCalled?.();
       return { ok: true, result: { url: "" } };
     });
diff --git a/extensions/zalo/src/monitor.reply-once.lifecycle.test-support.ts b/extensions/zalo/src/monitor.reply-once.lifecycle.test-support.ts
index 719e527f0f6..28a6cb8aeb8 100644
--- a/extensions/zalo/src/monitor.reply-once.lifecycle.test-support.ts
+++ b/extensions/zalo/src/monitor.reply-once.lifecycle.test-support.ts
@@ -72,7 +72,8 @@ describe("Zalo reply-once lifecycle", () => {
 
   it("routes one accepted webhook event to one visible reply across duplicate replay", async () => {
     dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(
-      async ({ dispatcherOptions }) => {
+      async ({ dispatcherOptions, replyOptions }) => {
+        await replyOptions.turnAdoptionLifecycle?.onAdopted();
         await dispatcherOptions.deliver({ text: "zalo reply once" });
       },
     );
@@ -132,8 +133,10 @@ describe("Zalo reply-once lifecycle", () => {
   it("does not emit a second visible reply when replay arrives after a post-send failure", async () => {
     let dispatchAttempts = 0;
     dispatchReplyWithBufferedBlockDispatcherMock.mockImplementation(
-      async ({ dispatcherOptions }) => {
+      async ({ dispatcherOptions, replyOptions }) => {
         dispatchAttempts += 1;
+        expect(replyOptions.turnAdoptionLifecycle).toBeDefined();
+        await replyOptions.turnAdoptionLifecycle?.onAdopted();
         await dispatcherOptions.deliver({ text: "zalo reply after failure" });
         if (dispatchAttempts === 1) {
           throw new Error("post-send failure");
@@ -173,9 +176,7 @@ describe("Zalo reply-once lifecycle", () => {
 
       expect(dispatchReplyWithBufferedBlockDispatcherMock).toHaveBeenCalledTimes(1);
       expect(sendMessageMock).toHaveBeenCalledTimes(1);
-      expect(monitor.runtime.error).toHaveBeenCalledWith(
-        "[acct-zalo-lifecycle] Zalo webhook failed: Error: post-send failure",
-      );
+      expect(monitor.runtime.error).not.toHaveBeenCalled();
     } finally {
       await monitor.stop();
     }
diff --git a/extensions/zalo/src/monitor.ts b/extensions/zalo/src/monitor.ts
index de3968b15f7..7ec040c7a32 100644
--- a/extensions/zalo/src/monitor.ts
+++ b/extensions/zalo/src/monitor.ts
@@ -8,7 +8,10 @@ import {
 import { resolveStableChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
 import type { MarkdownTableMode, OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
-import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import {
+  createLazyRuntimeModule,
+  createLazyRuntimeNamedExport,
+} from "openclaw/plugin-sdk/lazy-runtime";
 import {
   deliverTextOrMediaReply,
   resolveSendableOutboundReplyParts,
@@ -48,6 +51,7 @@ import {
 } from "./outbound-media.js";
 import { resolveZaloProxyFetch } from "./proxy.js";
 import { getZaloRuntime } from "./runtime.js";
+import type { ZaloWebhookIngressLifecycle } from "./webhook-spool.js";
 
 /** Default idle timeout for Zalo inbound photo downloads (30 seconds). */
 const ZALO_MEDIA_READ_IDLE_TIMEOUT_MS = 30_000;
@@ -88,6 +92,7 @@ type ZaloProcessingContext = {
   webhookPath?: string;
   statusSink?: ZaloStatusSink;
   fetcher?: ZaloFetch;
+  turnAdoptionLifecycle?: ZaloWebhookIngressLifecycle;
 };
 
 type ZaloPollingLoopParams = ZaloProcessingContext & {
@@ -106,7 +111,18 @@ function resolveZaloTimestampMs(date: number | undefined): number | undefined {
   return date >= UNIX_MILLISECONDS_THRESHOLD ? date : date * 1000;
 }
 
-const loadZaloWebhookModule = createLazyRuntimeModule(() => import("./monitor.webhook.js"));
+const loadZaloWebhookRuntime = createLazyRuntimeNamedExport(
+  () => import("./monitor.webhook.js"),
+  "zaloWebhookRuntime",
+);
+const loadZaloWebhookIngressRuntime = createLazyRuntimeNamedExport(
+  () => import("./webhook-spool.js"),
+  "zaloWebhookIngressRuntime",
+);
+const loadZaloWebhookModule = createLazyRuntimeModule(async () => ({
+  ...(await loadZaloWebhookRuntime()),
+  ...(await loadZaloWebhookIngressRuntime()),
+}));
 
 function releaseSharedHostedMediaRouteRef(routePath: string): void {
   const current = hostedMediaRouteRefs.get(routePath);
@@ -210,22 +226,7 @@ async function handleZaloWebhookRequest(
 ): Promise<boolean> {
   const { handleZaloWebhookRequest: handleZaloWebhookRequestInternal } =
     await loadZaloWebhookModule();
-  return await handleZaloWebhookRequestInternal(req, res, async ({ update, target }) => {
-    await processUpdate({
-      update,
-      token: target.token,
-      account: target.account,
-      config: target.config,
-      runtime: target.runtime,
-      core: target.core as ZaloCoreRuntime,
-      mediaMaxMb: target.mediaMaxMb,
-      canHostMedia: target.canHostMedia,
-      webhookUrl: target.webhookUrl,
-      webhookPath: target.webhookPath,
-      statusSink: target.statusSink,
-      fetcher: target.fetcher,
-    });
-  });
+  return await handleZaloWebhookRequestInternal(req, res);
 }
 
 function startPollingLoop(params: ZaloPollingLoopParams) {
@@ -313,6 +314,7 @@ async function processUpdate(params: ZaloUpdateProcessingParams): Promise<void>
     webhookPath: params.webhookPath,
     statusSink,
     fetcher,
+    turnAdoptionLifecycle: params.turnAdoptionLifecycle,
   };
   if (!message) {
     return undefined;
@@ -725,6 +727,9 @@ async function processMessageWithPipeline(params: ZaloMessagePipelineParams): Pr
         runtime.error?.(`zalo: failed updating session meta: ${String(err)}`);
       },
     },
+    ...(params.turnAdoptionLifecycle
+      ? { turnAdoptionLifecycle: params.turnAdoptionLifecycle }
+      : {}),
   });
 }
 
@@ -840,6 +845,7 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
 
   let stopped = false;
   const stopHandlers: Array<() => void> = [];
+  const asyncStopHandlers: Array<() => Promise<void>> = [];
   let cleanupWebhook: (() => Promise<void>) | undefined;
 
   const stop = () => {
@@ -874,7 +880,7 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
     }
 
     if (useWebhook) {
-      const { registerZaloWebhookTarget } = await loadZaloWebhookModule();
+      const { createZaloWebhookIngress, registerZaloWebhookTarget } = await loadZaloWebhookModule();
       if (!effectiveWebhookUrl || !webhookSecret) {
         throw new Error("Zalo webhookUrl and webhookSecret are required for webhook mode");
       }
@@ -893,43 +899,38 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
       runtime.log?.(
         `[${account.accountId}] Zalo configuring webhook path=${path} target=${describeWebhookTarget(effectiveWebhookUrl)}`,
       );
-      await setWebhook(token, { url: effectiveWebhookUrl, secret_token: webhookSecret }, fetcher);
-      let webhookCleanupPromise: Promise<void> | undefined;
-      cleanupWebhook = async () => {
-        if (!webhookCleanupPromise) {
-          webhookCleanupPromise = (async () => {
-            runtime.log?.(`[${account.accountId}] Zalo stopping; deleting webhook`);
-            try {
-              await deleteWebhook(token, fetcher, WEBHOOK_CLEANUP_TIMEOUT_MS);
-              runtime.log?.(`[${account.accountId}] Zalo webhook deleted`);
-            } catch (err) {
-              const detail =
-                err instanceof Error && err.name === "AbortError"
-                  ? `timed out after ${String(WEBHOOK_CLEANUP_TIMEOUT_MS)}ms`
-                  : formatZaloError(err);
-              runtime.error?.(`[${account.accountId}] Zalo webhook delete failed: ${detail}`);
-            }
-          })();
-        }
-        await webhookCleanupPromise;
-      };
-      runtime.log?.(`[${account.accountId}] Zalo webhook registered path=${path}`);
-
+      const ingress = createZaloWebhookIngress({
+        accountId: account.accountId,
+        runtime,
+        deliver: async (update, turnAdoptionLifecycle) => {
+          statusSink?.({ lastInboundAt: Date.now() });
+          await processUpdate({
+            update,
+            token,
+            account,
+            config,
+            runtime,
+            core,
+            mediaMaxMb: effectiveMediaMaxMb,
+            canHostMedia,
+            webhookUrl: effectiveWebhookUrl,
+            webhookPath: path,
+            statusSink,
+            fetcher,
+            turnAdoptionLifecycle,
+          });
+        },
+      });
+      ingress.start();
+      asyncStopHandlers.push(ingress.stop);
       const unregister = registerZaloWebhookTarget(
         {
-          token,
           account,
           config,
           runtime,
-          core,
           path,
-          webhookUrl: effectiveWebhookUrl,
-          webhookPath: path,
           secret: webhookSecret,
-          statusSink: (patch) => statusSink?.(patch),
-          mediaMaxMb: effectiveMediaMaxMb,
-          canHostMedia,
-          fetcher,
+          acceptWebhook: ingress.accept,
         },
         {
           route: {
@@ -951,6 +952,31 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
         },
       );
       stopHandlers.push(unregister);
+      await setWebhook(
+        token,
+        { url: effectiveWebhookUrl, secret_token: webhookSecret }, // pragma: allowlist secret
+        fetcher,
+      );
+      let webhookCleanupPromise: Promise<void> | undefined;
+      cleanupWebhook = async () => {
+        if (!webhookCleanupPromise) {
+          webhookCleanupPromise = (async () => {
+            runtime.log?.(`[${account.accountId}] Zalo stopping; deleting webhook`);
+            try {
+              await deleteWebhook(token, fetcher, WEBHOOK_CLEANUP_TIMEOUT_MS);
+              runtime.log?.(`[${account.accountId}] Zalo webhook deleted`);
+            } catch (err) {
+              const detail =
+                err instanceof Error && err.name === "AbortError"
+                  ? `timed out after ${String(WEBHOOK_CLEANUP_TIMEOUT_MS)}ms`
+                  : formatZaloError(err);
+              runtime.error?.(`[${account.accountId}] Zalo webhook delete failed: ${detail}`);
+            }
+          })();
+        }
+        await webhookCleanupPromise;
+      };
+      runtime.log?.(`[${account.accountId}] Zalo webhook registered path=${path}`);
       await waitForAbortSignal(abortSignal);
       return;
     }
@@ -1012,6 +1038,9 @@ export async function monitorZaloProvider(options: ZaloMonitorOptions): Promise<
     abortSignal.removeEventListener("abort", stopOnAbort);
     await cleanupWebhook?.();
     stop();
+    for (const stopAsync of asyncStopHandlers) {
+      await stopAsync();
+    }
     runtime.log?.(`[${account.accountId}] Zalo provider stopped mode=${mode}`);
   }
 }
diff --git a/extensions/zalo/src/monitor.webhook.test.ts b/extensions/zalo/src/monitor.webhook.test.ts
index addf95847f3..53d7420d84a 100644
--- a/extensions/zalo/src/monitor.webhook.test.ts
+++ b/extensions/zalo/src/monitor.webhook.test.ts
@@ -6,27 +6,19 @@ import {
 } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { withServer } from "openclaw/plugin-sdk/test-env";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js";
+import type { OpenClawConfig } from "../runtime-api.js";
 import type { ZaloRuntimeEnv } from "./monitor.types.js";
-import {
+import { zaloWebhookRuntime } from "./monitor.webhook.js";
+import type { ResolvedZaloAccount } from "./types.js";
+import { ZaloWebhookPayloadError } from "./webhook-spool.js";
+
+const {
   clearZaloWebhookSecurityStateForTest,
   getZaloWebhookRateLimitStateSizeForTest,
   getZaloWebhookStatusCounterSizeForTest,
-  handleZaloWebhookRequest as handleZaloWebhookRequestInternal,
+  handleZaloWebhookRequest: handleZaloWebhookRequestInternal,
   registerZaloWebhookTarget,
-  type ZaloWebhookProcessUpdate,
-  ZaloRetryableWebhookError,
-} from "./monitor.webhook.js";
-import { createTextUpdate, postWebhookReplay } from "./test-support/lifecycle-test-support.js";
-import type { ResolvedZaloAccount } from "./types.js";
-
-const runDetachedWebhookWork = vi.hoisted(() => vi.fn((run: () => Promise<void>) => run()));
-
-vi.mock("openclaw/plugin-sdk/webhook-request-guards", async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import("openclaw/plugin-sdk/webhook-request-guards")>();
-  return { ...actual, runDetachedWebhookWork };
-});
+} = zaloWebhookRuntime;
 
 const DEFAULT_ACCOUNT: ResolvedZaloAccount = {
   accountId: "default",
@@ -36,12 +28,10 @@ const DEFAULT_ACCOUNT: ResolvedZaloAccount = {
   config: {},
 };
 
-function createWebhookRequestHandler(
-  processUpdate: ZaloWebhookProcessUpdate = async () => {},
-): RequestListener {
+function createWebhookRequestHandler(): RequestListener {
   return (req, res) => {
     void (async () => {
-      const handled = await handleZaloWebhookRequestInternal(req, res, processUpdate);
+      const handled = await handleZaloWebhookRequestInternal(req, res);
       if (!handled) {
         res.statusCode = 404;
         res.end("not found");
@@ -58,22 +48,45 @@ function registerTarget(params: {
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
   account?: ResolvedZaloAccount;
   config?: OpenClawConfig;
-  core?: PluginRuntime;
   runtime?: Partial<ZaloRuntimeEnv>;
+  acceptWebhook?: (rawEvent: string) => Promise<void>;
 }): () => void {
   return registerZaloWebhookTarget({
-    token: "tok",
     account: params.account ?? DEFAULT_ACCOUNT,
     config: params.config ?? ({} as OpenClawConfig),
     runtime: (params.runtime ?? {}) as ZaloRuntimeEnv,
-    core: params.core ?? ({} as PluginRuntime),
     secret: params.secret ?? "secret",
     path: params.path,
-    webhookUrl: `https://example.com${params.path}`,
-    webhookPath: params.path,
-    mediaMaxMb: 5,
-    canHostMedia: true,
-    statusSink: params.statusSink,
+    acceptWebhook:
+      params.acceptWebhook ??
+      (async (rawEvent) => {
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(rawEvent);
+        } catch (error) {
+          throw new ZaloWebhookPayloadError("invalid JSON", { cause: error });
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          throw new ZaloWebhookPayloadError("payload must be an object");
+        }
+        params.statusSink?.({ lastInboundAt: Date.now() });
+      }),
+  });
+}
+
+async function postWebhook(params: {
+  baseUrl: string;
+  path: string;
+  body: string;
+  secret?: string;
+}) {
+  return await fetch(`${params.baseUrl}${params.path}`, {
+    method: "POST",
+    headers: {
+      "x-bot-api-secret-token": params.secret ?? "secret",
+      "content-type": "application/json",
+    },
+    body: params.body,
   });
 }
 
@@ -104,44 +117,6 @@ async function postUntilRateLimited(params: {
   return false;
 }
 
-async function postWebhookJson(params: {
-  baseUrl: string;
-  path: string;
-  secret: string;
-  payload: unknown;
-}) {
-  return fetch(`${params.baseUrl}${params.path}`, {
-    method: "POST",
-    headers: {
-      "x-bot-api-secret-token": params.secret,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify(params.payload),
-  });
-}
-
-async function expectTwoWebhookPostsOk(params: {
-  baseUrl: string;
-  first: { path: string; secret: string; payload: unknown };
-  second: { path: string; secret: string; payload: unknown };
-}) {
-  const first = await postWebhookJson({
-    baseUrl: params.baseUrl,
-    path: params.first.path,
-    secret: params.first.secret,
-    payload: params.first.payload,
-  });
-  const second = await postWebhookJson({
-    baseUrl: params.baseUrl,
-    path: params.second.path,
-    secret: params.second.secret,
-    payload: params.second.payload,
-  });
-
-  expect(first.status).toBe(200);
-  expect(second.status).toBe(200);
-}
-
 describe("handleZaloWebhookRequest", () => {
   afterEach(() => {
     clearZaloWebhookSecurityStateForTest();
@@ -218,308 +193,72 @@ describe("handleZaloWebhookRequest", () => {
     }
   });
 
-  it("deduplicates webhook replay for the same event origin", async () => {
-    runDetachedWebhookWork.mockClear();
-    const sink = vi.fn();
-    const unregister = registerTarget({ path: "/hook-replay", statusSink: sink });
-    const payload = createTextUpdate({
-      messageId: "msg-replay-1",
-      userId: "123",
-      userName: "",
-      chatId: "123",
-      text: "hello",
-    });
-
-    try {
-      await withServer(webhookRequestHandler, async (baseUrl) => {
-        const { first, replay } = await postWebhookReplay({
-          baseUrl,
-          path: "/hook-replay",
-          secret: "secret",
-          payload,
-        });
-
-        expect(first.status).toBe(200);
-        expect(replay.status).toBe(200);
-        expect(sink).toHaveBeenCalledTimes(1);
-        expect(runDetachedWebhookWork).toHaveBeenCalledTimes(2);
-      });
-    } finally {
-      unregister();
-    }
-  });
-
-  it("allows a retry after processUpdate throws a retryable replay error", async () => {
-    const error = vi.fn();
-    const unregister = registerTarget({
-      path: "/hook-retry-after-failure",
-      runtime: { error },
+  it("waits for durable admission before acknowledging", async () => {
+    let releaseAdmission = () => {};
+    const admission = new Promise<void>((resolve) => {
+      releaseAdmission = resolve;
     });
-    const payload = createTextUpdate({
-      messageId: "msg-retry-after-failure-1",
-      userId: "123",
-      userName: "",
-      chatId: "123",
-      text: "hello",
-    });
-    let attempts = 0;
-    const processUpdate = vi.fn<ZaloWebhookProcessUpdate>(async () => {
-      attempts += 1;
-      if (attempts === 1) {
-        throw new ZaloRetryableWebhookError("boom");
-      }
-    });
-
-    try {
-      await withServer(createWebhookRequestHandler(processUpdate), async (baseUrl) => {
-        const first = await postWebhookJson({
-          baseUrl,
-          path: "/hook-retry-after-failure",
-          secret: "secret",
-          payload,
-        });
-
-        expect(first.status).toBe(200);
-        await vi.waitFor(() => expect(error).toHaveBeenCalledTimes(1));
-
-        const second = await postWebhookJson({
-          baseUrl,
-          path: "/hook-retry-after-failure",
-          secret: "secret",
-          payload,
-        });
-
-        expect(second.status).toBe(200);
-        await vi.waitFor(() => expect(processUpdate).toHaveBeenCalledTimes(2));
-      });
-    } finally {
-      unregister();
-    }
-  });
-
-  it("keeps replay dedupe isolated per authenticated target", async () => {
-    const sinkA = vi.fn();
-    const sinkB = vi.fn();
-    const unregisterA = registerTarget({
-      path: "/hook-replay-scope",
-      secret: "secret-a",
-      statusSink: sinkA,
-    });
-    const unregisterB = registerTarget({
-      path: "/hook-replay-scope",
-      secret: "secret-b",
-      statusSink: sinkB,
-      account: {
-        ...DEFAULT_ACCOUNT,
-        accountId: "work",
-      },
-    });
-    const payload = createTextUpdate({
-      messageId: "msg-replay-scope-1",
-      userId: "123",
-      userName: "",
-      chatId: "123",
-      text: "hello",
+    const acceptWebhook = vi.fn(async () => {
+      await admission;
     });
+    const unregister = registerTarget({ path: "/hook-durable-ack", acceptWebhook });
 
     try {
       await withServer(webhookRequestHandler, async (baseUrl) => {
-        await expectTwoWebhookPostsOk({
+        let settled = false;
+        const responsePromise = postWebhook({
           baseUrl,
-          first: { path: "/hook-replay-scope", secret: "secret-a", payload },
-          second: { path: "/hook-replay-scope", secret: "secret-b", payload },
+          path: "/hook-durable-ack",
+          body: '{"event_name":"message.text.received"}',
+        }).then((response) => {
+          settled = true;
+          return response;
         });
-      });
-
-      expect(sinkA).toHaveBeenCalledTimes(1);
-      expect(sinkB).toHaveBeenCalledTimes(1);
-    } finally {
-      unregisterA();
-      unregisterB();
-    }
-  });
-
-  it("does not collide replay dedupe across different chats", async () => {
-    const sink = vi.fn();
-    const unregister = registerTarget({ path: "/hook-replay-chat-scope", statusSink: sink });
-    const firstPayload = createTextUpdate({
-      messageId: "msg-replay-chat-1",
-      userId: "123",
-      userName: "",
-      chatId: "chat-a",
-      text: "hello from a",
-    });
-    const secondPayload = createTextUpdate({
-      messageId: "msg-replay-chat-1",
-      userId: "123",
-      userName: "",
-      chatId: "chat-b",
-      text: "hello from b",
-    });
 
-    try {
-      await withServer(webhookRequestHandler, async (baseUrl) => {
-        await expectTwoWebhookPostsOk({
-          baseUrl,
-          first: { path: "/hook-replay-chat-scope", secret: "secret", payload: firstPayload },
-          second: { path: "/hook-replay-chat-scope", secret: "secret", payload: secondPayload },
-        });
+        await vi.waitFor(() => expect(acceptWebhook).toHaveBeenCalledTimes(1));
+        expect(settled).toBe(false);
+        releaseAdmission();
+        expect((await responsePromise).status).toBe(200);
       });
-
-      expect(sink).toHaveBeenCalledTimes(2);
     } finally {
+      releaseAdmission();
       unregister();
     }
   });
 
-  it("does not collide replay dedupe across different senders in the same chat", async () => {
-    const sink = vi.fn();
-    const unregister = registerTarget({ path: "/hook-replay-sender-scope", statusSink: sink });
-    const firstPayload = createTextUpdate({
-      messageId: "msg-replay-sender-1",
-      userId: "user-a",
-      userName: "",
-      chatId: "chat-shared",
-      text: "hello from user a",
-    });
-    const secondPayload = createTextUpdate({
-      messageId: "msg-replay-sender-1",
-      userId: "user-b",
-      userName: "",
-      chatId: "chat-shared",
-      text: "hello from user b",
-    });
+  it("passes the exact raw webhook JSON to durable admission", async () => {
+    const acceptWebhook = vi.fn(async () => {});
+    const unregister = registerTarget({ path: "/hook-raw", acceptWebhook });
+    const body = '{ "event_name": "message.text.received", "extra": true }';
 
     try {
       await withServer(webhookRequestHandler, async (baseUrl) => {
-        await expectTwoWebhookPostsOk({
-          baseUrl,
-          first: { path: "/hook-replay-sender-scope", secret: "secret", payload: firstPayload },
-          second: { path: "/hook-replay-sender-scope", secret: "secret", payload: secondPayload },
-        });
-      });
-
-      expect(sink).toHaveBeenCalledTimes(2);
-    } finally {
-      unregister();
-    }
-  });
-
-  it("accepts replay metadata when optional fields are missing", async () => {
-    const sink = vi.fn();
-    const unregister = registerTarget({ path: "/hook-replay-partial", statusSink: sink });
-    const payload = {
-      event_name: "message.text.received",
-      message: {
-        message_id: "msg-replay-partial-1",
-        date: Math.floor(Date.now() / 1000),
-        text: "hello",
-      },
-    };
-
-    try {
-      await withServer(webhookRequestHandler, async (baseUrl) => {
-        const response = await fetch(`${baseUrl}/hook-replay-partial`, {
-          method: "POST",
-          headers: {
-            "x-bot-api-secret-token": "secret",
-            "content-type": "application/json",
-          },
-          body: JSON.stringify(payload),
-        });
-
+        const response = await postWebhook({ baseUrl, path: "/hook-raw", body });
         expect(response.status).toBe(200);
       });
-
-      expect(sink).toHaveBeenCalledTimes(1);
+      expect(acceptWebhook).toHaveBeenCalledWith(body);
     } finally {
       unregister();
     }
   });
 
-  it("keeps replay dedupe isolated when path/account values collide under colon-joined keys", async () => {
-    const sinkA = vi.fn();
-    const sinkB = vi.fn();
-    // Old key format `${path}:${accountId}:${event_name}:${messageId}` would collide for these two targets.
-    const unregisterA = registerTarget({
-      path: "/hook-replay-collision:a",
-      secret: "secret-a",
-      statusSink: sinkA,
-      account: {
-        ...DEFAULT_ACCOUNT,
-        accountId: "team",
-      },
-    });
-    const unregisterB = registerTarget({
-      path: "/hook-replay-collision",
-      secret: "secret-b",
-      statusSink: sinkB,
-      account: {
-        ...DEFAULT_ACCOUNT,
-        accountId: "a:team",
-      },
-    });
-    const payload = createTextUpdate({
-      messageId: "msg-replay-collision-1",
-      userId: "123",
-      userName: "",
-      chatId: "123",
-      text: "hello",
+  it("does not acknowledge a durable admission failure", async () => {
+    const acceptWebhook = vi.fn(async () => {
+      throw new Error("sqlite unavailable");
     });
+    const unregister = registerTarget({ path: "/hook-append-failure", acceptWebhook });
 
     try {
       await withServer(webhookRequestHandler, async (baseUrl) => {
-        await expectTwoWebhookPostsOk({
+        const response = await postWebhook({
           baseUrl,
-          first: { path: "/hook-replay-collision:a", secret: "secret-a", payload },
-          second: { path: "/hook-replay-collision", secret: "secret-b", payload },
+          path: "/hook-append-failure",
+          body: '{"event_name":"message.text.received"}',
         });
+        expect(response.status).toBe(500);
       });
-
-      expect(sinkA).toHaveBeenCalledTimes(1);
-      expect(sinkB).toHaveBeenCalledTimes(1);
     } finally {
-      unregisterA();
-      unregisterB();
-    }
-  });
-
-  it("keeps replay dedupe isolated across different webhook paths", async () => {
-    const sinkA = vi.fn();
-    const sinkB = vi.fn();
-    const sharedSecret = "secret";
-    const unregisterA = registerTarget({
-      path: "/hook-replay-scope-a",
-      secret: sharedSecret,
-      statusSink: sinkA,
-    });
-    const unregisterB = registerTarget({
-      path: "/hook-replay-scope-b",
-      secret: sharedSecret,
-      statusSink: sinkB,
-    });
-    const payload = createTextUpdate({
-      messageId: "msg-replay-cross-path-1",
-      userId: "123",
-      userName: "",
-      chatId: "123",
-      text: "hello",
-    });
-
-    try {
-      await withServer(webhookRequestHandler, async (baseUrl) => {
-        await expectTwoWebhookPostsOk({
-          baseUrl,
-          first: { path: "/hook-replay-scope-a", secret: sharedSecret, payload },
-          second: { path: "/hook-replay-scope-b", secret: sharedSecret, payload },
-        });
-      });
-
-      expect(sinkA).toHaveBeenCalledTimes(1);
-      expect(sinkB).toHaveBeenCalledTimes(1);
-    } finally {
-      unregisterA();
-      unregisterB();
+      unregister();
     }
   });
 
diff --git a/extensions/zalo/src/monitor.webhook.ts b/extensions/zalo/src/monitor.webhook.ts
index d090ac41b79..e7ad4c93767 100644
--- a/extensions/zalo/src/monitor.webhook.ts
+++ b/extensions/zalo/src/monitor.webhook.ts
@@ -1,15 +1,12 @@
 // Zalo plugin module implements monitor.webhook behavior.
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { createChannelReplayGuard } from "openclaw/plugin-sdk/persistent-dedupe";
 import { safeEqualSecret } from "openclaw/plugin-sdk/security-runtime";
-import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";
+import { readWebhookBodyOrReject } from "openclaw/plugin-sdk/webhook-request-guards";
 import type { ResolvedZaloAccount } from "./accounts.js";
-import type { ZaloFetch, ZaloUpdate } from "./api.js";
 import type { ZaloRuntimeEnv } from "./monitor.types.js";
 import {
   createFixedWindowRateLimiter,
   createWebhookAnomalyTracker,
-  readJsonWebhookBodyOrReject,
   applyBasicWebhookRequestGuards,
   registerWebhookTargetWithPluginRoute,
   type RegisterWebhookTargetOptions,
@@ -22,30 +19,17 @@ import {
   resolveClientIp,
   type OpenClawConfig,
 } from "./runtime-api.js";
-
-const ZALO_WEBHOOK_REPLAY_WINDOW_MS = 5 * 60_000;
+import { ZaloWebhookPayloadError } from "./webhook-spool.js";
 
 type ZaloWebhookTarget = {
-  token: string;
   account: ResolvedZaloAccount;
   config: OpenClawConfig;
   runtime: ZaloRuntimeEnv;
-  core: unknown;
   secret: string;
   path: string;
-  webhookUrl: string;
-  webhookPath: string;
-  mediaMaxMb: number;
-  canHostMedia: boolean;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-  fetcher?: ZaloFetch;
+  acceptWebhook: (rawEvent: string) => Promise<void>;
 };
 
-export type ZaloWebhookProcessUpdate = (params: {
-  update: ZaloUpdate;
-  target: ZaloWebhookTarget;
-}) => Promise<void>;
-
 const webhookTargets = new Map<string, ZaloWebhookTarget[]>();
 const webhookRateLimiter = createFixedWindowRateLimiter({
   windowMs: WEBHOOK_RATE_LIMIT_DEFAULTS.windowMs,
@@ -58,76 +42,19 @@ const webhookAnomalyTracker = createWebhookAnomalyTracker({
   logEvery: WEBHOOK_ANOMALY_COUNTER_DEFAULTS.logEvery,
 });
 
-export function clearZaloWebhookSecurityStateForTest(): void {
+function clearZaloWebhookSecurityStateForTest(): void {
   webhookRateLimiter.clear();
-  recentWebhookEvents.clearMemory();
   webhookAnomalyTracker.clear();
 }
 
-export function getZaloWebhookRateLimitStateSizeForTest(): number {
+function getZaloWebhookRateLimitStateSizeForTest(): number {
   return webhookRateLimiter.size();
 }
 
-export function getZaloWebhookStatusCounterSizeForTest(): number {
+function getZaloWebhookStatusCounterSizeForTest(): number {
   return webhookAnomalyTracker.size();
 }
 
-function buildReplayEventCacheKey(target: ZaloWebhookTarget, update: ZaloUpdate): string | null {
-  const messageId = update.message?.message_id;
-  if (!messageId) {
-    return null;
-  }
-  const chatId = update.message?.chat?.id ?? "";
-  const senderId = update.message?.from?.id ?? "";
-  return JSON.stringify([
-    target.path,
-    target.account.accountId,
-    update.event_name,
-    chatId,
-    senderId,
-    messageId,
-  ]);
-}
-
-const recentWebhookEvents = createChannelReplayGuard<{
-  target: ZaloWebhookTarget;
-  update: ZaloUpdate;
-}>({
-  dedupe: {
-    ttlMs: ZALO_WEBHOOK_REPLAY_WINDOW_MS,
-    memoryMaxSize: 5000,
-  },
-  buildReplayKey: ({ target, update }) => buildReplayEventCacheKey(target, update),
-});
-
-export class ZaloRetryableWebhookError extends Error {
-  constructor(message: string, options?: ErrorOptions) {
-    super(message, options);
-    this.name = "ZaloRetryableWebhookError";
-  }
-}
-
-async function processZaloReplayGuardedUpdate(params: {
-  target: ZaloWebhookTarget;
-  update: ZaloUpdate;
-  processUpdate: ZaloWebhookProcessUpdate;
-  nowMs?: number;
-}): Promise<"processed" | "duplicate"> {
-  const event = { target: params.target, update: params.update };
-  const result = await recentWebhookEvents.processGuarded(
-    event,
-    async () => {
-      params.target.statusSink?.({ lastInboundAt: Date.now() });
-      await params.processUpdate(event);
-    },
-    {
-      dedupe: { now: params.nowMs },
-      onError: (error) => (error instanceof ZaloRetryableWebhookError ? "release" : "commit"),
-    },
-  );
-  return result.kind === "processed" ? "processed" : "duplicate";
-}
-
 function recordWebhookStatus(
   runtime: ZaloRuntimeEnv | undefined,
   path: string,
@@ -146,7 +73,7 @@ function headerValue(value: string | string[] | undefined): string | undefined {
   return Array.isArray(value) ? value[0] : value;
 }
 
-export function registerZaloWebhookTarget(
+function registerZaloWebhookTarget(
   target: ZaloWebhookTarget,
   opts?: {
     route?: RegisterWebhookPluginRouteOptions;
@@ -166,10 +93,9 @@ export function registerZaloWebhookTarget(
   return registerWebhookTarget(webhookTargets, target, opts).unregister;
 }
 
-export async function handleZaloWebhookRequest(
+async function handleZaloWebhookRequest(
   req: IncomingMessage,
   res: ServerResponse,
-  processUpdate: ZaloWebhookProcessUpdate,
 ): Promise<boolean> {
   return await withResolvedWebhookRequestPipeline({
     req,
@@ -226,50 +152,42 @@ export async function handleZaloWebhookRequest(
         recordWebhookStatus(target.runtime, path, res.statusCode);
         return true;
       }
-      const body = await readJsonWebhookBodyOrReject({
+      const body = await readWebhookBodyOrReject({
         req,
         res,
         maxBytes: 1024 * 1024,
         timeoutMs: 30_000,
-        emptyObjectOnEmpty: false,
-        invalidJsonMessage: "Bad Request",
+        invalidBodyMessage: "Bad Request",
       });
       if (!body.ok) {
         recordWebhookStatus(target.runtime, path, res.statusCode);
         return true;
       }
-      const raw = body.value;
-
-      // Zalo sends updates directly as { event_name, message, ... }, not wrapped in { ok, result }.
-      const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
-      const update: ZaloUpdate | undefined =
-        record && record.ok === true && record.result
-          ? (record.result as ZaloUpdate)
-          : ((record as ZaloUpdate | null) ?? undefined);
-
-      if (!update?.event_name) {
-        res.statusCode = 400;
-        res.end("Bad Request");
+      try {
+        // Ack only after the raw envelope is durably appended. The spool reserves
+        // detached drain work before this request's admission root is released.
+        await target.acceptWebhook(body.value);
+      } catch (error) {
+        res.statusCode = error instanceof ZaloWebhookPayloadError ? 400 : 500;
+        res.end(res.statusCode === 400 ? "Bad Request" : "Internal Server Error");
         recordWebhookStatus(target.runtime, path, res.statusCode);
+        target.runtime.error?.(
+          `[${target.account.accountId}] Zalo webhook admission failed: ${String(error)}`,
+        );
         return true;
       }
 
-      // Reserve the detached task before the HTTP admission is released;
-      // otherwise later queue work inherits a released admission root.
-      void runDetachedWebhookWork(() =>
-        processZaloReplayGuardedUpdate({
-          target,
-          update,
-          processUpdate,
-          nowMs,
-        }),
-      ).catch((err: unknown) => {
-        target.runtime.error?.(`[${target.account.accountId}] Zalo webhook failed: ${String(err)}`);
-      });
-
       res.statusCode = 200;
       res.end("ok");
       return true;
     },
   });
 }
+
+export const zaloWebhookRuntime = {
+  clearZaloWebhookSecurityStateForTest,
+  getZaloWebhookRateLimitStateSizeForTest,
+  getZaloWebhookStatusCounterSizeForTest,
+  handleZaloWebhookRequest,
+  registerZaloWebhookTarget,
+};
diff --git a/extensions/zalo/src/test-support/monitor-mocks-test-support.ts b/extensions/zalo/src/test-support/monitor-mocks-test-support.ts
index 17859ff8c65..7529f3b18ab 100644
--- a/extensions/zalo/src/test-support/monitor-mocks-test-support.ts
+++ b/extensions/zalo/src/test-support/monitor-mocks-test-support.ts
@@ -1,13 +1,20 @@
 // Zalo plugin module implements monitor mocks test support behavior.
+import fs from "node:fs/promises";
+import path from "node:path";
 import { createPluginRuntimeMock } from "openclaw/plugin-sdk/channel-test-helpers";
 import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
+import {
+  closeOpenClawStateDatabaseForTest,
+  createChannelIngressQueueForTests,
+} from "openclaw/plugin-sdk/plugin-state-test-runtime";
 import {
   createEmptyPluginRegistry,
   createRuntimeEnv,
   setActivePluginRegistry,
 } from "openclaw/plugin-sdk/plugin-test-runtime";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
 import { vi, type Mock } from "vitest";
-import type { OpenClawConfig } from "../runtime-api.js";
+import type { OpenClawConfig, PluginRuntime } from "../runtime-api.js";
 import type { ResolvedZaloAccount } from "../types.js";
 
 type MonitorModule = typeof import("../monitor.js");
@@ -23,6 +30,8 @@ const runtimeModuleId = new URL("../runtime.js", import.meta.url).pathname;
 type UnknownMock = Mock<(...args: unknown[]) => unknown>;
 type AsyncUnknownMock = Mock<(...args: unknown[]) => Promise<unknown>>;
 const cachedMonitorModules = new Map<string, Promise<MonitorModule>>();
+let lifecycleStateDir: string | undefined;
+let previousLifecycleStateDir: string | undefined;
 
 type ZaloLifecycleMocks = {
   setWebhookMock: AsyncUnknownMock;
@@ -105,11 +114,39 @@ const importCachedWebhookModule = createLazyRuntimeModule(
 );
 
 export async function resetLifecycleTestState() {
+  closeOpenClawStateDatabaseForTest();
+  if (lifecycleStateDir) {
+    await fs.rm(lifecycleStateDir, { recursive: true, force: true });
+    lifecycleStateDir = undefined;
+  }
+  if (previousLifecycleStateDir === undefined) {
+    delete process.env.OPENCLAW_STATE_DIR;
+  } else {
+    process.env.OPENCLAW_STATE_DIR = previousLifecycleStateDir;
+    previousLifecycleStateDir = undefined;
+  }
   vi.clearAllMocks();
-  (await importCachedWebhookModule()).clearZaloWebhookSecurityStateForTest();
+  (await importCachedWebhookModule()).zaloWebhookRuntime.clearZaloWebhookSecurityStateForTest();
   setActivePluginRegistry(createEmptyPluginRegistry());
 }
 
+async function installLifecycleWebhookIngressState(): Promise<void> {
+  const runtime = getZaloRuntimeMock() as PluginRuntime;
+  const createdDir = await fs.mkdtemp(
+    path.join(resolvePreferredOpenClawTmpDir(), "openclaw-zalo-lifecycle-"),
+  );
+  const stateDir = await fs.realpath(createdDir);
+  previousLifecycleStateDir = process.env.OPENCLAW_STATE_DIR;
+  lifecycleStateDir = stateDir;
+  process.env.OPENCLAW_STATE_DIR = stateDir;
+  runtime.state.openChannelIngressQueue = (<T>(options: { accountId?: string }) =>
+    createChannelIngressQueueForTests<T>({
+      channelId: "zalo",
+      accountId: options.accountId ?? "default",
+      stateDir,
+    })) as PluginRuntime["state"]["openChannelIngressQueue"];
+}
+
 export function setLifecycleRuntimeCore(
   channel: NonNullable<NonNullable<Parameters<typeof createPluginRuntimeMock>[0]>["channel"]>,
   state?: NonNullable<Parameters<typeof createPluginRuntimeMock>[0]>["state"],
@@ -150,6 +187,7 @@ export async function startWebhookLifecycleMonitor(params: {
   webhookSecret?: string;
   cacheKey?: string;
 }) {
+  await installLifecycleWebhookIngressState();
   const registry = createEmptyPluginRegistry();
   setActivePluginRegistry(registry);
   const abort = new AbortController();
diff --git a/extensions/zalo/src/webhook-spool.test-support.ts b/extensions/zalo/src/webhook-spool.test-support.ts
new file mode 100644
index 00000000000..4686ecb0a02
--- /dev/null
+++ b/extensions/zalo/src/webhook-spool.test-support.ts
@@ -0,0 +1,75 @@
+// Zalo tests share isolated durable-ingress state and Bot API envelopes.
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  closeOpenClawStateDatabaseForTest,
+  createChannelIngressQueueForTests,
+} from "openclaw/plugin-sdk/plugin-state-test-runtime";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
+import { expect, vi } from "vitest";
+import type { zaloWebhookIngressRuntime } from "./webhook-spool.js";
+
+type CreateZaloWebhookIngress = (typeof zaloWebhookIngressRuntime)["createZaloWebhookIngress"];
+
+type ZaloWebhookTestQueue = NonNullable<Parameters<CreateZaloWebhookIngress>[0]["queue"]>;
+export type ZaloWebhookTestPayload = Parameters<ZaloWebhookTestQueue["enqueue"]>[1];
+
+export function createZaloWebhookTestEvent(params?: {
+  messageId?: string;
+  userId?: string;
+  chatId?: string;
+  text?: string;
+  date?: number;
+}) {
+  return {
+    event_name: "message.text.received" as const,
+    message: {
+      message_id: params?.messageId ?? "message-1",
+      from: { id: params?.userId ?? "user-1", name: "Test User" },
+      chat: { id: params?.chatId ?? "chat-1", chat_type: "PRIVATE" as const },
+      date: params?.date ?? Date.now(),
+      text: params?.text ?? "hello",
+    },
+  };
+}
+
+export async function withZaloWebhookTestQueue<T>(
+  fn: (queue: ZaloWebhookTestQueue) => Promise<T>,
+): Promise<T> {
+  const createdDir = await fs.mkdtemp(
+    path.join(resolvePreferredOpenClawTmpDir(), "openclaw-zalo-ingress-"),
+  );
+  const stateDir = await fs.realpath(createdDir);
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  process.env.OPENCLAW_STATE_DIR = stateDir;
+  const queue = createChannelIngressQueueForTests<ZaloWebhookTestPayload>({
+    channelId: "zalo",
+    accountId: "default",
+    stateDir,
+  });
+  try {
+    return await fn(queue);
+  } finally {
+    if (previousStateDir === undefined) {
+      delete process.env.OPENCLAW_STATE_DIR;
+    } else {
+      process.env.OPENCLAW_STATE_DIR = previousStateDir;
+    }
+    closeOpenClawStateDatabaseForTest();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+export async function waitForZaloWebhookVerdict(
+  queue: ZaloWebhookTestQueue,
+  eventId: string,
+  expected: "completed" | "failed",
+): Promise<void> {
+  await vi.waitFor(
+    async () => {
+      const verdict = await queue.enqueue(eventId, { version: 1, rawEvent: "{}" });
+      expect(verdict.kind).toBe(expected);
+    },
+    { timeout: 5_000 },
+  );
+}
diff --git a/extensions/zalo/src/webhook-spool.test.ts b/extensions/zalo/src/webhook-spool.test.ts
new file mode 100644
index 00000000000..9f16c3128f2
--- /dev/null
+++ b/extensions/zalo/src/webhook-spool.test.ts
@@ -0,0 +1,367 @@
+// Zalo tests cover durable webhook admission, replay, recovery, and failure taxonomy.
+import type { ChannelIngressQueue } from "openclaw/plugin-sdk/channel-outbound";
+import { closeOpenClawStateDatabaseForTest } from "openclaw/plugin-sdk/plugin-state-test-runtime";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { zaloWebhookIngressRuntime } from "./webhook-spool.js";
+import {
+  createZaloWebhookTestEvent,
+  waitForZaloWebhookVerdict,
+  withZaloWebhookTestQueue,
+  type ZaloWebhookTestPayload,
+} from "./webhook-spool.test-support.js";
+
+const { createZaloWebhookIngress } = zaloWebhookIngressRuntime;
+
+function runtime() {
+  return { error: vi.fn(), log: vi.fn() };
+}
+
+function rawEvent(params?: Parameters<typeof createZaloWebhookTestEvent>[0]): string {
+  return JSON.stringify(createZaloWebhookTestEvent(params));
+}
+
+afterEach(() => {
+  closeOpenClawStateDatabaseForTest();
+  vi.restoreAllMocks();
+});
+
+describe("Zalo durable webhook ingress", () => {
+  it("serializes concurrent admissions across append backoff", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const realEnqueue = queue.enqueue.bind(queue);
+      const admissionOrder: string[] = [];
+      let failedFirstAttempt = false;
+      const enqueue: typeof queue.enqueue = async (...args) => {
+        admissionOrder.push(args[0]);
+        if (!failedFirstAttempt) {
+          failedFirstAttempt = true;
+          throw new Error("sqlite busy");
+        }
+        return await realEnqueue(...args);
+      };
+      const serializedQueue: ChannelIngressQueue<ZaloWebhookTestPayload> = {
+        ...queue,
+        enqueue,
+      };
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue: serializedQueue,
+        deliver: vi.fn(),
+      });
+
+      await Promise.all([
+        ingress.accept(rawEvent({ messageId: "admission-a", chatId: "same-chat" })),
+        ingress.accept(rawEvent({ messageId: "admission-b", chatId: "same-chat" })),
+      ]);
+
+      expect(admissionOrder).toEqual(["admission-a", "admission-a", "admission-b"]);
+      expect((await queue.listPending({ limit: "all" })).map((entry) => entry.id)).toEqual([
+        "admission-a",
+        "admission-b",
+      ]);
+      await ingress.stop();
+    });
+  });
+
+  it("retries a failed append before acknowledging and fails closed after the bound", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const enqueue = vi.fn(async () => {
+        throw new Error("sqlite unavailable");
+      });
+      const failingQueue: ChannelIngressQueue<ZaloWebhookTestPayload> = { ...queue, enqueue };
+      const deliver = vi.fn(async () => {});
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue: failingQueue,
+        deliver,
+      });
+
+      await expect(ingress.accept(rawEvent({ messageId: "append-failure" }))).rejects.toThrow(
+        "sqlite unavailable",
+      );
+      expect(enqueue).toHaveBeenCalledTimes(3);
+      expect(deliver).not.toHaveBeenCalled();
+      await ingress.stop();
+    });
+  });
+
+  it("recovers an uncompleted event with a fresh drain and dispatches exactly once", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const interrupted = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver: vi.fn(),
+      });
+      await interrupted.accept(rawEvent({ messageId: "restart" }));
+      await interrupted.stop();
+
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        await lifecycle.onAdopted();
+      });
+      const recovered = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      recovered.start();
+      try {
+        await waitForZaloWebhookVerdict(queue, "restart", "completed");
+        expect(deliver).toHaveBeenCalledTimes(1);
+      } finally {
+        await recovered.stop();
+      }
+    });
+  });
+
+  it("keeps a completion tombstone and rejects a post-completion duplicate", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        await lifecycle.onAdopted();
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      const raw = rawEvent({ messageId: "duplicate" });
+      ingress.start();
+      try {
+        await ingress.accept(raw);
+        await waitForZaloWebhookVerdict(queue, "duplicate", "completed");
+        await ingress.accept(raw);
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 600);
+        });
+        expect(deliver).toHaveBeenCalledTimes(1);
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("preserves old replay-guard parity for the same message id with changed payload bytes", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        await lifecycle.onAdopted();
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      try {
+        await ingress.accept(rawEvent({ messageId: "redelivery", text: "original", date: 1 }));
+        await waitForZaloWebhookVerdict(queue, "redelivery", "completed");
+        await ingress.accept(
+          rawEvent({ messageId: "redelivery", text: "transport redelivery", date: 2 }),
+        );
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 600);
+        });
+        expect(deliver).toHaveBeenCalledTimes(1);
+        expect(deliver.mock.calls[0]?.[0].message?.text).toBe("original");
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("stores raw JSON and derives the conversation lane before dispatch normalization", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const event = createZaloWebhookTestEvent({
+        messageId: "raw",
+        chatId: "conversation-42",
+        text: "before",
+      });
+      const deliveredText: string[] = [];
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver: async (update, lifecycle) => {
+          deliveredText.push(update.message?.text ?? "");
+          await lifecycle.onAdopted();
+        },
+      });
+      const raw = JSON.stringify(event);
+      await ingress.accept(raw);
+      expect(await queue.listPending()).toEqual([
+        expect.objectContaining({
+          id: "raw",
+          laneKey: "chat:conversation-42",
+          payload: { version: 1, rawEvent: raw },
+        }),
+      ]);
+      event.message.text = "after";
+
+      ingress.start();
+      try {
+        await waitForZaloWebhookVerdict(queue, "raw", "completed");
+        expect(deliveredText).toEqual(["before"]);
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("dead-letters malformed persisted JSON without dispatch", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      await queue.enqueue(
+        "malformed",
+        { version: 1, rawEvent: "{" },
+        { laneKey: "chat:conversation-1" },
+      );
+      const deliver = vi.fn(async () => {});
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      try {
+        await waitForZaloWebhookVerdict(queue, "malformed", "failed");
+        expect(deliver).not.toHaveBeenCalled();
+        const verdict = await queue.enqueue("malformed", { version: 1, rawEvent: "{}" });
+        expect(verdict.kind).toBe("failed");
+        if (verdict.kind === "failed") {
+          expect(verdict.record.reason).toBe("invalid-event");
+        }
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("retries transient dispatch failures", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        if (deliver.mock.calls.length === 1) {
+          throw new Error("temporary dispatch outage");
+        }
+        await lifecycle.onAdopted();
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      try {
+        await ingress.accept(rawEvent({ messageId: "retry" }));
+        await waitForZaloWebhookVerdict(queue, "retry", "completed");
+        expect(deliver).toHaveBeenCalledTimes(2);
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("dead-letters authentication failures without retry", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      const deliver = vi.fn(async () => {
+        throw Object.assign(new Error("invalid Zalo token"), { statusCode: 401 });
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      try {
+        await ingress.accept(rawEvent({ messageId: "auth-failure" }));
+        await waitForZaloWebhookVerdict(queue, "auth-failure", "failed");
+        expect(deliver).toHaveBeenCalledTimes(1);
+        const verdict = await queue.enqueue("auth-failure", { version: 1, rawEvent: "{}" });
+        expect(verdict.kind).toBe("failed");
+        if (verdict.kind === "failed") {
+          expect(verdict.record.reason).toBe("authentication-failed");
+        }
+      } finally {
+        await ingress.stop();
+      }
+    });
+  });
+
+  it("waits for an active delivery before shutdown returns", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      let releaseDelivery = () => {};
+      const deliveryGate = new Promise<void>((resolve) => {
+        releaseDelivery = resolve;
+      });
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        await lifecycle.onAdopted();
+        await deliveryGate;
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      await ingress.accept(rawEvent({ messageId: "active-stop" }));
+      await vi.waitFor(() => expect(deliver).toHaveBeenCalledTimes(1));
+
+      let stopped = false;
+      const stopping = ingress.stop().then(() => {
+        stopped = true;
+      });
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 50);
+      });
+      expect(stopped).toBe(false);
+      releaseDelivery();
+      await stopping;
+      expect(stopped).toBe(true);
+    });
+  });
+
+  it("holds a deferred claim through shutdown until adoption settles", async () => {
+    await withZaloWebhookTestQueue(async (queue) => {
+      let deferredLifecycle:
+        | Parameters<Parameters<typeof createZaloWebhookIngress>[0]["deliver"]>[1]
+        | undefined;
+      const deliver = vi.fn(async (_update, lifecycle) => {
+        deferredLifecycle = lifecycle;
+        lifecycle.onDeferred();
+      });
+      const ingress = createZaloWebhookIngress({
+        accountId: "default",
+        runtime: runtime(),
+        queue,
+        deliver,
+      });
+      ingress.start();
+      await ingress.accept(rawEvent({ messageId: "deferred-stop" }));
+      await vi.waitFor(() => expect(deliver).toHaveBeenCalledTimes(1));
+      expect(await queue.listClaims()).toHaveLength(1);
+
+      let stopped = false;
+      const stopping = ingress.stop().then(() => {
+        stopped = true;
+      });
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, 50);
+      });
+      expect(stopped).toBe(false);
+      if (!deferredLifecycle) {
+        throw new Error("Zalo delivery did not expose its deferred lifecycle");
+      }
+      await deferredLifecycle.onAdopted();
+      await stopping;
+      expect(stopped).toBe(true);
+      const verdict = await queue.enqueue("deferred-stop", { version: 1, rawEvent: "{}" });
+      expect(verdict.kind).toBe("completed");
+    });
+  });
+});
diff --git a/extensions/zalo/src/webhook-spool.ts b/extensions/zalo/src/webhook-spool.ts
new file mode 100644
index 00000000000..b844242d5fd
--- /dev/null
+++ b/extensions/zalo/src/webhook-spool.ts
@@ -0,0 +1,364 @@
+// Zalo plugin owns raw webhook durable admission and replay draining.
+import {
+  bindIngressLifecycleToReplyOptions,
+  createChannelIngressDrain,
+  DEFAULT_INGRESS_ADOPTION_STALL_MS,
+  DEFAULT_INGRESS_RETRY_MAX_ATTEMPTS,
+  type ChannelIngressQueue,
+} from "openclaw/plugin-sdk/channel-outbound";
+import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";
+import { ZaloApiError, type ZaloUpdate } from "./api.js";
+import type { ZaloRuntimeEnv } from "./monitor.types.js";
+import { getZaloRuntime } from "./runtime.js";
+
+const ZALO_WEBHOOK_SPOOL_VERSION = 1;
+const ZALO_WEBHOOK_DRAIN_INTERVAL_MS = 500;
+const ZALO_WEBHOOK_MAX_CONCURRENT_DELIVERIES = 8;
+const ZALO_WEBHOOK_PRUNE_INTERVAL_MS = 60 * 60 * 1_000;
+// Durable tombstones dominate the retired 5-minute / 5,000-key replay cache.
+const ZALO_WEBHOOK_COMPLETED_TTL_MS = 30 * 24 * 60 * 60_000;
+const ZALO_WEBHOOK_COMPLETED_MAX_ENTRIES = 20_000;
+const ZALO_WEBHOOK_FAILED_TTL_MS = 30 * 24 * 60 * 60_000;
+const ZALO_WEBHOOK_FAILED_MAX_ENTRIES = 5_000;
+const ZALO_WEBHOOK_APPEND_RETRY_DELAYS_MS = [0, 100, 300] as const;
+
+type ZaloWebhookSpoolPayload = {
+  version: 1;
+  rawEvent: string;
+};
+
+export type ZaloWebhookIngressLifecycle = ReturnType<
+  typeof bindIngressLifecycleToReplyOptions
+>["turnAdoptionLifecycle"];
+
+export class ZaloWebhookPayloadError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ZaloWebhookPayloadError";
+  }
+}
+
+type ZaloWebhookIngress = {
+  accept: (rawEvent: string) => Promise<void>;
+  start: () => void;
+  stop: () => Promise<void>;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function parseRawRecord(rawEvent: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawEvent);
+  } catch (error) {
+    throw new ZaloWebhookPayloadError("Zalo webhook body contains invalid JSON.", { cause: error });
+  }
+  if (!isRecord(parsed)) {
+    throw new ZaloWebhookPayloadError("Zalo webhook body must be a JSON object.");
+  }
+  return parsed;
+}
+
+function resolveUpdateRecord(envelope: Record<string, unknown>): Record<string, unknown> {
+  // Preserve the accepted direct and legacy { ok, result } envelope shapes.
+  if (envelope.ok === true && isRecord(envelope.result)) {
+    return envelope.result;
+  }
+  return envelope;
+}
+
+function inspectZaloWebhookEvent(rawEvent: string): {
+  eventId: string;
+  laneKey: string;
+  update: Record<string, unknown>;
+} {
+  const update = resolveUpdateRecord(parseRawRecord(rawEvent));
+  const message = isRecord(update.message) ? update.message : null;
+  const eventId = nonEmptyString(message?.message_id);
+  if (!eventId) {
+    throw new ZaloWebhookPayloadError("Zalo webhook message is missing message.message_id.");
+  }
+  const chat = isRecord(message?.chat) ? message.chat : null;
+  const chatId = nonEmptyString(chat?.id);
+  if (!chatId) {
+    throw new ZaloWebhookPayloadError("Zalo webhook message is missing message.chat.id.");
+  }
+  return { eventId, laneKey: `chat:${chatId}`, update };
+}
+
+function parseClaimedUpdate(payload: ZaloWebhookSpoolPayload, claimedId: string): ZaloUpdate {
+  if (payload.version !== ZALO_WEBHOOK_SPOOL_VERSION || typeof payload.rawEvent !== "string") {
+    throw new ZaloWebhookPayloadError("Zalo webhook spool payload is invalid.");
+  }
+  const facts = inspectZaloWebhookEvent(payload.rawEvent);
+  if (facts.eventId !== claimedId) {
+    throw new ZaloWebhookPayloadError("Zalo webhook message id changed after durable admission.");
+  }
+  const eventName = nonEmptyString(facts.update.event_name);
+  if (
+    eventName !== "message.text.received" &&
+    eventName !== "message.image.received" &&
+    eventName !== "message.sticker.received" &&
+    eventName !== "message.unsupported.received"
+  ) {
+    throw new ZaloWebhookPayloadError("Zalo webhook event_name is unsupported.");
+  }
+  const message = facts.update.message as Record<string, unknown>;
+  const from = isRecord(message.from) ? message.from : null;
+  const chat = isRecord(message.chat) ? message.chat : null;
+  if (!nonEmptyString(from?.id)) {
+    throw new ZaloWebhookPayloadError("Zalo webhook message is missing message.from.id.");
+  }
+  if (chat?.chat_type !== "PRIVATE" && chat?.chat_type !== "GROUP") {
+    throw new ZaloWebhookPayloadError("Zalo webhook message has an invalid chat type.");
+  }
+  if (typeof message.date !== "number" || !Number.isFinite(message.date)) {
+    throw new ZaloWebhookPayloadError("Zalo webhook message has an invalid date.");
+  }
+  if (eventName === "message.text.received" && typeof message.text !== "string") {
+    throw new ZaloWebhookPayloadError("Zalo text event is missing message.text.");
+  }
+  return facts.update as unknown as ZaloUpdate;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isZaloAuthenticationFailure(error: unknown): boolean {
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const candidate = current as {
+      cause?: unknown;
+      errorCode?: unknown;
+      status?: unknown;
+      statusCode?: unknown;
+    };
+    if (
+      (current instanceof ZaloApiError &&
+        (current.errorCode === 401 || current.errorCode === 403)) ||
+      candidate.status === 401 ||
+      candidate.status === 403 ||
+      candidate.statusCode === 401 ||
+      candidate.statusCode === 403
+    ) {
+      return true;
+    }
+    current = candidate.cause;
+  }
+  return false;
+}
+
+function createZaloWebhookIngress(options: {
+  accountId: string;
+  runtime: Pick<ZaloRuntimeEnv, "error" | "log">;
+  deliver: (update: ZaloUpdate, lifecycle: ZaloWebhookIngressLifecycle) => Promise<void>;
+  queue?: ChannelIngressQueue<ZaloWebhookSpoolPayload>;
+}): ZaloWebhookIngress {
+  const queue =
+    options.queue ??
+    getZaloRuntime().state.openChannelIngressQueue<ZaloWebhookSpoolPayload>({
+      accountId: options.accountId,
+    });
+  let running = false;
+  let stopped = false;
+  let drainRequested = false;
+  let drainTask: Promise<void> | undefined;
+  let drainTimer: ReturnType<typeof setInterval> | undefined;
+  let lastPrunedAt = 0;
+  let admissionTail: Promise<void> = Promise.resolve();
+  const activeDeliveries = new Set<Promise<void>>();
+  const deferredClaims = new Map<string, Promise<void>>();
+
+  const drain = createChannelIngressDrain<ZaloWebhookSpoolPayload>({
+    queue,
+    adoptionStallTimeoutMs: DEFAULT_INGRESS_ADOPTION_STALL_MS,
+    startLimit: ZALO_WEBHOOK_MAX_CONCURRENT_DELIVERIES,
+    retryPolicy: {
+      maxAttempts: DEFAULT_INGRESS_RETRY_MAX_ATTEMPTS,
+      deadLetterMinAgeMs: 0,
+    },
+    resolveNonRetryableFailure: (error) => {
+      if (error instanceof ZaloWebhookPayloadError) {
+        return { reason: "invalid-event", message: error.message };
+      }
+      if (isZaloAuthenticationFailure(error)) {
+        return { reason: "authentication-failed", message: errorText(error) };
+      }
+      return null;
+    },
+    onLog: (message) => options.runtime.error?.(`zalo ingress: ${message}`),
+    dispatchClaimedEvent: async (claimed, lifecycle) => {
+      if (!running || lifecycle.abortSignal.aborted) {
+        return { kind: "failed-retryable", error: new Error("Zalo ingress stopped.") };
+      }
+      const update = parseClaimedUpdate(claimed.payload, claimed.id);
+      const boundLifecycle = bindIngressLifecycleToReplyOptions(lifecycle).turnAdoptionLifecycle;
+      let resolveDeferredClaim!: () => void;
+      const deferredClaim = new Promise<void>((resolve) => {
+        resolveDeferredClaim = resolve;
+      });
+      let deferredClaimSettled = false;
+      const settleDeferredClaim = () => {
+        if (deferredClaimSettled) {
+          return;
+        }
+        deferredClaimSettled = true;
+        if (deferredClaims.get(claimed.id) === deferredClaim) {
+          deferredClaims.delete(claimed.id);
+        }
+        resolveDeferredClaim();
+      };
+      const delivery = options.deliver(update, {
+        ...boundLifecycle,
+        onAdopted: async () => {
+          try {
+            await boundLifecycle.onAdopted();
+          } finally {
+            settleDeferredClaim();
+          }
+        },
+        onDeferred: () => {
+          if (!deferredClaimSettled) {
+            deferredClaims.set(claimed.id, deferredClaim);
+          }
+          boundLifecycle.onDeferred();
+        },
+        onAbandoned: () => {
+          void Promise.resolve(boundLifecycle.onAbandoned()).finally(settleDeferredClaim);
+        },
+      });
+      activeDeliveries.add(delivery);
+      try {
+        await delivery;
+      } finally {
+        activeDeliveries.delete(delivery);
+      }
+      return deferredClaims.has(claimed.id) ? { kind: "deferred" } : { kind: "completed" };
+    },
+  });
+
+  const pruneIfDue = async (): Promise<void> => {
+    const now = Date.now();
+    if (now - lastPrunedAt < ZALO_WEBHOOK_PRUNE_INTERVAL_MS) {
+      return;
+    }
+    await queue.prune({
+      completedTtlMs: ZALO_WEBHOOK_COMPLETED_TTL_MS,
+      completedMaxEntries: ZALO_WEBHOOK_COMPLETED_MAX_ENTRIES,
+      failedTtlMs: ZALO_WEBHOOK_FAILED_TTL_MS,
+      failedMaxEntries: ZALO_WEBHOOK_FAILED_MAX_ENTRIES,
+      now,
+    });
+    lastPrunedAt = now;
+  };
+
+  const requestDrain = (): void => {
+    if (!running || stopped) {
+      return;
+    }
+    drainRequested = true;
+    if (drainTask) {
+      return;
+    }
+    drainTask = runDetachedWebhookWork(async () => {
+      while (drainRequested) {
+        if (!running) {
+          break;
+        }
+        drainRequested = false;
+        await pruneIfDue();
+        // stop() can run during the async prune; never start a new claim afterwards.
+        if (!running) {
+          break;
+        }
+        await drain.drainOnce({
+          shouldStop: () =>
+            !running || activeDeliveries.size >= ZALO_WEBHOOK_MAX_CONCURRENT_DELIVERIES,
+        });
+      }
+    })
+      .catch((error: unknown) => {
+        options.runtime.error?.(`zalo ingress drain failed: ${errorText(error)}`);
+      })
+      .finally(() => {
+        drainTask = undefined;
+        if (running && drainRequested) {
+          requestDrain();
+        }
+      });
+  };
+
+  const admitOnce = async (rawEvent: string): Promise<void> => {
+    const facts = inspectZaloWebhookEvent(rawEvent);
+    const receivedAt = Date.now();
+    let lastError: unknown;
+    for (const delayMs of ZALO_WEBHOOK_APPEND_RETRY_DELAYS_MS) {
+      if (delayMs > 0) {
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, delayMs);
+        });
+      }
+      try {
+        await queue.enqueue(
+          facts.eventId,
+          { version: ZALO_WEBHOOK_SPOOL_VERSION, rawEvent },
+          { receivedAt, laneKey: facts.laneKey },
+        );
+        requestDrain();
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw lastError;
+  };
+
+  return {
+    accept: (rawEvent) => {
+      // Serialize concurrent webhook admissions so append backoff cannot invert lane order.
+      const admission = admissionTail.then(() => admitOnce(rawEvent));
+      admissionTail = admission.catch(() => undefined);
+      return admission;
+    },
+    start: () => {
+      if (running || stopped) {
+        return;
+      }
+      running = true;
+      requestDrain();
+      drainTimer = setInterval(requestDrain, ZALO_WEBHOOK_DRAIN_INTERVAL_MS);
+      drainTimer.unref?.();
+    },
+    stop: async () => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      running = false;
+      if (drainTimer) {
+        clearInterval(drainTimer);
+        drainTimer = undefined;
+      }
+      // Every accepted request must finish its durable append before shutdown returns.
+      await admissionTail;
+      drain.dispose();
+      await drainTask;
+      // A pump may have been between prune and drain when the first dispose ran.
+      drain.dispose();
+      await Promise.allSettled(activeDeliveries);
+      await Promise.allSettled(deferredClaims.values());
+      await drain.waitForIdle();
+    },
+  };
+}
+
+export const zaloWebhookIngressRuntime = { createZaloWebhookIngress };

From 3b2797f09ba14632b1ada2ab1f8bc84a27d53993 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:10:20 +0100
Subject: [PATCH 41/76] =?UTF-8?q?improve(ui):=20settings=20cleanup=20batch?=
 =?UTF-8?q?=20=E2=80=94=20universal=20config.changed=20emitter,=20synced?=
 =?UTF-8?q?=20chat=20prefs,=20dedupe=20and=20copy=20fixes=20(#110581)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(gateway): emit config.changed from the reload committer for every accepted write

Agent config_set, CLI, and doctor writes reach the gateway through the file
watcher's reload path, which never broadcast config.changed - only direct RPC
writes did. Move the broadcast to a single onConfigCandidateCommitted hook in
the reload committer so all writers notify connected UIs, including
runtime-skipped commits (writer-intent echo suppression, reload mode off),
and delete the duplicate RPC-side broadcasts.

* feat(ui): sync chat follow-up and commentary prefs across devices

Add chatPersistCommentary and chatFollowUpMode to the ui.prefs sync surface
(schema, types, docs) with clearable null removal for the follow-up override.
Rewrite server-prefs around a descriptor table so a synced pref is one entry
instead of five hand-written code sites. Caption synced rows/sections
(chat prefs, theme, language) and refresh the stale Settings subtitle.

* refactor(ui): dedupe settings constants, drop dead composer branch, refresh copy and docs

Derive the Security tool-profile options from PROFILE_OPTIONS and General's
thinking levels from BASE_THINKING_LEVELS instead of parallel literals.
Remove the unused composer mode:"model" branch, the orphaned
.config-view-toggle CSS family, and stale quick-settings wording. Add static
settings-search entries for the Sessions and Managed Worktrees pages plus a
provenance-row test, and update docs/cli/openclaw.md to describe the current
system-agent config-write policy (denylist roots, route-backing plugin guard,
per-agent routing escalations).

* chore: refresh plugin SDK API baseline after rebase onto current main
---
 .../.generated/plugin-sdk-api-baseline.sha256 |   2 +-
 docs/cli/openclaw.md                          |  33 +--
 docs/gateway/configuration-reference.md       |   2 +
 docs/web/control-ui.md                        |   4 +-
 src/config/types.openclaw.ts                  |   4 +
 src/config/zod-schema.root-shape.ts           |   2 +
 src/gateway/config-reload.test.ts             |  60 +++++
 src/gateway/config-reload.ts                  |  24 ++
 src/gateway/server-methods/config.ts          |  24 --
 src/gateway/server-reload-handlers.ts         |  10 +
 ui/src/app-navigation.test.ts                 |   2 +-
 ui/src/app/server-prefs.test.ts               |  29 +++
 ui/src/app/server-prefs.ts                    | 214 +++++++++++-------
 ...fig-quick-thinking-persistence.e2e.test.ts |   2 +-
 ui/src/i18n/locales/en.ts                     |   6 +-
 ui/src/lib/agents/display.ts                  |   4 +-
 ui/src/lib/chat/thinking.ts                   |   3 +-
 ui/src/pages/chat/chat-view.test.ts           |  33 +++
 .../chat/components/chat-model-controls.ts    |  16 +-
 ui/src/pages/config/config-page.ts            |  10 +-
 ui/src/pages/config/quick.ts                  |   6 +-
 ui/src/pages/config/security.test.ts          |   6 +-
 ui/src/pages/config/security.ts               |  15 +-
 ui/src/pages/config/settings-search.test.ts   |  17 ++
 ui/src/pages/config/settings-search.ts        |  25 ++
 ui/src/pages/config/view.ts                   |   8 +-
 ui/src/pages/profile/identity-section.ts      |   2 +-
 ui/src/styles/config-quick.css                |  25 --
 ui/src/styles/layout.css                      |   3 +-
 ui/src/styles/settings.css                    |   9 +-
 30 files changed, 412 insertions(+), 188 deletions(-)

diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 10596e14b98..7b67958017e 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -94,7 +94,7 @@ d340686cf814326b5a554a32cc5ca324a9e1254a933c4d9d8d1ada5ac7109a10  module/command
 a821f9cc4e6f9339399d99e73f58c3b00baf139aa9d85c22d73c89d8be5702d2  module/config-contracts
 20f3f8042de53e4eee61b64de9102c8c202b9299e6a29235647a4729f70145f2  module/config-mutation
 316949815affe623ac63951a5db580527f02663576dffa084f02768f612c0c1c  module/config-runtime
-a7d72564e1766cc51fafcba150e32cac267afb2fc8c92ffce4095a1bb5152030  module/config-schema
+20a92012a24deb819aad3866c6e2b3cf8fee3ca83e0135464b2188bae01278e5  module/config-schema
 bfe6eec12f45bc2fda6df28699681b22dfd819a2261aabe8e0c789a20a017058  module/config-types
 42d15153981cfe3adc1d5f91621434c56f07a9bd48c15ce34742f72dd040c142  module/context-visibility-runtime
 03636897fb99cb73e4d8620c8a0e0d72b4d52fc32bf94f525af2aa88c489c6c2  module/conversation-binding-runtime
diff --git a/docs/cli/openclaw.md b/docs/cli/openclaw.md
index 2b6ea94df0c..fb3e0cf0c2c 100644
--- a/docs/cli/openclaw.md
+++ b/docs/cli/openclaw.md
@@ -104,19 +104,26 @@ Doctor repairs are unavailable inside OpenClaw because they can rewrite the prov
 
 New agents inherit the live-verified default inference route. The agent ids `openclaw` and `crestodian` are reserved for the system agent and cannot be created as normal agents. The retired id remains blocked so an old config cannot claim it.
 
-`config set` and `config set-ref` cannot change inference-route state,
-including inference-provider credentials, top-level `auth.*`, model catalogs,
-CLI backends, default/per-agent model routes, agent params/tools, or root
-`tools.*`. Raw writes under `env.*`, `secrets.*`, `plugins.*`, and `$include`
-are also refused because they can replace credential resolution or provider
-activation. Gateway and channel auth remain normal config surfaces. Use typed plugin/channel workflows and
-`set default model <provider/model>` for an already
-configured route; it live-tests the route before saving it. To configure or
-repair provider/auth access, exit OpenClaw and run `openclaw onboard`.
-
-Plugin uninstall is refused inside OpenClaw because removing a provider
-plugin could disable the inference route powering the session. Exit OpenClaw
-and run `openclaw plugins uninstall <id>` from a terminal.
+`config set` and `config set-ref` can change any setting a user can change,
+with a short human-only denylist: `$include`, `auth.*`, `env.*`, `models.*`,
+and `secrets.*` stay refused because they carry credential material,
+alternate-config inclusion, or the provider/catalog definitions that feed
+inference routing. Inference routing itself is also protected: default model
+routes (`agents.defaults` model/params/runtime fields) and the routing fields
+of whichever agent backs the active default route are refused, as are agent
+identity/topology fields (`id`, `agentDir`, `default`). Routing fields for
+other agents remain writable behind approval. Gateway and channel auth remain
+normal config surfaces. Use `set default model <provider/model>` for an
+already configured route; it live-tests the route before saving it. To
+configure or repair provider/auth access, exit OpenClaw and run
+`openclaw onboard`.
+
+`plugins.entries.<id>.*` writes (enable/disable/config of installed plugins)
+are allowed unless that plugin backs the active inference route. Plugin
+install sources and load policy keep their trust boundary in the typed
+plugin-install workflow. Plugin uninstall of the route-backing plugin is
+refused for the same reason; exit OpenClaw and run
+`openclaw plugins uninstall <id>` from a terminal.
 
 Approval is given in your own words: unambiguous replies ("yes", "sure", "go ahead", "not now") resolve from a closed deterministic list. When the configured route supports a separate completion call, other replies can be classified from only your message and the pending proposal — never by the conversation model itself, which cannot self-approve. Unclassified or ambiguous replies keep the proposal pending and the conversation asks again.
 
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 35c280050a0..b847e644b25 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -519,7 +519,9 @@ See [Inferred commitments](/concepts/commitments).
       locale: "en",
       chatShowThinking: true,
       chatShowToolCalls: true,
+      chatPersistCommentary: false,
       chatSendShortcut: "enter", // enter | modifier-enter
+      chatFollowUpMode: "steer", // steer | queue; omit to use the server queue mode
     },
   },
 }
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index ea1876bccaa..8c578570a3d 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -94,11 +94,11 @@ The Control UI fetches its runtime settings from `/control-ui-config.json`, reso
 
 ## Gateway host status
 
-Open **Settings** in Simple view to see the **Gateway Host** card with the Gateway machine, LAN address, operating system, runtime, uptime, CPU load, memory, and state-volume disk space. The card refreshes every 10 seconds while visible through the `system.info` Gateway RPC, which requires the `operator.read` scope. Older Gateways and connections without that scope omit the card.
+Open **Settings → General** to see the **Gateway Host** card with the Gateway machine, LAN address, operating system, runtime, uptime, CPU load, memory, and state-volume disk space. The card refreshes every 10 seconds while visible through the `system.info` Gateway RPC, which requires the `operator.read` scope. Older Gateways and connections without that scope omit the card.
 
 ## Language support
 
-The Control UI localizes itself on first load based on your browser locale. To override it later, open **Settings -> General -> Language** (the picker lives in the General quick-settings card, not under Appearance).
+The Control UI localizes itself on first load based on your browser locale. To override it later, open **Settings -> General -> Language** (the picker lives on the General page, not under Appearance).
 
 - Supported locales: `en`, `ar`, `de`, `es`, `fa`, `fr`, `hi`, `id`, `it`, `ja-JP`, `ko`, `nl`, `pl`, `pt-BR`, `ru`, `th`, `tr`, `uk`, `vi`, `zh-CN`, `zh-TW`
 - Non-English translations are lazy-loaded in the browser.
diff --git a/src/config/types.openclaw.ts b/src/config/types.openclaw.ts
index dda7d445f9c..54e00fe0868 100644
--- a/src/config/types.openclaw.ts
+++ b/src/config/types.openclaw.ts
@@ -206,8 +206,12 @@ export type OpenClawConfig = {
       chatShowThinking?: boolean;
       /** Show tool call cards in chat. */
       chatShowToolCalls?: boolean;
+      /** Keep model commentary visible in the transcript after a run. */
+      chatPersistCommentary?: boolean;
       /** Chat send shortcut: Enter sends, or modifier+Enter sends. */
       chatSendShortcut?: "enter" | "modifier-enter";
+      /** Follow-up handling while a run is active; unset uses the server queue mode. */
+      chatFollowUpMode?: "steer" | "queue";
     };
   };
   /** Terminal UI display settings. */
diff --git a/src/config/zod-schema.root-shape.ts b/src/config/zod-schema.root-shape.ts
index 08dc934639b..ed22a6f9403 100644
--- a/src/config/zod-schema.root-shape.ts
+++ b/src/config/zod-schema.root-shape.ts
@@ -295,7 +295,9 @@ export const OpenClawSchemaShape = {
           locale: z.string().max(20).optional(),
           chatShowThinking: z.boolean().optional(),
           chatShowToolCalls: z.boolean().optional(),
+          chatPersistCommentary: z.boolean().optional(),
           chatSendShortcut: z.union([z.literal("enter"), z.literal("modifier-enter")]).optional(),
+          chatFollowUpMode: z.union([z.literal("steer"), z.literal("queue")]).optional(),
         })
         .optional(),
     })
diff --git a/src/gateway/config-reload.test.ts b/src/gateway/config-reload.test.ts
index ebd106db069..cae8cb4c9d2 100644
--- a/src/gateway/config-reload.test.ts
+++ b/src/gateway/config-reload.test.ts
@@ -724,6 +724,9 @@ function createReloaderHarness(
   const onRestart = vi.fn(
     options.onRestart ?? ((_plan: GatewayReloadPlan, _nextConfig: OpenClawConfig) => {}),
   );
+  const onConfigCandidateCommitted = vi.fn(
+    (_info: { path: string; persistedHash: string | null; changedPaths: readonly string[] }) => {},
+  );
   let writeListener: ((event: ConfigWriteNotification) => void) | null = null;
   const subscribeToWrites = vi.fn((listener: (event: ConfigWriteNotification) => void) => {
     writeListener = listener;
@@ -762,6 +765,7 @@ function createReloaderHarness(
     onNoopConfigCommit,
     onHotReload,
     onRestart,
+    onConfigCandidateCommitted,
     ...(options.runTransaction ? { runTransaction: options.runTransaction } : {}),
     log,
     watchPath: "/tmp/openclaw.json",
@@ -776,6 +780,7 @@ function createReloaderHarness(
     onNoopConfigCommit,
     onHotReload,
     onRestart,
+    onConfigCandidateCommitted,
     log,
     reloader,
     emitWrite(event: ConfigWriteNotification) {
@@ -848,6 +853,61 @@ describe("startGatewayConfigReloader", () => {
     },
   );
 
+  it("notifies change listeners for every accepted external edit, including runtime-skipped ones", async () => {
+    const initialConfig: OpenClawConfig = {
+      gateway: { reload: { debounceMs: 0 } },
+    };
+    // ui.* is a no-op reload class: the runtime snapshot refreshes without a
+    // hot reload or restart — exactly the agent-changes-theme case.
+    const nextConfig: OpenClawConfig = {
+      gateway: { reload: { debounceMs: 0 } },
+      ui: { prefs: { themeMode: "dark" } },
+    };
+    const readSnapshot = vi.fn(async () =>
+      makeSnapshot({ config: nextConfig, hash: "external-prefs-write" }),
+    );
+    const harness = createReloaderHarness(readSnapshot, { initialConfig });
+
+    harness.watcher.emit("change");
+    await vi.runAllTimersAsync();
+
+    expect(harness.onConfigCandidateCommitted).toHaveBeenCalledOnce();
+    expect(harness.onConfigCandidateCommitted).toHaveBeenCalledWith({
+      path: "/tmp/openclaw.json",
+      persistedHash: "external-prefs-write",
+      changedPaths: ["ui"],
+    });
+
+    // A same-content echo must not re-notify: nothing changed.
+    harness.onConfigCandidateCommitted.mockClear();
+    harness.watcher.emit("change");
+    await vi.runAllTimersAsync();
+    expect(harness.onConfigCandidateCommitted).not.toHaveBeenCalled();
+    await harness.reloader.stop();
+  });
+
+  it("notifies change listeners when reload mode off skips the runtime apply", async () => {
+    const initialConfig: OpenClawConfig = {
+      gateway: { reload: { mode: "off", debounceMs: 0 } },
+    };
+    const nextConfig: OpenClawConfig = {
+      gateway: { reload: { mode: "off", debounceMs: 0 } },
+      ui: { prefs: { themeMode: "light" } },
+    };
+    const readSnapshot = vi.fn(async () =>
+      makeSnapshot({ config: nextConfig, hash: "mode-off-write" }),
+    );
+    const harness = createReloaderHarness(readSnapshot, { initialConfig });
+
+    harness.watcher.emit("change");
+    await vi.runAllTimersAsync();
+
+    expect(harness.onHotReload).not.toHaveBeenCalled();
+    expect(harness.onRestart).not.toHaveBeenCalled();
+    expect(harness.onConfigCandidateCommitted).toHaveBeenCalledOnce();
+    await harness.reloader.stop();
+  });
+
   it("notifies lifecycle owners when a persisted edit reverts to the current baseline", async () => {
     const initialConfig: OpenClawConfig = {
       gateway: { reload: { debounceMs: 0 }, port: 18789 },
diff --git a/src/gateway/config-reload.ts b/src/gateway/config-reload.ts
index e3a86c7c127..301fe04458d 100644
--- a/src/gateway/config-reload.ts
+++ b/src/gateway/config-reload.ts
@@ -180,6 +180,17 @@ export function startGatewayConfigReloader(opts: {
     /** Runs only when this exact source publication can no longer roll back. */
     commit?: () => void;
   }>;
+  /**
+   * Fires once per accepted candidate whose persisted content changed —
+   * regardless of writer (gateway RPC, agent/CLI config_set, doctor, hand
+   * edit) and of whether the runtime applied it. The single notification
+   * point for change listeners such as the config.changed broadcast.
+   */
+  onConfigCandidateCommitted?: (info: {
+    path: string;
+    persistedHash: string | null;
+    changedPaths: readonly string[];
+  }) => void;
   onNoopConfigCommit: (
     plan: GatewayReloadPlan,
     nextConfig: OpenClawConfig,
@@ -445,6 +456,17 @@ export function startGatewayConfigReloader(opts: {
       // a baseline-only candidate, which can discard prepared lifecycle state.
       await appliedRevision.flush(currentConfig);
       assertCurrent();
+      // Persisted content changed even when the runtime skipped applying it
+      // (writer intent, reload mode off): change listeners still refresh.
+      const notifyCommitted = () => {
+        if (changedPaths.length > 0) {
+          opts.onConfigCandidateCommitted?.({
+            path: opts.watchPath,
+            persistedHash: persistedHash ?? null,
+            changedPaths,
+          });
+        }
+      };
       let rollbackAcceptedSource: (() => Promise<void>) | undefined;
       try {
         const acceptedSourceRollback = await opts.onConfigAccepted?.(
@@ -471,6 +493,7 @@ export function startGatewayConfigReloader(opts: {
           lastSourceOnlyRuntimeRefresh = ownership.runtimeRefresh;
           lastSourceOnlyRuntimeConfig = nextConfig;
           lastSourceOnlySourceConfig = nextSourceConfig;
+          notifyCommitted();
           return;
         }
         // Runtime owners publish env at their commit edge. Keep this idempotent
@@ -499,6 +522,7 @@ export function startGatewayConfigReloader(opts: {
         await rollbackAcceptedSource?.();
         throw error;
       }
+      notifyCommitted();
     };
     if (changedPaths.length === 0) {
       let publishedSource: { rollback: () => Promise<void>; commit?: () => void } | undefined;
diff --git a/src/gateway/server-methods/config.ts b/src/gateway/server-methods/config.ts
index d35dc4e17ef..bfe1e1ae551 100644
--- a/src/gateway/server-methods/config.ts
+++ b/src/gateway/server-methods/config.ts
@@ -522,28 +522,6 @@ function clearConfigSchemaResponseCache() {
   configSchemaResponseCache = null;
 }
 
-/**
- * Hash-only change notice so connected operator clients can refresh their
- * config snapshot (e.g. live ui.prefs sync after an agent-approved write).
- * Config content never rides the event; readers fetch via config.get.
- */
-function broadcastConfigChanged(
-  context: GatewayRequestContext | undefined,
-  writeResult: Pick<ConfigWriteCommitResult, "path" | "hash">,
-): void {
-  // Test doubles and embedded hosts may omit broadcast; the notice is
-  // best-effort either way.
-  context?.broadcast?.(
-    "config.changed",
-    {
-      path: writeResult.path,
-      hash: writeResult.hash ?? null,
-      ts: Date.now(),
-    },
-    { dropIfSlow: true },
-  );
-}
-
 async function respondWithConfigRestartWrite(params: {
   requestParams: unknown;
   kind: ConfigRestartWriteKind;
@@ -583,7 +561,6 @@ async function respondWithConfigRestartWrite(params: {
     },
     undefined,
   );
-  broadcastConfigChanged(params.context, params.writeResult);
   params.writeResult.queueFollowUp();
 }
 
@@ -737,7 +714,6 @@ export const configHandlers: GatewayRequestHandlers = {
       },
       undefined,
     );
-    broadcastConfigChanged(context, writeResult);
     writeResult.queueFollowUp();
   },
   "config.patch": async ({ params, respond, client, context }) => {
diff --git a/src/gateway/server-reload-handlers.ts b/src/gateway/server-reload-handlers.ts
index 5a2c1e5aaa7..59871d65074 100644
--- a/src/gateway/server-reload-handlers.ts
+++ b/src/gateway/server-reload-handlers.ts
@@ -1850,6 +1850,16 @@ export function startManagedGatewayConfigReloader(
   const configReloader = startGatewayConfigReloader({
     initialConfig: params.initialConfig,
     initialCompareConfig: params.initialCompareConfig,
+    // Single notification point for every persisted config change — gateway
+    // RPC writes, agent/CLI config_set, doctor, and hand edits all land here
+    // once the candidate is accepted. Hash-only; clients refresh via config.get.
+    onConfigCandidateCommitted: (info) => {
+      params.broadcast(
+        "config.changed",
+        { path: info.path, hash: info.persistedHash, ts: Date.now() },
+        { dropIfSlow: true },
+      );
+    },
     ...(params.prepareConfigCandidate
       ? { prepareConfigCandidate: params.prepareConfigCandidate }
       : {}),
diff --git a/ui/src/app-navigation.test.ts b/ui/src/app-navigation.test.ts
index 779a893ff86..7d4329762e6 100644
--- a/ui/src/app-navigation.test.ts
+++ b/ui/src/app-navigation.test.ts
@@ -201,7 +201,7 @@ describe("subtitleForRoute", () => {
       plugins: "Install and manage optional capabilities.",
       "skill-workshop": "Review, refine, and apply proposals before they become live skills.",
       nodes: "Paired devices, pairing approvals, and exec bindings.",
-      config: "Edit openclaw.json.",
+      config: "Model defaults, language, and gateway host.",
       profile: "Your agent's stats, streaks, and life in the reef.",
       communications: "Channels, messages, and audio settings.",
       appearance: "Theme, UI, and setup wizard settings.",
diff --git a/ui/src/app/server-prefs.test.ts b/ui/src/app/server-prefs.test.ts
index 5db7ae58b8e..e5b53162e8f 100644
--- a/ui/src/app/server-prefs.test.ts
+++ b/ui/src/app/server-prefs.test.ts
@@ -131,6 +131,35 @@ describe("changedServerUiPrefs", () => {
     expect(changedServerUiPrefs(previous, next)).toEqual({ themeMode: "dark" });
     expect(changedServerUiPrefs(previous, { ...previous })).toBeNull();
   });
+
+  it("syncs chat behavior prefs and pushes clearable resets as null", () => {
+    const previous = loadSettings();
+    const withOverrides = {
+      ...previous,
+      chatPersistCommentary: true,
+      chatFollowUpMode: "queue" as const,
+    };
+    expect(changedServerUiPrefs(previous, withOverrides)).toEqual({
+      chatPersistCommentary: true,
+      chatFollowUpMode: "queue",
+    });
+
+    // Clearing the follow-up override must propagate as an explicit removal.
+    expect(
+      changedServerUiPrefs(withOverrides, { ...withOverrides, chatFollowUpMode: undefined }),
+    ).toEqual({ chatFollowUpMode: null });
+  });
+});
+
+describe("clearable pref removal from the server", () => {
+  it("clears the local follow-up override when the server removes it", () => {
+    const onApplied = vi.fn();
+    applyServerUiPrefs(configWithPrefs({ chatFollowUpMode: "queue" }), { onApplied });
+    expect(loadSettings().chatFollowUpMode).toBe("queue");
+
+    expect(applyServerUiPrefs(configWithPrefs({}), { onApplied })).toBe(true);
+    expect(loadSettings().chatFollowUpMode).toBeUndefined();
+  });
 });
 
 describe("pushServerUiPrefs", () => {
diff --git a/ui/src/app/server-prefs.ts b/ui/src/app/server-prefs.ts
index 927fc8a0683..7bd04f0a3d4 100644
--- a/ui/src/app/server-prefs.ts
+++ b/ui/src/app/server-prefs.ts
@@ -10,55 +10,105 @@ import type { GatewayBrowserClient } from "../api/gateway.ts";
 import { isSupportedLocale } from "../i18n/index.ts";
 import {
   loadSettings,
+  normalizeChatFollowUpModeOverride,
   normalizeChatSendShortcut,
   normalizeTextScale,
   patchSettings,
   TEXT_SCALE_STOPS,
+  type ChatFollowUpMode,
   type ChatSendShortcut,
   type TextScaleStop,
   type UiSettings,
 } from "./settings.ts";
 import type { ThemeMode, ThemeName } from "./theme.ts";
 
-type ServerUiPrefs = {
-  theme?: ThemeName;
-  themeMode?: ThemeMode;
-  textScale?: TextScaleStop;
-  locale?: string;
-  chatShowThinking?: boolean;
-  chatShowToolCalls?: boolean;
-  chatSendShortcut?: ChatSendShortcut;
-};
-
 const THEMES: ReadonlySet<ThemeName> = new Set(["claw", "knot", "dash", "custom"]);
 const THEME_MODES: ReadonlySet<ThemeMode> = new Set(["light", "dark", "system"]);
 
+/**
+ * One descriptor per synced pref — the single source of truth for what syncs
+ * through config ui.prefs. Each key defines how to validate the server value,
+ * read the normalized local value, and (optionally) whether a server value is
+ * applicable on this device. `clearable` keys push an explicit JSON null when
+ * unset locally so the merge patch removes them server-side.
+ */
+type SyncedPrefSpec<T> = {
+  extract: (value: unknown) => T | undefined;
+  local: (settings: UiSettings) => T | undefined;
+  canApply?: (value: T, settings: UiSettings) => boolean;
+  clearable?: boolean;
+};
+
+const prefSpec = <T>(specification: SyncedPrefSpec<T>) => specification;
+
+const SYNCED_PREFS = {
+  theme: prefSpec<ThemeName>({
+    extract: (value) => (THEMES.has(value as ThemeName) ? (value as ThemeName) : undefined),
+    local: (settings) => settings.theme,
+    // A server "custom" theme is only honorable once this browser imported
+    // one; the imported palette itself is too large to live in config.
+    canApply: (value, settings) => value !== "custom" || Boolean(settings.customTheme),
+  }),
+  themeMode: prefSpec<ThemeMode>({
+    extract: (value) => (THEME_MODES.has(value as ThemeMode) ? (value as ThemeMode) : undefined),
+    local: (settings) => settings.themeMode,
+  }),
+  textScale: prefSpec<TextScaleStop>({
+    extract: (value) =>
+      TEXT_SCALE_STOPS.includes(value as TextScaleStop) ? normalizeTextScale(value) : undefined,
+    local: (settings) => normalizeTextScale(settings.textScale),
+  }),
+  locale: prefSpec<string>({
+    extract: (value) => (typeof value === "string" && isSupportedLocale(value) ? value : undefined),
+    local: (settings) => settings.locale,
+  }),
+  chatShowThinking: prefSpec<boolean>({
+    extract: (value) => (typeof value === "boolean" ? value : undefined),
+    local: (settings) => settings.chatShowThinking,
+  }),
+  chatShowToolCalls: prefSpec<boolean>({
+    extract: (value) => (typeof value === "boolean" ? value : undefined),
+    local: (settings) => settings.chatShowToolCalls,
+  }),
+  chatPersistCommentary: prefSpec<boolean>({
+    extract: (value) => (typeof value === "boolean" ? value : undefined),
+    local: (settings) => settings.chatPersistCommentary ?? false,
+  }),
+  chatSendShortcut: prefSpec<ChatSendShortcut>({
+    extract: (value) =>
+      value === "enter" || value === "modifier-enter"
+        ? normalizeChatSendShortcut(value)
+        : undefined,
+    local: (settings) => normalizeChatSendShortcut(settings.chatSendShortcut),
+  }),
+  chatFollowUpMode: prefSpec<ChatFollowUpMode>({
+    extract: (value) => normalizeChatFollowUpModeOverride(value),
+    local: (settings) => normalizeChatFollowUpModeOverride(settings.chatFollowUpMode),
+    // Unset means "use the server-configured queue mode"; clearing must
+    // propagate, so the push serializes an explicit null removal.
+    clearable: true,
+  }),
+} as const;
+
+type SyncedPrefKey = keyof typeof SYNCED_PREFS;
+type SyncedPrefValue<K extends SyncedPrefKey> =
+  ReturnType<(typeof SYNCED_PREFS)[K]["extract"]> extends (infer T) | undefined ? T : never;
+
+type ServerUiPrefs = { [K in SyncedPrefKey]?: SyncedPrefValue<K> | null };
+
+const SYNCED_PREF_KEYS = Object.keys(SYNCED_PREFS) as SyncedPrefKey[];
+
 function extractServerUiPrefs(configObject: unknown): ServerUiPrefs {
   const prefs = asRecord(asRecord(asRecord(configObject)?.ui)?.prefs);
   if (!prefs) {
     return {};
   }
   const result: ServerUiPrefs = {};
-  if (THEMES.has(prefs.theme as ThemeName)) {
-    result.theme = prefs.theme as ThemeName;
-  }
-  if (THEME_MODES.has(prefs.themeMode as ThemeMode)) {
-    result.themeMode = prefs.themeMode as ThemeMode;
-  }
-  if (TEXT_SCALE_STOPS.includes(prefs.textScale as TextScaleStop)) {
-    result.textScale = normalizeTextScale(prefs.textScale);
-  }
-  if (typeof prefs.locale === "string" && isSupportedLocale(prefs.locale)) {
-    result.locale = prefs.locale;
-  }
-  if (typeof prefs.chatShowThinking === "boolean") {
-    result.chatShowThinking = prefs.chatShowThinking;
-  }
-  if (typeof prefs.chatShowToolCalls === "boolean") {
-    result.chatShowToolCalls = prefs.chatShowToolCalls;
-  }
-  if (prefs.chatSendShortcut === "enter" || prefs.chatSendShortcut === "modifier-enter") {
-    result.chatSendShortcut = normalizeChatSendShortcut(prefs.chatSendShortcut);
+  for (const key of SYNCED_PREF_KEYS) {
+    const value = SYNCED_PREFS[key].extract(prefs[key]);
+    if (value !== undefined) {
+      (result as Record<string, unknown>)[key] = value;
+    }
   }
   return result;
 }
@@ -69,39 +119,33 @@ function serverPrefsLocalPatch(
   settings: UiSettings,
 ): Partial<UiSettings> | null {
   const patch: Partial<UiSettings> = {};
-  // A server "custom" theme is only honorable once this browser imported one;
-  // the imported palette itself is too large to live in config.
-  if (prefs.theme !== undefined && prefs.theme !== settings.theme) {
-    if (prefs.theme !== "custom" || settings.customTheme) {
-      patch.theme = prefs.theme;
+  for (const key of SYNCED_PREF_KEYS) {
+    const specification = SYNCED_PREFS[key];
+    const serverValue = prefs[key];
+    if (serverValue === undefined) {
+      continue;
     }
-  }
-  if (prefs.themeMode !== undefined && prefs.themeMode !== settings.themeMode) {
-    patch.themeMode = prefs.themeMode;
-  }
-  if (prefs.textScale !== undefined && prefs.textScale !== normalizeTextScale(settings.textScale)) {
-    patch.textScale = prefs.textScale;
-  }
-  if (prefs.locale !== undefined && prefs.locale !== settings.locale) {
-    patch.locale = prefs.locale;
-  }
-  if (
-    prefs.chatShowThinking !== undefined &&
-    prefs.chatShowThinking !== settings.chatShowThinking
-  ) {
-    patch.chatShowThinking = prefs.chatShowThinking;
-  }
-  if (
-    prefs.chatShowToolCalls !== undefined &&
-    prefs.chatShowToolCalls !== settings.chatShowToolCalls
-  ) {
-    patch.chatShowToolCalls = prefs.chatShowToolCalls;
-  }
-  if (
-    prefs.chatSendShortcut !== undefined &&
-    prefs.chatSendShortcut !== normalizeChatSendShortcut(settings.chatSendShortcut)
-  ) {
-    patch.chatSendShortcut = prefs.chatSendShortcut;
+    // Null marks a server-side removal of a clearable key: drop the local
+    // override so this device falls back to the server-configured behavior.
+    if (serverValue === null) {
+      if (specification.clearable && specification.local(settings) !== undefined) {
+        (patch as Record<string, unknown>)[key] = undefined;
+      }
+      continue;
+    }
+    if (serverValue === specification.local(settings)) {
+      continue;
+    }
+    if (
+      specification.canApply &&
+      !(specification.canApply as (value: unknown, settings: UiSettings) => boolean)(
+        serverValue,
+        settings,
+      )
+    ) {
+      continue;
+    }
+    (patch as Record<string, unknown>)[key] = serverValue;
   }
   return Object.keys(patch).length > 0 ? patch : null;
 }
@@ -109,29 +153,21 @@ function serverPrefsLocalPatch(
 /** Synced-key delta between two local settings snapshots, for the push path. */
 export function changedServerUiPrefs(previous: UiSettings, next: UiSettings): ServerUiPrefs | null {
   const prefs: ServerUiPrefs = {};
-  if (next.theme !== previous.theme) {
-    prefs.theme = next.theme;
-  }
-  if (next.themeMode !== previous.themeMode) {
-    prefs.themeMode = next.themeMode;
-  }
-  if (normalizeTextScale(next.textScale) !== normalizeTextScale(previous.textScale)) {
-    prefs.textScale = normalizeTextScale(next.textScale);
-  }
-  if (next.locale !== previous.locale && next.locale) {
-    prefs.locale = next.locale;
-  }
-  if (next.chatShowThinking !== previous.chatShowThinking) {
-    prefs.chatShowThinking = next.chatShowThinking;
-  }
-  if (next.chatShowToolCalls !== previous.chatShowToolCalls) {
-    prefs.chatShowToolCalls = next.chatShowToolCalls;
-  }
-  if (
-    normalizeChatSendShortcut(next.chatSendShortcut) !==
-    normalizeChatSendShortcut(previous.chatSendShortcut)
-  ) {
-    prefs.chatSendShortcut = normalizeChatSendShortcut(next.chatSendShortcut);
+  for (const key of SYNCED_PREF_KEYS) {
+    const specification = SYNCED_PREFS[key];
+    const previousValue = specification.local(previous);
+    const nextValue = specification.local(next);
+    if (previousValue === nextValue) {
+      continue;
+    }
+    if (nextValue === undefined) {
+      // JSON merge patch removes keys via explicit null.
+      if (specification.clearable) {
+        (prefs as Record<string, unknown>)[key] = null;
+      }
+      continue;
+    }
+    (prefs as Record<string, unknown>)[key] = nextValue;
   }
   return Object.keys(prefs).length > 0 ? prefs : null;
 }
@@ -225,6 +261,14 @@ export function applyServerUiPrefs(
       (changed as Record<string, unknown>)[prefKey] = prefs[prefKey];
     }
   }
+  // A clearable key that disappeared from the server was removed by another
+  // writer; surface the removal as an explicit null so the local override
+  // clears too (non-clearable keys keep their device-local value).
+  for (const prefKey of Object.keys(lastSeen) as Array<keyof ServerUiPrefs>) {
+    if (!(prefKey in prefs) && SYNCED_PREFS[prefKey]?.clearable) {
+      (changed as Record<string, unknown>)[prefKey] = null;
+    }
+  }
   storeLastSeenKey(scope, key);
   const patch = serverPrefsLocalPatch(changed, loadSettings());
   if (!patch) {
diff --git a/ui/src/e2e/config-quick-thinking-persistence.e2e.test.ts b/ui/src/e2e/config-quick-thinking-persistence.e2e.test.ts
index 19165c881bb..6ead6030303 100644
--- a/ui/src/e2e/config-quick-thinking-persistence.e2e.test.ts
+++ b/ui/src/e2e/config-quick-thinking-persistence.e2e.test.ts
@@ -37,7 +37,7 @@ function requestRaw(request: MockGatewayRequest): Record<string, unknown> {
   return JSON.parse(String((params as Record<string, unknown>).raw)) as Record<string, unknown>;
 }
 
-describeControlUiE2e("Control UI Quick Config thinking persistence mocked Gateway E2E", () => {
+describeControlUiE2e("Control UI General settings thinking persistence mocked Gateway E2E", () => {
   beforeAll(async () => {
     if (!chromiumAvailable) {
       throw new Error(
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 6cc9715ca73..b075894f148 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -1038,6 +1038,9 @@ export const en: TranslationMap = {
       },
     },
   },
+  // Historical namespace from the pre-restructure "quick settings" page; its
+  // keys now serve General, Privacy & Security, Appearance, and Profile.
+  // Renaming would force retranslation of every key, so the name stays.
   quickSettings: {
     language: "Language",
     model: {
@@ -1198,6 +1201,7 @@ export const en: TranslationMap = {
       xl: "XL",
       xxl: "XXL",
     },
+    syncedHint: "Synced across your devices through the gateway.",
     notifications: {
       title: "Push notifications",
       hint: "Receive browser push notifications from your gateway.",
@@ -1671,7 +1675,7 @@ export const en: TranslationMap = {
     nodes: "Paired devices, pairing approvals, and exec bindings.",
     chat: "Gateway chat for quick interventions.",
     custodian: "System setup and care.",
-    config: "Edit openclaw.json.",
+    config: "Model defaults, language, and gateway host.",
     profile: "Your agent's stats, streaks, and life in the reef.",
     communications: "Channels, messages, and audio settings.",
     appearance: "Theme, UI, and setup wizard settings.",
diff --git a/ui/src/lib/agents/display.ts b/ui/src/lib/agents/display.ts
index bd33e983477..2b37c90fc34 100644
--- a/ui/src/lib/agents/display.ts
+++ b/ui/src/lib/agents/display.ts
@@ -202,7 +202,9 @@ const FALLBACK_TOOL_SECTIONS: FallbackToolSection[] = [
   },
 ];
 
-const PROFILE_OPTIONS = [
+// Canonical UI tool-profile list; Security and Agents surfaces share it so
+// labels stay translated and consistent.
+export const PROFILE_OPTIONS = [
   { id: "minimal", labelKey: "agents.toolCatalog.profiles.minimal" },
   { id: "coding", labelKey: "agents.toolCatalog.profiles.coding" },
   { id: "messaging", labelKey: "agents.toolCatalog.profiles.messaging" },
diff --git a/ui/src/lib/chat/thinking.ts b/ui/src/lib/chat/thinking.ts
index d496658e211..a35d15a8f11 100644
--- a/ui/src/lib/chat/thinking.ts
+++ b/ui/src/lib/chat/thinking.ts
@@ -15,7 +15,8 @@ type ThinkingCatalogEntry = {
   reasoning?: boolean;
 };
 
-const BASE_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"] as const;
+/** Canonical thinking levels; surfaces needing a subset derive it explicitly. */
+export const BASE_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"] as const;
 
 export function normalizeThinkLevel(raw?: string | null): string | undefined {
   if (!raw) {
diff --git a/ui/src/pages/chat/chat-view.test.ts b/ui/src/pages/chat/chat-view.test.ts
index 719d7aca2b5..8f14b7cf21c 100644
--- a/ui/src/pages/chat/chat-view.test.ts
+++ b/ui/src/pages/chat/chat-view.test.ts
@@ -4023,6 +4023,39 @@ describe("chat model controls", () => {
     expect(onModelSelect).toHaveBeenCalledWith(modelOption?.dataset.chatModelOption, "main");
   });
 
+  it("marks the inherited default muted and resets an override from the provenance row", () => {
+    const { state } = createChatHeaderState({
+      model: null,
+      models: [
+        { id: "gpt-5.4", name: "GPT-5.4", provider: "openai" },
+        { id: "gpt-5.5", name: "GPT-5.5", provider: "openai" },
+      ],
+    });
+    const container = document.createElement("div");
+    render(renderChatModelControls(createChatModelControlsProps(state)), container);
+
+    expect(
+      container.querySelector(".chat-controls__model-provenance-value--inherit"),
+    ).not.toBeNull();
+    expect(container.querySelector("[data-chat-model-reset]")).toBeNull();
+
+    const onModelSelect = vi.fn(async () => true);
+    render(
+      renderChatModelControls({
+        ...createChatModelControlsProps(state),
+        modelOverrides: { main: "openai/gpt-5.4" },
+        onModelSelect,
+      }),
+      container,
+    );
+
+    expect(container.querySelector(".chat-controls__model-provenance-value--inherit")).toBeNull();
+    const reset = container.querySelector<HTMLButtonElement>("[data-chat-model-reset]");
+    expect(reset).toBeInstanceOf(HTMLButtonElement);
+    reset?.click();
+    expect(onModelSelect).toHaveBeenCalledWith("", "main");
+  });
+
   it("hides model choices for locked sessions while preserving reasoning and speed", () => {
     const { state } = createChatHeaderState({
       model: "gpt-5.5",
diff --git a/ui/src/pages/chat/components/chat-model-controls.ts b/ui/src/pages/chat/components/chat-model-controls.ts
index 41398cf081e..3385c6c3a89 100644
--- a/ui/src/pages/chat/components/chat-model-controls.ts
+++ b/ui/src/pages/chat/components/chat-model-controls.ts
@@ -41,7 +41,6 @@ export type ChatModelControlsProps = {
   modelSelectionRuntimeId?: string;
   modelSwitching: boolean;
   modelsLoading?: boolean;
-  mode?: "combined" | "model";
   showFastMode?: boolean;
   sending: boolean;
   sessionKey: string;
@@ -249,7 +248,6 @@ export function renderChatModelControls(props: ChatModelControlsProps) {
     disabled,
     fastMode,
     modelSelectionLocked: props.modelSelectionLocked === true,
-    modelOnly: props.mode === "model",
     modelOptions,
     onRequestUpdate: props.onRequestUpdate,
     selectedModelValue: currentOverride,
@@ -357,7 +355,6 @@ function renderChatModelReasoningSelect(params: {
   fastMode: ChatFastModeSelectState;
   disabled: boolean;
   modelSelectionLocked: boolean;
-  modelOnly: boolean;
   modelOptions: ChatModelProviderOption[];
   selectedModelValue: string;
   selectedThinkingValue: string;
@@ -378,7 +375,6 @@ function renderChatModelReasoningSelect(params: {
     disabled,
     fastMode,
     modelSelectionLocked,
-    modelOnly,
     modelOptions,
     selectedModelValue,
     selectedThinkingValue,
@@ -396,7 +392,7 @@ function renderChatModelReasoningSelect(params: {
   } = params;
   const triggerModel = formatCombinedPickerModelLabel(triggerModelLabel);
   const triggerThinking = formatCombinedPickerThinkingLabel(triggerThinkingLabel);
-  const triggerTitle = modelOnly ? triggerModel : `${triggerModel} · ${triggerThinking}`;
+  const triggerTitle = `${triggerModel} · ${triggerThinking}`;
   const triggerLabel = triggerTitle;
   const sliderStops = thinkingOptions.filter((option) => option.value !== "");
   const defaultStopIndex = sliderStops.findIndex((option) => option.value === thinkingDefaultValue);
@@ -487,7 +483,7 @@ function renderChatModelReasoningSelect(params: {
   const onlyStop = sliderStops.length === 1 ? sliderStops[0] : undefined;
   const effectiveThinkingValue = selectedThinkingValue || thinkingDefaultValue;
   const onlyStopSelected = onlyStop?.value === effectiveThinkingValue;
-  const showReasoningPanel = !modelOnly && (showReasoning || showFastMode);
+  const showReasoningPanel = showReasoning || showFastMode;
   const providerGroups = new Map<string, ChatModelProviderOption[]>();
   for (const option of modelOptions) {
     const existing = providerGroups.get(option.provider);
@@ -573,13 +569,13 @@ function renderChatModelReasoningSelect(params: {
           : ""}"
         data-chat-model-select="true"
         data-chat-model-locked=${modelSelectionLocked ? "true" : "false"}
-        data-chat-thinking-select=${modelOnly ? nothing : "true"}
+        data-chat-thinking-select="true"
         data-chat-select-value=${selectedModelValue}
         data-chat-thinking-value=${selectedThinkingValue}
         data-chat-thinking-disabled=${thinkingDisabled ? "true" : "false"}
-        aria-label=${modelOnly
-          ? `${t("chat.selectors.model")}: ${triggerTitle}`
-          : `${t("chat.selectors.model")}, ${t("chat.selectors.thinkingLevel")}: ${triggerTitle}`}
+        aria-label="${t("chat.selectors.model")}, ${t(
+          "chat.selectors.thinkingLevel",
+        )}: ${triggerTitle}"
         aria-disabled=${disabled ? "true" : "false"}
         @click=${(event: MouseEvent) => {
           if (disabled) {
diff --git a/ui/src/pages/config/config-page.ts b/ui/src/pages/config/config-page.ts
index 78f242bc367..469219f9e7d 100644
--- a/ui/src/pages/config/config-page.ts
+++ b/ui/src/pages/config/config-page.ts
@@ -54,7 +54,13 @@ export type { ConfigPageId } from "./config-sections.ts";
 
 type ConfigFormMode = "form" | "raw";
 type ConfigSelection = { activeSection: string | null; activeSubsection: string | null };
-type LocalUiSetting = "textScale" | "chatSendShortcut" | "chatFollowUpMode" | "catalogOpenTarget";
+// Keys settable through this page's setSetting helper. Whether a key syncs
+// across devices is owned by app/server-prefs.ts, not by this type.
+type ConfigPageSetting =
+  | "textScale"
+  | "chatSendShortcut"
+  | "chatFollowUpMode"
+  | "catalogOpenTarget";
 
 const CONFIG_PAGE_I18N_KEYS = {
   config: "config",
@@ -621,7 +627,7 @@ export class ConfigPage extends OpenClawLightDomElement {
     });
   }
 
-  private setSetting<K extends LocalUiSetting>(key: K, value: UiSettings[K]) {
+  private setSetting<K extends ConfigPageSetting>(key: K, value: UiSettings[K]) {
     this.applySettings({ ...this.settings, [key]: value });
   }
 
diff --git a/ui/src/pages/config/quick.ts b/ui/src/pages/config/quick.ts
index 8529595e896..fc70d2ffe90 100644
--- a/ui/src/pages/config/quick.ts
+++ b/ui/src/pages/config/quick.ts
@@ -23,6 +23,7 @@ import {
 } from "../../components/settings-ui.ts";
 import { t, type Locale } from "../../i18n/index.ts";
 import { formatBytes } from "../../lib/agents/display.ts";
+import { BASE_THINKING_LEVELS } from "../../lib/chat/thinking.ts";
 import type { ConfigAutoSaveStatus } from "../../lib/config/index.ts";
 import { formatDurationHuman } from "../../lib/format.ts";
 import { renderLanguageSelect } from "./language-select.ts";
@@ -67,7 +68,9 @@ type QuickSettingsProps = {
   version: string;
 };
 
-const THINKING_LEVELS = ["off", "low", "medium", "high"];
+// The compact General hub intentionally omits "minimal"; the full list stays
+// available on session-level pickers.
+const THINKING_LEVELS = BASE_THINKING_LEVELS.filter((level) => level !== "minimal");
 
 /** Section wrapper that keeps the stable settings-search scroll target ids. */
 function renderTargetSection(
@@ -97,6 +100,7 @@ function renderGeneralSection(props: QuickSettingsProps) {
   return renderSettingsSection({ title: t("nav.settingsGeneral") }, [
     renderSettingsRow({
       title: t("quickSettings.language"),
+      description: t("configView.syncedHint"),
       control: renderLanguageSelect(props.locale, props.onLocaleChange),
     }),
   ]);
diff --git a/ui/src/pages/config/security.test.ts b/ui/src/pages/config/security.test.ts
index 1679f162a75..0efa4373f26 100644
--- a/ui/src/pages/config/security.test.ts
+++ b/ui/src/pages/config/security.test.ts
@@ -94,9 +94,9 @@ describe("renderSecurity", () => {
     browserInput.dispatchEvent(new Event("change"));
     expect(onBrowserEnabledToggle).toHaveBeenCalledWith(true);
 
-    selectRadio(expectButtonByText(container, "full"));
+    selectRadio(expectButtonByText(container, "Full"));
     expect(onToolProfileChange).toHaveBeenCalledWith("full");
-    const activeProfile = expectButtonByText(container, "messaging");
+    const activeProfile = expectButtonByText(container, "Messaging");
     expect(activeProfile.classList.contains("settings-segmented__btn--active")).toBe(true);
   });
 
@@ -106,7 +106,7 @@ describe("renderSecurity", () => {
 
     render(renderSecurity(createProps({ configBusy: true, onToolProfileChange })), container);
 
-    const profileButton = expectButtonByText(expectRowByTitle(container, "Tool profile"), "full");
+    const profileButton = expectButtonByText(expectRowByTitle(container, "Tool profile"), "Full");
     expect(
       (profileButton.closest("wa-radio-group") as HTMLElement & { disabled?: boolean }).disabled,
     ).toBe(true);
diff --git a/ui/src/pages/config/security.ts b/ui/src/pages/config/security.ts
index 1a1b742f74f..44686f7095f 100644
--- a/ui/src/pages/config/security.ts
+++ b/ui/src/pages/config/security.ts
@@ -12,6 +12,7 @@ import {
   renderSettingsValue,
 } from "../../components/settings-ui.ts";
 import { t } from "../../i18n/index.ts";
+import { PROFILE_OPTIONS } from "../../lib/agents/display.ts";
 
 export type SecurityOverview = {
   gatewayAuth: string;
@@ -32,14 +33,16 @@ type SecurityViewProps = {
   editor: TemplateResult;
 };
 
-const TOOL_PROFILES = ["minimal", "coding", "messaging", "full"];
-
 function renderSecurityOverview(props: SecurityViewProps) {
   const { gatewayAuth, execPolicy, deviceAuth, browserEnabled, toolProfile } = props.security;
   const normalizedToolProfile = toolProfile.trim() || "full";
-  const toolProfiles = TOOL_PROFILES.includes(normalizedToolProfile)
-    ? TOOL_PROFILES
-    : [...TOOL_PROFILES, normalizedToolProfile];
+  const profileOptions = PROFILE_OPTIONS.map((profile) => ({
+    value: profile.id as string,
+    label: t(profile.labelKey),
+  }));
+  if (!profileOptions.some((option) => option.value === normalizedToolProfile)) {
+    profileOptions.push({ value: normalizedToolProfile, label: normalizedToolProfile });
+  }
   return renderSettingsSection({ title: t("quickSettings.security.title") }, [
     renderSettingsRow({
       title: t("quickSettings.security.gatewayAuth"),
@@ -63,7 +66,7 @@ function renderSecurityOverview(props: SecurityViewProps) {
       stacked: true,
       control: renderSettingsSegmented({
         value: normalizedToolProfile,
-        options: toolProfiles.map((profile) => ({ value: profile, label: profile })),
+        options: profileOptions,
         disabled: props.configBusy,
         onChange: (profile) => props.onToolProfileChange?.(profile),
       }),
diff --git a/ui/src/pages/config/settings-search.test.ts b/ui/src/pages/config/settings-search.test.ts
index 0aef30b06a6..66ba835b013 100644
--- a/ui/src/pages/config/settings-search.test.ts
+++ b/ui/src/pages/config/settings-search.test.ts
@@ -201,6 +201,23 @@ describe("findSettingsSearchBlocks", () => {
     ]);
   });
 
+  it("routes workspace queries to the sessions-hub pages", () => {
+    const matches = findSettingsSearchBlocks({
+      query: "worktree",
+      schema: null,
+      value: null,
+      uiHints: {},
+    });
+
+    expect(matches).toEqual([
+      expect.objectContaining({
+        routeId: "worktrees",
+        label: "Managed Worktrees",
+        hash: "",
+      }),
+    ]);
+  });
+
   it("does not create block results for an empty query", () => {
     expect(
       findSettingsSearchBlocks({
diff --git a/ui/src/pages/config/settings-search.ts b/ui/src/pages/config/settings-search.ts
index c7fc8755718..05e15aa1765 100644
--- a/ui/src/pages/config/settings-search.ts
+++ b/ui/src/pages/config/settings-search.ts
@@ -187,10 +187,35 @@ const COMMUNICATION_SETTINGS_BLOCKS = {
   },
 } as const satisfies Record<string, StaticSettingsBlockDescriptor>;
 
+// Sessions-hub workspace pages have no schema-backed config section, so they
+// only surface in search through these static entries.
+const WORKSPACE_SETTINGS_BLOCKS = {
+  sessions: {
+    routeId: "sessions",
+    labelKey: "sessionsView.title",
+    hash: "",
+    searchKeys: ["sessionsView.subtitle", "sessionsView.archivedOnly"],
+    aliases: "history archive overrides",
+  },
+  worktrees: {
+    routeId: "worktrees",
+    labelKey: "worktrees.title",
+    hash: "",
+    searchKeys: [
+      "worktrees.subtitle",
+      "worktrees.cleanupTitle",
+      "worktrees.cleanupMaxCount",
+      "worktrees.cleanupMaxSize",
+    ],
+    aliases: "git checkout branch cleanup",
+  },
+} as const satisfies Record<string, StaticSettingsBlockDescriptor>;
+
 const STATIC_SETTINGS_BLOCKS: readonly StaticSettingsBlockDescriptor[] = [
   ...Object.values(GENERAL_SETTINGS_BLOCKS),
   ...Object.values(APPEARANCE_SETTINGS_BLOCKS),
   ...Object.values(COMMUNICATION_SETTINGS_BLOCKS),
+  ...Object.values(WORKSPACE_SETTINGS_BLOCKS),
 ];
 
 const COMMUNICATION_SECTIONS = new Set<string>(COMMUNICATION_SECTION_KEYS);
diff --git a/ui/src/pages/config/view.ts b/ui/src/pages/config/view.ts
index 313d9c800f5..cf18d467b2f 100644
--- a/ui/src/pages/config/view.ts
+++ b/ui/src/pages/config/view.ts
@@ -1110,7 +1110,9 @@ function renderChatPreferencesSection(props: ConfigProps) {
       <div class="settings-section__header">
         <h2 class="settings-section__heading">${t("configView.chatPrefs.title")}</h2>
       </div>
-      <p class="settings-section__desc">${t("configView.chatPrefs.hint")}</p>
+      <p class="settings-section__desc">
+        ${t("configView.chatPrefs.hint")} ${t("configView.syncedHint")}
+      </p>
       <div class="settings-group">
         ${renderSettingsSelectRow({
           title: t("chat.sendShortcut"),
@@ -1287,7 +1289,9 @@ function renderAppearanceSection(props: ConfigProps) {
         <div class="settings-section__header">
           <h2 class="settings-section__heading">${t("configView.appearance.theme")}</h2>
         </div>
-        <p class="settings-section__desc">${t("configView.appearance.chooseTheme")}</p>
+        <p class="settings-section__desc">
+          ${t("configView.appearance.chooseTheme")} ${t("configView.syncedHint")}
+        </p>
         <div class="settings-group">
           <div class="settings-row settings-row--stacked">
             <div class="settings-theme-grid">
diff --git a/ui/src/pages/profile/identity-section.ts b/ui/src/pages/profile/identity-section.ts
index 5de3f3f33d2..69048080673 100644
--- a/ui/src/pages/profile/identity-section.ts
+++ b/ui/src/pages/profile/identity-section.ts
@@ -1,5 +1,5 @@
 // Profile identity section: local user avatar plus the assistant's configured
-// avatar. Moved from the General quick-settings page so identity has one home.
+// avatar. Moved from the General settings page so identity has one home.
 import { sliceUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { html, nothing } from "lit";
 import {
diff --git a/ui/src/styles/config-quick.css b/ui/src/styles/config-quick.css
index 082e8a6b3c3..ad73e90f4d6 100644
--- a/ui/src/styles/config-quick.css
+++ b/ui/src/styles/config-quick.css
@@ -41,31 +41,6 @@ openclaw-logs-page {
   max-height: none;
 }
 
-/* Persistent Simple/Advanced switch in the page header; keeps the way back
-   from advanced settings visible at all times. */
-.config-view-toggle {
-  flex: 0 0 auto;
-  align-self: center;
-}
-
-/* Mobile fallback: layout.mobile.css hides .content-header at small widths,
-   which would strand users in advanced mode with no way back. Mirror the
-   switch in an in-body row that only shows when the header is hidden. */
-.config-view-toggle-row {
-  display: none;
-}
-
-@media (max-width: 768px), (max-width: 932px) and (max-height: 500px) and (orientation: landscape) {
-  .config-view-toggle-row {
-    display: flex;
-    justify-content: flex-end;
-    width: 100%;
-    max-width: 760px;
-    margin: 0 auto;
-    padding: var(--space-3) var(--space-4) 0;
-  }
-}
-
 /* ── Config Accordion Nav (Advanced Settings, rendered by view.ts) ── */
 
 .config-accordion-nav {
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index 996e6cf42cc..c95d374aca5 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -229,8 +229,7 @@ html.openclaw-native-web-chrome .shell:not(.shell--mobile-nav) .sidebar-brand .s
 }
 
 .shell--settings .content-header,
-.shell--settings .settings-workspace,
-.shell--settings .config-view-toggle-row {
+.shell--settings .settings-workspace {
   width: 100%;
   max-width: 1120px;
   margin-inline: auto;
diff --git a/ui/src/styles/settings.css b/ui/src/styles/settings.css
index 36bfaaa5977..d859c334dc4 100644
--- a/ui/src/styles/settings.css
+++ b/ui/src/styles/settings.css
@@ -27,8 +27,7 @@
   width: 100%;
 }
 
-.content-header + .settings-workspace,
-.config-view-toggle-row + .settings-workspace {
+.content-header + .settings-workspace {
   margin-top: var(--space-5);
 }
 
@@ -53,14 +52,12 @@
 /* The page headline adopts the column of the page below it; without this the
    shell caps headers at 1120px while narrow pages use a 760px column, leaving
    the title floating left of the content. */
-.shell--settings .content:has(.settings-page) .content-header,
-.shell--settings .content:has(.settings-page) .config-view-toggle-row {
+.shell--settings .content:has(.settings-page) .content-header {
   max-width: 760px;
   padding-inline: var(--space-4);
 }
 
-.shell--settings .content:has(.settings-page--wide) .content-header,
-.shell--settings .content:has(.settings-page--wide) .config-view-toggle-row {
+.shell--settings .content:has(.settings-page--wide) .content-header {
   max-width: 1120px;
 }
 

From c989b8a519db4ea337c7b91f37b6a983472cddda Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:16:30 +0100
Subject: [PATCH 42/76] fix(ui): settings language picker was oversized and
 unthemed (#110621)

* fix(ui): settings language picker matches the settings design language

* fix(ui): keep Web Awesome available-height bound in language listbox cap

* fix(ui): restore forced-colors focus outlines for the language picker
---
 ui/src/styles/settings.css | 90 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 87 insertions(+), 3 deletions(-)

diff --git a/ui/src/styles/settings.css b/ui/src/styles/settings.css
index d859c334dc4..c1ae6ec56fb 100644
--- a/ui/src/styles/settings.css
+++ b/ui/src/styles/settings.css
@@ -416,12 +416,18 @@ wa-radio-group.settings-segmented::part(radios) {
 .settings-select {
   width: 100%;
   min-width: 0;
+  font: inherit;
+  font-size: var(--control-ui-input-text-size);
+}
+
+/* Native controls own their box. wa-select draws the same box on its shadow
+   combobox part below; host chrome would double-border the web component. */
+.settings-input,
+select.settings-select {
   border: 1px solid color-mix(in srgb, var(--border) 70%, transparent);
   border-radius: var(--radius-md);
   background: color-mix(in srgb, var(--bg) 80%, var(--bg-elevated) 20%);
   color: var(--text);
-  font: inherit;
-  font-size: var(--control-ui-input-text-size);
   padding: 7px 10px;
   transition: border-color var(--duration-fast) var(--ease-out);
 }
@@ -495,12 +501,90 @@ wa-radio-group.settings-segmented::part(radios) {
 }
 
 .settings-input:focus-visible,
-.settings-select:focus-visible {
+select.settings-select:focus-visible {
+  outline: none;
+  border-color: color-mix(in srgb, var(--accent) 55%, var(--border) 45%);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 18%, transparent);
+}
+
+/* ── Web Awesome select ── */
+
+wa-select.settings-select {
+  --wa-form-control-activated-color: var(--accent);
+}
+
+wa-select.settings-select::part(combobox) {
+  min-height: var(--settings-control-height);
+  padding-inline: 10px;
+  border: 1px solid color-mix(in srgb, var(--border) 70%, transparent);
+  border-radius: var(--radius-md);
+  background: color-mix(in srgb, var(--bg) 80%, var(--bg-elevated) 20%);
+  color: var(--text);
+  cursor: default;
+  transition: border-color var(--duration-fast) var(--ease-out);
+}
+
+/* [open] is required alongside :focus-within: Chromium does not propagate
+   :focus-within to the host while a slotted option holds focus, so the open
+   state must key off the reflected attribute or the stock ring leaks through. */
+wa-select.settings-select[open]::part(combobox),
+wa-select.settings-select:focus-within::part(combobox) {
   outline: none;
   border-color: color-mix(in srgb, var(--accent) 55%, var(--border) 45%);
   box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 18%, transparent);
 }
 
+wa-select.settings-select::part(expand-icon) {
+  margin-inline-start: var(--space-2);
+  font-size: var(--control-ui-text-sm);
+  color: var(--muted);
+}
+
+wa-select.settings-select::part(listbox) {
+  /* Keep Web Awesome's collision-aware bound in the cap; replacing it outright
+     would let the listbox overflow when the popup has little room to open. */
+  max-height: min(320px, var(--auto-size-available-height, calc(100vh - 48px)));
+  padding: 6px;
+  border: 1px solid color-mix(in srgb, var(--border-strong) 86%, transparent);
+  border-radius: var(--radius-md);
+  background: var(--bg-elevated);
+  box-shadow: var(--shadow-lg);
+  color: var(--text);
+}
+
+wa-select.settings-select wa-option {
+  padding: 6px 8px;
+  border-radius: calc(var(--radius-md) - 4px);
+  font-size: var(--control-ui-text-md);
+  color: var(--text);
+  cursor: default;
+}
+
+/* The roving "current" option already carries the accent fill; the global
+   :focus-visible accent outline on top of it is pure noise. */
+wa-select.settings-select wa-option:focus-visible {
+  outline: none;
+}
+
+wa-select.settings-select wa-option:state(current) {
+  color: var(--accent-foreground);
+}
+
+/* Forced colors suppresses the box-shadow ring and accent fill that stand in
+   for the outlines removed above, so restore system-color outlines there. */
+@media (forced-colors: active) {
+  wa-select.settings-select[open]::part(combobox),
+  wa-select.settings-select:focus-within::part(combobox) {
+    outline: 2px solid SelectedItem;
+    outline-offset: 2px;
+  }
+
+  wa-select.settings-select wa-option:focus-visible {
+    outline: 2px solid SelectedItem;
+    outline-offset: 2px;
+  }
+}
+
 textarea.settings-input {
   min-height: 88px;
   resize: vertical;

From 01a9e1d398fd12970e936335811f13ee913e29c1 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:16:49 +0100
Subject: [PATCH 43/76] feat(memory): default cross-conversation recall for
 personal installs (#110597)

* feat(memory): default private recall for personal installs

* fix(memory): repair remember-across CI checks
---
 docs/concepts/active-memory.md                | 20 ++++---
 docs/reference/memory-config.md               | 11 ++--
 extensions/active-memory/index.test.ts        | 19 +++++-
 extensions/active-memory/session-policy.ts    | 19 ++----
 .../src/host/backend-config.test.ts           |  3 +-
 .../src/host/backend-config.ts                |  3 +-
 .../memory-host-sdk/src/host/config-utils.ts  | 33 ++++++++++-
 scripts/plugin-sdk-surface-report.mjs         |  6 +-
 src/agents/memory-search.test.ts              | 58 ++++++++++++++++++-
 src/agents/memory-search.ts                   |  4 +-
 src/commands/doctor-memory-search.test.ts     | 12 ++--
 src/commands/doctor-memory-search.ts          | 23 +++-----
 src/commands/doctor-state-integrity.test.ts   |  5 ++
 src/config/schema.help.models.ts              |  2 +-
 src/memory-host-sdk/host/config-utils.ts      |  2 +
 .../memory-core-host-runtime-core.ts          |  1 +
 16 files changed, 162 insertions(+), 59 deletions(-)
 create mode 100644 src/memory-host-sdk/host/config-utils.ts

diff --git a/docs/concepts/active-memory.md b/docs/concepts/active-memory.md
index bd45f94554a..57d3f01ec30 100644
--- a/docs/concepts/active-memory.md
+++ b/docs/concepts/active-memory.md
@@ -35,11 +35,13 @@ private conversations with one per-agent setting:
 }
 ```
 
-The setting is off by default. When enabled, OpenClaw indexes that agent's
-session transcripts and runs an Active Memory retrieval pass before eligible
-private replies. The pass can read relevant transcript excerpts from the same
-agent's other private conversations. It excludes the conversation already
-being answered.
+The setting defaults on for personal installs: global `session.dmScope` must be
+unset or `"main"`, and no binding may override `session.dmScope`. Any configured
+DM isolation defaults it off. An explicit `true` or `false` always wins. When
+enabled, OpenClaw indexes that agent's session transcripts and runs an Active
+Memory retrieval pass before eligible private replies. The pass can read
+relevant transcript excerpts from the same agent's other private conversations.
+It excludes the conversation already being answered.
 
 The privacy boundary is fixed:
 
@@ -156,8 +158,8 @@ personalization would be surprising.
 Active Memory has two activation paths:
 
 1. **Remember across conversations** automatically targets agents whose
-   `memorySearch.rememberAcrossConversations` setting is enabled, but only for
-   private direct or persistent explicit UI conversations.
+   effective `memorySearch.rememberAcrossConversations` setting is enabled, but
+   only for private direct or persistent explicit UI conversations.
 2. **Advanced Active Memory** targets agent IDs listed in
    `plugins.entries.active-memory.config.agents` and applies the plugin's chat
    type and chat ID controls.
@@ -727,8 +729,8 @@ while warm-up finishes.
 If active memory is not showing up where you expect:
 
 1. Confirm the plugin is enabled under `plugins.entries.active-memory.enabled`.
-2. For Remember across conversations, confirm the agent's
-   `memorySearch.rememberAcrossConversations` setting is `true`, run
+2. For Remember across conversations, confirm the agent's effective
+   `memorySearch.rememberAcrossConversations` setting is enabled, run
    `openclaw doctor` to verify the current memory provider supports protected
    transcript recall, and confirm `config.toolsAllow` includes `memory_search`
    when explicitly configured. For advanced Active Memory, confirm the agent ID
diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md
index 33f6e447eba..672b883784b 100644
--- a/docs/reference/memory-config.md
+++ b/docs/reference/memory-config.md
@@ -44,9 +44,9 @@ transcript persistence, and safe rollout guidance.
 
 ## Remember across conversations
 
-| Key                           | Type      | Default | Description                                                                    |
-| ----------------------------- | --------- | ------- | ------------------------------------------------------------------------------ |
-| `rememberAcrossConversations` | `boolean` | `false` | Use relevant context from this agent's other recognized private conversations. |
+| Key                           | Type      | Default                                                    | Description                                                                    |
+| ----------------------------- | --------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `rememberAcrossConversations` | `boolean` | On for personal installs; off with configured DM isolation | Use relevant context from this agent's other recognized private conversations. |
 
 Configure it per agent when only a trusted personal agent should use
 cross-conversation transcript recall:
@@ -67,7 +67,10 @@ cross-conversation transcript recall:
 ```
 
 The value follows normal `agents.defaults.memorySearch` inheritance with a
-per-agent override. Enabling it implies session transcript indexing and
+per-agent override. When unset, it defaults on only if global
+`session.dmScope` is unset or `"main"` and no binding has a `session.dmScope`
+override. Any configured DM isolation defaults it off. An explicit `true` or
+`false` always wins. Enabling it implies session transcript indexing and
 adds `sessions` to the agent's resolved memory sources. With QMD, it also
 enables that agent's session export; no separate
 `memory.qmd.sessions.enabled` setting is required for this mode.
diff --git a/extensions/active-memory/index.test.ts b/extensions/active-memory/index.test.ts
index 0fa561aa96a..c9b3489a3e6 100644
--- a/extensions/active-memory/index.test.ts
+++ b/extensions/active-memory/index.test.ts
@@ -15,6 +15,7 @@ import { appendSessionTranscriptMessageByIdentity } from "openclaw/plugin-sdk/se
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { applyCliRuntimeRecallTimeoutDefault } from "./config.js";
 import plugin, { testing } from "./index.js";
+import { hasRememberAcrossConversationsAgent } from "./session-policy.js";
 
 // Match only lone surrogates so valid supplementary-plane characters remain allowed.
 const UNPAIRED_SURROGATE_RE =
@@ -505,6 +506,7 @@ describe("active-memory plugin", () => {
     }).clear();
     runEmbeddedAgent.mockReset();
     configFile = {
+      session: { dmScope: "per-peer" },
       plugins: {
         entries: {
           "active-memory": {
@@ -521,6 +523,7 @@ describe("active-memory plugin", () => {
       logging: true,
     });
     api.config = {
+      session: { dmScope: "per-peer" },
       agents: {
         defaults: {
           model: {
@@ -628,6 +631,19 @@ describe("active-memory plugin", () => {
     expect(hookOptions.before_prompt_build?.timeoutMs).toBe(153_000);
   });
 
+  it("does not synthesize a main agent when every configured agent opts out", () => {
+    expect(
+      hasRememberAcrossConversationsAgent({
+        agents: {
+          list: [
+            { id: "personal", memorySearch: { rememberAcrossConversations: false } },
+            { id: "support", memorySearch: { rememberAcrossConversations: false } },
+          ],
+        },
+      }),
+    ).toBe(false);
+  });
+
   it("keeps the outer hook timeout at the live-config ceiling", () => {
     api.pluginConfig = {
       agents: ["main"],
@@ -1016,14 +1032,13 @@ describe("active-memory plugin", () => {
     }
   });
 
-  it("runs product recall without an explicit Active Memory config entry", async () => {
+  it("runs product recall by default for a personal install without Active Memory config", async () => {
     configFile = {
       agents: {
         list: [
           {
             id: "personal",
             model: { primary: "github-copilot/gpt-5.4-mini" },
-            memorySearch: { rememberAcrossConversations: true },
           },
         ],
       },
diff --git a/extensions/active-memory/session-policy.ts b/extensions/active-memory/session-policy.ts
index 087644dc33e..02cd296eb09 100644
--- a/extensions/active-memory/session-policy.ts
+++ b/extensions/active-memory/session-policy.ts
@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { resolveRememberAcrossConversations } from "openclaw/plugin-sdk/memory-core-host-runtime-core";
 import {
   normalizePluginsConfig,
   resolvePluginConfigObject,
@@ -127,23 +128,13 @@ function isActiveMemoryPluginEnabled(cfg: OpenClawConfig): boolean {
 }
 
 function hasRememberAcrossConversationsAgent(cfg: OpenClawConfig): boolean {
-  return (
-    cfg.agents?.defaults?.memorySearch?.rememberAcrossConversations === true ||
-    cfg.agents?.list?.some((agent) => agent.memorySearch?.rememberAcrossConversations === true) ===
-      true
-  );
+  const configuredAgentIds = cfg.agents?.list?.map((agent) => agent.id) ?? [];
+  const agentIds = configuredAgentIds.length > 0 ? configuredAgentIds : ["main"];
+  return agentIds.some((agentId) => resolveRememberAcrossConversations(cfg, agentId));
 }
 
 function shouldRememberAcrossConversations(cfg: OpenClawConfig, agentId: string): boolean {
-  const normalizedAgentId = agentId.trim().toLowerCase();
-  const agent = cfg.agents?.list?.find(
-    (candidate) => candidate.id?.trim().toLowerCase() === normalizedAgentId,
-  );
-  return (
-    agent?.memorySearch?.rememberAcrossConversations ??
-    cfg.agents?.defaults?.memorySearch?.rememberAcrossConversations ??
-    false
-  );
+  return resolveRememberAcrossConversations(cfg, agentId);
 }
 
 function updateActiveMemoryGlobalEnabledInConfig(
diff --git a/packages/memory-host-sdk/src/host/backend-config.test.ts b/packages/memory-host-sdk/src/host/backend-config.test.ts
index b0e11a9183e..e6f5927cf5f 100644
--- a/packages/memory-host-sdk/src/host/backend-config.test.ts
+++ b/packages/memory-host-sdk/src/host/backend-config.test.ts
@@ -132,9 +132,10 @@ describe("resolveMemoryBackendConfig", () => {
     expect(requireQmdCollection(resolved, "memory-root-main").pattern).toBe("MEMORY.md");
   });
 
-  it("keeps QMD session export off by default", () => {
+  it("keeps QMD session export off by default when DM isolation is configured", () => {
     const cfg = {
       agents: { defaults: { workspace: "/tmp/memory-test" } },
+      session: { dmScope: "per-peer" },
       memory: { backend: "qmd", qmd: {} },
     } as OpenClawConfig;
 
diff --git a/packages/memory-host-sdk/src/host/backend-config.ts b/packages/memory-host-sdk/src/host/backend-config.ts
index a09f446d1e2..c9f0699ac9e 100644
--- a/packages/memory-host-sdk/src/host/backend-config.ts
+++ b/packages/memory-host-sdk/src/host/backend-config.ts
@@ -495,8 +495,7 @@ export function resolveMemoryBackendConfig(params: {
     sessions: resolveSessionConfig(
       {
         ...qmdCfg?.sessions,
-        enabled:
-          qmdCfg?.sessions?.enabled === true || memorySearch?.rememberAcrossConversations === true,
+        enabled: qmdCfg?.sessions?.enabled === true || memorySearch?.rememberAcrossConversations,
       },
       workspaceDir,
       // Remember-only export is search-only for trusted recall; ordinary
diff --git a/packages/memory-host-sdk/src/host/config-utils.ts b/packages/memory-host-sdk/src/host/config-utils.ts
index 1c4112d28b1..f697835df80 100644
--- a/packages/memory-host-sdk/src/host/config-utils.ts
+++ b/packages/memory-host-sdk/src/host/config-utils.ts
@@ -18,6 +18,7 @@ export { splitShellArgs } from "./openclaw-runtime-io.js";
 
 /** Chat shape used by memory send-policy matching. */
 type ChatType = "direct" | "group" | "channel";
+type DmScope = "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer";
 /** Memory backend selected by user config. */
 export type MemoryBackend = "builtin" | "qmd";
 /** Citation injection behavior for memory search results. */
@@ -156,6 +157,10 @@ export type OpenClawConfig = {
     };
     list?: AgentConfig[];
   };
+  session?: {
+    dmScope?: DmScope;
+  };
+  bindings?: unknown[];
   memory?: MemoryConfig;
   models?: {
     providers?: Record<
@@ -169,6 +174,31 @@ export type OpenClawConfig = {
   };
 };
 
+export function resolveRememberAcrossConversations(cfg: OpenClawConfig, agentId: string): boolean {
+  const defaults = cfg.agents?.defaults?.memorySearch;
+  const overrides = resolveAgentConfig(cfg, agentId)?.memorySearch;
+  const explicit = overrides?.rememberAcrossConversations ?? defaults?.rememberAcrossConversations;
+  if (explicit !== undefined) {
+    return explicit;
+  }
+  // Recall is per-agent/private-shaped, not per-sender. Any DM isolation signals a
+  // multi-user install, where silently recalling across senders would leak context.
+  return (
+    (cfg.session?.dmScope === undefined || cfg.session.dmScope === "main") &&
+    !cfg.bindings?.some((binding) => {
+      if (!binding || typeof binding !== "object") {
+        return false;
+      }
+      const session = (binding as { session?: unknown }).session;
+      return (
+        Boolean(session) &&
+        typeof session === "object" &&
+        (session as { dmScope?: unknown }).dmScope !== undefined
+      );
+    })
+  );
+}
+
 /** Root memory filename used in agent workspaces. */
 export const MEMORY_HOST_ROOT_FILENAME = "MEMORY.md";
 
@@ -341,8 +371,7 @@ export function resolveMemoryHostSearchPathConfig(
   ]);
   return {
     enabled,
-    rememberAcrossConversations:
-      overrides?.rememberAcrossConversations ?? defaults?.rememberAcrossConversations ?? false,
+    rememberAcrossConversations: resolveRememberAcrossConversations(cfg, agentId),
     extraPaths: uniqueStrings(rawPaths),
   };
 }
diff --git a/scripts/plugin-sdk-surface-report.mjs b/scripts/plugin-sdk-surface-report.mjs
index 16af5621b8f..e4448e93b8e 100644
--- a/scripts/plugin-sdk-surface-report.mjs
+++ b/scripts/plugin-sdk-surface-report.mjs
@@ -266,9 +266,10 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
       // +3: question-gateway-runtime resolver plus request/result types.
       // +1: async memory prompt preparation registration.
       // +1: canonical memory host event normalization for SQLite storage.
+      // +1: centralized remember-across-conversations effective-default resolver.
       // +4: gateway-backed harness question runner, claim/cancel helpers, and caller type.
       // Harvest: internal question runtime exports -2.
-      8156,
+      8157,
       env,
     ),
     publicFunctionExports: readPluginSdkSurfaceBudgetEnv(
@@ -305,9 +306,10 @@ export function readPluginSdkSurfaceBudgets(env = process.env) {
       // +1: question-gateway-runtime resolver.
       // +1: async memory prompt preparation registration.
       // +1: canonical memory host event normalization for SQLite storage.
+      // +1: centralized remember-across-conversations effective-default resolver.
       // +3: gateway-backed harness question runner and claim/cancel helpers.
       // Harvest: internal question runtime callable -1.
-      4538,
+      4539,
       env,
     ),
     publicDeprecatedExports: readPluginSdkSurfaceBudgetEnv(
diff --git a/src/agents/memory-search.test.ts b/src/agents/memory-search.test.ts
index fe2a3fd549d..5b0150c59ac 100644
--- a/src/agents/memory-search.test.ts
+++ b/src/agents/memory-search.test.ts
@@ -1,6 +1,7 @@
 // Verifies memory-search config resolution across providers, sync, and batching.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
+import { resolveRememberAcrossConversations } from "../memory-host-sdk/host/config-utils.js";
 import {
   clearEmbeddingProviders,
   listRegisteredEmbeddingProviders,
@@ -234,9 +235,63 @@ describe("memory search config", () => {
     expect(resolved).toBeNull();
   });
 
-  it("keeps cross-conversation recall off by default", () => {
+  it.each([
+    { name: "unset with main scope", cfg: {}, expected: true },
+    {
+      name: "unset with per-channel-peer scope",
+      cfg: { session: { dmScope: "per-channel-peer" } },
+      expected: false,
+    },
+    {
+      name: "unset with main scope and a binding override",
+      cfg: {
+        session: { dmScope: "main" },
+        bindings: [
+          {
+            agentId: "main",
+            match: { channel: "telegram" },
+            session: { dmScope: "per-peer" },
+          },
+        ],
+      },
+      expected: false,
+    },
+    {
+      name: "explicit false with main scope",
+      cfg: {
+        session: { dmScope: "main" },
+        agents: { defaults: { memorySearch: { rememberAcrossConversations: false } } },
+      },
+      expected: false,
+    },
+    {
+      name: "explicit true with per-peer scope",
+      cfg: {
+        session: { dmScope: "per-peer" },
+        agents: { defaults: { memorySearch: { rememberAcrossConversations: true } } },
+      },
+      expected: true,
+    },
+  ])("resolves remember-across-conversations for $name", ({ cfg, expected }) => {
+    expect(resolveRememberAcrossConversations(asConfig(cfg as OpenClawConfig), "main")).toBe(
+      expected,
+    );
+  });
+
+  it("enables cross-conversation recall by default for a personal install", () => {
     const resolved = resolveMemorySearchConfig(asConfig({}), "main");
 
+    expect(resolved?.rememberAcrossConversations).toBe(true);
+    expect(resolved?.experimental.sessionMemory).toBe(true);
+    expect(resolved?.sources).toEqual(["memory", "sessions"]);
+  });
+
+  it("keeps cross-conversation recall off by default for isolated DMs", () => {
+    const resolved = resolveMemorySearchConfig(
+      asConfig({ session: { dmScope: "per-channel-peer" } }),
+      "main",
+    );
+
     expect(resolved?.rememberAcrossConversations).toBe(false);
     expect(resolved?.experimental.sessionMemory).toBe(false);
     expect(resolved?.sources).toEqual(["memory"]);
@@ -887,6 +942,7 @@ describe("memory search config", () => {
             id: "main",
             default: true,
             memorySearch: {
+              rememberAcrossConversations: false,
               experimental: { sessionMemory: false },
             },
           },
diff --git a/src/agents/memory-search.ts b/src/agents/memory-search.ts
index f4b380f0b62..d2a7821fd9e 100644
--- a/src/agents/memory-search.ts
+++ b/src/agents/memory-search.ts
@@ -15,6 +15,7 @@ import {
 } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig, MemorySearchConfig } from "../config/config.js";
 import type { SecretInput } from "../config/types.secrets.js";
+import { resolveRememberAcrossConversations } from "../memory-host-sdk/host/config-utils.js";
 import {
   isMemoryMultimodalEnabled,
   normalizeMemoryMultimodalSettings,
@@ -224,8 +225,7 @@ function mergeConfig(
   agentId: string,
 ): ResolvedMemorySearchConfig {
   const enabled = overrides?.enabled ?? defaults?.enabled ?? true;
-  const rememberAcrossConversations =
-    overrides?.rememberAcrossConversations ?? defaults?.rememberAcrossConversations ?? false;
+  const rememberAcrossConversations = resolveRememberAcrossConversations(cfg, agentId);
   const configuredSessionMemory =
     overrides?.experimental?.sessionMemory ?? defaults?.experimental?.sessionMemory ?? false;
   const sessionMemory = rememberAcrossConversations || configuredSessionMemory;
diff --git a/src/commands/doctor-memory-search.test.ts b/src/commands/doctor-memory-search.test.ts
index d847a4dfef5..6db2f1da252 100644
--- a/src/commands/doctor-memory-search.test.ts
+++ b/src/commands/doctor-memory-search.test.ts
@@ -483,6 +483,7 @@ describe("noteMemorySearchHealth", () => {
       remote: {},
     });
     const cfgWithLancedb = {
+      session: { dmScope: "per-peer" },
       plugins: {
         slots: { memory: "memory-lancedb" },
         entries: { "memory-lancedb": { enabled: true, config: { dbPath: ".openclaw/memory" } } },
@@ -504,6 +505,7 @@ describe("noteMemorySearchHealth", () => {
       remote: {},
     });
     const cfgWithSlotOnly = {
+      session: { dmScope: "per-peer" },
       plugins: { slots: { memory: "memory-lancedb" } },
     } as unknown as OpenClawConfig;
 
@@ -521,6 +523,7 @@ describe("noteMemorySearchHealth", () => {
       remote: {},
     });
     const cfgWithDisabledLancedb = {
+      session: { dmScope: "per-peer" },
       plugins: {
         slots: { memory: "memory-lancedb" },
         entries: { "memory-lancedb": { enabled: false } },
@@ -541,6 +544,7 @@ describe("noteMemorySearchHealth", () => {
       remote: {},
     });
     const cfgWithPlaceholderEntry = {
+      session: { dmScope: "per-peer" },
       plugins: {
         slots: { memory: "memory-lancedb" },
         entries: { "memory-lancedb": {} },
@@ -704,7 +708,7 @@ describe("noteMemorySearchHealth", () => {
       await noteMemorySearchHealth(qmdCfg, { skipQmdBinaryProbe: true });
 
       expect(firstNoteMessage()).toBe(
-        'Remember across conversations is enabled for agent "personal", but the current memory provider does not support protected private transcript recall. Turn off Remember across conversations or use that provider\'s own recall path; advanced Active Memory can still use its recall tools.',
+        'Remember across conversations is effectively enabled for agent "personal", but the current memory provider does not support protected private transcript recall. Set memorySearch.rememberAcrossConversations to false or use that provider\'s own recall path; advanced Active Memory can still use its recall tools.',
       );
     },
   );
@@ -726,7 +730,7 @@ describe("noteMemorySearchHealth", () => {
     await noteMemorySearchHealth(qmdCfg, { skipQmdBinaryProbe: true });
 
     expect(firstNoteMessage()).toBe(
-      'Remember across conversations is enabled for agent "personal", but the Active Memory plugin is disabled. Enable the plugin or turn off Remember across conversations.',
+      'Remember across conversations is effectively enabled for agent "personal", but the Active Memory plugin is disabled. Enable the plugin or set memorySearch.rememberAcrossConversations to false.',
     );
   });
 
@@ -774,7 +778,7 @@ describe("noteMemorySearchHealth", () => {
     await noteMemorySearchHealth(qmdCfg, { skipQmdBinaryProbe: true });
 
     expect(firstNoteMessage()).toBe(
-      'Remember across conversations is enabled for agent "personal", but Active Memory does not allow memory_search. Add memory_search to the plugin toolsAllow list or turn off Remember across conversations.',
+      'Remember across conversations is effectively enabled for agent "personal", but Active Memory does not allow memory_search. Add memory_search to the plugin toolsAllow list or set memorySearch.rememberAcrossConversations to false.',
     );
   });
 
@@ -792,7 +796,7 @@ describe("noteMemorySearchHealth", () => {
     await noteMemorySearchHealth(qmdCfg, { skipQmdBinaryProbe: true });
 
     expect(firstNoteMessage()).toBe(
-      'Remember across conversations is enabled for agent "personal", but memory search is disabled. Enable memory search or turn off Remember across conversations.',
+      'Remember across conversations is effectively enabled for agent "personal", but memory search is disabled. Enable memory search or set memorySearch.rememberAcrossConversations to false.',
     );
   });
 
diff --git a/src/commands/doctor-memory-search.ts b/src/commands/doctor-memory-search.ts
index f232f583445..87ec82e6bb3 100644
--- a/src/commands/doctor-memory-search.ts
+++ b/src/commands/doctor-memory-search.ts
@@ -30,6 +30,7 @@ import {
   checkQmdBinaryAvailability,
   resolveQmdBinaryUnavailableReason,
 } from "../memory-host-sdk/engine-qmd.js";
+import { resolveRememberAcrossConversations } from "../memory-host-sdk/host/config-utils.js";
 import { hasConfiguredMemorySecretInput } from "../memory-host-sdk/secret.js";
 import {
   auditDreamingArtifacts,
@@ -444,20 +445,12 @@ function listRememberAcrossConversationAgentIds(
   cfg: OpenClawConfig,
   defaultAgentId: string,
 ): string[] {
-  const defaultsEnabled = cfg.agents?.defaults?.memorySearch?.rememberAcrossConversations === true;
   const configuredAgents = cfg.agents?.list ?? [];
   const enabledAgentIds = configuredAgents
-    .filter(
-      (agent) =>
-        (agent.memorySearch?.rememberAcrossConversations ?? defaultsEnabled) &&
-        Boolean(agent.id?.trim()),
-    )
+    .filter((agent) => resolveRememberAcrossConversations(cfg, agent.id))
     .map((agent) => agent.id.trim());
-  const defaultEntry = configuredAgents.find(
-    (agent) => agent.id.trim().toLowerCase() === defaultAgentId.trim().toLowerCase(),
-  );
   if (
-    (defaultEntry?.memorySearch?.rememberAcrossConversations ?? defaultsEnabled) &&
+    resolveRememberAcrossConversations(cfg, defaultAgentId) &&
     !enabledAgentIds.some(
       (agentId) => agentId.toLowerCase() === defaultAgentId.trim().toLowerCase(),
     )
@@ -514,18 +507,18 @@ function noteRememberAcrossConversationsHealth(params: {
   for (const agentId of agentIds) {
     if (!activeMemoryAvailable) {
       params.noteFn(
-        `Remember across conversations is enabled for agent "${agentId}", but the Active Memory plugin is disabled. Enable the plugin or turn off Remember across conversations.`,
+        `Remember across conversations is effectively enabled for agent "${agentId}", but the Active Memory plugin is disabled. Enable the plugin or set memorySearch.rememberAcrossConversations to false.`,
         "Memory search",
       );
     }
     if (activeMemoryAvailable && !conversationRecallSupport.providerSupported) {
       params.noteFn(
-        `Remember across conversations is enabled for agent "${agentId}", but the current memory provider does not support protected private transcript recall. Turn off Remember across conversations or use that provider's own recall path; advanced Active Memory can still use its recall tools.`,
+        `Remember across conversations is effectively enabled for agent "${agentId}", but the current memory provider does not support protected private transcript recall. Set memorySearch.rememberAcrossConversations to false or use that provider's own recall path; advanced Active Memory can still use its recall tools.`,
         "Memory search",
       );
     } else if (activeMemoryAvailable && !conversationRecallSupport.memorySearchAllowed) {
       params.noteFn(
-        `Remember across conversations is enabled for agent "${agentId}", but Active Memory does not allow memory_search. Add memory_search to the plugin toolsAllow list or turn off Remember across conversations.`,
+        `Remember across conversations is effectively enabled for agent "${agentId}", but Active Memory does not allow memory_search. Add memory_search to the plugin toolsAllow list or set memorySearch.rememberAcrossConversations to false.`,
         "Memory search",
       );
     }
@@ -534,7 +527,7 @@ function noteRememberAcrossConversationsHealth(params: {
       !resolveMemorySearchConfig(params.cfg, agentId)
     ) {
       params.noteFn(
-        `Remember across conversations is enabled for agent "${agentId}", but memory search is disabled. Enable memory search or turn off Remember across conversations.`,
+        `Remember across conversations is effectively enabled for agent "${agentId}", but memory search is disabled. Enable memory search or set memorySearch.rememberAcrossConversations to false.`,
         "Memory search",
       );
     }
@@ -586,7 +579,7 @@ export async function noteMemorySearchHealth(
   if (!resolved) {
     noteFn(
       recallHealth.defaultAgentEnabled
-        ? `Remember across conversations is enabled for agent "${agentId}", but memory search is disabled. Enable memory search or turn off Remember across conversations.`
+        ? `Remember across conversations is effectively enabled for agent "${agentId}", but memory search is disabled. Enable memory search or set memorySearch.rememberAcrossConversations to false.`
         : "Memory search is explicitly disabled (enabled: false).",
       "Memory search",
     );
diff --git a/src/commands/doctor-state-integrity.test.ts b/src/commands/doctor-state-integrity.test.ts
index 784cc25bf97..3ca6f6dd290 100644
--- a/src/commands/doctor-state-integrity.test.ts
+++ b/src/commands/doctor-state-integrity.test.ts
@@ -233,6 +233,11 @@ describe("structured state integrity findings", () => {
 
 async function runOrphanTranscriptCheckWithQmdSessions(enabled: boolean, homeDir: string) {
   const cfg: OpenClawConfig = {
+    agents: {
+      defaults: {
+        memorySearch: { rememberAcrossConversations: false },
+      },
+    },
     memory: {
       backend: "qmd",
       qmd: {
diff --git a/src/config/schema.help.models.ts b/src/config/schema.help.models.ts
index 7aaf4feceb3..d3a72fb70c3 100644
--- a/src/config/schema.help.models.ts
+++ b/src/config/schema.help.models.ts
@@ -225,7 +225,7 @@ export const MODEL_FIELD_HELP: Record<string, string> = {
   "agents.defaults.memorySearch.enabled":
     "Master toggle for memory search indexing and retrieval behavior on this agent profile. Keep enabled for semantic recall, and disable when you want fully stateless responses.",
   "agents.defaults.memorySearch.rememberAcrossConversations":
-    "Use relevant context from this agent's other private conversations through protected transcript recall. Groups and channels stay separate. Enable this only for a personal or fully trusted agent.",
+    'Use relevant context from this agent\'s other private conversations through protected transcript recall. Defaults on only when global session.dmScope is unset or "main" and no binding overrides DM scope; any configured DM isolation defaults it off. An explicit true or false always wins.',
   "agents.defaults.memorySearch.sources":
     'Chooses which sources are indexed: "memory" reads MEMORY.md + memory files, and "sessions" includes transcript history. Keep ["memory"] unless you need recall from prior chat transcripts.',
   "agents.defaults.memorySearch.extraPaths":
diff --git a/src/memory-host-sdk/host/config-utils.ts b/src/memory-host-sdk/host/config-utils.ts
new file mode 100644
index 00000000000..a3ad1cb0400
--- /dev/null
+++ b/src/memory-host-sdk/host/config-utils.ts
@@ -0,0 +1,2 @@
+/** Core-facing memory host config helpers. */
+export { resolveRememberAcrossConversations } from "../../../packages/memory-host-sdk/src/host/config-utils.js";
diff --git a/src/plugin-sdk/memory-core-host-runtime-core.ts b/src/plugin-sdk/memory-core-host-runtime-core.ts
index 2a731dd3cbf..1fd8df39fe6 100644
--- a/src/plugin-sdk/memory-core-host-runtime-core.ts
+++ b/src/plugin-sdk/memory-core-host-runtime-core.ts
@@ -1,5 +1,6 @@
 // Memory core host runtime exports bridge memory host runtime-core APIs into the SDK.
 export { SILENT_REPLY_TOKEN } from "../../packages/memory-host-sdk/src/runtime-core.js";
+export { resolveRememberAcrossConversations } from "../../packages/memory-host-sdk/src/host/config-utils.js";
 export { DEFAULT_AGENT_COMPACTION_RESERVE_TOKENS_FLOOR } from "../agents/agent-settings.js";
 export {
   asToolParamsRecord,

From 0bbb862c55a5f3f71aa06a774be6593fc53e0a24 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:19:59 +0100
Subject: [PATCH 44/76] fix(gateway): keep setup.detect off the event loop so
 health stays live (#110625)

---
 config/knip.config.ts                         |   2 +
 scripts/release-check.ts                      |   1 +
 src/commands/onboard-inference.test.ts        |  20 ++
 src/commands/onboard-inference.ts             |   6 +-
 .../server-methods/system-agent.test.ts       |  15 +-
 src/gateway/server-methods/system-agent.ts    |   9 +-
 src/infra/tsdown-config.test.ts               |   1 +
 src/system-agent/probes.test.ts               |   1 +
 src/system-agent/probes.ts                    |   2 +
 .../setup-inference-detection.test.ts         | 125 ++++++++++++
 src/system-agent/setup-inference-detection.ts | 190 ++++++++++++++++++
 .../setup-inference-detection.worker.ts       |  36 ++++
 src/system-agent/setup-inference.ts           |   6 +-
 test/release-check.test.ts                    |   2 +
 tsdown.config.ts                              |   2 +
 15 files changed, 404 insertions(+), 14 deletions(-)
 create mode 100644 src/system-agent/setup-inference-detection.test.ts
 create mode 100644 src/system-agent/setup-inference-detection.ts
 create mode 100644 src/system-agent/setup-inference-detection.worker.ts

diff --git a/config/knip.config.ts b/config/knip.config.ts
index 883fabfacc0..77ce250f3c8 100644
--- a/config/knip.config.ts
+++ b/config/knip.config.ts
@@ -113,6 +113,8 @@ const rootEntries = [
   "src/audit/audit-event-writer.worker.ts!",
   "src/state/openclaw-database-verify.worker.ts!",
   "src/agents/model-provider-auth.worker.ts!",
+  // Loaded by URL from setup-inference-detection.ts; no static import edge exists.
+  "src/system-agent/setup-inference-detection.worker.ts!",
   // Split runtime loaded through a path assembled in subagent-registry.ts.
   "src/agents/subagent-registry.runtime.ts!",
   // Loaded lazily by the registry; its callbacks form the orphan-recovery runtime contract.
diff --git a/scripts/release-check.ts b/scripts/release-check.ts
index bf4cb08ed95..5ec9a0f6f8b 100755
--- a/scripts/release-check.ts
+++ b/scripts/release-check.ts
@@ -114,6 +114,7 @@ const requiredPathGroups = [
   "dist/audit/audit-event-writer.worker.js",
   "dist/config/sessions/session-transcript-reconcile.worker.js",
   "dist/state/openclaw-database-verify.worker.js",
+  "dist/system-agent/setup-inference-detection.worker.js",
   "dist/task-registry-control.runtime.js",
   "dist/telegram-ingress-worker.runtime.js",
   "dist/build-info.json",
diff --git a/src/commands/onboard-inference.test.ts b/src/commands/onboard-inference.test.ts
index 6530b01f3e3..e1dad014d30 100644
--- a/src/commands/onboard-inference.test.ts
+++ b/src/commands/onboard-inference.test.ts
@@ -36,6 +36,26 @@ describe("detectInferenceBackends", () => {
     expect(candidates).toEqual([]);
   });
 
+  it("does not offer external CLIs whose version probes time out", async () => {
+    const candidates = await detectInferenceBackends({
+      env: {},
+      platform: "linux",
+      deps: {
+        probeLocalCommand: async (command) => ({
+          command,
+          found: true,
+          timedOut: true,
+          error: "timed out after 1500ms",
+        }),
+        readClaudeCliCredentials: () => ({ type: "oauth" }),
+        readCodexCliCredentials: () => ({ type: "oauth" }),
+        readGeminiCliCredentials: () => ({ type: "oauth" }),
+      },
+    });
+
+    expect(candidates).toEqual([]);
+  });
+
   it("orders the ladder: existing model, env keys, then CLI logins", async () => {
     const candidates = await detectInferenceBackends({
       config: { agents: { defaults: { model: "zai/glm-5.2" } } },
diff --git a/src/commands/onboard-inference.ts b/src/commands/onboard-inference.ts
index 7d03bf3b7f7..f8d7a92cb03 100644
--- a/src/commands/onboard-inference.ts
+++ b/src/commands/onboard-inference.ts
@@ -237,7 +237,7 @@ export async function detectInferenceBackends(
     probe("gemini"),
   ]);
   const cliCandidates: InferenceBackendCandidate[] = [];
-  if (claudeProbe.found) {
+  if (claudeProbe.found && !claudeProbe.timedOut) {
     const credentials = detectCliCredentialState({
       probe: claudeProbe,
       hasStoredCredentials: readClaude() !== null,
@@ -251,7 +251,7 @@ export async function detectInferenceBackends(
       ...(credentials === undefined ? {} : { credentials }),
     });
   }
-  if (codexProbe.found) {
+  if (codexProbe.found && !codexProbe.timedOut) {
     const credentials = options.deps?.readCodexCliCredentials
       ? detectCliCredentialState({
           probe: codexProbe,
@@ -267,7 +267,7 @@ export async function detectInferenceBackends(
       ...(credentials === undefined ? {} : { credentials }),
     });
   }
-  if (geminiProbe.found) {
+  if (geminiProbe.found && !geminiProbe.timedOut) {
     // Gemini CLI stores its OAuth login in a plain file on every platform (no
     // keychain), so a missing credential file is a definitive logout signal.
     const credentials = readGemini() !== null;
diff --git a/src/gateway/server-methods/system-agent.test.ts b/src/gateway/server-methods/system-agent.test.ts
index 971cdc7a713..7651aaea940 100644
--- a/src/gateway/server-methods/system-agent.test.ts
+++ b/src/gateway/server-methods/system-agent.test.ts
@@ -29,6 +29,9 @@ const setupInferenceMocks = vi.hoisted(() => ({
   detectSetupInference: vi.fn(),
   verifySetupInference: vi.fn(),
 }));
+const setupInferenceDetectionMocks = vi.hoisted(() => ({
+  detectSetupInferenceIsolated: vi.fn(),
+}));
 const providerAuthChoiceMocks = vi.hoisted(() => ({
   applyAuthChoiceLoadedPluginProvider: vi.fn(),
 }));
@@ -42,6 +45,9 @@ vi.mock("../../system-agent/setup-inference.js", () => ({
   detectSetupInference: setupInferenceMocks.detectSetupInference,
   verifySetupInference: setupInferenceMocks.verifySetupInference,
 }));
+vi.mock("../../system-agent/setup-inference-detection.js", () => ({
+  detectSetupInferenceIsolated: setupInferenceDetectionMocks.detectSetupInferenceIsolated,
+}));
 vi.mock("../../plugins/provider-auth-choice.js", () => ({
   applyAuthChoiceLoadedPluginProvider: providerAuthChoiceMocks.applyAuthChoiceLoadedPluginProvider,
 }));
@@ -168,6 +174,7 @@ afterEach(() => {
   vi.restoreAllMocks();
   setupInferenceMocks.activateSetupInference.mockReset();
   setupInferenceMocks.detectSetupInference.mockReset();
+  setupInferenceDetectionMocks.detectSetupInferenceIsolated.mockReset();
   setupInferenceMocks.verifySetupInference.mockReset();
   providerAuthChoiceMocks.applyAuthChoiceLoadedPluginProvider.mockReset();
   setupSharedMocks.readSetupConfigFileSnapshot.mockReset();
@@ -443,10 +450,10 @@ describe("openclaw.chat", () => {
     expect(secondCall.ok).toBe(true);
   });
 
-  it("tracks setup detection until its RPC response is sent", async () => {
+  it("keeps read-only setup detection outside the serialized system-agent lane", async () => {
     const started = createDeferred();
     const release = createDeferred();
-    setupInferenceMocks.detectSetupInference.mockImplementation(async () => {
+    setupInferenceDetectionMocks.detectSetupInferenceIsolated.mockImplementation(async () => {
       started.resolve();
       await release.promise;
       return {
@@ -472,11 +479,11 @@ describe("openclaw.chat", () => {
     } as never);
 
     await started.promise;
-    expect(getCommandLaneSnapshot(CommandLane.SystemAgent).activeCount).toBe(1);
+    expect(getCommandLaneSnapshot(CommandLane.SystemAgent).activeCount).toBe(0);
     release.resolve();
     await pending;
 
-    expect(activeAtResponse).toEqual([1]);
+    expect(activeAtResponse).toEqual([0]);
     expect(getCommandLaneSnapshot(CommandLane.SystemAgent).activeCount).toBe(0);
   });
 
diff --git a/src/gateway/server-methods/system-agent.ts b/src/gateway/server-methods/system-agent.ts
index f3481b2717b..5112ab71bdf 100644
--- a/src/gateway/server-methods/system-agent.ts
+++ b/src/gateway/server-methods/system-agent.ts
@@ -213,10 +213,11 @@ export const systemAgentHandlers: GatewayRequestHandlers = {
     ) {
       return;
     }
-    await runSystemAgentGatewayTask(async () => {
-      const { detectSetupInference } = await import("../../system-agent/setup-inference.js");
-      respond(true, await detectSetupInference(), undefined);
-    });
+    // Detection is read-only and may load native provider code. Keep it outside
+    // the mutation lane and off the Gateway event loop so health stays live.
+    const { detectSetupInferenceIsolated } =
+      await import("../../system-agent/setup-inference-detection.js");
+    respond(true, await detectSetupInferenceIsolated(), undefined);
   },
   /** Re-run the exact current default-agent inference route without mutating setup. */
   "openclaw.setup.verify": async ({ params, respond }) => {
diff --git a/src/infra/tsdown-config.test.ts b/src/infra/tsdown-config.test.ts
index 29660764bfb..b95f0771c74 100644
--- a/src/infra/tsdown-config.test.ts
+++ b/src/infra/tsdown-config.test.ts
@@ -103,6 +103,7 @@ describe("tsdown config", () => {
       "agents/compaction-planning.worker",
       "agents/model-provider-auth.worker",
       "state/openclaw-database-verify.worker",
+      "system-agent/setup-inference-detection.worker",
       "plugins/memory-state",
       "subagent-registry.runtime",
       "task-registry-control.runtime",
diff --git a/src/system-agent/probes.test.ts b/src/system-agent/probes.test.ts
index 685700954dd..2b19384f364 100644
--- a/src/system-agent/probes.test.ts
+++ b/src/system-agent/probes.test.ts
@@ -34,6 +34,7 @@ describe("openclaw probes", () => {
         command: process.execPath,
         error: "timed out after 25ms",
         found: true,
+        timedOut: true,
       });
       expect(Date.now() - startedAt).toBeLessThan(2_000);
     },
diff --git a/src/system-agent/probes.ts b/src/system-agent/probes.ts
index a46c1342ace..06b8671eebc 100644
--- a/src/system-agent/probes.ts
+++ b/src/system-agent/probes.ts
@@ -14,6 +14,7 @@ export type LocalCommandProbe = {
   found: boolean;
   version?: string;
   error?: string;
+  timedOut?: boolean;
 };
 
 const LOCAL_COMMAND_PROBE_OUTPUT_MAX_CHARS = 16 * 1024;
@@ -36,6 +37,7 @@ export async function probeLocalCommand(
         command,
         found: true,
         error: `timed out after ${timeoutMs}ms`,
+        timedOut: true,
       };
     }
     // Version output can arrive on stdout or stderr depending on the CLI.
diff --git a/src/system-agent/setup-inference-detection.test.ts b/src/system-agent/setup-inference-detection.test.ts
new file mode 100644
index 00000000000..084331010d6
--- /dev/null
+++ b/src/system-agent/setup-inference-detection.test.ts
@@ -0,0 +1,125 @@
+import { createServer, get } from "node:http";
+import type { AddressInfo } from "node:net";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SetupInferenceDetection } from "./setup-inference.js";
+
+const blockingWorkerUrl = new URL(
+  `data:text/javascript,${encodeURIComponent(`
+    import { parentPort, workerData } from "node:worker_threads";
+    parentPort.postMessage({ type: "partial", detection: workerData.partialDetection });
+    const deadline = Date.now() + workerData.blockMs;
+    while (Date.now() < deadline) {}
+    parentPort.postMessage({ type: "result", detection: workerData.detection });
+    parentPort.close();
+  `)}`,
+);
+
+function emptyDetection(): SetupInferenceDetection {
+  return {
+    candidates: [],
+    unavailableCandidates: [],
+    manualProviders: [],
+    authOptions: [],
+    recommendedInstalls: [],
+    workspace: "/tmp/work",
+    setupComplete: false,
+  };
+}
+
+const servers = new Set<ReturnType<typeof createServer>>();
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+async function loadDetectionModule() {
+  return await import("./setup-inference-detection.js");
+}
+
+async function requestHealth(url: string): Promise<{ body: string; statusCode: number }> {
+  return await new Promise((resolve, reject) => {
+    const request = get(url, { agent: false, headers: { connection: "close" } }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+      });
+      response.on("end", () => resolve({ body, statusCode: response.statusCode ?? 0 }));
+    });
+    request.on("error", reject);
+  });
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...servers].map(
+      (server) =>
+        new Promise<void>((resolve, reject) => {
+          server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    ),
+  );
+  servers.clear();
+});
+
+describe("isolated setup inference detection", () => {
+  it("keeps HTTP responsive while a detection worker is synchronously blocked", async () => {
+    const { detectSetupInferenceIsolated } = await loadDetectionModule();
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end('{"ok":true,"status":"live"}');
+    });
+    servers.add(server);
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => {
+        resolve();
+      });
+    });
+    const address = server.address() as AddressInfo;
+    const fallback = emptyDetection();
+
+    const pendingStartedAt = performance.now();
+    const pending = detectSetupInferenceIsolated({
+      workerUrl: blockingWorkerUrl,
+      workerData: {
+        blockMs: 10_000,
+        detection: emptyDetection(),
+        partialDetection: fallback,
+      },
+      timeoutMs: 100,
+    });
+    const startedAt = performance.now();
+    const response = await requestHealth(`http://127.0.0.1:${address.port}/health`);
+    const elapsedMs = performance.now() - startedAt;
+
+    expect(response.statusCode).toBe(200);
+    expect(JSON.parse(response.body)).toEqual({ ok: true, status: "live" });
+    expect(elapsedMs).toBeLessThan(500);
+    await expect(pending).resolves.toEqual(fallback);
+    expect(performance.now() - pendingStartedAt).toBeLessThan(1_000);
+  });
+
+  it("coalesces concurrent detections behind one bounded worker", async () => {
+    const { detectSetupInferenceIsolated } = await loadDetectionModule();
+    const fallback = vi.fn(async () => emptyDetection());
+    const options = {
+      workerUrl: blockingWorkerUrl,
+      workerData: {
+        blockMs: 10_000,
+        detection: emptyDetection(),
+        partialDetection: emptyDetection(),
+      },
+      timeoutMs: 50,
+      fallback,
+    };
+
+    const [first, second] = await Promise.all([
+      detectSetupInferenceIsolated(options),
+      detectSetupInferenceIsolated(options),
+    ]);
+
+    expect(first).toEqual(emptyDetection());
+    expect(second).toEqual(emptyDetection());
+    expect(fallback).toHaveBeenCalledOnce();
+  });
+});
diff --git a/src/system-agent/setup-inference-detection.ts b/src/system-agent/setup-inference-detection.ts
new file mode 100644
index 00000000000..363da08e436
--- /dev/null
+++ b/src/system-agent/setup-inference-detection.ts
@@ -0,0 +1,190 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Worker, type WorkerOptions } from "node:worker_threads";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "../agents/workspace-default.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import { listRecommendedToolInstalls } from "../plugins/recommended-tool-installs.js";
+import type { SetupInferenceDetection } from "./setup-inference.js";
+
+const SETUP_INFERENCE_DETECTION_TIMEOUT_MS = 10_000;
+
+const log = createSubsystemLogger("system-agent/setup-inference-detection");
+
+type DetectionWorkerMessage =
+  | { type: "partial"; detection: SetupInferenceDetection }
+  | { type: "result"; detection: SetupInferenceDetection }
+  | { ok: false; error: string };
+
+type DetectionWorkerOptions = {
+  timeoutMs?: number;
+  workerUrl?: URL;
+  workerData?: WorkerOptions["workerData"];
+  fallback?: () => Promise<SetupInferenceDetection>;
+};
+
+let inFlightDetection: Promise<SetupInferenceDetection> | undefined;
+let workerShutdown: Promise<void> | undefined;
+let workerShutdownResult: SetupInferenceDetection | undefined;
+
+function trackWorkerShutdown(worker: Worker): void {
+  const current = worker.terminate().then(
+    () => undefined,
+    (error: unknown) => {
+      log.warn(`Setup inference detection worker termination failed: ${String(error)}`);
+    },
+  );
+  workerShutdown = current;
+  void current.finally(() => {
+    if (workerShutdown === current) {
+      workerShutdown = undefined;
+      workerShutdownResult = undefined;
+    }
+  });
+}
+
+function resolveDetectionWorkerUrl(currentModuleUrl = import.meta.url): URL {
+  const currentPath = fileURLToPath(currentModuleUrl);
+  const normalized = currentPath.replaceAll(path.sep, "/");
+  const distMarker = "/dist/";
+  const distIndex = normalized.lastIndexOf(distMarker);
+  if (distIndex >= 0) {
+    const distRoot = currentPath.slice(0, distIndex + distMarker.length);
+    return pathToFileURL(
+      path.join(distRoot, "system-agent", "setup-inference-detection.worker.js"),
+    );
+  }
+  const extension = path.extname(currentPath) || ".js";
+  return new URL(`./setup-inference-detection.worker${extension}`, currentModuleUrl);
+}
+
+function parseDetectionWorkerMessage(value: unknown): DetectionWorkerMessage | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const message = value as Record<string, unknown>;
+  if (
+    (message.type === "partial" || message.type === "result") &&
+    message.detection &&
+    typeof message.detection === "object"
+  ) {
+    return message as DetectionWorkerMessage;
+  }
+  if (message.ok === false && typeof message.error === "string") {
+    return message as DetectionWorkerMessage;
+  }
+  return undefined;
+}
+
+function createUndetectedFallback(): SetupInferenceDetection {
+  // This fallback must stay independent of the detection/plugin graph. The worker
+  // supplies richer partial data when that graph loads before the deadline.
+  return {
+    candidates: [],
+    unavailableCandidates: [],
+    manualProviders: [],
+    authOptions: [],
+    recommendedInstalls: listRecommendedToolInstalls(),
+    workspace: DEFAULT_AGENT_WORKSPACE_DIR,
+    setupComplete: false,
+  };
+}
+
+async function runDetectionWorker(
+  options: DetectionWorkerOptions = {},
+): Promise<SetupInferenceDetection> {
+  const workerUrl = options.workerUrl ?? resolveDetectionWorkerUrl();
+  const execArgv = workerUrl.pathname.endsWith(".ts") ? ["--import", "tsx"] : undefined;
+  const worker = new Worker(workerUrl, {
+    execArgv,
+    ...(options.workerData === undefined ? {} : { workerData: options.workerData }),
+  });
+  const timeoutMs = options.timeoutMs ?? SETUP_INFERENCE_DETECTION_TIMEOUT_MS;
+
+  return await new Promise<SetupInferenceDetection>((resolve, reject) => {
+    let settled = false;
+    let partialDetection: SetupInferenceDetection | undefined;
+    const settle = (finish: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      worker.removeAllListeners();
+      // terminate() is asynchronous; keep teardown errors from becoming uncaught events.
+      worker.on("error", () => undefined);
+      trackWorkerShutdown(worker);
+      finish();
+    };
+    worker.on("message", (value: unknown) => {
+      const message = parseDetectionWorkerMessage(value);
+      if (message && "type" in message && message.type === "partial") {
+        partialDetection = message.detection;
+        return;
+      }
+      settle(() => {
+        if (!message) {
+          reject(new Error("setup inference detection worker returned an invalid result"));
+          return;
+        }
+        if ("ok" in message) {
+          reject(new Error(message.error));
+          return;
+        }
+        workerShutdownResult = message.detection;
+        resolve(message.detection);
+      });
+    });
+    worker.once("error", (error) =>
+      settle(() => reject(error instanceof Error ? error : new Error(String(error)))),
+    );
+    worker.once("exit", (code) => {
+      if (code !== 0) {
+        settle(() =>
+          reject(new Error(`setup inference detection worker exited with code ${code}`)),
+        );
+      } else {
+        settle(() => reject(new Error("setup inference detection worker exited without results")));
+      }
+    });
+    const timer = setTimeout(() => {
+      settle(() => {
+        log.warn(
+          `Setup inference detection timed out after ${timeoutMs}ms; returning partial detection.`,
+        );
+        if (options.fallback) {
+          void options.fallback().then(resolve, reject);
+          return;
+        }
+        const detection = partialDetection ?? createUndetectedFallback();
+        workerShutdownResult = detection;
+        resolve(detection);
+      });
+    }, timeoutMs);
+    // Installing a message listener references the underlying MessagePort.
+    // Unref only after all listeners exist so timed-out workers cannot pin shutdown.
+    worker.unref();
+  });
+}
+
+/** Coalesce read-only detection and isolate native/plugin discovery from Gateway liveness. */
+export async function detectSetupInferenceIsolated(
+  options: DetectionWorkerOptions = {},
+): Promise<SetupInferenceDetection> {
+  if (inFlightDetection) {
+    return await inFlightDetection;
+  }
+  // A native provider probe can delay Worker termination. Reuse the bounded
+  // result until exit instead of allowing repeat UI requests to stack threads.
+  if (workerShutdown) {
+    return workerShutdownResult ?? createUndetectedFallback();
+  }
+  const current = runDetectionWorker(options);
+  inFlightDetection = current;
+  try {
+    return await current;
+  } finally {
+    if (inFlightDetection === current) {
+      inFlightDetection = undefined;
+    }
+  }
+}
diff --git a/src/system-agent/setup-inference-detection.worker.ts b/src/system-agent/setup-inference-detection.worker.ts
new file mode 100644
index 00000000000..427d6ff81d5
--- /dev/null
+++ b/src/system-agent/setup-inference-detection.worker.ts
@@ -0,0 +1,36 @@
+import { parentPort } from "node:worker_threads";
+import { listRecommendedToolInstalls } from "../plugins/recommended-tool-installs.js";
+import {
+  detectSetupInference,
+  listManualSetupInferenceOptions,
+  type SetupInferenceDetection,
+} from "./setup-inference.js";
+
+if (!parentPort) {
+  throw new Error("setup inference detection worker requires a parent port");
+}
+
+const port = parentPort;
+
+try {
+  const manual = await listManualSetupInferenceOptions();
+  const partial: SetupInferenceDetection = {
+    candidates: [],
+    unavailableCandidates: [],
+    recommendedInstalls: listRecommendedToolInstalls(),
+    ...manual,
+  };
+  port.postMessage({
+    type: "partial",
+    detection: partial,
+  });
+  const detection = await detectSetupInference();
+  port.postMessage({ type: "result", detection });
+} catch (error) {
+  port.postMessage({
+    ok: false,
+    error: error instanceof Error ? error.message : String(error),
+  });
+} finally {
+  port.close();
+}
diff --git a/src/system-agent/setup-inference.ts b/src/system-agent/setup-inference.ts
index cb17aedb728..debd5686e7c 100644
--- a/src/system-agent/setup-inference.ts
+++ b/src/system-agent/setup-inference.ts
@@ -441,7 +441,7 @@ export async function detectSetupInference(
     probe("pi"),
     probe("opencode"),
   ]);
-  if (antigravity.found) {
+  if (antigravity.found && !antigravity.timedOut) {
     unavailableCandidates.push({
       id: "antigravity-cli",
       label: "Antigravity CLI",
@@ -450,7 +450,7 @@ export async function detectSetupInference(
         "Can't be auto-tested safely here. Sign in with a provider or use an API key instead.",
     });
   }
-  if (pi.found) {
+  if (pi.found && !pi.timedOut) {
     unavailableCandidates.push({
       id: "pi-cli",
       label: "Pi CLI",
@@ -459,7 +459,7 @@ export async function detectSetupInference(
         "Pi CLI is installed, but its whole-agent sessions require separate setup and are not a reusable guided-setup inference route.",
     });
   }
-  if (opencode.found) {
+  if (opencode.found && !opencode.timedOut) {
     unavailableCandidates.push({
       id: "opencode-cli",
       label: "OpenCode CLI",
diff --git a/test/release-check.test.ts b/test/release-check.test.ts
index a71355c4f38..49942a833fb 100644
--- a/test/release-check.test.ts
+++ b/test/release-check.test.ts
@@ -712,6 +712,7 @@ describe("collectMissingPackPaths", () => {
       "dist/audit/audit-event-writer.worker.js",
       "dist/config/sessions/session-transcript-reconcile.worker.js",
       "dist/state/openclaw-database-verify.worker.js",
+      "dist/system-agent/setup-inference-detection.worker.js",
       "dist/task-registry-control.runtime.js",
       "dist/telegram-ingress-worker.runtime.js",
       bundledDistPluginFile("telegram", "runtime-api.js"),
@@ -750,6 +751,7 @@ describe("collectMissingPackPaths", () => {
         "dist/audit/audit-event-writer.worker.js",
         "dist/config/sessions/session-transcript-reconcile.worker.js",
         "dist/state/openclaw-database-verify.worker.js",
+        "dist/system-agent/setup-inference-detection.worker.js",
         "dist/task-registry-control.runtime.js",
         "dist/telegram-ingress-worker.runtime.js",
         "dist/build-info.json",
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 7fa3ca1c8c1..9af230fb625 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -278,6 +278,8 @@ function buildCoreDistEntries(): Record<string, string> {
     "config/sessions/session-transcript-reconcile.worker":
       "src/config/sessions/session-transcript-reconcile.worker.ts",
     "state/openclaw-database-verify.worker": "src/state/openclaw-database-verify.worker.ts",
+    "system-agent/setup-inference-detection.worker":
+      "src/system-agent/setup-inference-detection.worker.ts",
     "acp/control-plane/manager": "src/acp/control-plane/manager.ts",
     "cli/gateway-lifecycle.runtime": "src/cli/gateway-cli/lifecycle.runtime.ts",
     "provider-dispatcher.runtime": "src/auto-reply/reply/provider-dispatcher.runtime.ts",

From 00257c3093afe06d6690bd1676849a3265a73f57 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:23:05 +0100
Subject: [PATCH 45/76] feat(ui): theme cards preview their real color palettes
 (#110626)

---
 ui/src/pages/config/view.ts | 31 ++++++++++-----
 ui/src/styles/config.css    | 77 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 97 insertions(+), 11 deletions(-)

diff --git a/ui/src/pages/config/view.ts b/ui/src/pages/config/view.ts
index cf18d467b2f..e28a12f37cf 100644
--- a/ui/src/pages/config/view.ts
+++ b/ui/src/pages/config/view.ts
@@ -1,7 +1,7 @@
 // Control UI view renders config screen content.
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import JSON5 from "json5";
-import { html, nothing, type TemplateResult } from "lit";
+import { html, nothing } from "lit";
 import type { QueueMode } from "../../../../src/auto-reply/reply/queue/types.js";
 import type { ConfigUiHints } from "../../api/types.ts";
 import {
@@ -836,29 +836,42 @@ type ThemeOption = {
   id: ThemeName;
   labelKey: string;
   descriptionKey: string;
-  icon: TemplateResult;
 };
 const BUILTIN_THEME_OPTIONS: ThemeOption[] = [
   {
     id: "claw",
     labelKey: "configView.themes.claw.label",
     descriptionKey: "configView.themes.claw.description",
-    icon: icons.zap,
   },
   {
     id: "knot",
     labelKey: "configView.themes.knot.label",
     descriptionKey: "configView.themes.knot.description",
-    icon: icons.link,
   },
   {
     id: "dash",
     labelKey: "configView.themes.dash.label",
     descriptionKey: "configView.themes.dash.description",
-    icon: icons.barChart,
   },
 ];
 
+/* Builtin cards preview their real palette (chip colors live in config.css,
+   mirrored from the base.css theme blocks). The custom card only has real
+   colors while active — its chips read the live CSS variables — so it falls
+   back to the spark icon otherwise. */
+function renderThemeCardVisual(id: ThemeName, activeTheme: ThemeName) {
+  if (id === "custom" && activeTheme !== "custom") {
+    return html`<span class="settings-theme-card__icon" aria-hidden="true">${icons.spark}</span>`;
+  }
+  return html`
+    <span class="settings-theme-card__palette" aria-hidden="true">
+      <span class="settings-theme-card__chip settings-theme-card__chip--accent"></span>
+      <span class="settings-theme-card__chip settings-theme-card__chip--accent-2"></span>
+      <span class="settings-theme-card__chip settings-theme-card__chip--bg"></span>
+    </span>
+  `;
+}
+
 function importedThemeName(props: Pick<ConfigProps, "hasCustomTheme" | "customThemeLabel">) {
   return props.hasCustomTheme && props.customThemeLabel
     ? props.customThemeLabel
@@ -1266,13 +1279,11 @@ function renderAppearanceSection(props: ConfigProps) {
     id: ThemeName;
     label: string;
     description: string;
-    icon: TemplateResult;
   }> = [
     ...BUILTIN_THEME_OPTIONS.map((option) => ({
       id: option.id,
       label: t(option.labelKey),
       description: t(option.descriptionKey),
-      icon: option.icon,
     })),
     {
       id: "custom",
@@ -1280,7 +1291,6 @@ function renderAppearanceSection(props: ConfigProps) {
       description: props.hasCustomTheme
         ? t("configView.appearance.importedFrom", { name: importedName })
         : t("configView.appearance.importHint"),
-      icon: icons.spark,
     },
   ];
   return html`
@@ -1298,7 +1308,8 @@ function renderAppearanceSection(props: ConfigProps) {
               ${themeOptions.map(
                 (opt) => html`
                   <button
-                    class="settings-theme-card ${opt.id === props.theme
+                    class="settings-theme-card settings-theme-card--${opt.id} ${opt.id ===
+                    props.theme
                       ? "settings-theme-card--active"
                       : ""}"
                     title=${opt.description}
@@ -1315,7 +1326,7 @@ function renderAppearanceSection(props: ConfigProps) {
                       }
                     }}
                   >
-                    <span class="settings-theme-card__icon" aria-hidden="true">${opt.icon}</span>
+                    ${renderThemeCardVisual(opt.id, props.theme)}
                     <span class="settings-theme-card__label">${opt.label}</span>
                     ${opt.id === props.theme
                       ? html`<span class="settings-theme-card__check" aria-hidden="true"
diff --git a/ui/src/styles/config.css b/ui/src/styles/config.css
index 52b98122c87..7df8c43dfd5 100644
--- a/ui/src/styles/config.css
+++ b/ui/src/styles/config.css
@@ -287,7 +287,82 @@
 .settings-theme-card__label {
   font-size: 13px;
   font-weight: 600;
-  color: var(--accent);
+  color: var(--text);
+}
+
+.settings-theme-card--active .settings-theme-card__label {
+  color: var(--text-strong);
+}
+
+/* Real-palette preview chips. Colors mirror the :root[data-theme] blocks in
+   base.css (claw = the default :root palette); keep both in sync when
+   retuning a theme. The custom card reads the live variables instead — it is
+   only rendered with chips while the imported theme is active. */
+.settings-theme-card__palette {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.settings-theme-card__chip {
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--text) 18%, transparent);
+}
+
+.settings-theme-card__chip--bg {
+  background: var(--theme-chip-bg);
+}
+
+.settings-theme-card__chip--accent {
+  background: var(--theme-chip-accent);
+}
+
+.settings-theme-card__chip--accent-2 {
+  background: var(--theme-chip-accent-2);
+}
+
+.settings-theme-card--claw {
+  --theme-chip-bg: #0e1015;
+  --theme-chip-accent: #ff5c5c;
+  --theme-chip-accent-2: #14b8a6;
+}
+
+.settings-theme-card--knot {
+  --theme-chip-bg: #080808;
+  --theme-chip-accent: #e5243b;
+  --theme-chip-accent-2: #8b1a2b;
+}
+
+.settings-theme-card--dash {
+  --theme-chip-bg: #1a1210;
+  --theme-chip-accent: #b47840;
+  --theme-chip-accent-2: #a88050;
+}
+
+:root[data-theme-mode="light"] .settings-theme-card--claw {
+  --theme-chip-bg: #faf9f7;
+  --theme-chip-accent: #bd4531;
+  --theme-chip-accent-2: #0d9488;
+}
+
+:root[data-theme-mode="light"] .settings-theme-card--knot {
+  --theme-chip-bg: #f9f9fb;
+  --theme-chip-accent: #c41e30;
+  --theme-chip-accent-2: #7a1420;
+}
+
+:root[data-theme-mode="light"] .settings-theme-card--dash {
+  --theme-chip-bg: #f7f2ec;
+  --theme-chip-accent: #6e4828;
+  --theme-chip-accent-2: #6a4e30;
+}
+
+.settings-theme-card--custom {
+  --theme-chip-bg: var(--bg);
+  --theme-chip-accent: var(--accent);
+  --theme-chip-accent-2: var(--accent-2);
 }
 
 .settings-theme-import {

From 105aebacea1f0a9f4dc7d1aa9e60398c71f32d9d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:23:39 +0100
Subject: [PATCH 46/76] fix: report agent deletion cleanup failures (#110560)

---
 .../OpenClawProtocol/GatewayModels.swift      | 10 ++-
 docs/cli/agents.md                            |  2 +-
 .../src/schema/agents-models-skills.test.ts   | 15 ++++
 .../src/schema/agents-models-skills.ts        | 16 +++++
 src/commands/agents.commands.delete.ts        |  9 +++
 src/commands/agents.config.ts                 | 34 ++++++++-
 src/commands/agents.delete.test.ts            | 33 +++++++++
 src/commands/agents.test.ts                   |  9 ++-
 .../server-methods/agents-mutate.test.ts      | 72 ++++++++++++++++---
 src/gateway/server-methods/agents.ts          | 62 ++++++++++++----
 10 files changed, 235 insertions(+), 27 deletions(-)

diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
index 76d3ac69d3a..7e777e97f73 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -8679,21 +8679,29 @@ public struct AgentsDeleteResult: Codable, Sendable {
     public let ok: Bool
     public let agentid: String
     public let removedbindings: Int
+    public let removed: [[String: AnyCodable]]?
+    public let failed: [[String: AnyCodable]]?
 
     public init(
         ok: Bool,
         agentid: String,
-        removedbindings: Int)
+        removedbindings: Int,
+        removed: [[String: AnyCodable]]? = nil,
+        failed: [[String: AnyCodable]]? = nil)
     {
         self.ok = ok
         self.agentid = agentid
         self.removedbindings = removedbindings
+        self.removed = removed
+        self.failed = failed
     }
 
     private enum CodingKeys: String, CodingKey {
         case ok
         case agentid = "agentId"
         case removedbindings = "removedBindings"
+        case removed
+        case failed
     }
 }
 
diff --git a/docs/cli/agents.md b/docs/cli/agents.md
index 97a9e484909..f54cf0f60ea 100644
--- a/docs/cli/agents.md
+++ b/docs/cli/agents.md
@@ -68,7 +68,7 @@ Options: `--force`, `--json`.
 
 - `main` cannot be deleted.
 - Without `--force`, interactive confirmation is required (fails in a non-TTY session; re-run with `--force`).
-- Workspace, agent state, and session transcript directories move to Trash, not hard-deleted.
+- Workspace, agent state, and session transcript directories move to Trash, not hard-deleted. If Trash is unavailable, agent config deletion still succeeds and reports paths requiring manual cleanup.
 - When the Gateway is reachable, deletion routes through the Gateway so config and session-store cleanup share the same writer as runtime traffic. If the Gateway is unreachable, the CLI falls back to the offline local path.
 - If another agent's workspace is the same path, inside this workspace, or contains this workspace, the workspace is retained, and `--json` reports `workspaceRetained`, `workspaceRetainedReason`, and `workspaceSharedWith`.
 
diff --git a/packages/gateway-protocol/src/schema/agents-models-skills.test.ts b/packages/gateway-protocol/src/schema/agents-models-skills.test.ts
index 6fa04f868b1..df56bd173fd 100644
--- a/packages/gateway-protocol/src/schema/agents-models-skills.test.ts
+++ b/packages/gateway-protocol/src/schema/agents-models-skills.test.ts
@@ -2,6 +2,7 @@
 import { Value } from "typebox/value";
 import { describe, expect, it } from "vitest";
 import {
+  AgentsDeleteResultSchema,
   AgentsListResultSchema,
   AgentsUpdateParamsSchema,
   ModelsListParamsSchema,
@@ -15,6 +16,20 @@ import {
   ToolsInvokeParamsSchema,
 } from "./agents-models-skills.js";
 
+describe("AgentsDeleteResultSchema", () => {
+  it("accepts per-path cleanup outcomes", () => {
+    expect(
+      Value.Check(AgentsDeleteResultSchema, {
+        ok: true,
+        agentId: "ops",
+        removedBindings: 1,
+        removed: [{ path: "/state/agents/ops/agent", method: "trash" }],
+        failed: [{ path: "/state/workspace-ops", reason: "trash unavailable" }],
+      }),
+    ).toBe(true);
+  });
+});
+
 /**
  * Schema regression tests for agent metadata, skill proposals, and effective
  * tool catalogs. These payloads are UI-facing but also consumed by runtime
diff --git a/packages/gateway-protocol/src/schema/agents-models-skills.ts b/packages/gateway-protocol/src/schema/agents-models-skills.ts
index 68d88f14f30..89b310f3d0e 100644
--- a/packages/gateway-protocol/src/schema/agents-models-skills.ts
+++ b/packages/gateway-protocol/src/schema/agents-models-skills.ts
@@ -142,6 +142,22 @@ export const AgentsDeleteResultSchema = closedObject({
   ok: Type.Literal(true),
   agentId: NonEmptyString,
   removedBindings: Type.Integer({ minimum: 0 }),
+  removed: Type.Optional(
+    Type.Array(
+      closedObject({
+        path: NonEmptyString,
+        method: Type.Union([Type.Literal("trash"), Type.Literal("missing")]),
+      }),
+    ),
+  ),
+  failed: Type.Optional(
+    Type.Array(
+      closedObject({
+        path: NonEmptyString,
+        reason: NonEmptyString,
+      }),
+    ),
+  ),
 });
 
 /** File metadata and optional content for agent-local editable files. */
diff --git a/src/commands/agents.commands.delete.ts b/src/commands/agents.commands.delete.ts
index 8b3b39779d2..9dccf6595e9 100644
--- a/src/commands/agents.commands.delete.ts
+++ b/src/commands/agents.commands.delete.ts
@@ -40,6 +40,8 @@ type AgentsDeleteGatewayResult = {
   ok: true;
   agentId: string;
   removedBindings: number;
+  removed?: Array<{ path: string; method: "trash" | "missing" }>;
+  failed?: Array<{ path: string; reason: string }>;
 };
 
 async function maybeDeleteAgentThroughGateway(params: {
@@ -144,10 +146,17 @@ export async function agentsDeleteCommand(
         sessionsDir,
         removedBindings: gatewayResult.removedBindings,
         removedAllow: result.removedAllow,
+        removed: gatewayResult.removed,
+        failed: gatewayResult.failed,
         transport: "gateway",
       });
     } else {
       runtime.log(`Deleted agent: ${agentId}`);
+      for (const failure of gatewayResult.failed ?? []) {
+        runtime.error(
+          `Warning: path could not be moved to Trash: ${failure.reason}; remove it manually at ${failure.path}`,
+        );
+      }
     }
     return;
   }
diff --git a/src/commands/agents.config.ts b/src/commands/agents.config.ts
index 11aee9c894b..75c1a7c8cec 100644
--- a/src/commands/agents.config.ts
+++ b/src/commands/agents.config.ts
@@ -181,7 +181,28 @@ export function pruneAgentConfig(
 } {
   const id = normalizeAgentId(agentId);
   const agents = listAgentEntries(cfg);
-  const nextAgentsList = agents.filter((entry) => normalizeAgentId(entry.id) !== id);
+  const pruneAllowAgents = (allowAgents: string[] | undefined) =>
+    allowAgents?.filter((entry) => {
+      const trimmed = entry.trim();
+      return !trimmed || trimmed === "*" || normalizeAgentId(trimmed) !== id;
+    });
+  const nextAgentsList = [];
+  for (const entry of agents) {
+    if (normalizeAgentId(entry.id) === id) {
+      continue;
+    }
+    nextAgentsList.push(
+      entry.subagents?.allowAgents
+        ? {
+            ...entry,
+            subagents: {
+              ...entry.subagents,
+              allowAgents: pruneAllowAgents(entry.subagents.allowAgents),
+            },
+          }
+        : entry,
+    );
+  }
   const nextAgents = nextAgentsList.length > 0 ? nextAgentsList : undefined;
 
   const bindings = cfg.bindings ?? [];
@@ -190,8 +211,17 @@ export function pruneAgentConfig(
   const allow = cfg.tools?.agentToAgent?.allow ?? [];
   const filteredAllow = allow.filter((entry) => entry !== id);
 
+  const nextDefaults = cfg.agents?.defaults?.subagents?.allowAgents
+    ? {
+        ...cfg.agents.defaults,
+        subagents: {
+          ...cfg.agents.defaults.subagents,
+          allowAgents: pruneAllowAgents(cfg.agents.defaults.subagents.allowAgents),
+        },
+      }
+    : cfg.agents?.defaults;
   const nextAgentsConfig = cfg.agents
-    ? { ...cfg.agents, list: nextAgents }
+    ? { ...cfg.agents, defaults: nextDefaults, list: nextAgents }
     : nextAgents
       ? { list: nextAgents }
       : undefined;
diff --git a/src/commands/agents.delete.test.ts b/src/commands/agents.delete.test.ts
index a03f9ad750e..0a71b3a7811 100644
--- a/src/commands/agents.delete.test.ts
+++ b/src/commands/agents.delete.test.ts
@@ -179,6 +179,8 @@ describe("agents delete command", () => {
         ok: true,
         agentId: "ops",
         removedBindings: 0,
+        removed: [{ path: path.join(stateDir, "agents", "ops", "agent"), method: "trash" }],
+        failed: [{ path: path.join(stateDir, "workspace-ops"), reason: "trash unavailable" }],
       });
 
       await agentsDeleteCommand({ id: "ops", force: true, json: true }, runtime);
@@ -193,10 +195,41 @@ describe("agents delete command", () => {
       const output = readJsonLogs()[0];
       expect(output?.agentId).toBe("ops");
       expect(output?.removedBindings).toBe(0);
+      expect(output?.removed).toEqual([
+        { path: path.join(stateDir, "agents", "ops", "agent"), method: "trash" },
+      ]);
+      expect(output?.failed).toEqual([
+        { path: path.join(stateDir, "workspace-ops"), reason: "trash unavailable" },
+      ]);
       expect(output?.transport).toBe("gateway");
     });
   });
 
+  it("warns about Gateway cleanup failures without failing committed deletion", async () => {
+    await withStateDirEnv("openclaw-agents-delete-gateway-warning-", async ({ stateDir }) => {
+      const workspace = path.join(stateDir, "workspace-ops");
+      const cfg: OpenClawConfig = {
+        agents: { list: [{ id: "main" }, { id: "ops", workspace }] },
+      };
+      await arrangeAgentsDeleteTest({ stateDir, cfg, sessions: {} });
+      gatewayMocks.callGateway.mockResolvedValue({
+        ok: true,
+        agentId: "ops",
+        removedBindings: 0,
+        removed: [],
+        failed: [{ path: workspace, reason: "trash unavailable" }],
+      });
+
+      await agentsDeleteCommand({ id: "ops", force: true }, runtime);
+
+      expect(runtime.log).toHaveBeenCalledWith("Deleted agent: ops");
+      expect(runtime.error).toHaveBeenCalledWith(
+        `Warning: path could not be moved to Trash: trash unavailable; remove it manually at ${workspace}`,
+      );
+      expect(runtime.exit).not.toHaveBeenCalled();
+    });
+  });
+
   it("falls back to local deletion when the optional Gateway probe needs credentials", async () => {
     await withStateDirEnv("openclaw-agents-delete-gateway-auth-", async ({ stateDir }) => {
       const now = Date.now();
diff --git a/src/commands/agents.test.ts b/src/commands/agents.test.ts
index 4965f570786..e839234803d 100644
--- a/src/commands/agents.test.ts
+++ b/src/commands/agents.test.ts
@@ -414,9 +414,14 @@ describe("agents helpers", () => {
   it("pruneAgentConfig removes agent, bindings, and allowlist entries", () => {
     const cfg: OpenClawConfig = {
       agents: {
+        defaults: { subagents: { allowAgents: ["work", "home"] } },
         list: [
           { id: "work", default: true, workspace: "/work-ws" },
-          { id: "home", workspace: "/home-ws" },
+          {
+            id: "home",
+            workspace: "/home-ws",
+            subagents: { allowAgents: ["WORK", "home"] },
+          },
         ],
       },
       bindings: [
@@ -435,6 +440,8 @@ describe("agents helpers", () => {
       { agentId: "home", match: { channel: "telegram" } },
     ]);
     expect(result.config.tools?.agentToAgent?.allow).toEqual(["home"]);
+    expect(result.config.agents?.defaults?.subagents?.allowAgents).toEqual(["home"]);
+    expect(result.config.agents?.list?.[0]?.subagents?.allowAgents).toEqual(["home"]);
     expect(result.removedBindings).toBe(1);
     expect(result.removedAllow).toBe(1);
   });
diff --git a/src/gateway/server-methods/agents-mutate.test.ts b/src/gateway/server-methods/agents-mutate.test.ts
index 1648872ff74..cbfe4f924b3 100644
--- a/src/gateway/server-methods/agents-mutate.test.ts
+++ b/src/gateway/server-methods/agents-mutate.test.ts
@@ -1,6 +1,8 @@
 // Agent mutation tests cover create/update/delete handlers, safe workspace file
 // access, config preconditions, trash cleanup, and workspace-state handling.
 
+import os from "node:os";
+import path from "node:path";
 import { expectDefined } from "@openclaw/normalization-core";
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import { FsSafeError } from "../../infra/fs-safe.js";
@@ -44,6 +46,7 @@ const mocks = vi.hoisted(() => ({
   fsLstat: vi.fn(async (..._args: unknown[]) => null as import("node:fs").Stats | null),
   fsRealpath: vi.fn(async (p: string) => p),
   fsReadlink: vi.fn(async () => ""),
+  fsRm: vi.fn(async () => undefined),
   fsOpen: vi.fn(async () => ({}) as unknown),
   rootRead: vi.fn(async (_params?: unknown) => ({
     buffer: Buffer.from(""),
@@ -197,6 +200,7 @@ vi.mock("node:fs/promises", async () => {
     lstat: mocks.fsLstat,
     realpath: mocks.fsRealpath,
     readlink: mocks.fsReadlink,
+    rm: mocks.fsRm,
     open: mocks.fsOpen,
   };
   return { ...patched, default: patched };
@@ -1169,11 +1173,20 @@ describe("agents.delete", () => {
 
     expect(respond).toHaveBeenCalledWith(
       true,
-      { ok: true, agentId: "test-agent", removedBindings: 2 },
+      {
+        ok: true,
+        agentId: "test-agent",
+        removedBindings: 2,
+        removed: [
+          { path: "/workspace/test-agent", method: "trash" },
+          { path: "/agents/test-agent", method: "trash" },
+          { path: "/transcripts/test-agent", method: "trash" },
+        ],
+        failed: [],
+      },
       undefined,
     );
     expect(mocks.writeConfigFile).toHaveBeenCalled();
-    // moveToTrashBestEffort calls fs.lstat then movePathToTrash for each dir
     expect(mocks.movePathToTrash).toHaveBeenCalled();
   });
 
@@ -1221,16 +1234,55 @@ describe("agents.delete", () => {
     expect(mocks.movePathToTrash).not.toHaveBeenCalledWith("/workspace/test-agent");
   });
 
-  it("retains workspace state when best-effort workspace trash fails", async () => {
-    mocks.movePathToTrash.mockRejectedValueOnce(new Error("trash unavailable"));
+  it("reports trash failures without deleting the retained directory", async () => {
+    const actualFs = await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises");
+    const workspaceDir = await actualFs.mkdtemp(
+      path.join(os.tmpdir(), "openclaw-agent-delete-trash-failure-"),
+    );
+    mocks.resolveAgentWorkspaceDir.mockReturnValueOnce(workspaceDir);
+    mocks.movePathToTrash.mockRejectedValueOnce(
+      Object.assign(new Error("trash destination missing"), { code: "ENOENT" }),
+    );
+
+    try {
+      const { respond, promise } = makeCall("agents.delete", {
+        agentId: "test-agent",
+      });
+      await promise;
+
+      expectRespondOk(respond, {
+        removed: [
+          { path: "/agents/test-agent", method: "trash" },
+          { path: "/transcripts/test-agent", method: "trash" },
+        ],
+        failed: [{ path: workspaceDir, reason: "trash destination missing" }],
+      });
+      await expect(actualFs.stat(workspaceDir)).resolves.toBeDefined();
+      expect(mocks.fsRm).not.toHaveBeenCalled();
+      expect(mocks.deleteWorkspaceState).not.toHaveBeenCalled();
+    } finally {
+      await actualFs.rm(workspaceDir, { recursive: true, force: true });
+    }
+  });
+
+  it("reports an absent source without invoking the trash backend", async () => {
+    mocks.fsLstat.mockRejectedValueOnce(createEnoentError());
 
     const { respond, promise } = makeCall("agents.delete", {
       agentId: "test-agent",
     });
     await promise;
 
-    expectRespondOk(respond, { ok: true });
-    expect(mocks.deleteWorkspaceState).not.toHaveBeenCalled();
+    expectRespondOk(respond, {
+      removed: [
+        { path: "/workspace/test-agent", method: "missing" },
+        { path: "/agents/test-agent", method: "trash" },
+        { path: "/transcripts/test-agent", method: "trash" },
+      ],
+      failed: [],
+    });
+    expect(mocks.movePathToTrash).not.toHaveBeenCalledWith("/workspace/test-agent");
+    expect(mocks.deleteWorkspaceState).toHaveBeenCalled();
   });
 
   it("retains workspace state when workspace presence cannot be checked", async () => {
@@ -1243,12 +1295,15 @@ describe("agents.delete", () => {
     });
     await promise;
 
-    expectRespondOk(respond, { ok: true });
+    expectRespondOk(respond, {
+      failed: [{ path: "/workspace/test-agent", reason: "permission denied" }],
+    });
     expect(mocks.deleteWorkspaceState).not.toHaveBeenCalled();
   });
 
   it("skips file deletion when deleteFiles is false", async () => {
     mocks.fsLstat.mockClear();
+    mocks.movePathToTrash.mockClear();
 
     const { respond, promise } = makeCall("agents.delete", {
       agentId: "test-agent",
@@ -1257,8 +1312,9 @@ describe("agents.delete", () => {
     await promise;
 
     expectRespondOk(respond, { ok: true });
-    // moveToTrashBestEffort should not be called at all
+    // No filesystem cleanup should run.
     expect(mocks.fsLstat).not.toHaveBeenCalled();
+    expect(mocks.movePathToTrash).not.toHaveBeenCalled();
     expect(mocks.deleteWorkspaceState).not.toHaveBeenCalled();
   });
 
diff --git a/src/gateway/server-methods/agents.ts b/src/gateway/server-methods/agents.ts
index 51878ecedc0..e5c68b4aaa1 100644
--- a/src/gateway/server-methods/agents.ts
+++ b/src/gateway/server-methods/agents.ts
@@ -319,21 +319,38 @@ function respondAgentConfigPreconditionError(
   );
 }
 
-async function moveToTrashBestEffort(pathname: string): Promise<boolean> {
-  if (!pathname) {
-    return false;
-  }
+type AgentDeleteRemovedPath = {
+  path: string;
+  method: "trash" | "missing";
+};
+
+type AgentDeleteFailedPath = {
+  path: string;
+  reason: string;
+};
+
+type AgentDeletePathOutcome =
+  | { removed: AgentDeleteRemovedPath }
+  | { failed: AgentDeleteFailedPath };
+
+function cleanupFailure(pathname: string, error: unknown): AgentDeletePathOutcome {
+  const reason = error instanceof Error && error.message ? error.message : String(error);
+  return { failed: { path: pathname, reason: reason || "unknown error" } };
+}
+
+async function removeAgentPath(pathname: string): Promise<AgentDeletePathOutcome> {
   try {
     await fs.lstat(pathname);
   } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "ENOENT";
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { removed: { path: pathname, method: "missing" } }
+      : cleanupFailure(pathname, error);
   }
   try {
     await movePathToTrash(pathname);
-    return true;
-  } catch {
-    // Best-effort: path may already be gone or trash unavailable.
-    return false;
+    return { removed: { path: pathname, method: "trash" } };
+  } catch (error) {
+    return cleanupFailure(pathname, error);
   }
 }
 
@@ -742,6 +759,16 @@ export const agentsHandlers: GatewayRequestHandlers = {
     // Purge session store entries so orphaned sessions cannot be targeted (#65524).
     await purgeAgentSessionStoreEntries(cfg, agentId);
 
+    const removed: AgentDeleteRemovedPath[] = [];
+    const failed: AgentDeleteFailedPath[] = [];
+    const recordOutcome = (outcome: AgentDeletePathOutcome) => {
+      if ("removed" in outcome) {
+        removed.push(outcome.removed);
+      } else {
+        failed.push(outcome.failed);
+      }
+    };
+
     if (deleteFiles) {
       const workspaceSharedWith = findOverlappingWorkspaceAgentIds(
         committed.nextConfig,
@@ -749,12 +776,12 @@ export const agentsHandlers: GatewayRequestHandlers = {
         deleteResult.workspaceDir,
       );
       const deleteWorkspace = workspaceSharedWith.length === 0;
-      const pathsToTrash = [deleteResult.agentDir, deleteResult.sessionsDir];
       if (deleteWorkspace) {
         const legacyPlan = prepareLegacyWorkspaceStateReset(deleteResult.workspaceDir);
         const statePlan = prepareWorkspaceStateDeletion(deleteResult.workspaceDir);
-        const workspaceRemoved = await moveToTrashBestEffort(deleteResult.workspaceDir);
-        if (workspaceRemoved) {
+        const workspaceOutcome = await removeAgentPath(deleteResult.workspaceDir);
+        recordOutcome(workspaceOutcome);
+        if ("removed" in workspaceOutcome) {
           try {
             await removeLegacyWorkspaceStateForReset(legacyPlan);
             deleteWorkspaceState(statePlan);
@@ -763,10 +790,17 @@ export const agentsHandlers: GatewayRequestHandlers = {
           }
         }
       }
-      await Promise.all(pathsToTrash.map((pathname) => moveToTrashBestEffort(pathname)));
+      const stateOutcomes = await Promise.all(
+        [deleteResult.agentDir, deleteResult.sessionsDir].map(removeAgentPath),
+      );
+      stateOutcomes.forEach(recordOutcome);
     }
 
-    respond(true, { ok: true, agentId, removedBindings: deleteResult.removedBindings }, undefined);
+    respond(
+      true,
+      { ok: true, agentId, removedBindings: deleteResult.removedBindings, removed, failed },
+      undefined,
+    );
   },
   "agents.files.list": async ({ params, respond, context }) => {
     if (!validateAgentsFilesListParams(params)) {

From b95035491cab2a1bb1cb2c71f7266233bafb9aaf Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:23:54 +0100
Subject: [PATCH 47/76] fix: repair model refs after provider deletion
 (#110648)

* fix(doctor): repair stale provider model refs

* test(doctor): satisfy type and export gates
---
 src/commands/doctor-config-flow.ts            |  14 +
 .../doctor-legacy-config.migrations.test.ts   | 181 ++++++
 .../shared/stale-agent-model-ref-repair.ts    | 577 ++++++++++++++++++
 3 files changed, 772 insertions(+)
 create mode 100644 src/commands/doctor/shared/stale-agent-model-ref-repair.ts

diff --git a/src/commands/doctor-config-flow.ts b/src/commands/doctor-config-flow.ts
index ea400bf829f..4cd6fbebcc7 100644
--- a/src/commands/doctor-config-flow.ts
+++ b/src/commands/doctor-config-flow.ts
@@ -273,6 +273,20 @@ export async function loadAndMaybeMigrateDoctorConfig(params: {
     }));
   }
 
+  const { repairStaleAgentModelRefs } =
+    await import("./doctor/shared/stale-agent-model-ref-repair.js");
+  const staleAgentModelRepair = repairStaleAgentModelRefs(candidate, { env: process.env });
+  emitDoctorChangesPanel(staleAgentModelRepair.changes, shouldRepair, { sanitize: true });
+  if (staleAgentModelRepair.warnings.length > 0) {
+    emitDoctorNotes({ note, warningNotes: staleAgentModelRepair.warnings });
+  }
+  ({ cfg, candidate, pendingChanges, fixHints } = applyDoctorConfigMutation({
+    state: { cfg, candidate, pendingChanges, fixHints },
+    mutation: staleAgentModelRepair,
+    shouldRepair,
+    fixHint: `Run "${doctorFixCommand}" to remove stale agent model references.`,
+  }));
+
   const { collectPluginToolAllowlistWarnings } =
     await import("./doctor/shared/plugin-tool-allowlist-warnings.js");
   const pluginToolAllowlistWarnings = collectPluginToolAllowlistWarnings({
diff --git a/src/commands/doctor-legacy-config.migrations.test.ts b/src/commands/doctor-legacy-config.migrations.test.ts
index b9e64ab1380..eb024ca2619 100644
--- a/src/commands/doctor-legacy-config.migrations.test.ts
+++ b/src/commands/doctor-legacy-config.migrations.test.ts
@@ -9,6 +9,7 @@ import { maybeRepairCodexRoutes } from "./doctor/shared/codex-route-warnings.js"
 import { normalizeCompatibilityConfigValues } from "./doctor/shared/legacy-config-core-migrate.js";
 import { LEGACY_CONFIG_MIGRATIONS } from "./doctor/shared/legacy-config-migrations.js";
 import { collectBlockedLegacyOpenAICodexProviderPlan } from "./doctor/shared/legacy-config-migrations.runtime.models.js";
+import { repairStaleAgentModelRefs } from "./doctor/shared/stale-agent-model-ref-repair.js";
 
 vi.mock("../plugins/setup-registry.js", () => ({
   resolvePluginSetupCliBackend: () => undefined,
@@ -712,6 +713,186 @@ describe("normalizeCompatibilityConfigValues", () => {
     );
   });
 
+  it("repairs agent model refs whose configured provider was deleted", () => {
+    const result = repairStaleAgentModelRefs(
+      {
+        models: {
+          providers: {
+            custom: { baseUrl: "http://localhost:1234", models: [] },
+          },
+        },
+        agents: {
+          defaults: {
+            model: {
+              primary: "deleted/default-primary",
+              fallbacks: ["custom/kept", "openai/gpt-5.6-sol", "deleted/default-fallback"],
+            },
+            models: {
+              "custom/kept": { alias: "kept" },
+              "deleted/models-add-row": { alias: "stale" },
+            },
+          },
+          list: [
+            {
+              id: "main",
+              model: "deleted/agent-primary",
+              models: {
+                "plugin-provider/kept": {},
+                "deleted/agent-models-add-row": {},
+              },
+            },
+          ],
+        },
+      } as OpenClawConfig,
+      {
+        pluginProviderIds: new Set(["plugin-provider"]),
+        persistedProviderIdsByAgentId: new Map(),
+      },
+    );
+
+    expect(result.config.agents?.defaults?.model).toEqual({
+      primary: "openai/gpt-5.6-sol",
+      fallbacks: ["custom/kept"],
+    });
+    expect(result.config.agents?.defaults?.models).toEqual({
+      "custom/kept": { alias: "kept" },
+      "openai/gpt-5.6-sol": {},
+    });
+    expect(result.config.agents?.list?.[0]).toMatchObject({
+      id: "main",
+      models: { "plugin-provider/kept": {}, "openai/gpt-5.6-sol": {} },
+    });
+    expect(result.config.agents?.list?.[0]?.model).toBeUndefined();
+    expect(result.changes).toEqual([
+      'Replaced stale agents.defaults.model primary "deleted/default-primary" with default "openai/gpt-5.6-sol" (provider "deleted" is unavailable).',
+      'Removed stale agents.defaults.model fallback "deleted/default-fallback" (provider "deleted" is unavailable).',
+      'Removed duplicate agents.defaults.model fallback "openai/gpt-5.6-sol" after selecting it as the default primary.',
+      'Removed stale agents.defaults.models entry "deleted/models-add-row" (provider "deleted" is unavailable).',
+      'Added agents.defaults.models entry "openai/gpt-5.6-sol" to keep the repaired allowlist restrictive.',
+      'Removed stale agents.list[0].model "deleted/agent-primary" so agent "main" inherits the default model (provider "deleted" is unavailable).',
+      'Removed stale agents.list[0].models entry "deleted/agent-models-add-row" (provider "deleted" is unavailable).',
+      'Added agents.list[0].models entry "openai/gpt-5.6-sol" to keep the repaired allowlist restrictive.',
+    ]);
+  });
+
+  it("preserves configured CLI backends and agent-local models.json providers", () => {
+    const result = repairStaleAgentModelRefs(
+      {
+        agents: {
+          defaults: {
+            model: "my-cli/model",
+            cliBackends: { "my-cli": { command: "my-cli" } },
+          },
+          list: [
+            { id: "worker", model: "agent-local/model" },
+            { id: "core", model: "anthropic/claude-sonnet-4-6" },
+          ],
+        },
+      } as OpenClawConfig,
+      {
+        pluginProviderIds: new Set(["anthropic"]),
+        persistedProviderIdsByAgentId: new Map([["worker", new Set(["agent-local"])]]),
+      },
+    );
+
+    expect(result.changes).toEqual([]);
+    expect(result.config.agents?.defaults?.model).toBe("my-cli/model");
+    expect(result.config.agents?.list?.[0]?.model).toBe("agent-local/model");
+    expect(result.config.agents?.list?.[1]?.model).toBe("anthropic/claude-sonnet-4-6");
+  });
+
+  it("does not treat one agent-local provider as globally available", () => {
+    const result = repairStaleAgentModelRefs(
+      {
+        agents: {
+          defaults: { model: "agent-local/model" },
+          list: [{ id: "main" }, { id: "worker" }],
+        },
+      } as OpenClawConfig,
+      {
+        pluginProviderIds: new Set(),
+        persistedProviderIdsByAgentId: new Map([
+          ["main", new Set(["agent-local"])],
+          ["worker", new Set()],
+        ]),
+      },
+    );
+
+    expect(result.config.agents?.defaults?.model).toBe("openai/gpt-5.6-sol");
+    expect(result.changes).toEqual([
+      'Replaced stale agents.defaults.model "agent-local/model" with default "openai/gpt-5.6-sol" (provider "agent-local" is unavailable).',
+    ]);
+  });
+
+  it("keeps a repaired model allowlist restrictive", () => {
+    const result = repairStaleAgentModelRefs(
+      {
+        agents: {
+          defaults: {
+            model: "deleted/main",
+            models: { "deleted/main": {} },
+          },
+        },
+      } as OpenClawConfig,
+      { pluginProviderIds: new Set(), persistedProviderIdsByAgentId: new Map() },
+    );
+
+    expect(result.config.agents?.defaults?.models).toEqual({ "openai/gpt-5.6-sol": {} });
+    expect(result.changes).toContain(
+      'Added agents.defaults.models entry "openai/gpt-5.6-sol" to keep the repaired allowlist restrictive.',
+    );
+  });
+
+  it("does not throw on malformed best-effort model config", () => {
+    expect(() =>
+      repairStaleAgentModelRefs(
+        {
+          agents: {
+            defaults: {
+              model: { primary: "deleted/main", fallbacks: 42 },
+            },
+          },
+        } as unknown as OpenClawConfig,
+        { pluginProviderIds: new Set(), persistedProviderIdsByAgentId: new Map() },
+      ),
+    ).not.toThrow();
+  });
+
+  it("uses only explicit providers when models.mode is replace", () => {
+    const result = repairStaleAgentModelRefs(
+      {
+        models: {
+          mode: "replace",
+          providers: {
+            custom: {
+              baseUrl: "http://localhost:1234",
+              models: [{ id: "kept", name: "Kept" }],
+            },
+          },
+        },
+        agents: {
+          defaults: {
+            model: {
+              primary: "deleted/main",
+              fallbacks: ["plugin-provider/model", "custom/kept"],
+            },
+          },
+        },
+      } as unknown as OpenClawConfig,
+      {
+        pluginProviderIds: new Set(["plugin-provider"]),
+        persistedProviderIdsByAgentId: new Map(),
+      },
+    );
+
+    expect(result.config.agents?.defaults?.model).toEqual({ primary: "custom/kept" });
+    expect(result.changes).toEqual([
+      'Replaced stale agents.defaults.model primary "deleted/main" with default "custom/kept" (provider "deleted" is unavailable).',
+      'Removed stale agents.defaults.model fallback "plugin-provider/model" (provider "plugin-provider" is unavailable).',
+      'Removed duplicate agents.defaults.model fallback "custom/kept" after selecting it as the default primary.',
+    ]);
+  });
+
   it("does not mark untagged manual OpenAI Codex metadata overrides", () => {
     const res = normalizeCompatibilityConfigValues({
       models: {
diff --git a/src/commands/doctor/shared/stale-agent-model-ref-repair.ts b/src/commands/doctor/shared/stale-agent-model-ref-repair.ts
new file mode 100644
index 00000000000..f455041c9d4
--- /dev/null
+++ b/src/commands/doctor/shared/stale-agent-model-ref-repair.ts
@@ -0,0 +1,577 @@
+// Doctor-only repair for agent model refs whose provider is no longer available.
+import fs from "node:fs";
+import path from "node:path";
+import {
+  resolveAgentDir,
+  resolveAgentWorkspaceDir,
+  resolveDefaultAgentId,
+} from "../../../agents/agent-scope.js";
+import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../../agents/defaults.js";
+import { normalizeProviderId } from "../../../agents/model-selection.js";
+import type { AgentModelConfig } from "../../../config/types.agents-shared.js";
+import type { OpenClawConfig } from "../../../config/types.openclaw.js";
+import { resolvePluginMetadataSnapshot } from "../../../plugins/plugin-metadata-snapshot.js";
+
+type StaleAgentModelRefRepair = {
+  config: OpenClawConfig;
+  changes: string[];
+  warnings: string[];
+};
+
+type RepairOptions = {
+  env?: NodeJS.ProcessEnv;
+  /** Test seam for the provider ids supplied by bundled or installed plugins. */
+  pluginProviderIds?: ReadonlySet<string>;
+  /** Test seam for provider ids already present in each agent's models.json. */
+  persistedProviderIdsByAgentId?: ReadonlyMap<string, ReadonlySet<string>>;
+};
+
+const DEFAULT_MODEL_REF = `${DEFAULT_PROVIDER}/${DEFAULT_MODEL}`;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function providerFromModelRef(ref: string): string | undefined {
+  const trimmed = ref.trim();
+  const slash = trimmed.indexOf("/");
+  if (slash <= 0 || slash === trimmed.length - 1) {
+    return undefined;
+  }
+  const provider = normalizeProviderId(trimmed.slice(0, slash));
+  return provider || undefined;
+}
+
+function collectPluginProviderIds(
+  cfg: OpenClawConfig,
+  options: RepairOptions,
+): { providerIds?: Set<string>; warnings: string[] } {
+  if (options.pluginProviderIds) {
+    return {
+      providerIds: new Set([...options.pluginProviderIds].map(normalizeProviderId).filter(Boolean)),
+      warnings: [],
+    };
+  }
+
+  const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));
+  const snapshot = resolvePluginMetadataSnapshot({
+    config: cfg,
+    workspaceDir: workspaceDir ?? undefined,
+    env: options.env ?? process.env,
+    allowWorkspaceScopedCurrent: true,
+  });
+  if (snapshot.diagnostics.some((diagnostic) => diagnostic.level === "error")) {
+    return {
+      warnings: [
+        "Skipped stale agent model reference repair because plugin discovery reported errors.",
+      ],
+    };
+  }
+
+  const providerIds = new Set<string>();
+  for (const owners of [
+    snapshot.owners.providers,
+    snapshot.owners.modelCatalogProviders,
+    snapshot.owners.setupProviders,
+    snapshot.owners.cliBackends,
+  ]) {
+    for (const providerId of owners.keys()) {
+      const normalized = normalizeProviderId(providerId);
+      if (normalized) {
+        providerIds.add(normalized);
+      }
+    }
+  }
+  return { providerIds, warnings: [] };
+}
+
+function collectPersistedProviderIds(params: {
+  cfg: OpenClawConfig;
+  agentId: string;
+  env: NodeJS.ProcessEnv;
+  injected?: ReadonlyMap<string, ReadonlySet<string>>;
+}): { providerIds?: Set<string>; warning?: string } {
+  const injected = params.injected?.get(params.agentId);
+  if (injected) {
+    return {
+      providerIds: new Set([...injected].map(normalizeProviderId).filter(Boolean)),
+    };
+  }
+  if (params.injected) {
+    return { providerIds: new Set() };
+  }
+
+  const modelsPath = path.join(
+    resolveAgentDir(params.cfg, params.agentId, params.env),
+    "models.json",
+  );
+  let raw: string;
+  try {
+    raw = fs.readFileSync(modelsPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { providerIds: new Set() };
+    }
+    return {
+      warning: `Skipped stale model reference repair for agent "${params.agentId}" because ${modelsPath} could not be read.`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(raw) as { providers?: unknown };
+    if (
+      !parsed.providers ||
+      typeof parsed.providers !== "object" ||
+      Array.isArray(parsed.providers)
+    ) {
+      return { providerIds: new Set() };
+    }
+    return {
+      providerIds: new Set(Object.keys(parsed.providers).map(normalizeProviderId).filter(Boolean)),
+    };
+  } catch {
+    return {
+      warning: `Skipped stale model reference repair for agent "${params.agentId}" because ${modelsPath} is invalid JSON.`,
+    };
+  }
+}
+
+function repairModelMap(params: {
+  models: Record<string, unknown> | undefined;
+  path: string;
+  isStale: (ref: string) => string | undefined;
+  replacementRef?: string;
+  ensureReplacement?: boolean;
+  changes: string[];
+  warnings: string[];
+}): void {
+  if (!isRecord(params.models)) {
+    return;
+  }
+  const refs = Object.keys(params.models);
+  const staleRefs = refs.filter((ref) => params.isStale(ref));
+  if (staleRefs.length === refs.length && staleRefs.length > 0 && !params.replacementRef) {
+    params.warnings.push(
+      `Skipped clearing ${params.path} because no available replacement model could keep the allowlist restrictive.`,
+    );
+    return;
+  }
+  for (const ref of staleRefs) {
+    const provider = params.isStale(ref);
+    delete params.models[ref];
+    params.changes.push(
+      `Removed stale ${params.path} entry "${ref}" (provider "${provider}" is unavailable).`,
+    );
+  }
+  if (
+    refs.length > 0 &&
+    (staleRefs.length > 0 || params.ensureReplacement === true) &&
+    params.replacementRef &&
+    !Object.hasOwn(params.models, params.replacementRef)
+  ) {
+    params.models[params.replacementRef] = {};
+    params.changes.push(
+      `Added ${params.path} entry "${params.replacementRef}" to keep the repaired allowlist restrictive.`,
+    );
+  }
+}
+
+function filterFallbacks(params: {
+  model: Exclude<AgentModelConfig, string>;
+  path: string;
+  isStale: (ref: string) => string | undefined;
+  changes: string[];
+}): void {
+  if (!Array.isArray(params.model.fallbacks)) {
+    return;
+  }
+  params.model.fallbacks = params.model.fallbacks.filter((ref) => {
+    if (typeof ref !== "string") {
+      return true;
+    }
+    const provider = params.isStale(ref);
+    if (!provider) {
+      return true;
+    }
+    params.changes.push(
+      `Removed stale ${params.path} fallback "${ref}" (provider "${provider}" is unavailable).`,
+    );
+    return false;
+  });
+  if (params.model.fallbacks.length === 0) {
+    delete params.model.fallbacks;
+  }
+}
+
+function firstExplicitModelRef(cfg: OpenClawConfig): string | undefined {
+  if (!isRecord(cfg.models?.providers)) {
+    return undefined;
+  }
+  for (const [providerId, provider] of Object.entries(cfg.models.providers)) {
+    if (!isRecord(provider) || !Array.isArray(provider.models)) {
+      continue;
+    }
+    const normalizedProvider = normalizeProviderId(providerId);
+    const modelId = provider.models
+      .map((model) => (isRecord(model) && typeof model.id === "string" ? model.id.trim() : ""))
+      .find(Boolean);
+    if (normalizedProvider && modelId) {
+      return `${normalizedProvider}/${modelId}`;
+    }
+  }
+  return undefined;
+}
+
+function modelPrimaryRef(model: unknown): string | undefined {
+  if (typeof model === "string") {
+    return model;
+  }
+  return isRecord(model) && typeof model.primary === "string" ? model.primary : undefined;
+}
+
+export function repairStaleAgentModelRefs(
+  cfg: OpenClawConfig,
+  options: RepairOptions = {},
+): StaleAgentModelRefRepair {
+  const replaceMode = cfg.models?.mode === "replace";
+  const pluginProviders = replaceMode
+    ? { providerIds: new Set<string>(), warnings: [] }
+    : collectPluginProviderIds(cfg, options);
+  if (!pluginProviders.providerIds) {
+    return { config: cfg, changes: [], warnings: pluginProviders.warnings };
+  }
+
+  // Bundled core providers declare provider ownership in their plugin manifests,
+  // so the metadata snapshot is the canonical inventory for both core and plugins.
+  const baseAvailableProviders = pluginProviders.providerIds;
+  if (!replaceMode) {
+    baseAvailableProviders.add(normalizeProviderId(DEFAULT_PROVIDER));
+  }
+  for (const providerId of Object.keys(cfg.models?.providers ?? {})) {
+    const normalized = normalizeProviderId(providerId);
+    if (normalized) {
+      baseAvailableProviders.add(normalized);
+    }
+  }
+  for (const backendId of Object.keys(
+    isRecord(cfg.agents?.defaults?.cliBackends) ? cfg.agents.defaults.cliBackends : {},
+  )) {
+    const normalized = normalizeProviderId(backendId);
+    if (normalized) {
+      baseAvailableProviders.add(normalized);
+    }
+  }
+
+  const config = structuredClone(cfg);
+  const changes: string[] = [];
+  const warnings = [...pluginProviders.warnings];
+  const env = options.env ?? process.env;
+  const persistedForAgent = (agentId: string): Set<string> | undefined => {
+    const persisted = collectPersistedProviderIds({
+      cfg,
+      agentId,
+      env,
+      injected: options.persistedProviderIdsByAgentId,
+    });
+    if (!persisted.providerIds) {
+      if (persisted.warning) {
+        warnings.push(persisted.warning);
+      }
+      return undefined;
+    }
+    return persisted.providerIds;
+  };
+  const availabilityForAgent = (agentId: string): Set<string> | undefined => {
+    const available = new Set(baseAvailableProviders);
+    if (replaceMode) {
+      return available;
+    }
+    const persisted = persistedForAgent(agentId);
+    if (!persisted) {
+      return undefined;
+    }
+    for (const providerId of persisted) {
+      available.add(providerId);
+    }
+    return available;
+  };
+  const availabilityForDefaults = (): Set<string> | undefined => {
+    const available = new Set(baseAvailableProviders);
+    if (replaceMode) {
+      return available;
+    }
+    const inheritingAgentIds: string[] = [];
+    for (const agent of Array.isArray(cfg.agents?.list) ? cfg.agents.list : []) {
+      if (!isRecord(agent) || typeof agent.id !== "string") {
+        continue;
+      }
+      const explicitPrimary = modelPrimaryRef(agent.model);
+      if (!explicitPrimary) {
+        inheritingAgentIds.push(agent.id);
+        continue;
+      }
+      const agentAvailability = availabilityForAgent(agent.id);
+      const provider = providerFromModelRef(explicitPrimary);
+      if (agentAvailability && provider && !agentAvailability.has(provider)) {
+        // This stale override will be removed or replaced later in the same repair.
+        inheritingAgentIds.push(agent.id);
+      }
+    }
+    if (inheritingAgentIds.length === 0) {
+      inheritingAgentIds.push(resolveDefaultAgentId(cfg));
+    }
+    let commonPersisted: Set<string> | undefined;
+    for (const agentId of inheritingAgentIds) {
+      const persisted = persistedForAgent(agentId);
+      if (!persisted) {
+        return undefined;
+      }
+      commonPersisted = commonPersisted
+        ? new Set([...commonPersisted].filter((providerId) => persisted.has(providerId)))
+        : new Set(persisted);
+    }
+    for (const providerId of commonPersisted ?? []) {
+      available.add(providerId);
+    }
+    return available;
+  };
+  const availabilityForDefaultModelMap = (): Set<string> | undefined => {
+    const available = new Set(baseAvailableProviders);
+    if (replaceMode) {
+      return available;
+    }
+    const inheritingAgentIds = (Array.isArray(cfg.agents?.list) ? cfg.agents.list : [])
+      .filter((agent) => isRecord(agent) && typeof agent.id === "string" && !isRecord(agent.models))
+      .map((agent) => agent.id as string);
+    if (inheritingAgentIds.length === 0) {
+      inheritingAgentIds.push(resolveDefaultAgentId(cfg));
+    }
+    for (const agentId of inheritingAgentIds) {
+      const persisted = persistedForAgent(agentId);
+      if (!persisted) {
+        return undefined;
+      }
+      for (const providerId of persisted) {
+        available.add(providerId);
+      }
+    }
+    return available;
+  };
+  const makeStaleChecker = (available: ReadonlySet<string>) => (ref: string) => {
+    const provider = providerFromModelRef(ref);
+    return provider && !available.has(provider) ? provider : undefined;
+  };
+
+  const defaults = config.agents?.defaults;
+  const defaultAvailability = availabilityForDefaults();
+  const configuredDefaultPrimary = modelPrimaryRef(defaults?.model);
+  let repairedDefaultPrimary =
+    configuredDefaultPrimary ?? (replaceMode ? firstExplicitModelRef(cfg) : DEFAULT_MODEL_REF);
+  let defaultPrimaryChanged = false;
+  if (defaults && defaultAvailability) {
+    const isStale = makeStaleChecker(defaultAvailability);
+    const configuredReplacement = replaceMode ? firstExplicitModelRef(cfg) : DEFAULT_MODEL_REF;
+    if (defaults.model) {
+      if (typeof defaults.model === "string") {
+        const provider = isStale(defaults.model);
+        if (provider) {
+          const staleRef = defaults.model;
+          if (configuredReplacement) {
+            defaults.model = configuredReplacement;
+            defaultPrimaryChanged = true;
+            changes.push(
+              `Replaced stale agents.defaults.model "${staleRef}" with default "${configuredReplacement}" (provider "${provider}" is unavailable).`,
+            );
+          } else {
+            delete defaults.model;
+            defaultPrimaryChanged = true;
+            changes.push(
+              `Removed stale agents.defaults.model "${staleRef}" because provider "${provider}" is unavailable and no replacement model is configured.`,
+            );
+          }
+        }
+      } else if (isRecord(defaults.model)) {
+        const provider =
+          typeof defaults.model.primary === "string" ? isStale(defaults.model.primary) : undefined;
+        let replacement: string | undefined;
+        if (provider && typeof defaults.model.primary === "string") {
+          const staleRef = defaults.model.primary;
+          replacement = replaceMode
+            ? ((Array.isArray(defaults.model.fallbacks)
+                ? defaults.model.fallbacks.find(
+                    (fallback) => typeof fallback === "string" && !isStale(fallback),
+                  )
+                : undefined) ?? configuredReplacement)
+            : configuredReplacement;
+          if (replacement) {
+            defaults.model.primary = replacement;
+            defaultPrimaryChanged = true;
+            changes.push(
+              `Replaced stale agents.defaults.model primary "${staleRef}" with default "${replacement}" (provider "${provider}" is unavailable).`,
+            );
+          } else {
+            delete defaults.model.primary;
+            defaultPrimaryChanged = true;
+            changes.push(
+              `Removed stale agents.defaults.model primary "${staleRef}" because provider "${provider}" is unavailable and no replacement model is configured.`,
+            );
+          }
+        }
+        filterFallbacks({
+          model: defaults.model,
+          path: "agents.defaults.model",
+          isStale,
+          changes,
+        });
+        if (
+          replacement &&
+          Array.isArray(defaults.model.fallbacks) &&
+          defaults.model.fallbacks.includes(replacement)
+        ) {
+          defaults.model.fallbacks = defaults.model.fallbacks.filter(
+            (fallback) => fallback !== replacement,
+          );
+          changes.push(
+            `Removed duplicate agents.defaults.model fallback "${replacement}" after selecting it as the default primary.`,
+          );
+          if (defaults.model.fallbacks.length === 0) {
+            delete defaults.model.fallbacks;
+          }
+        }
+        if (!defaults.model.primary && !defaults.model.fallbacks) {
+          delete defaults.model;
+        }
+      }
+    }
+    repairedDefaultPrimary =
+      modelPrimaryRef(defaults.model) ??
+      (replaceMode ? firstExplicitModelRef(cfg) : DEFAULT_MODEL_REF);
+    const modelMapAvailability = availabilityForDefaultModelMap();
+    if (modelMapAvailability) {
+      repairModelMap({
+        models: defaults.models,
+        path: "agents.defaults.models",
+        isStale: makeStaleChecker(modelMapAvailability),
+        replacementRef: repairedDefaultPrimary,
+        ensureReplacement: defaultPrimaryChanged,
+        changes,
+        warnings,
+      });
+    }
+  }
+
+  for (const [index, agent] of (Array.isArray(config.agents?.list)
+    ? config.agents.list
+    : []
+  ).entries()) {
+    if (!isRecord(agent) || typeof agent.id !== "string") {
+      continue;
+    }
+    const available = availabilityForAgent(agent.id);
+    if (!available) {
+      continue;
+    }
+    const isStale = makeStaleChecker(available);
+    const modelPath = `agents.list[${index}].model`;
+    const inheritedDefaultAvailable = Boolean(
+      defaultAvailability &&
+      repairedDefaultPrimary &&
+      (!replaceMode || modelPrimaryRef(defaults?.model)) &&
+      !isStale(repairedDefaultPrimary),
+    );
+    const canInheritDefault = inheritedDefaultAvailable;
+    let agentPrimaryChanged = false;
+    if (typeof agent.model === "string") {
+      const provider = isStale(agent.model);
+      if (provider) {
+        const staleRef = agent.model;
+        if (canInheritDefault) {
+          delete agent.model;
+          agentPrimaryChanged = true;
+          changes.push(
+            `Removed stale ${modelPath} "${staleRef}" so agent "${agent.id}" inherits the default model (provider "${provider}" is unavailable).`,
+          );
+        } else if (repairedDefaultPrimary && !isStale(repairedDefaultPrimary)) {
+          agent.model = repairedDefaultPrimary;
+          agentPrimaryChanged = true;
+          changes.push(
+            `Replaced stale ${modelPath} "${staleRef}" with "${repairedDefaultPrimary}" (provider "${provider}" is unavailable).`,
+          );
+        } else {
+          warnings.push(
+            `Skipped stale ${modelPath} repair because no available inherited or replacement model is configured.`,
+          );
+        }
+      }
+    } else if (isRecord(agent.model)) {
+      const provider =
+        typeof agent.model.primary === "string" ? isStale(agent.model.primary) : undefined;
+      let agentReplacement: string | undefined;
+      if (provider && typeof agent.model.primary === "string") {
+        const staleRef = agent.model.primary;
+        if (canInheritDefault) {
+          delete agent.model.primary;
+          agentPrimaryChanged = true;
+          agentReplacement = repairedDefaultPrimary;
+          changes.push(
+            `Removed stale ${modelPath} primary "${staleRef}" so agent "${agent.id}" inherits the default model (provider "${provider}" is unavailable).`,
+          );
+        } else if (
+          (agentReplacement =
+            (Array.isArray(agent.model.fallbacks)
+              ? agent.model.fallbacks.find(
+                  (fallback) => typeof fallback === "string" && !isStale(fallback),
+                )
+              : undefined) ??
+            (repairedDefaultPrimary && !isStale(repairedDefaultPrimary)
+              ? repairedDefaultPrimary
+              : undefined))
+        ) {
+          agent.model.primary = agentReplacement;
+          agentPrimaryChanged = true;
+          changes.push(
+            `Replaced stale ${modelPath} primary "${staleRef}" with "${agentReplacement}" (provider "${provider}" is unavailable).`,
+          );
+        } else {
+          warnings.push(
+            `Skipped stale ${modelPath} primary repair because no available inherited or replacement model is configured.`,
+          );
+        }
+      }
+      filterFallbacks({ model: agent.model, path: modelPath, isStale, changes });
+      if (
+        agentReplacement &&
+        Array.isArray(agent.model.fallbacks) &&
+        agent.model.fallbacks.includes(agentReplacement)
+      ) {
+        agent.model.fallbacks = agent.model.fallbacks.filter(
+          (fallback) => fallback !== agentReplacement,
+        );
+        changes.push(
+          `Removed duplicate ${modelPath} fallback "${agentReplacement}" after selecting it as the primary.`,
+        );
+        if (agent.model.fallbacks.length === 0) {
+          delete agent.model.fallbacks;
+        }
+      }
+      if (!agent.model.primary && !agent.model.fallbacks) {
+        delete agent.model;
+      }
+    }
+    const effectiveAgentPrimary = modelPrimaryRef(agent.model) ?? repairedDefaultPrimary;
+    repairModelMap({
+      models: agent.models,
+      path: `agents.list[${index}].models`,
+      isStale,
+      replacementRef:
+        effectiveAgentPrimary && !isStale(effectiveAgentPrimary)
+          ? effectiveAgentPrimary
+          : undefined,
+      ensureReplacement:
+        agentPrimaryChanged || (!modelPrimaryRef(agent.model) && defaultPrimaryChanged),
+      changes,
+      warnings,
+    });
+  }
+
+  return { config: changes.length > 0 ? config : cfg, changes, warnings };
+}

From efa7e1a85ad795df08466891264ad408fb46fd78 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 19:25:40 +0800
Subject: [PATCH 48/76] fix(scripts): bound conflict-marker scan reads to
 prevent OOM on large files (#104420)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(scripts): bound conflict-marker scan reads to prevent OOM on large files

* test(scripts): add regression test for bounded conflict-marker scan on large files

* fix(scripts): update conflict-marker declaration for bounded scan params

* fix(scripts): bounded exact scan for conflict markers

* fix(scripts): use git grep line-number output for conflict-marker scan

* style(scripts): rename shadowed variable in conflict-marker parser

* ci(scripts): retry build artifacts after plugin-sdk export check flake

* fix(scripts): report tracked conflict-marker paths relative to cwd

* test(scripts): type execFileSync error by stderr shape

* fix(scripts): parse NUL-delimited path before record split in conflict-marker scan

* refactor(scripts): remove obsolete conflict scan helper

* fix(scripts): disable color in conflict marker scan

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 scripts/check-no-conflict-markers.d.mts       |  30 +--
 scripts/check-no-conflict-markers.mjs         |  97 +++++----
 .../scripts/check-no-conflict-markers.test.ts | 185 +++++++++++++++++-
 3 files changed, 255 insertions(+), 57 deletions(-)

diff --git a/scripts/check-no-conflict-markers.d.mts b/scripts/check-no-conflict-markers.d.mts
index ad1ceb752ca..984440cd201 100644
--- a/scripts/check-no-conflict-markers.d.mts
+++ b/scripts/check-no-conflict-markers.d.mts
@@ -2,30 +2,30 @@
 /**
  * Returns one-based line numbers containing merge conflict markers.
  */
-export function findConflictMarkerLines(content: unknown): unknown[];
+export function findConflictMarkerLines(content: string): number[];
 /**
- * Lists tracked files in the repository.
- */
-export function listTrackedFiles(cwd?: string): string[];
-/**
- * Scans files for merge conflict markers, skipping binary content.
+ * Scans a list of files for merge conflict markers, skipping binary content.
+ * Intended for direct/small-scale use; the tracked-files path uses git grep
+ * directly to avoid reading large files into memory.
  */
 export function findConflictMarkersInFiles(
-  filePaths: unknown,
-  readFile?: typeof fs.readFileSync,
+  filePaths: string[],
+  readFile?: (path: string) => string | Buffer,
 ): {
-  filePath: unknown;
-  lines: unknown[];
+  filePath: string;
+  lines: number[];
 }[];
 /**
- * Finds merge conflict markers in tracked repository files.
+ * Uses git grep to find exact conflict-marker matches in tracked files.
  */
-export function findConflictMarkersInTrackedFiles(cwd?: string): {
-  filePath: unknown;
-  lines: unknown[];
+export function findConflictMarkersInTrackedFiles(
+  cwd?: string,
+  run?: typeof import("node:child_process").spawnSync,
+): {
+  filePath: string;
+  lines: number[];
 }[];
 /**
  * Runs the merge conflict marker check.
  */
 export function main(): Promise<void>;
-import fs from "node:fs";
diff --git a/scripts/check-no-conflict-markers.mjs b/scripts/check-no-conflict-markers.mjs
index 807cc6cd6eb..2c9bf136293 100644
--- a/scripts/check-no-conflict-markers.mjs
+++ b/scripts/check-no-conflict-markers.mjs
@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // Rejects unresolved merge conflict markers in tracked files.
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -32,21 +32,9 @@ export function findConflictMarkerLines(content) {
 }
 
 /**
- * Lists tracked files in the repository.
- */
-export function listTrackedFiles(cwd = process.cwd()) {
-  const output = execFileSync("git", ["ls-files", "-z"], {
-    cwd,
-    encoding: "utf8",
-  });
-  return output
-    .split("\0")
-    .filter(Boolean)
-    .map((relativePath) => path.join(cwd, relativePath));
-}
-
-/**
- * Scans files for merge conflict markers, skipping binary content.
+ * Scans a list of files for merge conflict markers, skipping binary content.
+ * This is kept for direct, small-scale use (tests); the tracked-files path
+ * uses git grep directly to avoid reading large files into memory.
  */
 export function findConflictMarkersInFiles(filePaths, readFile = fs.readFileSync) {
   const violations = [];
@@ -75,12 +63,66 @@ export function findConflictMarkersInFiles(filePaths, readFile = fs.readFileSync
 }
 
 /**
- * Uses git grep to list tracked files that may contain conflict markers.
+ * Parses output from `git grep -n -z -o -I -E` into violation records.
+ * The record format is:
+ *   path\0line-number\0match-text\n
+ * The path must be read from its NUL delimiter before any newline-based
+ * record splitting: -z reports paths verbatim, and git allows newlines in
+ * tracked filenames, so splitting the output on newlines first would cut a
+ * newline-containing path across two records and silently mangle it.
+ * Keeping parsing to exact grep match records avoids reading candidate files
+ * whole and keeps memory bounded regardless of file size.
  */
-function listTrackedFilesWithConflictMarkerCandidates(cwd = process.cwd(), run = spawnSync) {
+function parseGitGrepConflictMarkerOutput(stdout) {
+  const byPath = new Map();
+  const output = stdout.toString("utf8");
+  let cursor = 0;
+
+  while (cursor < output.length) {
+    const pathEnd = output.indexOf("\0", cursor);
+    if (pathEnd === -1) {
+      break;
+    }
+    const lineNumberEnd = output.indexOf("\0", pathEnd + 1);
+    if (lineNumberEnd === -1) {
+      break;
+    }
+    // With -o the match text is a single-line match, so the record ends at
+    // the next newline after the line-number field.
+    const matchEnd = output.indexOf("\n", lineNumberEnd + 1);
+    const relativePath = output.slice(cursor, pathEnd);
+    const lineNumber = Number(output.slice(pathEnd + 1, lineNumberEnd));
+    cursor = matchEnd === -1 ? output.length : matchEnd + 1;
+    if (!relativePath || !Number.isFinite(lineNumber) || lineNumber <= 0) {
+      continue;
+    }
+    const existing = byPath.get(relativePath);
+    if (existing) {
+      existing.push(lineNumber);
+    } else {
+      byPath.set(relativePath, [lineNumber]);
+    }
+  }
+
+  const violations = [];
+  for (const [relativePath, lineNumbers] of byPath) {
+    lineNumbers.sort((a, b) => a - b);
+    violations.push({
+      filePath: relativePath,
+      lines: lineNumbers,
+    });
+  }
+  violations.sort((a, b) => a.filePath.localeCompare(b.filePath));
+  return violations;
+}
+
+/**
+ * Uses git grep to find exact conflict-marker matches in tracked files.
+ */
+export function findConflictMarkersInTrackedFiles(cwd = process.cwd(), run = spawnSync) {
   const result = run(
     "git",
-    ["grep", "-l", "-z", "-I", "-E", CONFLICT_MARKER_GREP_PATTERN, "--", "."],
+    ["grep", "--no-color", "-n", "-z", "-o", "-I", "-E", CONFLICT_MARKER_GREP_PATTERN, "--", "."],
     {
       cwd,
       encoding: "buffer",
@@ -93,18 +135,7 @@ function listTrackedFilesWithConflictMarkerCandidates(cwd = process.cwd(), run =
     const stderr = result.stderr?.toString("utf8").trim();
     throw new Error(stderr || `git grep failed with status ${result.status ?? "unknown"}`);
   }
-  return result.stdout
-    .toString("utf8")
-    .split("\0")
-    .filter(Boolean)
-    .map((relativePath) => path.join(cwd, relativePath));
-}
-
-/**
- * Finds merge conflict markers in tracked repository files.
- */
-export function findConflictMarkersInTrackedFiles(cwd = process.cwd()) {
-  return findConflictMarkersInFiles(listTrackedFilesWithConflictMarkerCandidates(cwd));
+  return parseGitGrepConflictMarkerOutput(result.stdout);
 }
 
 /**
@@ -119,8 +150,8 @@ export async function main() {
 
   console.error("Found unresolved merge conflict markers:");
   for (const violation of violations) {
-    const relativePath = path.relative(cwd, violation.filePath) || violation.filePath;
-    console.error(`- ${relativePath}:${violation.lines.join(",")}`);
+    // findConflictMarkersInTrackedFiles already returns paths relative to cwd.
+    console.error(`- ${violation.filePath}:${violation.lines.join(",")}`);
   }
   process.exitCode = 1;
 }
diff --git a/test/scripts/check-no-conflict-markers.test.ts b/test/scripts/check-no-conflict-markers.test.ts
index dcd8b6ff234..f950a9a5a53 100644
--- a/test/scripts/check-no-conflict-markers.test.ts
+++ b/test/scripts/check-no-conflict-markers.test.ts
@@ -7,7 +7,6 @@ import {
   findConflictMarkerLines,
   findConflictMarkersInFiles,
   findConflictMarkersInTrackedFiles,
-  listTrackedFiles,
 } from "../../scripts/check-no-conflict-markers.mjs";
 import { createScriptTestHarness } from "./test-helpers.js";
 
@@ -63,16 +62,17 @@ describe("check-no-conflict-markers", () => {
     ]);
   });
 
-  it("finds conflict markers in tracked script files", () => {
+  it("finds conflict markers in tracked files using git grep", () => {
     const rootDir = createTempDir("openclaw-conflict-markers-");
     git(rootDir, "init", "-q");
     git(rootDir, "config", "user.email", "test@example.com");
     git(rootDir, "config", "user.name", "Test User");
 
-    const scriptFile = path.join(rootDir, "scripts", "bundled-plugin-metadata-runtime.mjs");
-    fs.mkdirSync(path.dirname(scriptFile), { recursive: true });
+    const scriptFile = "scripts/bundled-plugin-metadata-runtime.mjs";
+    const scriptPath = path.join(rootDir, scriptFile);
+    fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
     fs.writeFileSync(
-      scriptFile,
+      scriptPath,
       [
         "<<<<<<< HEAD",
         'const left = "left";',
@@ -81,22 +81,189 @@ describe("check-no-conflict-markers", () => {
         ">>>>>>> branch",
       ].join("\n"),
     );
-    git(rootDir, "add", "scripts/bundled-plugin-metadata-runtime.mjs");
+    git(rootDir, "add", scriptFile);
 
-    expect(findConflictMarkersInFiles(listTrackedFiles(rootDir))).toEqual([
+    const violations = findConflictMarkersInTrackedFiles(rootDir);
+
+    expect(violations).toEqual([
       {
         filePath: scriptFile,
         lines: [1, 3, 5],
       },
     ]);
+  });
+
+  it("disables configured git grep colors before parsing records", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+    git(rootDir, "config", "color.grep", "always");
+    git(rootDir, "config", "color.grep.lineNumber", "red");
+
+    const conflictFile = "src/conflict.ts";
+    const conflictPath = path.join(rootDir, conflictFile);
+    fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
+    fs.writeFileSync(conflictPath, "<<<<<<< HEAD\nleft\n=======\nright\n>>>>>>> branch\n");
+    git(rootDir, "add", conflictFile);
+
+    expect(findConflictMarkersInTrackedFiles(rootDir)).toEqual([
+      {
+        filePath: conflictFile,
+        lines: [1, 3, 5],
+      },
+    ]);
+  });
+
+  it("returns no violations when tracked files have no conflict markers", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    const cleanFile = "src/clean.ts";
+    const cleanPath = path.join(rootDir, cleanFile);
+    fs.mkdirSync(path.dirname(cleanPath), { recursive: true });
+    fs.writeFileSync(cleanPath, "const x = 1;\n");
+    git(rootDir, "add", cleanFile);
+
+    expect(findConflictMarkersInTrackedFiles(rootDir)).toEqual([]);
+  });
+
+  it("skips binary tracked files via git grep binary exclusion", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    const binaryFile = "assets/image.png";
+    const binaryPath = path.join(rootDir, binaryFile);
+    fs.mkdirSync(path.dirname(binaryPath), { recursive: true });
+    // Marker-like bytes inside a binary file should not be reported because
+    // git grep -I skips binary files.
+    fs.writeFileSync(
+      binaryPath,
+      Buffer.from([0x3c, 0x3c, 0x3c, 0x3c, 0x3c, 0x3c, 0x3c, 0x20, 0x00]),
+    );
+    git(rootDir, "add", binaryFile);
+
+    expect(findConflictMarkersInTrackedFiles(rootDir)).toEqual([]);
+  });
+
+  it("handles tracked files with spaces and unusual characters in paths", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    const weirdFile = "docs/weird name (v2).md";
+    const weirdPath = path.join(rootDir, weirdFile);
+    fs.mkdirSync(path.dirname(weirdPath), { recursive: true });
+    fs.writeFileSync(
+      weirdPath,
+      "before\n<<<<<<< HEAD\nleft\n=======\nright\n>>>>>>> branch\nafter\n",
+    );
+    git(rootDir, "add", weirdFile);
 
     const violations = findConflictMarkersInTrackedFiles(rootDir);
 
     expect(violations).toEqual([
       {
-        filePath: scriptFile,
-        lines: [1, 3, 5],
+        filePath: weirdFile,
+        lines: [2, 4, 6],
       },
     ]);
   });
+
+  it("reports tracked filenames containing newlines without mangling the path", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    // git allows newlines in tracked filenames and git grep -z prints the
+    // path verbatim; the parser must read the NUL-delimited path before any
+    // newline-based record splitting or the path is silently truncated.
+    const newlineFile = "docs/weird\nname.md";
+    const newlinePath = path.join(rootDir, newlineFile);
+    fs.mkdirSync(path.dirname(newlinePath), { recursive: true });
+    fs.writeFileSync(
+      newlinePath,
+      "before\n<<<<<<< HEAD\nleft\n=======\nright\n>>>>>>> branch\nafter\n",
+    );
+    git(rootDir, "add", newlineFile);
+
+    const violations = findConflictMarkersInTrackedFiles(rootDir);
+
+    expect(violations).toEqual([
+      {
+        filePath: newlineFile,
+        lines: [2, 4, 6],
+      },
+    ]);
+  });
+
+  it("detects markers in a file larger than the previous scan byte limit without reading it whole", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    const largeFile = "generated/large.txt";
+    const largePath = path.join(rootDir, largeFile);
+    fs.mkdirSync(path.dirname(largePath), { recursive: true });
+    // 10 MiB of filler with a marker near the end; git grep reports the line
+    // number without us buffering the entire file.
+    const filler = ("a".repeat(10240) + "\n").repeat(1024);
+    fs.writeFileSync(largePath, filler + "<<<<<<< HEAD\nleft\n=======\nright\n>>>>>>> branch\n");
+    git(rootDir, "add", largeFile);
+
+    const violations = findConflictMarkersInTrackedFiles(rootDir);
+
+    expect(violations).toEqual([
+      {
+        filePath: largeFile,
+        lines: [1025, 1027, 1029],
+      },
+    ]);
+  });
+
+  it("main reports tracked violations with paths relative to cwd", () => {
+    const rootDir = createTempDir("openclaw-conflict-markers-main-");
+    git(rootDir, "init", "-q");
+    git(rootDir, "config", "user.email", "test@example.com");
+    git(rootDir, "config", "user.name", "Test User");
+
+    const conflictFile = "src/conflict.ts";
+    const conflictPath = path.join(rootDir, conflictFile);
+    fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
+    fs.writeFileSync(
+      conflictPath,
+      [
+        "<<<<<<< HEAD",
+        'const value = "left";',
+        "=======",
+        'const value = "right";',
+        ">>>>>>> branch",
+      ].join("\n"),
+    );
+    git(rootDir, "add", conflictFile);
+
+    const scriptPath = path.resolve(__dirname, "../../scripts/check-no-conflict-markers.mjs");
+    let error: Error | undefined;
+    try {
+      execFileSync(process.execPath, [scriptPath], {
+        cwd: rootDir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (caught) {
+      error = caught as Error;
+    }
+
+    expect(error).toBeDefined();
+    const stderr = (error as { stderr?: string }).stderr ?? "";
+    expect(stderr).toContain("Found unresolved merge conflict markers:");
+    expect(stderr).toContain(`- ${conflictFile}:1,3,5`);
+  });
 });

From 60cb6d78de9057befd3bacc78fe222dd575978bc Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:26:25 +0100
Subject: [PATCH 49/76] perf(ui): lazy-load the lobster pet out of the Control
 UI startup graph (#110628)

* perf(ui): lazy-load the lobster pet out of the Control UI startup graph

Keep the lightweight lobster contract on the sidebar's static path while idle-loading the heavy pet implementation. Move the logo stand-in custom element into the pet module so both decorative elements upgrade together after the lazy import.

* style(ui): format lobster-pet lazy boundary

* fix(ui): clear the lobster-pet chunk cache on load failure

A rejected import stayed cached forever and surfaced as an unhandled
rejection; clearing it lets a later scheduling call retry.

* fix(ui): retry the lobster-pet chunk once connectivity returns
---
 ui/src/components/app-sidebar.ts              |  61 +++---
 ui/src/components/lobster-pet-contract.ts     | 130 ++++++++++++
 ui/src/components/lobster-pet.ts              | 191 ++++++------------
 ui/src/e2e/sidebar-customization.e2e.test.ts  |   1 +
 .../app-sidebar-cases/sessions.ts             |  19 +-
 5 files changed, 240 insertions(+), 162 deletions(-)
 create mode 100644 ui/src/components/lobster-pet-contract.ts

diff --git a/ui/src/components/app-sidebar.ts b/ui/src/components/app-sidebar.ts
index d0c387b1911..2d7694e8b0d 100644
--- a/ui/src/components/app-sidebar.ts
+++ b/ui/src/components/app-sidebar.ts
@@ -22,20 +22,40 @@ import { AppSidebarSessionListElement } from "./app-sidebar-session-list.ts";
 import { icons } from "./icons.ts";
 import {
   LOBSTER_LOGO_VISIT_EVENT,
-  LOBSTER_PET_BUILD_MULS,
-  LOBSTER_PET_CLAW_MULS,
   lobsterPetSeed,
-  renderLobsterSvg,
   resolveLobsterPetMode,
   resolveLobsterRunOutcome,
   type LobsterLogoVisitDetail,
-} from "./lobster-pet.ts";
+} from "./lobster-pet-contract.ts";
 
 const PALETTE_SHORTCUT = /Mac|iP(hone|ad|od)/i.test(globalThis.navigator?.platform ?? "")
   ? "⌘K"
   : "Ctrl K";
 const OFFLINE_INDICATOR_DELAY_MS = 2_000;
 
+let lobsterPetModuleLoad: Promise<unknown> | null = null;
+
+function scheduleLobsterPetLoad() {
+  if (lobsterPetModuleLoad || customElements.get("openclaw-lobster-pet")) {
+    return;
+  }
+  const start = () => {
+    // A failed chunk fetch must not pin a rejected promise forever: clear the
+    // cache and retry when connectivity returns. The sidebar mounts once per
+    // page, so without this a transient failure would disable the pet for the
+    // whole session; a deploy-pruned chunk stays off until reload, by design.
+    lobsterPetModuleLoad ??= import("./lobster-pet.ts").catch(() => {
+      lobsterPetModuleLoad = null;
+      window.addEventListener("online", () => start(), { once: true });
+    });
+  };
+  if ("requestIdleCallback" in window) {
+    requestIdleCallback(() => start(), { timeout: 3000 });
+  } else {
+    setTimeout(start, 1500);
+  }
+}
+
 class AppSidebar extends AppSidebarSessionListElement {
   @state() private logoVisit: LobsterLogoVisitDetail | null = null;
   @state() private debouncedDisconnected = false;
@@ -51,6 +71,9 @@ class AppSidebar extends AppSidebarSessionListElement {
   override connectedCallback() {
     super.connectedCallback();
     this.syncOfflineIndicator();
+    // The decorative pet's large module stays out of startup and upgrades in place.
+    // Its first visit is at least 15 seconds after load, so idle loading cannot miss one.
+    scheduleLobsterPetLoad();
   }
 
   override disconnectedCallback() {
@@ -87,34 +110,6 @@ class AppSidebar extends AppSidebarSessionListElement {
     this.logoVisit = detail.phase === "out" ? null : detail;
   };
 
-  private renderLogoStandIn() {
-    const visit = this.logoVisit;
-    if (!visit?.look) {
-      return nothing;
-    }
-    const look = visit.look;
-    const classes = [
-      "sidebar-brand__pet",
-      `lobster-pet--palette-${look.palette.id}`,
-      visit.phase === "leaving" ? "sidebar-brand__pet--leaving" : "",
-    ]
-      .filter(Boolean)
-      .join(" ");
-    const style = [
-      `--lob-shell:${look.palette.shell}`,
-      `--lob-claw:${look.palette.claw}`,
-      `--lob-blink-delay:${look.blinkDelayS}s`,
-      `--lob-w:${LOBSTER_PET_BUILD_MULS[look.build].w}`,
-      `--lob-h:${LOBSTER_PET_BUILD_MULS[look.build].h}`,
-      `--lob-claw-scale:${LOBSTER_PET_CLAW_MULS[look.clawSize]}`,
-    ].join(";");
-    return html`
-      <span class=${classes} style=${style} title=${`${visit.name} · filling in for the logo`}
-        >${renderLobsterSvg(look)}</span
-      >
-    `;
-  }
-
   private renderBrand() {
     const collapseLabel = t("nav.collapse");
     const gatewayStatus = t("chat.gatewayStatus", {
@@ -238,7 +233,7 @@ class AppSidebar extends AppSidebarSessionListElement {
             alt=""
             aria-hidden="true"
           />
-          ${this.renderLogoStandIn()}
+          <openclaw-lobster-logo-standin .visit=${this.logoVisit}></openclaw-lobster-logo-standin>
         </span>
         <openclaw-sidebar-build-chip
           .basePath=${this.basePath}
diff --git a/ui/src/components/lobster-pet-contract.ts b/ui/src/components/lobster-pet-contract.ts
new file mode 100644
index 00000000000..b31e0eb8cab
--- /dev/null
+++ b/ui/src/components/lobster-pet-contract.ts
@@ -0,0 +1,130 @@
+export type LobsterPetMode = "idle" | "busy" | "offline";
+
+export type LobsterRunOutcome = "ok" | "error" | "aborted";
+
+export type LobsterPetPersonalityId = "sleepy" | "zoomy" | "friendly" | "showoff";
+
+export type LobsterPetPaletteId =
+  | "crimson"
+  | "coral"
+  | "teal"
+  | "violet"
+  | "ink"
+  | "blue"
+  | "gold"
+  | "calico"
+  | "abyss"
+  | "ghost"
+  | "split"
+  | "retro";
+
+export type LobsterPetPalette = {
+  id: LobsterPetPaletteId;
+  shell: string;
+  claw: string;
+};
+
+export type LobsterPetAccessory =
+  | "none"
+  | "crown"
+  | "sprout"
+  | "patch"
+  | "santa"
+  | "pumpkin"
+  | "party";
+
+export type LobsterPetAntennae = "perky" | "droopy";
+
+export type LobsterPetBuild = "round" | "squat" | "slender";
+
+export type LobsterPetClawSize = "dainty" | "regular" | "mighty";
+
+export type LobsterPetLook = {
+  palette: LobsterPetPalette;
+  scale: number;
+  accessory: LobsterPetAccessory;
+  antennae: LobsterPetAntennae;
+  side: "left" | "right";
+  spotPct: number;
+  facing: 1 | -1;
+  personality: LobsterPetPersonalityId;
+  blinkDelayS: number;
+  build: LobsterPetBuild;
+  clawSize: LobsterPetClawSize;
+  tailFan: boolean;
+};
+
+export type LobsterLogoVisitPhase = "in" | "leaving" | "out";
+
+export type LobsterLogoVisitDetail = {
+  phase: LobsterLogoVisitPhase;
+  // A null look on a non-"out" phase means "hide the logo, render no
+  // stand-in": a ledge visit scared the brand mark away.
+  look: LobsterPetLook | null;
+  name: string | null;
+};
+
+// Fired on the pet host whenever the logo stand-in phase changes; the
+// sidebar owns the brand slot, so the swap renders there, not here.
+export const LOBSTER_LOGO_VISIT_EVENT = "openclaw-lobster-logo-visit";
+
+function fnv1a(value: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return hash >>> 0;
+}
+
+// One salt per page load: revisiting the UI re-rolls every session's lobster,
+// while re-renders within a load stay stable for a given session key.
+const LOAD_SALT = Math.trunc(Math.random() * 0xffffffff);
+
+export function lobsterPetSeed(sessionKey: string): number {
+  return (fnv1a(sessionKey) ^ LOAD_SALT) >>> 0;
+}
+
+// The most recently active session with a terminal status decides how the
+// pet reacts when the busy state clears: failures earn sympathy, not cheers.
+export function resolveLobsterRunOutcome(
+  sessions:
+    | ReadonlyArray<{
+        status?: "running" | "done" | "failed" | "killed" | "timeout";
+        endedAt?: number | null;
+        lastActivityAt?: number | null;
+        updatedAt?: number | null;
+      }>
+    | null
+    | undefined,
+): LobsterRunOutcome {
+  let latest: { at: number; outcome: LobsterRunOutcome } | null = null;
+  for (const row of sessions ?? []) {
+    if (!row.status || row.status === "running") {
+      continue;
+    }
+    // endedAt is the run-completion timestamp; activity/updated stamps also
+    // move on unrelated events (reads, renames) and only serve as fallbacks.
+    const at = row.endedAt ?? row.lastActivityAt ?? row.updatedAt ?? 0;
+    if (!latest || at > latest.at) {
+      const outcome: LobsterRunOutcome =
+        row.status === "failed" || row.status === "timeout"
+          ? "error"
+          : row.status === "killed"
+            ? "aborted"
+            : "ok";
+      latest = { at, outcome };
+    }
+  }
+  return latest?.outcome ?? "ok";
+}
+
+export function resolveLobsterPetMode(
+  connected: boolean,
+  sessions: ReadonlyArray<{ hasActiveRun?: boolean | null }> | null | undefined,
+): LobsterPetMode {
+  if (!connected) {
+    return "offline";
+  }
+  return sessions?.some((row) => row.hasActiveRun === true) ? "busy" : "idle";
+}
diff --git a/ui/src/components/lobster-pet.ts b/ui/src/components/lobster-pet.ts
index 0cabe7a82b3..9795a58c327 100644
--- a/ui/src/components/lobster-pet.ts
+++ b/ui/src/components/lobster-pet.ts
@@ -20,6 +20,33 @@ import {
   recordLobsterVisit,
   type LobsterFamiliarity,
 } from "./lobster-dex.ts";
+import {
+  LOBSTER_LOGO_VISIT_EVENT,
+  type LobsterLogoVisitDetail,
+  type LobsterLogoVisitPhase,
+  type LobsterPetAccessory,
+  type LobsterPetAntennae,
+  type LobsterPetBuild,
+  type LobsterPetClawSize,
+  type LobsterPetLook,
+  type LobsterPetMode,
+  type LobsterPetPalette,
+  type LobsterPetPaletteId,
+  type LobsterPetPersonalityId,
+  type LobsterRunOutcome,
+} from "./lobster-pet-contract.ts";
+
+export {
+  LOBSTER_LOGO_VISIT_EVENT,
+  lobsterPetSeed,
+  resolveLobsterPetMode,
+  resolveLobsterRunOutcome,
+  type LobsterLogoVisitDetail,
+  type LobsterLogoVisitPhase,
+  type LobsterPetLook,
+  type LobsterPetMode,
+  type LobsterRunOutcome,
+} from "./lobster-pet-contract.ts";
 
 type LobsterPetAct =
   | "wave"
@@ -37,53 +64,6 @@ type LobsterPetAct =
   | "droop"
   | "sweep";
 
-type LobsterPetMode = "idle" | "busy" | "offline";
-
-type LobsterPetPersonalityId = "sleepy" | "zoomy" | "friendly" | "showoff";
-
-type LobsterPetPaletteId =
-  | "crimson"
-  | "coral"
-  | "teal"
-  | "violet"
-  | "ink"
-  | "blue"
-  | "gold"
-  | "calico"
-  | "abyss"
-  | "ghost"
-  | "split"
-  | "retro";
-
-type LobsterPetPalette = {
-  id: LobsterPetPaletteId;
-  shell: string;
-  claw: string;
-};
-
-type LobsterPetAccessory = "none" | "crown" | "sprout" | "patch" | "santa" | "pumpkin" | "party";
-
-type LobsterPetAntennae = "perky" | "droopy";
-
-type LobsterPetBuild = "round" | "squat" | "slender";
-
-type LobsterPetClawSize = "dainty" | "regular" | "mighty";
-
-type LobsterPetLook = {
-  palette: LobsterPetPalette;
-  scale: number;
-  accessory: LobsterPetAccessory;
-  antennae: LobsterPetAntennae;
-  side: "left" | "right";
-  spotPct: number;
-  facing: 1 | -1;
-  personality: LobsterPetPersonalityId;
-  blinkDelayS: number;
-  build: LobsterPetBuild;
-  clawSize: LobsterPetClawSize;
-  tailFan: boolean;
-};
-
 type ActProfile = {
   // [min, max] delay before the next act.
   delayMs: [number, number];
@@ -385,20 +365,6 @@ function isLobsterLogoLoad(seed: number): boolean {
   return mulberry32((seed ^ 0x1063) >>> 0)() < 0.12;
 }
 
-type LobsterLogoVisitPhase = "in" | "leaving" | "out";
-
-export type LobsterLogoVisitDetail = {
-  phase: LobsterLogoVisitPhase;
-  // A null look on a non-"out" phase means "hide the logo, render no
-  // stand-in": a ledge visit scared the brand mark away.
-  look: LobsterPetLook | null;
-  name: string | null;
-};
-
-// Fired on the pet host whenever the logo stand-in phase changes; the
-// sidebar owns the brand slot, so the swap renders there, not here.
-export const LOBSTER_LOGO_VISIT_EVENT = "openclaw-lobster-logo-visit";
-
 type LobsterPasserKind = "stranger" | "crab";
 
 type LobsterPasserPlan = {
@@ -461,15 +427,6 @@ function isLobsterNightTime(now: Date = new Date()): boolean {
   return hour >= 22 || hour < 6;
 }
 
-function fnv1a(value: string): number {
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < value.length; i++) {
-    hash ^= value.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193);
-  }
-  return hash >>> 0;
-}
-
 function mulberry32(seed: number): () => number {
   let a = seed >>> 0;
   return () => {
@@ -496,14 +453,6 @@ function randomBetween(rng: () => number, min: number, max: number): number {
   return min + rng() * (max - min);
 }
 
-// One salt per page load: revisiting the UI re-rolls every session's lobster,
-// while re-renders within a load stay stable for a given session key.
-const LOAD_SALT = Math.trunc(Math.random() * 0xffffffff);
-
-export function lobsterPetSeed(sessionKey: string): number {
-  return (fnv1a(sessionKey) ^ LOAD_SALT) >>> 0;
-}
-
 export function createLobsterPetLook(seed: number, now: Date = new Date()): LobsterPetLook {
   const rng = mulberry32(seed);
   const palette = pickWeighted(rng, PALETTES);
@@ -555,52 +504,6 @@ export function createLobsterPetLook(seed: number, now: Date = new Date()): Lobs
   };
 }
 
-type LobsterRunOutcome = "ok" | "error" | "aborted";
-
-// The most recently active session with a terminal status decides how the
-// pet reacts when the busy state clears: failures earn sympathy, not cheers.
-export function resolveLobsterRunOutcome(
-  sessions:
-    | ReadonlyArray<{
-        status?: "running" | "done" | "failed" | "killed" | "timeout";
-        endedAt?: number | null;
-        lastActivityAt?: number | null;
-        updatedAt?: number | null;
-      }>
-    | null
-    | undefined,
-): LobsterRunOutcome {
-  let latest: { at: number; outcome: LobsterRunOutcome } | null = null;
-  for (const row of sessions ?? []) {
-    if (!row.status || row.status === "running") {
-      continue;
-    }
-    // endedAt is the run-completion timestamp; activity/updated stamps also
-    // move on unrelated events (reads, renames) and only serve as fallbacks.
-    const at = row.endedAt ?? row.lastActivityAt ?? row.updatedAt ?? 0;
-    if (!latest || at > latest.at) {
-      const outcome: LobsterRunOutcome =
-        row.status === "failed" || row.status === "timeout"
-          ? "error"
-          : row.status === "killed"
-            ? "aborted"
-            : "ok";
-      latest = { at, outcome };
-    }
-  }
-  return latest?.outcome ?? "ok";
-}
-
-export function resolveLobsterPetMode(
-  connected: boolean,
-  sessions: ReadonlyArray<{ hasActiveRun?: boolean | null }> | null | undefined,
-): LobsterPetMode {
-  if (!connected) {
-    return "offline";
-  }
-  return sessions?.some((row) => row.hasActiveRun === true) ? "busy" : "idle";
-}
-
 function prefersReducedMotion(): boolean {
   return (
     typeof window !== "undefined" &&
@@ -904,6 +807,42 @@ export function renderLobsterSvg(
   `;
 }
 
+class LobsterLogoStandIn extends LitElement {
+  override createRenderRoot() {
+    return this;
+  }
+
+  @property({ attribute: false }) visit: LobsterLogoVisitDetail | null = null;
+
+  override render() {
+    const visit = this.visit;
+    if (!visit?.look) {
+      return nothing;
+    }
+    const look = visit.look;
+    const classes = [
+      "sidebar-brand__pet",
+      `lobster-pet--palette-${look.palette.id}`,
+      visit.phase === "leaving" ? "sidebar-brand__pet--leaving" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+    const style = [
+      `--lob-shell:${look.palette.shell}`,
+      `--lob-claw:${look.palette.claw}`,
+      `--lob-blink-delay:${look.blinkDelayS}s`,
+      `--lob-w:${LOBSTER_PET_BUILD_MULS[look.build].w}`,
+      `--lob-h:${LOBSTER_PET_BUILD_MULS[look.build].h}`,
+      `--lob-claw-scale:${LOBSTER_PET_CLAW_MULS[look.clawSize]}`,
+    ].join(";");
+    return html`
+      <span class=${classes} style=${style} title=${`${visit.name} · filling in for the logo`}
+        >${renderLobsterSvg(look)}</span
+      >
+    `;
+  }
+}
+
 class LobsterPet extends LitElement {
   override createRenderRoot() {
     return this;
@@ -1835,6 +1774,10 @@ class LobsterPet extends LitElement {
   }
 }
 
+if (!customElements.get("openclaw-lobster-logo-standin")) {
+  customElements.define("openclaw-lobster-logo-standin", LobsterLogoStandIn);
+}
+
 if (!customElements.get("openclaw-lobster-pet")) {
   customElements.define("openclaw-lobster-pet", LobsterPet);
 }
diff --git a/ui/src/e2e/sidebar-customization.e2e.test.ts b/ui/src/e2e/sidebar-customization.e2e.test.ts
index 536c9b7d826..2a9a901e60b 100644
--- a/ui/src/e2e/sidebar-customization.e2e.test.ts
+++ b/ui/src/e2e/sidebar-customization.e2e.test.ts
@@ -101,6 +101,7 @@ async function openSidebarTestPage() {
   const page = await context.newPage();
   await installMockGateway(page);
   await page.goto(`${server.baseUrl}chat`);
+  await page.waitForFunction(() => Boolean(customElements.get("openclaw-lobster-pet")));
   return { context, page };
 }
 
diff --git a/ui/src/test-helpers/app-sidebar-cases/sessions.ts b/ui/src/test-helpers/app-sidebar-cases/sessions.ts
index 3d3ac3c375a..bb24395f2e6 100644
--- a/ui/src/test-helpers/app-sidebar-cases/sessions.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/sessions.ts
@@ -232,13 +232,22 @@ describe("AppSidebar logo stand-in wiring", () => {
       );
     const logo = () => sidebar.querySelector(".sidebar-brand__logo");
     const standIn = () => sidebar.querySelector(".sidebar-brand__pet");
+    const standInHost = sidebar.querySelector<HTMLElement & { updateComplete: Promise<boolean> }>(
+      "openclaw-lobster-logo-standin",
+    );
+    const settleStandIn = async () => {
+      await sidebar.updateComplete;
+      await standInHost?.updateComplete;
+    };
 
+    expect(standInHost).not.toBeNull();
+    await standInHost?.updateComplete;
     expect(logo()?.classList.contains("sidebar-brand__logo--vacated")).toBe(false);
     expect(standIn()).toBeNull();
 
     const look = createLobsterPetLook(70);
     dispatch({ phase: "in", look, name: "Pinchy" });
-    await sidebar.updateComplete;
+    await settleStandIn();
     expect(logo()?.classList.contains("sidebar-brand__logo--vacated")).toBe(true);
     const sprite = standIn();
     expect(sprite).not.toBeNull();
@@ -247,23 +256,23 @@ describe("AppSidebar logo stand-in wiring", () => {
     expect(sprite?.querySelector(".lobster-pet__svg")).not.toBeNull();
 
     dispatch({ phase: "leaving", look, name: "Pinchy" });
-    await sidebar.updateComplete;
+    await settleStandIn();
     expect(standIn()?.classList.contains("sidebar-brand__pet--leaving")).toBe(true);
 
     dispatch({ phase: "out", look: null, name: null });
-    await sidebar.updateComplete;
+    await settleStandIn();
     expect(standIn()).toBeNull();
     expect(logo()?.classList.contains("sidebar-brand__logo--vacated")).toBe(false);
 
     // A lookless scare phase hides the logo with no stand-in crab, and the
     // "out" edge restores it.
     dispatch({ phase: "in", look: null, name: null });
-    await sidebar.updateComplete;
+    await settleStandIn();
     expect(logo()?.classList.contains("sidebar-brand__logo--vacated")).toBe(true);
     expect(standIn()).toBeNull();
 
     dispatch({ phase: "out", look: null, name: null });
-    await sidebar.updateComplete;
+    await settleStandIn();
     expect(logo()?.classList.contains("sidebar-brand__logo--vacated")).toBe(false);
   });
 });

From 05fb8e6e6190ae65b6f1c5fdc0c7dadd960fe3d4 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 19:29:33 +0800
Subject: [PATCH 50/76] fix(cli): bound --message-file reads for agent command
 (#101442)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(cli): bound --message-file reads for agent command

* fix(cli): preserve symlinked --message-file paths with bounded reads

* fix(cli): preserve FIFO message files with bounded reads, document 4 MiB cap

* fix(cli): accept FIFO --message-file targets via bounded descriptor read

* test(cli): drop duplicate FIFO message-file read test

* docs(cli): note 4 MiB --message-file cap in agent help text

* style(commands): format agent-via-gateway test

* fix(cli): preserve procfs message-file reads

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 docs/cli/agent.md                      |   2 +-
 docs/tools/agent-send.md               |   5 +-
 src/cli/program/register.agent-turn.ts |   2 +-
 src/commands/agent-via-gateway.test.ts | 125 +++++++++++++++++++++++++
 src/commands/agent-via-gateway.ts      |  32 ++++++-
 5 files changed, 159 insertions(+), 7 deletions(-)

diff --git a/docs/cli/agent.md b/docs/cli/agent.md
index ab6a1cac5c1..971246267a7 100644
--- a/docs/cli/agent.md
+++ b/docs/cli/agent.md
@@ -50,7 +50,7 @@ openclaw agent --agent ops --message "Run locally" --local
 
 ## Notes
 
-- Pass exactly one of `--message` or `--message-file`. `--message-file` strips a leading UTF-8 BOM and preserves multiline content; it rejects files that are not valid UTF-8.
+- Pass exactly one of `--message` or `--message-file`. `--message-file` strips a leading UTF-8 BOM and preserves multiline content; it rejects files that are not valid UTF-8. Files larger than 4 MiB are rejected before dispatch.
 - Slash commands (for example `/compact`) cannot run through `--message`. The CLI rejects them and points you at the first-class command instead (`openclaw sessions compact <key>` for compaction).
 - `--local` and embedded fallback runs are one-shot: bundled MCP loopback resources and warm Claude stdio sessions opened for the run are retired after the reply, so scripted invocations do not leave local child processes running. Gateway-backed runs keep Gateway-owned MCP loopback resources under the running Gateway process instead.
 - Standalone embedded execution (`--local` and transport fallback) refuses to reuse an existing main session while restart recovery is pending. Run the turn through a healthy Gateway, or reset it there with `/new` or `/reset`; an independent embedded process cannot safely coordinate that recovery owner with the Gateway scanner.
diff --git a/docs/tools/agent-send.md b/docs/tools/agent-send.md
index 4703fc4743d..7c021ec8194 100644
--- a/docs/tools/agent-send.md
+++ b/docs/tools/agent-send.md
@@ -67,7 +67,7 @@ programmatic delivery. Full flag and behavior reference:
 | Flag                        | Description                                                          |
 | --------------------------- | -------------------------------------------------------------------- |
 | `--message <text>`          | Inline message to send                                               |
-| `--message-file <path>`     | Read the message from a valid UTF-8 file                             |
+| `--message-file <path>`     | Read the message from a valid UTF-8 file (max 4 MiB)                 |
 | `--to <dest>`               | Derive session key from a target (phone, chat id)                    |
 | `--session-key <key>`       | Use an explicit session key                                          |
 | `--agent <id>`              | Target a configured agent (uses its `main` session)                  |
@@ -89,7 +89,8 @@ programmatic delivery. Full flag and behavior reference:
 - By default, the CLI goes **through the Gateway**. Add `--local` to force the
   embedded runtime on the current machine.
 - Pass exactly one of `--message` or `--message-file`. File messages preserve
-  multiline content after removing an optional UTF-8 BOM.
+  multiline content after removing an optional UTF-8 BOM. Files larger than
+  4 MiB are rejected before dispatch.
 - If the Gateway request fails, the CLI **falls back** to the local embedded
   run; a Gateway timeout falls back with a fresh session instead of racing the
   original transcript.
diff --git a/src/cli/program/register.agent-turn.ts b/src/cli/program/register.agent-turn.ts
index b7a2b05fe0b..70b3c97c2cc 100644
--- a/src/cli/program/register.agent-turn.ts
+++ b/src/cli/program/register.agent-turn.ts
@@ -35,7 +35,7 @@ export function registerAgentTurnCommand(
     .command("agent")
     .description("Run an agent turn via the Gateway (use --local for embedded)")
     .option("-m, --message <text>", "Message body for the agent")
-    .option("--message-file <path>", "Read the agent message body from a UTF-8 file")
+    .option("--message-file <path>", "Read the agent message body from a UTF-8 file (max 4 MiB)")
     .option("-t, --to <number>", "Recipient number in E.164 used to derive the session key")
     .option("--session-key <key>", "Explicit session key (agent:<id>:<key>, or scoped to --agent)")
     .option("--session-id <id>", "Use an explicit session id")
diff --git a/src/commands/agent-via-gateway.test.ts b/src/commands/agent-via-gateway.test.ts
index 3f6af1c6d0c..d4a69a5f32d 100644
--- a/src/commands/agent-via-gateway.test.ts
+++ b/src/commands/agent-via-gateway.test.ts
@@ -1,4 +1,5 @@
 // Agent via gateway tests cover gateway-backed agent command dispatch and session loading.
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -416,6 +417,130 @@ describe("agentCliCommand", () => {
     });
   });
 
+  it("rejects message files that exceed the size cap", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "huge.md");
+      fs.writeFileSync(messageFile, Buffer.alloc(5 * 1024 * 1024, "x"));
+
+      await expect(
+        agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime),
+      ).rejects.toThrow(/File exceeds 4194304 bytes/);
+      expect(callGateway).not.toHaveBeenCalled();
+    });
+  });
+
+  it("reports a directory message file with the legacy EISDIR message", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "not-a-file");
+      fs.mkdirSync(messageFile);
+
+      await expect(
+        agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime),
+      ).rejects.toThrow("Message file is a directory:");
+      expect(callGateway).not.toHaveBeenCalled();
+    });
+  });
+
+  it("follows a symlinked message file to a regular file", async () => {
+    await withTempStore(async ({ dir }) => {
+      const realFile = path.join(dir, "real.md");
+      const messageFile = path.join(dir, "link.md");
+      fs.writeFileSync(realFile, "hello from symlink target", "utf-8");
+      fs.symlinkSync(realFile, messageFile);
+
+      await agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime);
+
+      expect(callGateway).toHaveBeenCalledTimes(1);
+      const request = requireRecord(requireFirstCallArg(callGateway, "gateway"), "gateway request");
+      const params = requireRecord(request.params, "gateway request params");
+      expect(params.message).toBe("hello from symlink target");
+    });
+  });
+
+  it("follows a chain of symlinks to the final regular message file", async () => {
+    await withTempStore(async ({ dir }) => {
+      const realFile = path.join(dir, "real.md");
+      const linkA = path.join(dir, "link-a.md");
+      const linkB = path.join(dir, "link-b.md");
+      const messageFile = path.join(dir, "link-c.md");
+      fs.writeFileSync(realFile, "hello from chained symlink target", "utf-8");
+      fs.symlinkSync(realFile, linkA);
+      fs.symlinkSync(linkA, linkB);
+      fs.symlinkSync(linkB, messageFile);
+
+      await agentCliCommand({ messageFile, sessionKey: "agent:main:incident-42" }, runtime);
+
+      expect(callGateway).toHaveBeenCalledTimes(1);
+      const request = requireRecord(requireFirstCallArg(callGateway, "gateway"), "gateway request");
+      const params = requireRecord(request.params, "gateway request params");
+      expect(params.message).toBe("hello from chained symlink target");
+    });
+  });
+
+  it.skipIf(process.platform !== "linux")(
+    "reads a procfs file-descriptor link without resolving it to a pathname",
+    async () => {
+      await withTempStore(async ({ dir }) => {
+        const realFile = path.join(dir, "procfs-source.md");
+        fs.writeFileSync(realFile, "hello from procfs descriptor", "utf-8");
+        const sourceHandle = await fs.promises.open(realFile, "r");
+        fs.unlinkSync(realFile);
+        try {
+          await agentCliCommand(
+            {
+              messageFile: `/proc/self/fd/${sourceHandle.fd}`,
+              sessionKey: "agent:main:incident-42",
+            },
+            runtime,
+          );
+        } finally {
+          await sourceHandle.close();
+        }
+
+        expect(callGateway).toHaveBeenCalledTimes(1);
+        const request = requireRecord(
+          requireFirstCallArg(callGateway, "gateway"),
+          "gateway request",
+        );
+        const params = requireRecord(request.params, "gateway request params");
+        expect(params.message).toBe("hello from procfs descriptor");
+      });
+    },
+  );
+
+  // FIFOs have no stat-able size; the bounded descriptor read must drain them
+  // until EOF like the legacy fs.readFile path did. Windows lacks mkfifo.
+  it.skipIf(process.platform === "win32")("reads a FIFO message file until EOF", async () => {
+    await withTempStore(async ({ dir }) => {
+      const messageFile = path.join(dir, "pipe.md");
+      execFileSync("mkfifo", [messageFile]);
+      mockGatewaySuccessReply();
+
+      const dispatch = agentCliCommand(
+        { messageFile, sessionKey: "agent:main:incident-42" },
+        runtime,
+      );
+      // Opening a FIFO for reading blocks until a writer arrives; start the
+      // writer after dispatch kicks off, then close so the bounded read sees
+      // EOF instead of waiting forever.
+      const writer = (async () => {
+        const handle = await fs.promises.open(messageFile, "w");
+        try {
+          await handle.writeFile("hello from fifo");
+        } finally {
+          await handle.close();
+        }
+      })();
+      await dispatch;
+      await writer;
+
+      expect(callGateway).toHaveBeenCalledTimes(1);
+      const request = requireRecord(requireFirstCallArg(callGateway, "gateway"), "gateway request");
+      const params = requireRecord(request.params, "gateway request params");
+      expect(params.message).toBe("hello from fifo");
+    });
+  });
+
   it.each(["/new", "/RESET", "/reset check status"] as const)(
     "uses backend admin authority for %s gateway commands",
     async (message) => {
diff --git a/src/commands/agent-via-gateway.ts b/src/commands/agent-via-gateway.ts
index ab0eb2b8784..b26a6b02a05 100644
--- a/src/commands/agent-via-gateway.ts
+++ b/src/commands/agent-via-gateway.ts
@@ -1,6 +1,6 @@
-// Gateway-first agent CLI implementation with embedded fallback for local/runtime failures.
 import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+// Gateway-first agent CLI implementation with embedded fallback for local/runtime failures.
+import fs from "node:fs/promises";
 import { TextDecoder } from "node:util";
 import { resolveTimerTimeoutMs } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -28,6 +28,7 @@ import {
 import { isGatewaySecretRefUnavailableError } from "../gateway/credentials.js";
 import { ADMIN_SCOPE } from "../gateway/operator-scopes.js";
 import { createAbortError } from "../infra/abort-signal.js";
+import { readFileDescriptorBounded } from "../infra/file-descriptor-read.js";
 import { parseStrictNonNegativeInteger } from "../infra/parse-finite-number.js";
 import { routeLogsToStderr } from "../logging/console.js";
 import {
@@ -195,12 +196,37 @@ function formatMessageFileReadFailure(messageFile: string, err: unknown): string
   return `Unable to read message file ${messageFile}: ${message}`;
 }
 
+// Agent messages are prompt text; a 4 MiB cap gives generous headroom for
+// long system prompts while preventing a symlink/huge-file path from OOMing
+// the CLI before dispatch.
+const AGENT_MESSAGE_FILE_MAX_BYTES = 4 * 1024 * 1024;
+
 async function readAgentMessageFile(messageFile: string): Promise<string> {
+  // Open the original path so the kernel preserves symlink and procfs magic-link
+  // behavior (notably piped /dev/stdin), then inspect that exact descriptor.
+  let handle: Awaited<ReturnType<typeof fs.open>>;
+  try {
+    handle = await fs.open(messageFile, "r");
+  } catch (err) {
+    throw new Error(formatMessageFileReadFailure(messageFile, err), { cause: err });
+  }
   let buffer: Buffer;
   try {
-    buffer = await readFile(messageFile);
+    const stat = await handle.stat();
+    if (stat.isDirectory()) {
+      // Keep the legacy fs.readFile directory UX.
+      throw Object.assign(new Error("Message file is a directory"), { code: "EISDIR" });
+    }
+    // Regular files fail fast. Streams report size 0, so the descriptor reader
+    // enforces the same limit byte-by-byte while preserving FIFO behavior.
+    if (stat.isFile() && stat.size > AGENT_MESSAGE_FILE_MAX_BYTES) {
+      throw new Error(`File exceeds ${AGENT_MESSAGE_FILE_MAX_BYTES} bytes: ${messageFile}`);
+    }
+    buffer = await readFileDescriptorBounded(handle.fd, AGENT_MESSAGE_FILE_MAX_BYTES);
   } catch (err) {
     throw new Error(formatMessageFileReadFailure(messageFile, err), { cause: err });
+  } finally {
+    await handle.close().catch(() => undefined);
   }
   try {
     return MESSAGE_FILE_DECODER.decode(buffer).replace(/^\uFEFF/, "");

From e976e357ea5f26a27af1b4a0430fccb2f8e95032 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 19:33:20 +0800
Subject: [PATCH 51/76] fix(security): bound mcporter registry read in audit
 (#101772)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(security): bound mcporter registry read in audit

* refactor(security): extract bounded mcporter registry read to own module

Keeps src/security/audit.ts under the TS max-LOC ceiling after the
bounded-read security fix.

* fix(security): preserve bounded symlinked mcporter registry reads in audit

* fix(security): warn when an existing mcporter registry cannot be inspected

* fix(security): consume shared mcporter outcome type and exhaust rejection switch

* fix(security): scope mcporter registry audit

* fix(security): reject named-pipe mcporter registries

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
---
 src/security/audit-config-basics.test.ts | 301 +++++++++++++++++++++++
 src/security/audit-mcporter-registry.ts  |  71 ++++++
 src/security/audit.ts                    | 125 ++++++----
 3 files changed, 455 insertions(+), 42 deletions(-)
 create mode 100644 src/security/audit-mcporter-registry.ts

diff --git a/src/security/audit-config-basics.test.ts b/src/security/audit-config-basics.test.ts
index 07911b7830f..ff0f8ef190e 100644
--- a/src/security/audit-config-basics.test.ts
+++ b/src/security/audit-config-basics.test.ts
@@ -1,7 +1,9 @@
 // Covers baseline config security audit findings.
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 import { describe, expect, it } from "vitest";
 import {
   onInternalDiagnosticEvent,
@@ -12,6 +14,8 @@ import { collectMinimalProfileOverrideFindings } from "./audit-extra.sync.js";
 import { runSecurityAudit } from "./audit.js";
 import { collectSecurityAuditFindings } from "./audit.test-support.js";
 
+const execFileAsync = promisify(execFile);
+
 function captureSecurityEvents(): {
   events: DiagnosticSecurityEvent[];
   stop: () => void;
@@ -120,6 +124,303 @@ describe("security audit config basics", () => {
     }
   });
 
+  it("warns when an oversized global mcporter registry cannot be inspected", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-oversized-"));
+    try {
+      await fs.mkdir(path.join(stateDir, "skills", "config"), { recursive: true });
+      await fs.writeFile(
+        path.join(stateDir, "skills", "config", "mcporter.json"),
+        Buffer.alloc(16 * 1024 * 1024 + 1, 0x20),
+      );
+
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      const checkIds = report.findings.map((finding) => finding.checkId);
+      expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+      expect(report.findings).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            checkId: "tools.exec.mcporter_registry_inspection_incomplete",
+            severity: "warn",
+          }),
+        ]),
+      );
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not flag mcporter registry inspection when the registry is missing", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-missing-"));
+    try {
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      const checkIds = report.findings.map((finding) => finding.checkId);
+      expect(checkIds).not.toContain("tools.exec.mcporter_registry_inspection_incomplete");
+      expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("warns when a malformed global mcporter registry cannot be inspected", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-malformed-"));
+    try {
+      await fs.mkdir(path.join(stateDir, "skills", "config"), { recursive: true });
+      await fs.writeFile(
+        path.join(stateDir, "skills", "config", "mcporter.json"),
+        "{ not json",
+        "utf8",
+      );
+
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      const checkIds = report.findings.map((finding) => finding.checkId);
+      expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+      expect(checkIds).toContain("tools.exec.mcporter_registry_inspection_incomplete");
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not inspect a malformed mcporter registry without relevant agent skill scopes", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-unused-"));
+    try {
+      await fs.mkdir(path.join(stateDir, "skills", "config"), { recursive: true });
+      await fs.writeFile(
+        path.join(stateDir, "skills", "config", "mcporter.json"),
+        "{ not json",
+        "utf8",
+      );
+
+      const report = await runSecurityAudit({
+        config: {},
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      expect(report.findings.map((finding) => finding.checkId)).not.toContain(
+        "tools.exec.mcporter_registry_inspection_incomplete",
+      );
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("warns when the global mcporter registry path is not a regular file", async () => {
+    const stateDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "openclaw-audit-mcporter-non-regular-"),
+    );
+    try {
+      await fs.mkdir(path.join(stateDir, "skills", "config", "mcporter.json"), {
+        recursive: true,
+      });
+
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      const checkIds = report.findings.map((finding) => finding.checkId);
+      expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+      expect(checkIds).toContain("tools.exec.mcporter_registry_inspection_incomplete");
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "warns for a named-pipe mcporter registry without blocking",
+    async () => {
+      const stateDir = await fs.mkdtemp(
+        path.join(os.tmpdir(), "openclaw-audit-mcporter-named-pipe-"),
+      );
+      try {
+        const configDir = path.join(stateDir, "skills", "config");
+        await fs.mkdir(configDir, { recursive: true });
+        await execFileAsync("mkfifo", [path.join(configDir, "mcporter.json")]);
+
+        const report = await runSecurityAudit({
+          config: {
+            agents: {
+              list: [
+                {
+                  id: "asset-agent",
+                  skills: ["asset-lifecycle-tracking"],
+                  tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+                },
+              ],
+            },
+          },
+          sourceConfig: {},
+          env: { OPENCLAW_STATE_DIR: stateDir },
+          stateDir,
+          includeFilesystem: false,
+          includeChannelSecurity: false,
+        });
+
+        const checkIds = report.findings.map((finding) => finding.checkId);
+        expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+        expect(checkIds).toContain("tools.exec.mcporter_registry_inspection_incomplete");
+      } finally {
+        await fs.rm(stateDir, { recursive: true, force: true });
+      }
+    },
+  );
+
+  it("accepts a valid symlinked global mcporter registry", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-symlink-"));
+    try {
+      const configDir = path.join(stateDir, "skills", "config");
+      await fs.mkdir(configDir, { recursive: true });
+      const targetPath = path.join(stateDir, "real-mcporter.json");
+      await fs.writeFile(
+        targetPath,
+        JSON.stringify({
+          mcpServers: {
+            "whois-mcp": { baseUrl: "http://whois.example.test/mcp" },
+          },
+        }),
+        "utf8",
+      );
+      await fs.symlink(targetPath, path.join(configDir, "mcporter.json"));
+
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      expect(report.findings.map((finding) => finding.checkId)).toContain(
+        "tools.exec.agent_skill_mcp_boundary_drift",
+      );
+      expect(report.findings.map((finding) => finding.checkId)).not.toContain(
+        "tools.exec.mcporter_registry_inspection_incomplete",
+      );
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("warns when an oversized symlinked global mcporter registry cannot be inspected", async () => {
+    const stateDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), "openclaw-audit-mcporter-symlink-oversized-"),
+    );
+    try {
+      const configDir = path.join(stateDir, "skills", "config");
+      await fs.mkdir(configDir, { recursive: true });
+      const targetPath = path.join(stateDir, "real-mcporter.json");
+      await fs.writeFile(targetPath, Buffer.alloc(16 * 1024 * 1024 + 1, 0x20));
+      await fs.symlink(targetPath, path.join(configDir, "mcporter.json"));
+
+      const report = await runSecurityAudit({
+        config: {
+          agents: {
+            list: [
+              {
+                id: "asset-agent",
+                skills: ["asset-lifecycle-tracking"],
+                tools: { exec: { host: "gateway", security: "full", ask: "off" } },
+              },
+            ],
+          },
+        },
+        sourceConfig: {},
+        env: { OPENCLAW_STATE_DIR: stateDir },
+        stateDir,
+        includeFilesystem: false,
+        includeChannelSecurity: false,
+      });
+
+      const checkIds = report.findings.map((finding) => finding.checkId);
+      expect(checkIds).not.toContain("tools.exec.agent_skill_mcp_boundary_drift");
+      expect(checkIds).toContain("tools.exec.mcporter_registry_inspection_incomplete");
+    } finally {
+      await fs.rm(stateDir, { recursive: true, force: true });
+    }
+  });
+
   it("does not flag per-agent skill allowlists when matching agents deny exec", async () => {
     const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-audit-mcporter-deny-"));
     try {
diff --git a/src/security/audit-mcporter-registry.ts b/src/security/audit-mcporter-registry.ts
new file mode 100644
index 00000000000..e48d709152f
--- /dev/null
+++ b/src/security/audit-mcporter-registry.ts
@@ -0,0 +1,71 @@
+// Bounded read of the global MCP registry for security audit.
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const MAX_MCPORTER_REGISTRY_BYTES = 16 * 1024 * 1024;
+const READ_CHUNK_SIZE = 64 * 1024;
+
+export type McporterRegistryRejectReason = "oversized" | "unreadable" | "non-regular" | "malformed";
+
+// Missing means no registry exists (non-actionable); rejected means a registry
+// exists but could not be safely inspected, so the audit must warn instead of
+// silently dropping the MCP boundary input.
+export type McporterRegistryReadOutcome =
+  | { status: "ok"; value: unknown }
+  | { status: "missing" }
+  | { status: "rejected"; reason: McporterRegistryRejectReason };
+
+function isEnoent(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === "ENOENT";
+}
+
+export async function readBoundedMcporterRegistry(
+  stateDir: string,
+): Promise<McporterRegistryReadOutcome> {
+  const registryPath = path.join(stateDir, "skills", "config", "mcporter.json");
+  let handle: fs.FileHandle | undefined;
+  try {
+    // Open without O_NOFOLLOW so valid symlinked registries are followed,
+    // while still bounding the read to avoid audit OOM on oversized targets.
+    handle = await fs.open(registryPath, constants.O_RDONLY | constants.O_NONBLOCK);
+  } catch (error) {
+    // ENOENT (including a dangling symlink) means no registry; anything else
+    // means one exists but cannot be inspected.
+    return isEnoent(error) ? { status: "missing" } : { status: "rejected", reason: "unreadable" };
+  }
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+      return { status: "rejected", reason: "non-regular" };
+    }
+    if (stat.size > MAX_MCPORTER_REGISTRY_BYTES) {
+      return { status: "rejected", reason: "oversized" };
+    }
+    const chunks: Buffer[] = [];
+    const scratch = Buffer.allocUnsafe(Math.min(READ_CHUNK_SIZE, MAX_MCPORTER_REGISTRY_BYTES + 1));
+    let total = 0;
+    while (true) {
+      const { bytesRead } = await handle.read(scratch, 0, scratch.length, null);
+      if (bytesRead === 0) {
+        break;
+      }
+      total += bytesRead;
+      if (total > MAX_MCPORTER_REGISTRY_BYTES) {
+        return { status: "rejected", reason: "oversized" };
+      }
+      chunks.push(Buffer.from(scratch.subarray(0, bytesRead)));
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(Buffer.concat(chunks, total).toString("utf-8"));
+    } catch {
+      return { status: "rejected", reason: "malformed" };
+    }
+    return { status: "ok", value };
+  } catch {
+    return { status: "rejected", reason: "unreadable" };
+  } finally {
+    await handle.close();
+  }
+}
diff --git a/src/security/audit.ts b/src/security/audit.ts
index 99a798a8411..f8af9261070 100644
--- a/src/security/audit.ts
+++ b/src/security/audit.ts
@@ -1,5 +1,4 @@
 // Orchestrates security audit collection and report formatting.
-import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { asNullableRecord } from "@openclaw/normalization-core/record-coerce";
@@ -49,6 +48,11 @@ import {
   inspectPathPermissions,
 } from "./audit-fs.js";
 import { collectGatewayConfigFindings as collectGatewayConfigFindingsBase } from "./audit-gateway-config.js";
+import {
+  readBoundedMcporterRegistry,
+  type McporterRegistryReadOutcome,
+  type McporterRegistryRejectReason,
+} from "./audit-mcporter-registry.js";
 import type {
   SecurityAuditFinding,
   SecurityAuditReport,
@@ -1066,25 +1070,49 @@ function listConfiguredMcpServerNames(cfg: OpenClawConfig): string[] {
     .toSorted();
 }
 
+type GlobalMcporterRegistrySummary =
+  | { status: "source"; summary: McpServerSourceSummary }
+  | { status: "absent" }
+  | Extract<McporterRegistryReadOutcome, { status: "rejected" }>;
+
 async function readGlobalMcporterRegistrySummary(
   stateDir: string,
-): Promise<McpServerSourceSummary | null> {
-  const registryPath = path.join(stateDir, "skills", "config", "mcporter.json");
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(await fs.readFile(registryPath, "utf8")) as unknown;
-  } catch {
-    return null;
+): Promise<GlobalMcporterRegistrySummary> {
+  const outcome = await readBoundedMcporterRegistry(stateDir);
+  if (outcome.status === "missing") {
+    return { status: "absent" };
+  }
+  if (outcome.status === "rejected") {
+    return outcome;
   }
-  const mcpServers = asNullableRecord(asNullableRecord(parsed)?.mcpServers);
+  const mcpServers = asNullableRecord(asNullableRecord(outcome.value)?.mcpServers);
   if (!mcpServers) {
-    return null;
+    return { status: "absent" };
   }
   const names = Object.entries(mcpServers)
     .filter(([, value]) => asNullableRecord(value)?.enabled !== false)
     .map(([name]) => name)
     .toSorted();
-  return names.length > 0 ? { label: "skills/config/mcporter.json", names } : null;
+  return names.length > 0
+    ? { status: "source", summary: { label: "skills/config/mcporter.json", names } }
+    : { status: "absent" };
+}
+
+function describeMcporterRegistryRejection(reason: McporterRegistryRejectReason): string {
+  switch (reason) {
+    case "oversized":
+      return "larger than the 16 MiB audit cap";
+    case "unreadable":
+      return "unreadable";
+    case "non-regular":
+      return "not a regular file";
+    case "malformed":
+      return "not valid JSON";
+    default: {
+      const exhaustive: never = reason;
+      return exhaustive;
+    }
+  }
 }
 
 function hasOwnSkillsAllowlist(entry: object | undefined): boolean {
@@ -1152,47 +1180,60 @@ async function collectAgentSkillMcpBoundaryFindings(params: {
   cfg: OpenClawConfig;
   stateDir: string;
 }): Promise<SecurityAuditFinding[]> {
+  const scopes = collectAgentSkillMcpBoundaryScopes(params.cfg);
+  if (scopes.length === 0) {
+    return [];
+  }
+
+  const findings: SecurityAuditFinding[] = [];
   const sources: McpServerSourceSummary[] = [];
   const configServerNames = listConfiguredMcpServerNames(params.cfg);
   if (configServerNames.length > 0) {
     sources.push({ label: "mcp.servers", names: configServerNames });
   }
   const globalMcporterRegistry = await readGlobalMcporterRegistrySummary(params.stateDir);
-  if (globalMcporterRegistry) {
-    sources.push(globalMcporterRegistry);
+  if (globalMcporterRegistry.status === "rejected") {
+    // An existing registry that cannot be inspected must not silently vanish
+    // from the audit; tell the operator the MCP boundary check is incomplete.
+    findings.push({
+      checkId: "tools.exec.mcporter_registry_inspection_incomplete",
+      severity: "warn",
+      title: "Global mcporter registry could not be inspected",
+      detail:
+        `skills/config/mcporter.json exists but could not be safely inspected (${describeMcporterRegistryRejection(globalMcporterRegistry.reason)}). ` +
+        "The MCP boundary inspection is incomplete: the audit could not verify which MCP servers a host exec process can reach.",
+      remediation:
+        "Repair or remove skills/config/mcporter.json so the audit can inspect it: keep it a regular file readable by the gateway user, valid JSON, and below the 16 MiB audit cap.",
+    });
+  } else if (globalMcporterRegistry.status === "source") {
+    sources.push(globalMcporterRegistry.summary);
   }
   if (sources.length === 0) {
-    return [];
-  }
-
-  const scopes = collectAgentSkillMcpBoundaryScopes(params.cfg);
-  if (scopes.length === 0) {
-    return [];
+    return findings;
   }
 
-  return [
-    {
-      checkId: "tools.exec.agent_skill_mcp_boundary_drift",
-      severity: "warn",
-      title: "Agent skill allowlists do not constrain host exec MCP clients",
-      detail:
-        `Detected agent skill allowlists on host-exec-capable scopes:\n${scopes
-          .slice(0, 8)
-          .map(
-            (scope) =>
-              `- ${scope.id}: ${scope.skillSource}, exec.host=${scope.execHost}, security=${scope.execSecurity}, ask=${scope.execAsk}`,
-          )
-          .join("\n")}` +
-        (scopes.length > 8 ? `\n- +${scopes.length - 8} more scopes.` : "") +
-        `\nMCP server registries visible to the gateway configuration/state:\n${sources
-          .map((source) => `- ${source.label}: ${formatNamesPreview(source.names)}`)
-          .join("\n")}\n` +
-        "agents.*.skills filters OpenClaw skill visibility and snapshots; it is not a shell-time authorization boundary. " +
-        "A host exec process can run external MCP clients or read a global mcporter registry unless sandbox, filesystem, network, or MCP credential boundaries block it.",
-      remediation:
-        'For agents that need per-agent MCP isolation, set their exec policy to security="deny" or a tight allowlist, run them in sandbox/container/OS-user isolation where the global MCP registry is not readable, split sensitive MCP servers into a separate gateway/trust boundary, or require per-agent MCP credentials at the server layer.',
-    },
-  ];
+  findings.push({
+    checkId: "tools.exec.agent_skill_mcp_boundary_drift",
+    severity: "warn",
+    title: "Agent skill allowlists do not constrain host exec MCP clients",
+    detail:
+      `Detected agent skill allowlists on host-exec-capable scopes:\n${scopes
+        .slice(0, 8)
+        .map(
+          (scope) =>
+            `- ${scope.id}: ${scope.skillSource}, exec.host=${scope.execHost}, security=${scope.execSecurity}, ask=${scope.execAsk}`,
+        )
+        .join("\n")}` +
+      (scopes.length > 8 ? `\n- +${scopes.length - 8} more scopes.` : "") +
+      `\nMCP server registries visible to the gateway configuration/state:\n${sources
+        .map((source) => `- ${source.label}: ${formatNamesPreview(source.names)}`)
+        .join("\n")}\n` +
+      "agents.*.skills filters OpenClaw skill visibility and snapshots; it is not a shell-time authorization boundary. " +
+      "A host exec process can run external MCP clients or read a global mcporter registry unless sandbox, filesystem, network, or MCP credential boundaries block it.",
+    remediation:
+      'For agents that need per-agent MCP isolation, set their exec policy to security="deny" or a tight allowlist, run them in sandbox/container/OS-user isolation where the global MCP registry is not readable, split sensitive MCP servers into a separate gateway/trust boundary, or require per-agent MCP credentials at the server layer.',
+  });
+  return findings;
 }
 
 function collectOpenExecSurfacePaths(cfg: OpenClawConfig): string[] {

From 684ae080d4f1814bd648624af064be61f986b5d3 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:35:27 +0100
Subject: [PATCH 52/76] fix(signal): preserve durable ingress retry ownership
 (#110629)

* test(signal): await durable ingress adoption

* fix(signal): keep session conflict retries claim-aware

* test(signal): normalize captured monitor errors

* test(signal): exercise core ingress lifecycle seam
---
 ...-only-senders-uuid-allowlist-entry.test.ts |  31 +++--
 ...ends-tool-summaries-responseprefix.test.ts | 124 ++++++++++--------
 .../src/monitor.tool-result.test-harness.ts   | 113 ++++++++--------
 .../event-handler.ingress-lifecycle.test.ts   |  69 +++++-----
 .../signal/src/monitor/event-handler.ts       |   3 +
 5 files changed, 178 insertions(+), 162 deletions(-)

diff --git a/extensions/signal/src/monitor.tool-result.pairs-uuid-only-senders-uuid-allowlist-entry.test.ts b/extensions/signal/src/monitor.tool-result.pairs-uuid-only-senders-uuid-allowlist-entry.test.ts
index 7c2d804624c..aefae4b6f29 100644
--- a/extensions/signal/src/monitor.tool-result.pairs-uuid-only-senders-uuid-allowlist-entry.test.ts
+++ b/extensions/signal/src/monitor.tool-result.pairs-uuid-only-senders-uuid-allowlist-entry.test.ts
@@ -6,6 +6,7 @@ import {
   getSignalToolResultTestMocks,
   installSignalToolResultTestHooks,
   setSignalToolResultTestConfig,
+  toSignalToolResultTestError,
 } from "./monitor.tool-result.test-harness.js";
 
 installSignalToolResultTestHooks();
@@ -127,7 +128,6 @@ describe("monitorSignalProvider tool results", () => {
   });
 
   it("cancels a pending reply-session conflict retry when the monitor stops", async () => {
-    vi.useFakeTimers();
     const abortController = new AbortController();
     replyMock.mockRejectedValue(
       new Error(
@@ -151,22 +151,25 @@ describe("monitorSignalProvider tool results", () => {
       });
     });
 
+    const monitorPromise = monitorSignalProvider({
+      autoStart: false,
+      baseUrl: "http://127.0.0.1:8080",
+      abortSignal: abortController.signal,
+    });
+    let waitError: Error | undefined;
     try {
-      const monitorPromise = monitorSignalProvider({
-        autoStart: false,
-        baseUrl: "http://127.0.0.1:8080",
-        abortSignal: abortController.signal,
-      });
-
-      await vi.waitFor(() => expect(replyMock).toHaveBeenCalledTimes(1));
-      abortController.abort(new Error("monitor stopped"));
-      await monitorPromise;
-      await vi.advanceTimersByTimeAsync(10_000);
-
-      expect(replyMock).toHaveBeenCalledTimes(1);
+      await vi.waitFor(() => expect(replyMock).toHaveBeenCalledTimes(1), { timeout: 5_000 });
+    } catch (error) {
+      waitError = toSignalToolResultTestError(error, "Signal reply was not dispatched");
     } finally {
-      vi.useRealTimers();
+      abortController.abort(new Error("monitor stopped"));
+    }
+    await monitorPromise;
+    if (waitError) {
+      throw waitError;
     }
+
+    expect(replyMock).toHaveBeenCalledTimes(1);
   });
 
   it("drains an inline inbound message accepted before the monitor stops", async () => {
diff --git a/extensions/signal/src/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts b/extensions/signal/src/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts
index a8631be9e64..8c643a8d603 100644
--- a/extensions/signal/src/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts
+++ b/extensions/signal/src/monitor.tool-result.sends-tool-summaries-responseprefix.test.ts
@@ -10,6 +10,8 @@ import {
   getSignalToolResultTestMocks,
   installSignalToolResultTestHooks,
   setSignalToolResultTestConfig,
+  toSignalToolResultTestError,
+  waitForSignalToolResultIngressIdle,
 } from "./monitor.tool-result.test-harness.js";
 
 installSignalToolResultTestHooks();
@@ -31,7 +33,7 @@ const SIGNAL_BASE_URL = "http://127.0.0.1:8080";
 type MonitorSignalProviderOptions = NonNullable<Parameters<typeof monitorSignalProvider>[0]>;
 
 function waitForSignalDelivery(assertion: () => void) {
-  return vi.waitFor(assertion, { interval: 1 });
+  return vi.waitFor(assertion, { interval: 1, timeout: 5_000 });
 }
 
 async function runMonitorWithMocks(opts: MonitorSignalProviderOptions) {
@@ -48,6 +50,7 @@ async function receiveSignalPayloads(params: {
   opts?: Partial<MonitorSignalProviderOptions>;
 }) {
   const abortController = new AbortController();
+  let ingressIdleError: Error | undefined;
   streamMock.mockImplementation(async ({ onEvent }) => {
     for (const payload of params.payloads) {
       await onEvent({
@@ -55,11 +58,13 @@ async function receiveSignalPayloads(params: {
         data: JSON.stringify(payload),
       });
     }
-    // Durable receive returns after append; let the drain start before simulating shutdown.
-    await new Promise<void>((resolve) => {
-      setImmediate(resolve);
-    });
-    abortController.abort();
+    try {
+      await waitForSignalToolResultIngressIdle();
+    } catch (error) {
+      ingressIdleError = toSignalToolResultTestError(error, "Signal ingress did not become idle");
+    } finally {
+      abortController.abort();
+    }
   });
 
   await runMonitorWithMocks({
@@ -68,6 +73,9 @@ async function receiveSignalPayloads(params: {
     abortSignal: abortController.signal,
     ...params.opts,
   });
+  if (ingressIdleError) {
+    throw ingressIdleError;
+  }
 }
 
 function hasQueuedReactionEventFor(sender: string) {
@@ -517,61 +525,67 @@ describe("monitorSignalProvider tool results", () => {
   });
 
   it("keeps durable conversation events separate in batched reply mode", async () => {
-    vi.useFakeTimers();
-    try {
-      setSignalToolResultTestConfig({
-        ...createSignalToolResultConfig({
-          autoStart: false,
-          replyToMode: "batched",
-        }),
-        messages: { inbound: { debounceMs: 10 } },
-      });
-      replyMock.mockResolvedValue({ text: "reply" });
-      const abortController = new AbortController();
-      streamMock.mockImplementation(async ({ onEvent }) => {
-        for (const [timestamp, message] of [
-          [1700000000001, "first message"],
-          [1700000000002, "second message"],
-        ] as const) {
-          await onEvent({
-            event: "receive",
-            data: JSON.stringify({
-              envelope: {
-                sourceNumber: "+15550001111",
-                sourceName: "Ada",
-                timestamp,
-                dataMessage: { message },
-              },
-            }),
-          });
-        }
-        try {
-          await vi.advanceTimersByTimeAsync(2_000);
+    setSignalToolResultTestConfig({
+      ...createSignalToolResultConfig({
+        autoStart: false,
+        replyToMode: "batched",
+      }),
+      messages: { inbound: { debounceMs: 10 } },
+    });
+    replyMock.mockResolvedValue({ text: "reply" });
+    const abortController = new AbortController();
+    let ingressIdleError: Error | undefined;
+    streamMock.mockImplementation(async ({ onEvent }) => {
+      for (const [timestamp, message] of [
+        [1700000000001, "first message"],
+        [1700000000002, "second message"],
+      ] as const) {
+        await onEvent({
+          event: "receive",
+          data: JSON.stringify({
+            envelope: {
+              sourceNumber: "+15550001111",
+              sourceName: "Ada",
+              timestamp,
+              dataMessage: { message },
+            },
+          }),
+        });
+      }
+      try {
+        await waitForSignalDelivery(() => {
           expect(replyMock).toHaveBeenCalledTimes(2);
-        } finally {
-          abortController.abort();
-        }
-      });
+        });
+        await waitForSignalToolResultIngressIdle();
+      } catch (error) {
+        ingressIdleError = toSignalToolResultTestError(
+          error,
+          "Batched Signal ingress did not become idle",
+        );
+      } finally {
+        abortController.abort();
+      }
+    });
 
-      await runMonitorWithMocks({
-        autoStart: false,
-        baseUrl: SIGNAL_BASE_URL,
-        abortSignal: abortController.signal,
-      });
+    await runMonitorWithMocks({
+      autoStart: false,
+      baseUrl: SIGNAL_BASE_URL,
+      abortSignal: abortController.signal,
+    });
+    if (ingressIdleError) {
+      throw ingressIdleError;
+    }
 
-      expect(sendMock).toHaveBeenCalledTimes(2);
-      for (const call of sendMock.mock.calls) {
-        expect(call[2]).not.toHaveProperty("replyToId");
-        expect(call[2]).not.toHaveProperty("replyToAuthor");
-        expect(call[2]).not.toHaveProperty("replyToBody");
-      }
-    } finally {
-      vi.useRealTimers();
+    expect(sendMock).toHaveBeenCalledTimes(2);
+    for (const call of sendMock.mock.calls) {
+      expect(call[2]).not.toHaveProperty("replyToId");
+      expect(call[2]).not.toHaveProperty("replyToAuthor");
+      expect(call[2]).not.toHaveProperty("replyToBody");
     }
   });
 
   it("passes inbound Signal quote metadata to media replies", async () => {
-    replyMock.mockResolvedValue({ text: "caption", mediaUrl: "file:///tmp/reply.png" });
+    replyMock.mockResolvedValue({ text: "caption", mediaUrl: "https://example.com/reply.png" });
 
     await receiveSignalPayloads({
       payloads: [
@@ -592,7 +606,7 @@ describe("monitorSignalProvider tool results", () => {
       expect(sendMock).toHaveBeenCalledTimes(1);
     });
     expect(sendMock.mock.calls[0]?.[2]).toMatchObject({
-      mediaUrl: "file:///tmp/reply.png",
+      mediaUrl: "https://example.com/reply.png",
       replyToId: "1700000000001",
       replyToAuthor: "+15550001111",
       replyToBody: "quote me",
diff --git a/extensions/signal/src/monitor.tool-result.test-harness.ts b/extensions/signal/src/monitor.tool-result.test-harness.ts
index 072444e8da9..11d3d9fb19f 100644
--- a/extensions/signal/src/monitor.tool-result.test-harness.ts
+++ b/extensions/signal/src/monitor.tool-result.test-harness.ts
@@ -44,6 +44,32 @@ const signalToolResultSessionStorePath = vi.hoisted(
   () => `/tmp/openclaw-signal-tool-result-sessions-${process.pid}.json`,
 );
 let signalToolResultStateDir: string | undefined;
+let signalToolResultIngressQueue: ReturnType<typeof createChannelIngressQueueForTests> | undefined;
+
+export function toSignalToolResultTestError(value: unknown, fallbackMessage: string): Error {
+  return value instanceof Error ? value : new Error(fallbackMessage, { cause: value });
+}
+
+export async function waitForSignalToolResultIngressIdle() {
+  const queue = signalToolResultIngressQueue;
+  if (!queue) {
+    throw new Error("Signal tool-result ingress queue is not initialized");
+  }
+  await vi.waitFor(
+    async () => {
+      // Pending must be read before claims so a pending→claimed transition cannot
+      // disappear between two concurrent snapshots and produce a false idle.
+      const pending = await queue.listPending({ limit: "all" });
+      const claims = await queue.listClaims();
+      if (pending.length > 0 || claims.length > 0) {
+        throw new Error(
+          `Signal tool-result ingress still active: ${pending.length} pending, ${claims.length} claimed, ${replyMock.mock.calls.length} replies, ${sendMock.mock.calls.length} sends`,
+        );
+      }
+    },
+    { interval: 10, timeout: 5_000 },
+  );
+}
 
 export function getSignalToolResultTestMocks(): SignalToolResultTestMocks {
   return {
@@ -130,69 +156,30 @@ vi.mock("openclaw/plugin-sdk/session-store-runtime", async () => {
   };
 });
 
-vi.mock("openclaw/plugin-sdk/reply-runtime", async () => {
-  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/reply-runtime")>(
-    "openclaw/plugin-sdk/reply-runtime",
+vi.mock("openclaw/plugin-sdk/channel-inbound", async () => {
+  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/channel-inbound")>(
+    "openclaw/plugin-sdk/channel-inbound",
   );
   return {
     ...actual,
-    getReplyFromConfig: (...args: unknown[]) => replyMock(...args),
-    dispatchInboundMessage: async (params: {
-      ctx: unknown;
-      cfg: unknown;
-      replyOptions?: {
-        turnAdoptionLifecycle?: { onAdopted?: () => void | Promise<void> };
-      };
-      dispatcher: {
-        sendFinalReply: (payload: {
-          text?: string;
-          mediaUrl?: string;
-          mediaUrls?: string[];
-        }) => boolean;
-        markComplete?: () => void;
-        waitForIdle?: () => Promise<void>;
-      };
-    }) => {
-      type TestReplyPayload = {
-        text?: string;
-        mediaUrl?: string;
-        mediaUrls?: string[];
-        isCompactionNotice?: boolean;
-        isFallbackNotice?: boolean;
-        isStatusNotice?: boolean;
-        replyToId?: string;
-        replyToTag?: boolean;
-        replyToCurrent?: boolean;
-      };
-      const resolved = (await replyMock(params.ctx, {}, params.cfg)) as
-        | {
-            replies?: TestReplyPayload[];
-          }
-        | TestReplyPayload
-        | TestReplyPayload[]
-        | undefined;
-      const resolvedPayloads = Array.isArray(resolved)
-        ? resolved
-        : Array.isArray((resolved as { replies?: unknown })?.replies)
-          ? (resolved as { replies: TestReplyPayload[] }).replies
-          : resolved
-            ? [resolved as TestReplyPayload]
-            : [];
-      let queuedFinal = false;
-      for (const resolvedPayload of resolvedPayloads) {
-        const text = typeof resolvedPayload.text === "string" ? resolvedPayload.text.trim() : "";
-        const hasMedia =
-          typeof resolvedPayload.mediaUrl === "string" ||
-          (Array.isArray(resolvedPayload.mediaUrls) && resolvedPayload.mediaUrls.length > 0);
-        if (text || hasMedia) {
-          queuedFinal = true;
-          params.dispatcher.sendFinalReply(resolvedPayload);
-        }
-      }
-      params.dispatcher.markComplete?.();
-      await params.dispatcher.waitForIdle?.();
-      await params.replyOptions?.turnAdoptionLifecycle?.onAdopted?.();
-      return { queuedFinal };
+    runChannelInboundEvent: async (params: Parameters<typeof actual.runChannelInboundEvent>[0]) => {
+      const resolveTurn = params.adapter.resolveTurn;
+      return await actual.runChannelInboundEvent({
+        ...params,
+        adapter: {
+          ...params.adapter,
+          resolveTurn: async (...args: Parameters<typeof resolveTurn>) => {
+            const resolved = await resolveTurn(...args);
+            if ("runDispatch" in resolved) {
+              return resolved;
+            }
+            return {
+              ...resolved,
+              replyResolver: (...replyArgs: unknown[]) => replyMock(...replyArgs),
+            } as typeof resolved;
+          },
+        },
+      });
     },
   };
 });
@@ -277,6 +264,7 @@ export function installSignalToolResultTestHooks() {
     );
     const stateDir = await fs.realpath(createdStateDir);
     signalToolResultStateDir = stateDir;
+    signalToolResultIngressQueue = undefined;
     setSignalRuntime({
       logging: {
         getChildLogger: () => ({
@@ -294,11 +282,13 @@ export function installSignalToolResultTestHooks() {
         openChannelIngressQueue: (
           options?: Omit<Parameters<typeof createChannelIngressQueueForTests>[0], "channelId">,
         ) => {
-          return createChannelIngressQueueForTests({
+          const queue = createChannelIngressQueueForTests({
             ...options,
             channelId: "signal",
             stateDir: options?.stateDir ?? stateDir,
           });
+          signalToolResultIngressQueue = queue;
+          return queue;
         },
       },
     } as unknown as PluginRuntime);
@@ -327,6 +317,7 @@ export function installSignalToolResultTestHooks() {
 
   afterEach(async () => {
     clearSignalRuntimeForTest();
+    signalToolResultIngressQueue = undefined;
     closeOpenClawStateDatabaseForTest();
     if (signalToolResultStateDir) {
       await fs.rm(signalToolResultStateDir, { recursive: true, force: true });
diff --git a/extensions/signal/src/monitor/event-handler.ingress-lifecycle.test.ts b/extensions/signal/src/monitor/event-handler.ingress-lifecycle.test.ts
index edb5d37832d..a6a4906f28c 100644
--- a/extensions/signal/src/monitor/event-handler.ingress-lifecycle.test.ts
+++ b/extensions/signal/src/monitor/event-handler.ingress-lifecycle.test.ts
@@ -43,18 +43,6 @@ vi.mock("../send-reactions.js", () => ({
   removeReactionSignal: vi.fn(async () => ({ ok: true })),
 }));
 
-vi.mock("openclaw/plugin-sdk/reply-runtime", async () => {
-  const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/reply-runtime")>(
-    "openclaw/plugin-sdk/reply-runtime",
-  );
-  return {
-    ...actual,
-    dispatchInboundMessage: dispatchInboundMessageMock,
-    dispatchInboundMessageWithDispatcher: dispatchInboundMessageMock,
-    dispatchInboundMessageWithBufferedDispatcher: dispatchInboundMessageMock,
-  };
-});
-
 vi.mock("openclaw/plugin-sdk/channel-inbound", async () => {
   const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/channel-inbound")>(
     "openclaw/plugin-sdk/channel-inbound",
@@ -62,27 +50,44 @@ vi.mock("openclaw/plugin-sdk/channel-inbound", async () => {
   type RunParams = Parameters<typeof actual.runChannelInboundEvent>[0];
   return {
     ...actual,
-    runChannelInboundEvent: (params: RunParams) => {
-      const resolveTurn = params.adapter.resolveTurn;
-      return actual.runChannelInboundEvent({
-        ...params,
-        adapter: {
-          ...params.adapter,
-          resolveTurn: async (input, eventClass, preflight) => {
-            const resolved = await resolveTurn(input, eventClass, preflight);
-            if (!("route" in resolved) || !("runDispatch" in resolved)) {
-              return resolved;
-            }
-            const { route, ...turn } = resolved;
-            return {
-              ...turn,
-              routeSessionKey: route.sessionKey,
-              storePath: "/tmp/openclaw/signal-sessions.json",
-              recordInboundSession: recordInboundSessionMock,
-            };
-          },
-        },
+    runChannelInboundEvent: async (params: RunParams) => {
+      const input = await params.adapter.ingest(params.raw);
+      if (!input) {
+        return { admission: { kind: "drop" as const, reason: "ingest-null" }, dispatched: false };
+      }
+      const eventClass = (await params.adapter.classify?.(input)) ?? {
+        kind: "message" as const,
+        canStartAgentTurn: true,
+      };
+      const preflight = (await params.adapter.preflight?.(input, eventClass)) ?? {};
+      const resolved = await params.adapter.resolveTurn(
+        input,
+        eventClass,
+        "kind" in preflight ? { admission: preflight } : preflight,
+      );
+      if (!("route" in resolved) || !("delivery" in resolved)) {
+        throw new Error("expected assembled Signal channel turn plan");
+      }
+      const result = await actual.runPreparedInboundReply({
+        channel: resolved.channel,
+        accountId: resolved.accountId,
+        routeSessionKey: resolved.route.sessionKey,
+        storePath: "/tmp/openclaw/signal-sessions.json",
+        ctxPayload: resolved.ctxPayload,
+        recordInboundSession: recordInboundSessionMock,
+        afterRecord: resolved.afterRecord,
+        record: resolved.record,
+        history: resolved.history,
+        admission: resolved.admission,
+        botLoopProtection: resolved.botLoopProtection,
+        runDispatch: async () =>
+          await dispatchInboundMessageMock({
+            ctx: resolved.ctxPayload,
+            replyOptions: resolved.replyOptions,
+          }),
       });
+      await params.adapter.onFinalize?.(result);
+      return result;
     },
   };
 });
diff --git a/extensions/signal/src/monitor/event-handler.ts b/extensions/signal/src/monitor/event-handler.ts
index b03396fa43e..3d2e281b0cc 100644
--- a/extensions/signal/src/monitor/event-handler.ts
+++ b/extensions/signal/src/monitor/event-handler.ts
@@ -596,6 +596,9 @@ export function createSignalEventHandler(deps: SignalEventHandlerDeps) {
           },
           dispatcherOptions,
           delivery,
+          // Signal retries the whole debounced flush below so the keyed lane and durable claims
+          // remain owned during backoff; a nested dispatch retry breaks shutdown cancellation.
+          sessionInitRetry: { delaysMs: [] },
           replyOptions: {
             ...(entry.turnAdoptionLifecycle
               ? bindIngressLifecycleToReplyOptions(entry.turnAdoptionLifecycle)

From f98bcb7fa73caf4d720c4a9eb317592952af4c5d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:36:46 +0100
Subject: [PATCH 53/76] perf(ui): drop zod from the Control UI and lazy-load
 json5 with the config surfaces (#110623)

* perf(ui): drop zod and lazy-load json5 out of Control UI startup

zod's only UI consumer was the custom-theme shape layer, whose deep CSS
validators already re-check every token; replace the two shallow schemas
with a plain record reader and delete the zod jitless CSP shim + test.
Startup keeps one schema library total (typebox, protocol-owned, already
lazy via the approval page).

json5 now loads through a lazy runtime boundary: strict JSON.parse is the
fast path, the parser warms with the config editor and whenever a config
snapshot or raw draft actually needs JSON5 (comments, trailing commas).
The redaction sanitize path parses the authoritative raw once at snapshot
ingestion (async-safe) and submits against the carried parsed fact, so
secret-placeholder handling never races the lazy parser.

Startup JS: 321.8 -> 295.8 KiB gzip, 13 -> 12 requests; budgets ratchet
to 310 KiB / 18 requests.

* fix(ui): gate config submits on pending JSON5 original parse

A JSON5 config racing the first parser load could reach the sanitize step
with a null parsed original and pass redaction placeholders through.
setConfigRawOriginal now parses synchronously whenever the parser is warm
and tracks a pending promise otherwise; submit, auto-save, and teardown
flush paths defer to that promise (teardown keeps its synchronous prefix
when no parse is pending).

* fix(ui): keep teardown config flush synchronous and JSON5 diff cache non-sticky

Teardown flush must dispatch before unload destroys the context; the
gateway's restore-or-reject sentinel contract backs the rare unsanitized
window. Raw-diff parse failures no longer cache while the lazy JSON5
parser is still loading, so a transient cold-parser miss retries on the
next render instead of pinning an empty diff.

* fix(ui): harden lazy JSON5 boundary against double-submit and failed loads

Claim the config busy flag before awaiting a pending JSON5 original parse
so a second click cannot slip past the busy state (autosave overlap is
already serialized by the in-flight registry and drain discipline). A
rejected json5 chunk import now resets the loader for retry, the per-state
pending promise is never-rejecting and self-clearing, and fire-and-forget
warms swallow rejections.

* docs(ui): note autosave entry serialization at the JSON5 parse await

* fix(ui): fill raw pending-changes diff once the lazy JSON5 parser lands

First diff open could race the parser chunk and render an empty list with
nothing scheduling a retry; renderConfig now re-renders when the warm
completes, and the browser test warms the parser in setup to assert the
steady state the view module guarantees in prod.
---
 scripts/check-control-ui-performance.mjs  |   4 +-
 ui/src/app/custom-theme-jitless.test.ts   |  41 --------
 ui/src/app/custom-theme.ts                | 120 +++++++---------------
 ui/src/lib/config-form-utils.node.test.ts |  40 +++-----
 ui/src/lib/config-form-utils.ts           |  17 +--
 ui/src/lib/config/index.ts                |  76 +++++++++++++-
 ui/src/lib/json5-runtime.test.ts          |  16 +++
 ui/src/lib/json5-runtime.ts               |  44 ++++++++
 ui/src/pages/config/view.browser.test.ts  |   9 +-
 ui/src/pages/config/view.ts               |  26 ++++-
 10 files changed, 218 insertions(+), 175 deletions(-)
 delete mode 100644 ui/src/app/custom-theme-jitless.test.ts
 create mode 100644 ui/src/lib/json5-runtime.test.ts
 create mode 100644 ui/src/lib/json5-runtime.ts

diff --git a/scripts/check-control-ui-performance.mjs b/scripts/check-control-ui-performance.mjs
index b691f7652e5..4c20d03ce22 100644
--- a/scripts/check-control-ui-performance.mjs
+++ b/scripts/check-control-ui-performance.mjs
@@ -10,9 +10,9 @@ const KIB = 1024;
 // Small, explicit headroom over the optimized baseline. Budget changes should
 // accompany an intentional loading or chunking decision.
 export const CONTROL_UI_PERFORMANCE_BUDGETS = Object.freeze({
-  startupJsRequests: 20,
+  startupJsRequests: 18,
   startupCssRequests: 1,
-  startupJsGzipBytes: 340 * KIB,
+  startupJsGzipBytes: 310 * KIB,
   startupCssGzipBytes: 42 * KIB,
   largestJsGzipBytes: 215 * KIB,
   largestCssGzipBytes: 42 * KIB,
diff --git a/ui/src/app/custom-theme-jitless.test.ts b/ui/src/app/custom-theme-jitless.test.ts
deleted file mode 100644
index cbe1c679aae..00000000000
--- a/ui/src/app/custom-theme-jitless.test.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-// Control UI tests cover Zod initialization under the Gateway's strict CSP.
-import { describe, expect, it, vi } from "vitest";
-
-describe("custom theme Zod initialization", () => {
-  it("enables jitless mode before object schemas probe dynamic code", async () => {
-    vi.resetModules();
-    const { z } = await import("zod");
-    const config = z.config();
-    const previousJitless = config.jitless;
-    delete config.jitless;
-
-    const NativeFunction = globalThis.Function;
-    let evalProbeAttempted = false;
-    const FunctionProxy = new Proxy(NativeFunction, {
-      apply(target, thisArg, args) {
-        evalProbeAttempted ||= args.length === 1 && args[0] === "";
-        return Reflect.apply(target, thisArg, args);
-      },
-      construct(target, args, newTarget) {
-        evalProbeAttempted ||= args.length === 1 && args[0] === "";
-        return Reflect.construct(target, args, newTarget);
-      },
-    });
-    vi.stubGlobal("Function", FunctionProxy);
-
-    try {
-      await import("./custom-theme.ts");
-
-      expect(z.config().jitless).toBe(true);
-      expect(evalProbeAttempted).toBe(false);
-    } finally {
-      vi.unstubAllGlobals();
-      if (previousJitless === undefined) {
-        delete config.jitless;
-      } else {
-        config.jitless = previousJitless;
-      }
-      vi.resetModules();
-    }
-  });
-});
diff --git a/ui/src/app/custom-theme.ts b/ui/src/app/custom-theme.ts
index 71f38474a03..34a4849e1cd 100644
--- a/ui/src/app/custom-theme.ts
+++ b/ui/src/app/custom-theme.ts
@@ -1,12 +1,7 @@
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 // Control UI module implements custom theme behavior.
-import { z } from "zod";
 import { normalizeOptionalString } from "../lib/string-coerce.ts";
 
-// The Control UI CSP forbids dynamic code generation. Zod snapshots this flag
-// when z.object() is constructed, before its eval-backed fast path can probe.
-z.config({ jitless: true });
-
 const TWEAKCN_HOSTS = new Set(["tweakcn.com", "www.tweakcn.com"]);
 const THEME_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 const CUSTOM_THEME_STYLE_ID = "openclaw-custom-theme";
@@ -93,29 +88,6 @@ const MODE_TOKEN_ORDER = [
 type ModeTokenName = (typeof MODE_TOKEN_ORDER)[number];
 type ThemeTokenMap = Record<ModeTokenName, string>;
 
-const REQUIRED_TWEAKCN_MODE_VARS = [
-  "background",
-  "foreground",
-  "card",
-  "card-foreground",
-  "popover",
-  "popover-foreground",
-  "primary",
-  "primary-foreground",
-  "secondary",
-  "secondary-foreground",
-  "muted",
-  "muted-foreground",
-  "accent",
-  "accent-foreground",
-  "destructive",
-  "destructive-foreground",
-  "border",
-  "input",
-  "ring",
-] as const;
-type RequiredTweakcnModeVar = (typeof REQUIRED_TWEAKCN_MODE_VARS)[number];
-
 export type ImportedCustomTheme = {
   sourceUrl: string;
   themeId: string;
@@ -125,40 +97,15 @@ export type ImportedCustomTheme = {
   dark: ThemeTokenMap;
 };
 
-const cssTokenSchema = z.string().max(MAX_CSS_TOKEN_LENGTH);
-
-function createStringShape<const T extends readonly string[]>(keys: T) {
-  return Object.fromEntries(keys.map((key) => [key, cssTokenSchema])) as Record<
-    T[number],
-    typeof cssTokenSchema
-  >;
+// Shape checks are intentionally shallow: normalizeStoredTokenMap and
+// resolveModeVar re-validate every token (presence, length, safe CSS) and
+// throw on anything off, so no schema library is needed at this boundary.
+function readThemeRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
 }
 
-const tweakcnThemeSchema = z.object({
-  name: z.string().max(80).optional(),
-  cssVars: z.object({
-    theme: z
-      .object({
-        "font-sans": cssTokenSchema.optional(),
-        "font-mono": cssTokenSchema.optional(),
-      })
-      .optional(),
-    light: z.object(createStringShape(REQUIRED_TWEAKCN_MODE_VARS)),
-    dark: z.object(createStringShape(REQUIRED_TWEAKCN_MODE_VARS)),
-  }),
-});
-
-const importedCustomThemeSchema = z.object({
-  sourceUrl: z.string(),
-  themeId: z.string(),
-  label: z.string(),
-  importedAt: z.string(),
-  light: z.object(createStringShape(MODE_TOKEN_ORDER)),
-  dark: z.object(createStringShape(MODE_TOKEN_ORDER)),
-});
-
-type TweakcnThemePayload = z.infer<typeof tweakcnThemeSchema>;
-
 type TweakcnThemeResolution = {
   sourceUrl: string;
   fetchUrl: string;
@@ -305,7 +252,7 @@ function makeTokenMap(entries: Array<[ModeTokenName, string]>): ThemeTokenMap {
   return Object.fromEntries(entries) as ThemeTokenMap;
 }
 
-function normalizeStoredTokenMap(value: Record<string, string> | undefined): ThemeTokenMap | null {
+function normalizeStoredTokenMap(value: Record<string, unknown> | undefined): ThemeTokenMap | null {
   if (!value || typeof value !== "object") {
     return null;
   }
@@ -321,8 +268,8 @@ function normalizeStoredTokenMap(value: Record<string, string> | undefined): The
 }
 
 function resolveModeVar(
-  theme: Record<string, string | undefined>,
-  shared: Record<string, string | undefined> | undefined,
+  theme: Record<string, unknown>,
+  shared: Record<string, unknown> | undefined,
   key: string,
   fallback?: string,
 ) {
@@ -344,8 +291,8 @@ function resolveModeVar(
 
 function normalizeModeTokenMap(
   mode: "light" | "dark",
-  theme: Record<RequiredTweakcnModeVar, string>,
-  shared: Record<string, string | undefined> | undefined,
+  theme: Record<string, unknown>,
+  shared: Record<string, unknown> | undefined,
 ): ThemeTokenMap {
   const isLight = mode === "light";
   const contrastTarget = isLight ? "black" : "white";
@@ -461,22 +408,31 @@ function normalizeTweakcnThemeUrl(input: string): TweakcnThemeResolution {
 }
 
 export function parseImportedCustomTheme(value: unknown): ImportedCustomTheme | null {
-  const parsed = importedCustomThemeSchema.safeParse(value);
-  if (!parsed.success) {
+  const record = readThemeRecord(value);
+  if (!record) {
+    return null;
+  }
+  const { sourceUrl, themeId, label, importedAt } = record;
+  if (
+    typeof sourceUrl !== "string" ||
+    typeof themeId !== "string" ||
+    typeof label !== "string" ||
+    typeof importedAt !== "string"
+  ) {
     return null;
   }
   try {
-    requireThemeId(parsed.data.themeId);
-    const light = normalizeStoredTokenMap(parsed.data.light);
-    const dark = normalizeStoredTokenMap(parsed.data.dark);
+    requireThemeId(themeId);
+    const light = normalizeStoredTokenMap(readThemeRecord(record.light) ?? undefined);
+    const dark = normalizeStoredTokenMap(readThemeRecord(record.dark) ?? undefined);
     if (!light || !dark) {
       return null;
     }
     return {
-      sourceUrl: parsed.data.sourceUrl,
-      themeId: parsed.data.themeId,
-      label: describeThemeLabel(parsed.data.label),
-      importedAt: parsed.data.importedAt,
+      sourceUrl,
+      themeId,
+      label: describeThemeLabel(label),
+      importedAt,
       light,
       dark,
     };
@@ -489,19 +445,21 @@ function normalizeImportedCustomTheme(
   payload: unknown,
   resolution: Pick<TweakcnThemeResolution, "sourceUrl" | "themeId">,
 ): ImportedCustomTheme {
-  const parsed = tweakcnThemeSchema.safeParse(payload);
-  if (!parsed.success) {
+  const record = readThemeRecord(payload);
+  const cssVars = readThemeRecord(record?.cssVars);
+  const light = readThemeRecord(cssVars?.light);
+  const dark = readThemeRecord(cssVars?.dark);
+  const shared = cssVars?.theme === undefined ? undefined : readThemeRecord(cssVars.theme);
+  if (!record || !cssVars || !light || !dark || shared === null) {
     throw new Error("tweakcn returned an invalid theme payload.");
   }
-  const data: TweakcnThemePayload = parsed.data;
-  const shared = data.cssVars.theme;
   return {
     sourceUrl: resolution.sourceUrl,
     themeId: resolution.themeId,
-    label: describeThemeLabel(data.name),
+    label: describeThemeLabel(normalizeOptionalString(record.name)),
     importedAt: new Date().toISOString(),
-    light: normalizeModeTokenMap("light", data.cssVars.light, shared),
-    dark: normalizeModeTokenMap("dark", data.cssVars.dark, shared),
+    light: normalizeModeTokenMap("light", light, shared),
+    dark: normalizeModeTokenMap("dark", dark, shared),
   };
 }
 
diff --git a/ui/src/lib/config-form-utils.node.test.ts b/ui/src/lib/config-form-utils.node.test.ts
index 13c3031c275..e13d62bbf23 100644
--- a/ui/src/lib/config-form-utils.node.test.ts
+++ b/ui/src/lib/config-form-utils.node.test.ts
@@ -89,11 +89,7 @@ describe("sanitizeRedactedFormForSubmit", () => {
     };
 
     expect(
-      sanitizeRedactedFormForSubmit(
-        form,
-        originalForm,
-        '{\n  gateway: {\n    mode: "remote"\n  }\n}\n',
-      ),
+      sanitizeRedactedFormForSubmit(form, originalForm, { gateway: { mode: "remote" } }),
     ).toEqual({
       gateway: {
         mode: "remote",
@@ -113,11 +109,9 @@ describe("sanitizeRedactedFormForSubmit", () => {
     const originalForm = cloneConfigObject(form);
 
     expect(
-      sanitizeRedactedFormForSubmit(
-        form,
-        originalForm,
-        '{\n  gateway: {\n    mode: "remote",\n    remote: {\n      token: "__OPENCLAW_REDACTED__"\n    }\n  }\n}\n',
-      ),
+      sanitizeRedactedFormForSubmit(form, originalForm, {
+        gateway: { mode: "remote", remote: { token: "__OPENCLAW_REDACTED__" } },
+      }),
     ).toEqual(form);
   });
 
@@ -135,13 +129,9 @@ describe("sanitizeRedactedFormForSubmit", () => {
       },
     };
 
-    expect(
-      sanitizeRedactedFormForSubmit(
-        form,
-        originalForm,
-        "{\n  gateway: {\n    remote: {}\n  }\n}\n",
-      ),
-    ).toEqual(form);
+    expect(sanitizeRedactedFormForSubmit(form, originalForm, { gateway: { remote: {} } })).toEqual(
+      form,
+    );
   });
 
   it("prunes empty object parents when they are absent from original raw config", () => {
@@ -157,9 +147,7 @@ describe("sanitizeRedactedFormForSubmit", () => {
     };
     const originalForm = cloneConfigObject(form);
 
-    expect(
-      sanitizeRedactedFormForSubmit(form, originalForm, '{\n  ui: { theme: "dark" }\n}\n'),
-    ).toEqual({
+    expect(sanitizeRedactedFormForSubmit(form, originalForm, { ui: { theme: "dark" } })).toEqual({
       ui: { theme: "dark" },
     });
   });
@@ -175,15 +163,13 @@ describe("sanitizeRedactedFormForSubmit", () => {
     const originalForm = cloneConfigObject(form);
 
     expect(
-      sanitizeRedactedFormForSubmit(
-        form,
-        originalForm,
-        '{\n  channels: { slack: { tokens: ["second-token"] } }\n}\n',
-      ),
+      sanitizeRedactedFormForSubmit(form, originalForm, {
+        channels: { slack: { tokens: ["second-token"] } },
+      }),
     ).toEqual(form);
   });
 
-  it("leaves the form unchanged when original raw config cannot be parsed", () => {
+  it("leaves the form unchanged when the original raw config has no parsed snapshot", () => {
     const form = {
       gateway: {
         remote: {
@@ -193,7 +179,7 @@ describe("sanitizeRedactedFormForSubmit", () => {
     };
     const originalForm = cloneConfigObject(form);
 
-    expect(sanitizeRedactedFormForSubmit(form, originalForm, "{")).toEqual(form);
+    expect(sanitizeRedactedFormForSubmit(form, originalForm, null)).toEqual(form);
   });
 });
 describe("prototype pollution prevention", () => {
diff --git a/ui/src/lib/config-form-utils.ts b/ui/src/lib/config-form-utils.ts
index 36d4d971495..0ff201025af 100644
--- a/ui/src/lib/config-form-utils.ts
+++ b/ui/src/lib/config-form-utils.ts
@@ -1,6 +1,5 @@
 // Control UI controller manages form utils gateway state.
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
-import JSON5 from "json5";
 
 export function cloneConfigObject<T>(value: T): T {
   return structuredClone(value);
@@ -93,19 +92,11 @@ function sanitizeRedactedValue(params: {
 export function sanitizeRedactedFormForSubmit(
   form: Record<string, unknown>,
   originalForm: Record<string, unknown> | null | undefined,
-  originalRaw: string,
+  parsedOriginalRaw: Record<string, unknown> | null,
 ): Record<string, unknown> {
-  if (!originalForm || !originalRaw) {
-    return form;
-  }
-
-  let parsedOriginalRaw: unknown;
-  try {
-    parsedOriginalRaw = JSON5.parse(originalRaw);
-  } catch {
-    return form;
-  }
-  if (!isRecord(parsedOriginalRaw)) {
+  // Callers parse the original raw once at snapshot ingestion so this submit
+  // path stays synchronous and never races the lazy JSON5 parser.
+  if (!originalForm || !parsedOriginalRaw) {
     return form;
   }
 
diff --git a/ui/src/lib/config/index.ts b/ui/src/lib/config/index.ts
index 7d046dab046..663bcdbb575 100644
--- a/ui/src/lib/config/index.ts
+++ b/ui/src/lib/config/index.ts
@@ -1,5 +1,4 @@
 // Control UI runtime config capability and shared config-domain mutations.
-import JSON5 from "json5";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
 import type { ConfigSchemaResponse, ConfigSnapshot, ConfigUiHints } from "../../api/types.ts";
 import { schemaType, type JsonSchema } from "../../components/config-form.shared.ts";
@@ -12,6 +11,7 @@ import {
   serializeConfigForm,
   setPathValue,
 } from "../config-form-utils.ts";
+import { parseJson5Text, warmJson5 } from "../json5-runtime.ts";
 import { createAppliedConfigRefreshController } from "./applied-refresh.ts";
 
 export type ConfigAutoSaveStatus = "idle" | "saving" | "saved" | "error" | "conflict";
@@ -44,6 +44,8 @@ type ConfigState = {
   configLoading: boolean;
   configRaw: string;
   configRawOriginal: string;
+  configRawOriginalParsed: Record<string, unknown> | null;
+  configRawOriginalParsePending: Promise<void> | null;
   configValid: boolean | null;
   configIssues: unknown[];
   configSaving: boolean;
@@ -150,6 +152,8 @@ function createInitialConfigState(snapshot?: Partial<RuntimeConfigGatewaySnapsho
     configLoading: false,
     configRaw: "{\n}\n",
     configRawOriginal: "",
+    configRawOriginalParsed: null,
+    configRawOriginalParsePending: null,
     configValid: null,
     configIssues: [],
     configSaving: false,
@@ -347,7 +351,7 @@ function applyConfigSnapshot(
   if (!preservePendingChanges) {
     state.configForm = cloneConfigObject(editableConfig ?? {});
     state.configFormOriginal = cloneConfigObject(editableConfig ?? {});
-    state.configRawOriginal = rawFromSnapshot;
+    setConfigRawOriginal(state, rawFromSnapshot);
     state.configFormDirty = false;
     state.configFormMode = "form";
     state.configDraftBaseHash = snapshot.hash ?? null;
@@ -529,7 +533,7 @@ function serializeFormForSubmit(state: ConfigState): string {
   const sanitized = sanitizeRedactedFormForSubmit(
     form,
     state.configFormOriginal,
-    state.configRawOriginal,
+    state.configRawOriginalParsed,
   );
   return serializeConfigForm(sanitized);
 }
@@ -558,7 +562,7 @@ function adoptConfigSetAck(state: ConfigState, submittedRaw: string, ackHash: st
   };
   state.configValid = true;
   state.configIssues = [];
-  state.configRawOriginal = submittedRaw;
+  setConfigRawOriginal(state, submittedRaw);
   if (parsed) {
     state.configFormOriginal = cloneConfigObject(parsed);
   }
@@ -599,10 +603,19 @@ async function submitConfigChange(
   }
   const connectionEpoch = currentConfigConnectionEpoch(state);
   const isCurrent = () => isCurrentConfigConnection(state, client, connectionEpoch);
+  // Claim busy before any await so a second click cannot slip past the busy
+  // state while a JSON5 original parse settles; finally releases it.
   state[busyKey] = true;
   state.lastError = null;
   state.chatError = null;
   try {
+    if (state.configRawOriginalParsePending) {
+      // JSON5 originals parse asynchronously on first load; sanitize needs them.
+      await state.configRawOriginalParsePending;
+      if (!isCurrent()) {
+        return false;
+      }
+    }
     const raw = serializeFormForSubmit(state);
     const baseHash = state.configDraftBaseHash ?? state.configSnapshot?.hash;
     if (!baseHash) {
@@ -685,6 +698,11 @@ function teardownFlushConfigDraft(
   client: GatewayBrowserClient,
   baseHash: string,
 ): void {
+  // Must stay synchronous: page unload destroys the context before any
+  // deferred work runs. If a JSON5 original parse is still pending, sanitize
+  // passes placeholders through; the gateway restores restorable sentinels
+  // (restoreRedactedValues) and rejects unrestorable ones, so the worst case
+  // matches not flushing at all while the common case saves the draft.
   const raw = serializeFormForSubmit(state);
   void client.request("config.set", { raw, baseHash }).catch(() => undefined);
 }
@@ -706,6 +724,16 @@ async function autoSaveConfig(
   }
   const connectionEpoch = currentConfigConnectionEpoch(state);
   const isCurrent = () => isCurrentConfigConnection(state, client, connectionEpoch);
+  if (state.configRawOriginalParsePending) {
+    // JSON5 originals parse asynchronously on first load; sanitize needs them.
+    // Await only when pending: teardown flushes rely on a synchronous prefix.
+    // Entry stays serialized across this await: runAutoSave's synchronous
+    // in-flight check folds concurrent triggers into one trailing save.
+    await state.configRawOriginalParsePending;
+    if (!isCurrent() || !state.configFormDirty || state.configFormMode !== "form") {
+      return false;
+    }
+  }
   const submittedRaw = serializeFormForSubmit(state);
   const baseHash = state.configDraftBaseHash ?? state.configSnapshot?.hash;
   if (!baseHash) {
@@ -869,7 +897,7 @@ async function lookupConfigSchemaPath(
 
 function parseConfigRawDraft(raw: string): Record<string, unknown> | null {
   try {
-    const parsed = JSON5.parse(raw) as unknown;
+    const parsed = parseJson5Text(raw);
     return parsed && typeof parsed === "object" && !Array.isArray(parsed)
       ? (parsed as Record<string, unknown>)
       : null;
@@ -878,6 +906,41 @@ function parseConfigRawDraft(raw: string): Record<string, unknown> | null {
   }
 }
 
+// Parse the authoritative raw once at ingestion so submit-time sanitizing
+// stays synchronous and never races the lazy JSON5 parser. Submit paths await
+// configRawOriginalParsePending so a JSON5 config racing the first parser load
+// cannot bypass redaction sanitizing.
+function setConfigRawOriginal(state: ConfigState, raw: string) {
+  state.configRawOriginal = raw;
+  state.configRawOriginalParsePending = null;
+  try {
+    state.configRawOriginalParsed = asConfigRecord(parseJson5Text(raw));
+    return;
+  } catch {
+    state.configRawOriginalParsed = null;
+  }
+  const pending = warmJson5()
+    .then((json5) => {
+      if (state.configRawOriginal !== raw || state.configRawOriginalParsePending !== pending) {
+        return;
+      }
+      try {
+        state.configRawOriginalParsed = asConfigRecord(json5.parse(raw));
+      } catch {
+        state.configRawOriginalParsed = null;
+      }
+    })
+    // Never-rejecting and self-clearing: submit gates await this promise, and
+    // a failed chunk load must not wedge every later save of this state.
+    .catch(() => undefined)
+    .finally(() => {
+      if (state.configRawOriginalParsePending === pending) {
+        state.configRawOriginalParsePending = null;
+      }
+    });
+  state.configRawOriginalParsePending = pending;
+}
+
 function mutateConfigForm(state: ConfigState, mutate: (draft: Record<string, unknown>) => void) {
   let base: Record<string, unknown>;
   if (state.configFormDirty && state.configFormMode === "raw") {
@@ -986,6 +1049,9 @@ function updateConfigFormValue(state: ConfigState, path: Array<string | number>,
 }
 
 function updateConfigRawValue(state: ConfigState, value: string) {
+  // Raw drafts may carry JSON5 comments; warm the parser before any
+  // mutateConfigForm/diff path needs it synchronously.
+  void warmJson5().catch(() => undefined);
   state.configRaw = value;
   // A raw-text edit becomes the authoritative draft; without this,
   // serializeFormForSubmit would submit the stale form and drop raw edits.
diff --git a/ui/src/lib/json5-runtime.test.ts b/ui/src/lib/json5-runtime.test.ts
new file mode 100644
index 00000000000..4e9d6f801c7
--- /dev/null
+++ b/ui/src/lib/json5-runtime.test.ts
@@ -0,0 +1,16 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { parseJson5Text, warmJson5 } from "./json5-runtime.ts";
+
+const COMMENTED = '// comment\n{\n  "a": 1, // trailing\n}\n';
+
+describe("json5 runtime boundary", () => {
+  it("parses strict JSON on the fast path", () => {
+    expect(parseJson5Text('{"a":1}')).toEqual({ a: 1 });
+  });
+
+  it("parses JSON5 text once the module is warmed", async () => {
+    await warmJson5();
+    expect(parseJson5Text(COMMENTED)).toEqual({ a: 1 });
+  });
+});
diff --git a/ui/src/lib/json5-runtime.ts b/ui/src/lib/json5-runtime.ts
new file mode 100644
index 00000000000..e9e07ee1361
--- /dev/null
+++ b/ui/src/lib/json5-runtime.ts
@@ -0,0 +1,44 @@
+// Lazy JSON5 boundary: strict JSON parses without the library, so json5 stays
+// out of the startup graph and loads only for config text that needs it.
+type Json5Module = { parse: (text: string) => unknown };
+
+let json5: Json5Module | null = null;
+let json5Loading: Promise<Json5Module> | null = null;
+
+export function isJson5Warm(): boolean {
+  return json5 !== null;
+}
+
+export function warmJson5(): Promise<Json5Module> {
+  json5Loading ??= import("json5").then(
+    (mod) => {
+      json5 = mod.default;
+      return json5;
+    },
+    (error: unknown) => {
+      // Transient chunk-load failures must not pin a rejected loader forever;
+      // the next warm retries the import.
+      json5Loading = null;
+      throw error;
+    },
+  );
+  return json5Loading;
+}
+
+/**
+ * Strict-JSON fast path with a JSON5 fallback once the module is warmed.
+ * Callers on the config surfaces warm the module before raw drafts can exist;
+ * if a JSON5-only text races the warm-up, this throws like a parse failure and
+ * the caller's existing invalid-draft handling applies until retry.
+ */
+export function parseJson5Text(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch (jsonError) {
+    if (json5) {
+      return json5.parse(raw);
+    }
+    void warmJson5().catch(() => undefined);
+    throw jsonError;
+  }
+}
diff --git a/ui/src/pages/config/view.browser.test.ts b/ui/src/pages/config/view.browser.test.ts
index 3a9725fb3a5..50cf4c06a00 100644
--- a/ui/src/pages/config/view.browser.test.ts
+++ b/ui/src/pages/config/view.browser.test.ts
@@ -1,11 +1,18 @@
 // Control UI tests cover config behavior.
 import { render } from "lit";
-import { describe, expect, it, vi } from "vitest";
+import { beforeAll, describe, expect, it, vi } from "vitest";
 import "../../styles.css";
 import type { ThemeMode, ThemeName } from "../../app/theme.ts";
+import { warmJson5 } from "../../lib/json5-runtime.ts";
 import { createConfigViewState, renderConfig, type ConfigProps } from "./view.ts";
 
 describe("config view", () => {
+  // The view module warms the lazy JSON5 parser on load; tests assert the
+  // steady state where raw diffs parse synchronously.
+  beforeAll(async () => {
+    await warmJson5();
+  });
+
   const baseProps = () => ({
     raw: "{\n}\n",
     originalRaw: "{\n}\n",
diff --git a/ui/src/pages/config/view.ts b/ui/src/pages/config/view.ts
index e28a12f37cf..1922cfd2ba6 100644
--- a/ui/src/pages/config/view.ts
+++ b/ui/src/pages/config/view.ts
@@ -1,6 +1,5 @@
 // Control UI view renders config screen content.
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
-import JSON5 from "json5";
 import { html, nothing } from "lit";
 import type { QueueMode } from "../../../../src/auto-reply/reply/queue/types.js";
 import type { ConfigUiHints } from "../../api/types.ts";
@@ -25,12 +24,12 @@ import {
   schemaType,
   type JsonSchema,
 } from "../../components/config-form.shared.ts";
-import "../../components/tooltip.ts";
 import {
   analyzeConfigSchema,
   renderConfigForm,
   type ConfigSchemaAnalysis,
 } from "../../components/config-form.ts";
+import "../../components/tooltip.ts";
 import { icons } from "../../components/icons.ts";
 import { getLobsterdex, getLobsterdexEntries } from "../../components/lobster-dex.ts";
 import {
@@ -47,6 +46,7 @@ import {
 } from "../../components/settings-ui.ts";
 import { t } from "../../i18n/index.ts";
 import type { ConfigAutoSaveStatus } from "../../lib/config/index.ts";
+import { isJson5Warm, parseJson5Text, warmJson5 } from "../../lib/json5-runtime.ts";
 import type { RealtimeTalkInputDevice } from "../chat/realtime-talk-input.ts";
 import { renderSettingsSelectRow } from "./settings-select-row.ts";
 import {
@@ -54,6 +54,10 @@ import {
   COMMUNICATION_SETTINGS_TARGET_IDS,
 } from "./settings-targets.ts";
 
+// The config editor is where JSON5 text first appears; warm the parser with
+// the page instead of racing the first raw-draft keystroke.
+void warmJson5().catch(() => undefined);
+
 const TEXT_SCALE_LABELS: Record<TextScaleStop, string> = {
   90: "configView.textSizes.small",
   100: "configView.textSizes.default",
@@ -746,8 +750,8 @@ function computeRawDiff(
     return viewState.rawDiffCache.diff;
   }
   try {
-    const originalValue = JSON5.parse(original) as unknown;
-    const currentValue = JSON5.parse(current) as unknown;
+    const originalValue = parseJson5Text(original);
+    const currentValue = parseJson5Text(current);
     if (
       !originalValue ||
       !currentValue ||
@@ -766,7 +770,12 @@ function computeRawDiff(
     viewState.rawDiffCache = { original, current, diff };
     return diff;
   } catch {
-    viewState.rawDiffCache = { original, current, diff: [] };
+    // While the lazy JSON5 parser is still loading, a parse failure may be
+    // transient; skip the cache so the next render retries instead of pinning
+    // an empty diff for this text pair.
+    if (isJson5Warm()) {
+      viewState.rawDiffCache = { original, current, diff: [] };
+    }
     return [];
   }
 }
@@ -1799,6 +1808,13 @@ export function renderConfig(props: ConfigProps) {
     formMode === "raw" && hasRawChanges && viewState.rawDiffOpen
       ? computeRawDiff(viewState, props.originalRaw, props.raw)
       : [];
+  if (formMode === "raw" && hasRawChanges && viewState.rawDiffOpen && !isJson5Warm()) {
+    // First diff open can race the lazy JSON5 parser; re-render when it lands
+    // so the pending-changes list fills in instead of staying empty.
+    void warmJson5()
+      .then(() => requestUpdate())
+      .catch(() => undefined);
+  }
   // Includes the app updater: writes are suspended while it runs, so raw
   // Save/Discard must read busy instead of silently no-opping.
   const configBusy = props.loading || props.saving || props.applying || props.updating;

From 39ddf710f0f3f873c7fb2e73f8127bf649f9b018 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:50:51 +0100
Subject: [PATCH 54/76] feat(ui): session unarchive flows with undo toast
 (#110605)

* feat(ui): session unarchive flows with undo toast

Archiving from the web UI was silent and one-way. Adds a shared single-slot
toast with Undo (restores archive state, pin, and active selection), a sidebar
'View archived' entry into Settings -> Sessions, an Active|Archived segment
replacing the buried archived-only chip, an inline Restore button on archived
chats' disabled composer, and a guarded 'Delete all archived' bulk action that
fully re-enumerates archived sessions (paginated, aborts on any abnormal page)
and passes the protocol archivedOnly guard. No gateway/protocol changes.

* test(ui): adapt archive undo sidebar harness

* fix(ui): unexport ToastOptions and widen test mock casts for CI gates
---
 ui/src/app/app-host.ts                        |   2 +
 ui/src/components/app-sidebar-menus.ts        |   2 +-
 ui/src/components/app-sidebar-session-list.ts |   7 +
 .../app-sidebar-session-mutations.ts          |  75 ++++++-
 ui/src/i18n/locales/en.ts                     |   9 +-
 ui/src/lib/sessions/index.test.ts             |  13 +-
 ui/src/lib/sessions/index.ts                  |   3 +
 ui/src/lib/toast.test.ts                      |  56 ++++++
 ui/src/lib/toast.ts                           |  92 +++++++++
 ui/src/pages/chat/chat-composer.test.ts       |  15 ++
 ui/src/pages/chat/chat-pane.ts                |  29 +++
 ui/src/pages/chat/chat-view.ts                |   5 +-
 ui/src/pages/chat/components/chat-composer.ts |  16 ++
 ui/src/pages/sessions/sessions-page.test.ts   | 188 +++++++++++++++++-
 ui/src/pages/sessions/sessions-page.ts        | 132 +++++++++++-
 ui/src/pages/sessions/view.test.ts            |  34 ++--
 ui/src/pages/sessions/view.ts                 |  57 ++++--
 ui/src/styles/chat/layout.css                 |  15 ++
 ui/src/styles/components.css                  |  59 ++++++
 ui/src/styles/layout.css                      |  24 +++
 .../test-helpers/app-sidebar-cases/basics.ts  |  15 ++
 .../app-sidebar-cases/sessions.ts             |  51 +++++
 22 files changed, 846 insertions(+), 53 deletions(-)
 create mode 100644 ui/src/lib/toast.test.ts
 create mode 100644 ui/src/lib/toast.ts

diff --git a/ui/src/app/app-host.ts b/ui/src/app/app-host.ts
index 82eafaacd2c..be915151a0b 100644
--- a/ui/src/app/app-host.ts
+++ b/ui/src/app/app-host.ts
@@ -48,6 +48,7 @@ import { isGatewayMethodAdvertised } from "../lib/gateway-methods.ts";
 import { isWorkboardEnabledInConfigSnapshot } from "../lib/plugin-activation.ts";
 import { searchForSession } from "../lib/sessions/index.ts";
 import { isTerminalAvailable } from "../lib/terminal-availability.ts";
+import "../lib/toast.ts";
 import { OpenClawLightDomElement } from "../lit/openclaw-element.ts";
 import { SubscriptionsController } from "../lit/subscriptions-controller.ts";
 import { findSettingsSearchBlocks } from "../pages/config/settings-search.ts";
@@ -1520,6 +1521,7 @@ class OpenClawShell extends OpenClawLightDomElement {
               .context=${context}
             ></openclaw-onboarding-memory-import>`
           : nothing}
+        <openclaw-toast-host></openclaw-toast-host>
       </div>
     `;
   }
diff --git a/ui/src/components/app-sidebar-menus.ts b/ui/src/components/app-sidebar-menus.ts
index 841628dad77..dbc1dd4005e 100644
--- a/ui/src/components/app-sidebar-menus.ts
+++ b/ui/src/components/app-sidebar-menus.ts
@@ -465,7 +465,7 @@ export abstract class AppSidebarMenusElement extends AppSidebarSessionGroupsElem
                 this.createSessionGroup([session]);
                 break;
               case "toggle-archived":
-                void this.patchSession(session, { archived: true });
+                void this.archiveSessionWithUndo(session);
                 break;
               case "stop-cloud-worker":
                 void this.stopCloudWorker(session);
diff --git a/ui/src/components/app-sidebar-session-list.ts b/ui/src/components/app-sidebar-session-list.ts
index e3b2919c8a7..ab872da463f 100644
--- a/ui/src/components/app-sidebar-session-list.ts
+++ b/ui/src/components/app-sidebar-session-list.ts
@@ -595,6 +595,13 @@ export abstract class AppSidebarSessionListElement extends AppSidebarMenusElemen
             codingTrailing: html`${this.renderSessionCatalogs(navigationState)}`,
             codingTrailingPresent: this.sessionCatalogs.length > 0,
           })}
+          <button
+            type="button"
+            class="sidebar-view-archived"
+            @click=${() => this.onNavigate?.("sessions", { search: "?showArchived=1" })}
+          >
+            ${icons.archive} ${t("sessionsView.viewArchived")}
+          </button>
         </div>
       </section>
     `;
diff --git a/ui/src/components/app-sidebar-session-mutations.ts b/ui/src/components/app-sidebar-session-mutations.ts
index 87979e1d192..ee36adcfede 100644
--- a/ui/src/components/app-sidebar-session-mutations.ts
+++ b/ui/src/components/app-sidebar-session-mutations.ts
@@ -4,6 +4,7 @@ import {
   parseAgentSessionKey,
   resolveUiConfiguredMainKey,
 } from "../lib/sessions/session-key.ts";
+import { showToast } from "../lib/toast.ts";
 import { AppSidebarSessionNavigationElement } from "./app-sidebar-session-navigation.ts";
 import type {
   SidebarRecentSession,
@@ -80,6 +81,78 @@ export abstract class AppSidebarSessionMutationsElement extends AppSidebarSessio
     return result;
   }
 
+  protected async archiveSessionWithUndo(session: SidebarRecentSession) {
+    const scope = this.beginSessionMutation();
+    if (!scope) {
+      return;
+    }
+    const result = await this.patchSession(session, { archived: true }, scope);
+    if (result !== "completed" || !this.isSessionMutationScopeCurrent(scope)) {
+      return;
+    }
+    showToast({
+      message: t("sessionsView.sessionArchived"),
+      actionLabel: t("common.undo"),
+      onAction: () => {
+        void this.restoreArchivedSessions([{ session, pinned: session.pinned }], scope);
+      },
+    });
+  }
+
+  private async archiveSessionsWithUndo(rows: readonly SidebarRecentSession[]) {
+    const scope = this.beginSessionMutation();
+    if (!scope) {
+      return;
+    }
+    const archived: Array<{ session: SidebarRecentSession; pinned: boolean }> = [];
+    for (const session of rows) {
+      const result = await this.patchSession(session, { archived: true }, scope);
+      if (result === "stale") {
+        return;
+      }
+      if (result === "completed") {
+        archived.push({ session, pinned: session.pinned });
+      }
+    }
+    if (archived.length === 0 || !this.isSessionMutationScopeCurrent(scope)) {
+      return;
+    }
+    showToast({
+      message:
+        archived.length === 1
+          ? t("sessionsView.sessionArchived")
+          : t("sessionsView.sessionsArchived", { count: String(archived.length) }),
+      actionLabel: t("common.undo"),
+      onAction: () => void this.restoreArchivedSessions(archived, scope),
+    });
+  }
+
+  private async restoreArchivedSessions(
+    archived: readonly { session: SidebarRecentSession; pinned: boolean }[],
+    scope: SidebarSessionMutationScope,
+  ) {
+    if (!this.isSessionMutationScopeCurrent(scope)) {
+      return;
+    }
+    let restoredActiveKey: string | null = null;
+    for (const { session, pinned } of archived) {
+      const result = await this.patchSession(
+        session,
+        { archived: false, ...(pinned ? { pinned: true } : {}) },
+        scope,
+      );
+      if (result === "stale") {
+        return;
+      }
+      if (result === "completed" && session.active) {
+        restoredActiveKey = session.key;
+      }
+    }
+    if (restoredActiveKey && this.isSessionMutationScopeCurrent(scope)) {
+      this.replaceCurrentSession(restoredActiveKey);
+    }
+  }
+
   /** One confirm and one preserved-worktrees alert for the whole selection. */
   protected async deleteSessionsBatch(rows: readonly SidebarRecentSession[]) {
     if (rows.length === 0) {
@@ -153,7 +226,7 @@ export abstract class AppSidebarSessionMutationsElement extends AppSidebarSessio
         this.createSessionGroup(rows);
         break;
       case "toggle-archived":
-        void this.patchSessions(rows, { archived: true });
+        void this.archiveSessionsWithUndo(rows);
         break;
       case "delete":
         void this.deleteSessionsBatch(rows);
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index b075894f148..8ad97b84c24 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -20,6 +20,8 @@ export const en: TranslationMap = {
     staleData: "Showing stale data.",
     reload: "Reload",
     reset: "Reset",
+    restore: "Restore",
+    undo: "Undo",
     probe: "Probe",
     call: "Call",
     confirm: "Confirm",
@@ -528,7 +530,12 @@ export const en: TranslationMap = {
     sourceFilters: "Session source filters",
     global: "Global",
     unknown: "Unknown",
-    archivedOnly: "Archived only",
+    sessionState: "Session state",
+    viewArchived: "View archived",
+    sessionArchived: "Session archived",
+    sessionsArchived: "Archived {count} sessions",
+    deleteAllArchived: "Delete all archived…",
+    deleteAllArchivedConfirm: "Delete {count} archived sessions and their transcripts?",
     activeTooltip: "Loads sessions updated in the last {count} minutes.",
     limitTooltip: "Max sessions to load.",
     globalTooltip: "Include global sessions.",
diff --git a/ui/src/lib/sessions/index.test.ts b/ui/src/lib/sessions/index.test.ts
index d48f50d1d67..7beed42de68 100644
--- a/ui/src/lib/sessions/index.test.ts
+++ b/ui/src/lib/sessions/index.test.ts
@@ -385,14 +385,17 @@ describe("createSessionCapability", () => {
       deletedSnapshots.push(next.deletedSessions.map((target) => target.key));
     });
 
-    await expect(sessions.deleteMany([{ key: keptKey }, { key: deletedKey }])).resolves.toEqual({
-      deleted: [deletedKey],
-      errors: [],
-      preservedWorktrees: [],
-    });
+    await expect(
+      sessions.deleteMany([{ key: keptKey }, { key: deletedKey, archivedOnly: true }]),
+    ).resolves.toEqual({ deleted: [deletedKey], errors: [], preservedWorktrees: [] });
     expect(deletedSnapshots.some((keys) => keys.includes(deletedKey))).toBe(true);
     expect(deletedSnapshots.some((keys) => keys.includes(keptKey))).toBe(false);
     expect(request).toHaveBeenCalledTimes(3);
+    expect(request).toHaveBeenCalledWith("sessions.delete", {
+      key: deletedKey,
+      deleteTranscript: true,
+      archivedOnly: true,
+    });
     unsubscribe();
     sessions.dispose();
   });
diff --git a/ui/src/lib/sessions/index.ts b/ui/src/lib/sessions/index.ts
index 9a4842756a5..43fdbe921e9 100644
--- a/ui/src/lib/sessions/index.ts
+++ b/ui/src/lib/sessions/index.ts
@@ -98,12 +98,14 @@ export type { SessionPatch } from "./patch.ts";
 type SessionDeleteOptions = {
   agentId?: string;
   deleteTranscript?: boolean;
+  archivedOnly?: boolean;
 };
 
 type SessionDeleteTarget = {
   key: string;
   agentId?: string;
   deleteTranscript?: boolean;
+  archivedOnly?: boolean;
 };
 
 /** Dirty/unpushed checkouts survive session deletion; callers surface them. */
@@ -361,6 +363,7 @@ function requestSessionDelete(
   return client.request<SessionDeleteResponse>("sessions.delete", {
     ...buildSessionRequestParams(key, options.agentId),
     deleteTranscript: options.deleteTranscript ?? true,
+    ...(options.archivedOnly === true ? { archivedOnly: true } : {}),
   });
 }
 
diff --git a/ui/src/lib/toast.test.ts b/ui/src/lib/toast.test.ts
new file mode 100644
index 00000000000..782a2a530b5
--- /dev/null
+++ b/ui/src/lib/toast.test.ts
@@ -0,0 +1,56 @@
+/* @vitest-environment jsdom */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { showToast } from "./toast.ts";
+
+async function mountHost() {
+  const host = document.createElement("openclaw-toast-host");
+  document.body.append(host);
+  await host.updateComplete;
+  return host;
+}
+
+afterEach(() => {
+  document.body.replaceChildren();
+  vi.useRealTimers();
+});
+
+describe("shared toast", () => {
+  it("shows and replaces the active toast", async () => {
+    const host = await mountHost();
+
+    showToast({ message: "First" });
+    await host.updateComplete;
+    expect(host.querySelector(".app-toast__message")?.textContent).toBe("First");
+
+    showToast({ message: "Second" });
+    await host.updateComplete;
+    expect(host.querySelectorAll(".app-toast")).toHaveLength(1);
+    expect(host.querySelector(".app-toast__message")?.textContent).toBe("Second");
+  });
+
+  it("auto-dismisses after the configured duration", async () => {
+    vi.useFakeTimers();
+    const host = await mountHost();
+
+    showToast({ message: "Temporary", durationMs: 50 });
+    await host.updateComplete;
+    await vi.advanceTimersByTimeAsync(50);
+    await host.updateComplete;
+
+    expect(host.querySelector(".app-toast")).toBeNull();
+  });
+
+  it("runs its action once and dismisses", async () => {
+    const host = await mountHost();
+    const onAction = vi.fn();
+    showToast({ message: "Archived", actionLabel: "Undo", onAction });
+    await host.updateComplete;
+
+    host.querySelector<HTMLButtonElement>(".app-toast__action")?.click();
+    await host.updateComplete;
+
+    expect(onAction).toHaveBeenCalledOnce();
+    expect(host.querySelector(".app-toast")).toBeNull();
+  });
+});
diff --git a/ui/src/lib/toast.ts b/ui/src/lib/toast.ts
new file mode 100644
index 00000000000..33d8dc868c5
--- /dev/null
+++ b/ui/src/lib/toast.ts
@@ -0,0 +1,92 @@
+import { html, nothing } from "lit";
+import { state } from "lit/decorators.js";
+import { t } from "../i18n/index.ts";
+import { OpenClawLightDomContentsElement } from "../lit/openclaw-element.ts";
+
+type ToastOptions = {
+  message: string;
+  actionLabel?: string;
+  onAction?: () => void;
+  durationMs?: number;
+};
+
+const DEFAULT_TOAST_DURATION_MS = 6_000;
+
+class OpenClawToastHost extends OpenClawLightDomContentsElement {
+  @state() private toast: ToastOptions | null = null;
+  private dismissTimer: ReturnType<typeof globalThis.setTimeout> | null = null;
+
+  override disconnectedCallback() {
+    this.clearDismissTimer();
+    super.disconnectedCallback();
+  }
+
+  show(options: ToastOptions) {
+    this.clearDismissTimer();
+    this.toast = options;
+    this.dismissTimer = globalThis.setTimeout(
+      () => this.dismiss(),
+      options.durationMs ?? DEFAULT_TOAST_DURATION_MS,
+    );
+  }
+
+  private clearDismissTimer() {
+    if (this.dismissTimer !== null) {
+      globalThis.clearTimeout(this.dismissTimer);
+      this.dismissTimer = null;
+    }
+  }
+
+  private dismiss() {
+    this.clearDismissTimer();
+    this.toast = null;
+  }
+
+  override render() {
+    const toast = this.toast;
+    if (!toast) {
+      return nothing;
+    }
+    return html`
+      <div class="app-toast" role="status" aria-live="polite" aria-atomic="true">
+        <span class="app-toast__message">${toast.message}</span>
+        ${toast.actionLabel && toast.onAction
+          ? html`
+              <button
+                type="button"
+                class="app-toast__action"
+                @click=${() => {
+                  this.dismiss();
+                  toast.onAction?.();
+                }}
+              >
+                ${toast.actionLabel}
+              </button>
+            `
+          : nothing}
+        <button
+          type="button"
+          class="app-toast__dismiss"
+          aria-label=${t("common.dismiss")}
+          @click=${() => this.dismiss()}
+        >
+          ×
+        </button>
+      </div>
+    `;
+  }
+}
+
+export function showToast(options: ToastOptions): void {
+  document.querySelector<OpenClawToastHost>("openclaw-toast-host")?.show(options);
+}
+
+if (!customElements.get("openclaw-toast-host")) {
+  customElements.define("openclaw-toast-host", OpenClawToastHost);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "openclaw-toast-host": OpenClawToastHost;
+  }
+}
diff --git a/ui/src/pages/chat/chat-composer.test.ts b/ui/src/pages/chat/chat-composer.test.ts
index 1e032132aad..ea423d1d7e4 100644
--- a/ui/src/pages/chat/chat-composer.test.ts
+++ b/ui/src/pages/chat/chat-composer.test.ts
@@ -81,6 +81,21 @@ afterEach(async () => {
 });
 
 describe("renderChatComposer controls", () => {
+  it("renders and invokes an action beside the disabled reason", () => {
+    const onDisabledAction = vi.fn();
+    const { container } = renderComposer({
+      canSend: false,
+      disabledReason: "This session is archived.",
+      disabledActionLabel: "Restore",
+      onDisabledAction,
+    });
+
+    const reason = container.querySelector(".agent-chat__disabled-reason");
+    expect(reason?.textContent).toContain("This session is archived.");
+    reason?.querySelector<HTMLButtonElement>("button")?.click();
+    expect(onDisabledAction).toHaveBeenCalledOnce();
+  });
+
   it("switches the primary action between voice, send, queue, and stop", () => {
     const onToggleRealtimeTalk = vi.fn();
     let view = renderComposer({ onToggleRealtimeTalk });
diff --git a/ui/src/pages/chat/chat-pane.ts b/ui/src/pages/chat/chat-pane.ts
index faaef120675..d5588ef826b 100644
--- a/ui/src/pages/chat/chat-pane.ts
+++ b/ui/src/pages/chat/chat-pane.ts
@@ -658,6 +658,29 @@ class ChatPane extends OpenClawLightDomElement {
     });
   }
 
+  private async restoreArchivedSession(sessionKey: string) {
+    const scope = this.captureConnectionScope();
+    if (!scope || scope.state.sessionKey !== sessionKey) {
+      return;
+    }
+    const agentId = parseAgentSessionKey(sessionKey)?.agentId ?? resolveChatAgentId(scope.state);
+    let failure: string | null = null;
+    try {
+      // The patch can resolve falsy on failure; the capability error explains it.
+      const patched = await scope.sessions.patch(sessionKey, { archived: false }, { agentId });
+      if (!patched) {
+        failure = scope.sessions.state.error;
+      }
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error);
+    }
+    if (failure && this.isConnectionScopeCurrent(scope) && scope.state.sessionKey === sessionKey) {
+      scope.state.lastError = failure;
+      scope.state.chatError = failure;
+      scope.state.requestUpdate?.();
+    }
+  }
+
   private setPaneSessionKey(sessionKey: string): string | null {
     const state = this.state;
     if (!state) {
@@ -2343,6 +2366,12 @@ class ChatPane extends OpenClawLightDomElement {
       connected: state.connected,
       canSend: catalogKey ? this.catalogSession?.canContinue === true : !selectedSessionArchived,
       disabledReason: catalogDisabledReason ?? disabledReason,
+      disabledActionLabel:
+        selectedSessionArchived && !catalogDisabledReason ? t("common.restore") : null,
+      onDisabledAction:
+        selectedSessionArchived && !catalogDisabledReason
+          ? () => void this.restoreArchivedSession(state.sessionKey)
+          : null,
       error: state.lastError,
       sessions: state.sessionsResult,
       sessionHost: {
diff --git a/ui/src/pages/chat/chat-view.ts b/ui/src/pages/chat/chat-view.ts
index ba5e77b7bad..20b5f7f4d2c 100644
--- a/ui/src/pages/chat/chat-view.ts
+++ b/ui/src/pages/chat/chat-view.ts
@@ -112,6 +112,8 @@ export type ChatProps = {
   connected: boolean;
   canSend: boolean;
   disabledReason: string | null;
+  disabledActionLabel?: string | null;
+  onDisabledAction?: (() => void) | null;
   error: string | null;
   sessions: SessionsListResult | null;
   /** Host context resolving global-alias session keys (scope=global fleets). */
@@ -330,6 +332,8 @@ export function renderChat(props: ChatProps) {
     connected: props.connected,
     canSend: props.canSend,
     disabledReason: props.disabledReason,
+    disabledActionLabel: props.disabledActionLabel,
+    onDisabledAction: props.onDisabledAction,
     sending: props.sending,
     canAbort: props.canAbort,
     runStatus: props.runStatus,
@@ -443,7 +447,6 @@ export function renderChat(props: ChatProps) {
         }
       }}
     >
-      ${props.disabledReason ? html`<div class="callout">${props.disabledReason}</div>` : nothing}
       ${props.error
         ? html`
             <div class="callout danger callout--dismissible" role="alert">
diff --git a/ui/src/pages/chat/components/chat-composer.ts b/ui/src/pages/chat/components/chat-composer.ts
index 9a960c2c6f6..9524688ecb1 100644
--- a/ui/src/pages/chat/components/chat-composer.ts
+++ b/ui/src/pages/chat/components/chat-composer.ts
@@ -88,6 +88,8 @@ type ChatComposerProps = {
   connected: boolean;
   canSend: boolean;
   disabledReason: string | null;
+  disabledActionLabel?: string | null;
+  onDisabledAction?: (() => void) | null;
   sending: boolean;
   canAbort?: boolean;
   runStatus?: ChatRunUiStatus | null;
@@ -2410,6 +2412,20 @@ export function renderChatComposer(props: ChatComposerProps) {
               </div>
             `
           : nothing}
+        ${props.disabledReason
+          ? html`
+              <div class="agent-chat__disabled-reason">
+                <span>${props.disabledReason}</span>
+                ${props.disabledActionLabel && props.onDisabledAction
+                  ? html`
+                      <button type="button" class="btn btn--xs" @click=${props.onDisabledAction}>
+                        ${props.disabledActionLabel}
+                      </button>
+                    `
+                  : nothing}
+              </div>
+            `
+          : nothing}
 
         <div class="agent-chat__composer-input-row">
           ${renderChatAttachmentMenu({ ...props, disabled: !canCompose })}
diff --git a/ui/src/pages/sessions/sessions-page.test.ts b/ui/src/pages/sessions/sessions-page.test.ts
index 3c52fd99a47..003d252bda4 100644
--- a/ui/src/pages/sessions/sessions-page.test.ts
+++ b/ui/src/pages/sessions/sessions-page.test.ts
@@ -25,6 +25,7 @@ type TestSessionsPage = HTMLElement & {
   result: SessionsListResult | null;
   error: string | null;
   loading: boolean;
+  showArchived: boolean;
   selectedKeys: Set<string>;
   sessionMenu: { key: string; x: number; y: number } | null;
   sessionMenuTrigger: HTMLElement | null;
@@ -40,6 +41,7 @@ type TestSessionsPage = HTMLElement & {
   loadCheckpoint: (sessionKey: string) => Promise<void>;
   deleteSelected: () => Promise<void>;
   deleteSessionFromMenu: (row: GatewaySessionRow) => Promise<void>;
+  deleteAllArchived: () => Promise<void>;
   stopCloudWorker: (row: GatewaySessionRow) => Promise<void>;
   rememberCustomGroup: (name: string) => Promise<void>;
   openSessionMenu: (
@@ -47,7 +49,8 @@ type TestSessionsPage = HTMLElement & {
     position: { x: number; y: number },
     trigger: HTMLElement | null,
   ) => void;
-  patchSession: (key: string, patch: { archived?: boolean }) => Promise<void>;
+  patchSession: (key: string, patch: { archived?: boolean; pinned?: boolean }) => Promise<unknown>;
+  archiveSessionWithUndo: (row: GatewaySessionRow) => Promise<void>;
   forkSession: (key: string) => Promise<void>;
   branchCheckpoint: (sessionKey: string, checkpointId: string) => Promise<void>;
   restoreCheckpoint: (sessionKey: string, checkpointId: string) => Promise<void>;
@@ -177,6 +180,7 @@ async function createPage(context: ApplicationContext): Promise<TestSessionsPage
 async function createRenderedPage(
   context: ApplicationContext,
   result: SessionsListResult,
+  showArchived = false,
 ): Promise<TestSessionsPage> {
   const page = document.createElement("openclaw-sessions-page") as TestSessionsPage;
   page.context = context;
@@ -186,7 +190,7 @@ async function createRenderedPage(
     result,
     error: null,
     expandedSessionKey: null,
-    showArchived: false,
+    showArchived,
   };
   document.body.append(page);
   await page.updateComplete;
@@ -199,6 +203,186 @@ afterEach(() => {
 });
 
 describe("sessions page lifecycle", () => {
+  it("switches between Active and Archived with the route parameter", async () => {
+    const { gateway } = createGateway({} as GatewayBrowserClient);
+    const context = createContext(gateway, createSessions());
+    const page = await createRenderedPage(context, {
+      ts: Date.now(),
+      path: "",
+      count: 0,
+      defaults: { modelProvider: null, model: null, contextTokens: null },
+      sessions: [],
+    });
+
+    const archived = [
+      ...page.querySelectorAll<HTMLButtonElement>(".sessions-view-segment button"),
+    ].find((button) => button.textContent?.trim() === "Archived");
+    archived?.click();
+    await page.updateComplete;
+
+    expect(page.showArchived).toBe(true);
+    expect(context.navigate).toHaveBeenCalledWith("sessions", { search: "?showArchived=1" });
+    expect(archived?.getAttribute("aria-pressed")).toBe("true");
+  });
+
+  it("re-enumerates all archived sessions before bulk deletion", async () => {
+    // The rendered result holds one archived row; enumeration must find both.
+    const archivedKeys = ["agent:main:old-1", "agent:main:old-2"];
+    const sessions = createSessions({
+      list: vi.fn(async () => ({
+        count: 2,
+        sessions: archivedKeys.map((key) => ({ key, archived: true })),
+      })) as unknown as SessionCapability["list"],
+      deleteMany: vi.fn(async () => ({
+        deleted: archivedKeys,
+        errors: [],
+        preservedWorktrees: [],
+      })),
+    });
+    const { gateway } = createGateway({} as GatewayBrowserClient);
+    const page = await createRenderedPage(
+      createContext(gateway, sessions),
+      {
+        count: 2,
+        sessions: [
+          { key: archivedKeys[0], archived: true },
+          { key: "agent:main:active", archived: false },
+        ],
+      } as SessionsListResult,
+      true,
+    );
+    const confirm = vi.spyOn(window, "confirm").mockReturnValue(true);
+
+    page.querySelector<HTMLButtonElement>(".settings-section__actions .danger")?.click();
+    await vi.waitFor(() => expect(sessions.deleteMany).toHaveBeenCalledOnce());
+
+    expect(sessions.list).toHaveBeenCalledWith(
+      expect.objectContaining({ showArchived: true, limit: 1000 }),
+    );
+    expect(confirm).toHaveBeenCalledWith("Delete 2 archived sessions and their transcripts?");
+    expect(sessions.deleteMany).toHaveBeenCalledWith([
+      {
+        key: archivedKeys[0],
+        agentId: undefined,
+        deleteTranscript: true,
+        archivedOnly: true,
+      },
+      {
+        key: archivedKeys[1],
+        agentId: undefined,
+        deleteTranscript: true,
+        archivedOnly: true,
+      },
+    ]);
+  });
+
+  it("aborts delete-all when an enumeration page fails", async () => {
+    const sessions = createSessions({
+      list: vi.fn(async () => null) as unknown as SessionCapability["list"],
+      deleteMany: vi.fn(async () => ({ deleted: [], errors: [], preservedWorktrees: [] })),
+    });
+    sessions.state.error = "list failed";
+    const { gateway } = createGateway({} as GatewayBrowserClient);
+    const page = await createRenderedPage(
+      createContext(gateway, sessions),
+      {
+        count: 1,
+        sessions: [{ key: "agent:main:old-1", archived: true }],
+      } as SessionsListResult,
+      true,
+    );
+    const confirm = vi.spyOn(window, "confirm").mockReturnValue(true);
+
+    page.querySelector<HTMLButtonElement>(".settings-section__actions .danger")?.click();
+    await vi.waitFor(() => expect(sessions.list).toHaveBeenCalledOnce());
+
+    expect(confirm).not.toHaveBeenCalled();
+    expect(sessions.deleteMany).not.toHaveBeenCalled();
+  });
+
+  it("paginates the archived enumeration until the listing is exhausted", async () => {
+    const pageOne = ["agent:main:old-1", "agent:main:old-2"];
+    const pageTwo = ["agent:main:old-3"];
+    const list = vi
+      .fn()
+      .mockResolvedValueOnce({
+        count: 3,
+        sessions: pageOne.map((key) => ({ key, archived: true })),
+        hasMore: true,
+        nextOffset: 2,
+      })
+      .mockResolvedValueOnce({
+        count: 3,
+        sessions: pageTwo.map((key) => ({ key, archived: true })),
+        hasMore: false,
+        nextOffset: null,
+      });
+    const sessions = createSessions({
+      list: list as unknown as SessionCapability["list"],
+      deleteMany: vi.fn(async () => ({
+        deleted: [...pageOne, ...pageTwo],
+        errors: [],
+        preservedWorktrees: [],
+      })),
+    });
+    const { gateway } = createGateway({} as GatewayBrowserClient);
+    const page = await createRenderedPage(
+      createContext(gateway, sessions),
+      {
+        count: 1,
+        sessions: [{ key: pageOne[0], archived: true }],
+      } as SessionsListResult,
+      true,
+    );
+    const confirm = vi.spyOn(window, "confirm").mockReturnValue(true);
+
+    page.querySelector<HTMLButtonElement>(".settings-section__actions .danger")?.click();
+    await vi.waitFor(() => expect(sessions.deleteMany).toHaveBeenCalledOnce());
+
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(list).toHaveBeenNthCalledWith(2, expect.objectContaining({ offset: 2 }));
+    expect(confirm).toHaveBeenCalledWith("Delete 3 archived sessions and their transcripts?");
+    expect(sessions.deleteMany).toHaveBeenCalledWith(
+      [...pageOne, ...pageTwo].map((key) => ({
+        key,
+        agentId: undefined,
+        deleteTranscript: true,
+        archivedOnly: true,
+      })),
+    );
+  });
+
+  it("offers undo after archiving from the Sessions page", async () => {
+    const key = "agent:main:pinned";
+    const patch = vi.fn(async () => ({
+      ok: true as const,
+      path: "",
+      key,
+      entry: { sessionId: key },
+    }));
+    const sessions = createSessions({ patch });
+    const mutableGateway = createGateway({} as GatewayBrowserClient);
+    mutableGateway.emit({ sessionKey: key });
+    const page = await createPage(createContext(mutableGateway.gateway, sessions));
+    const toast = document.createElement("openclaw-toast-host");
+    document.body.append(toast);
+    await toast.updateComplete;
+
+    await page.archiveSessionWithUndo({ key, pinned: true } as GatewaySessionRow);
+    await toast.updateComplete;
+    toast.querySelector<HTMLButtonElement>(".app-toast__action")?.click();
+    await vi.waitFor(() => expect(patch).toHaveBeenCalledTimes(2));
+    await vi.waitFor(() => expect(mutableGateway.setSessionKey).toHaveBeenLastCalledWith(key));
+
+    expect(patch).toHaveBeenNthCalledWith(1, key, { archived: true }, { agentId: undefined });
+    expect(patch).toHaveBeenNthCalledWith(
+      2,
+      key,
+      { archived: false, pinned: true },
+      { agentId: undefined },
+    );
+  });
+
   it("submits one trimmed bounded transcript search and adopts its status", async () => {
     const response = deferred<SessionsSearchResult>();
     const request = vi.fn(() => response.promise);
diff --git a/ui/src/pages/sessions/sessions-page.ts b/ui/src/pages/sessions/sessions-page.ts
index bcf3f16000a..8fa2307e318 100644
--- a/ui/src/pages/sessions/sessions-page.ts
+++ b/ui/src/pages/sessions/sessions-page.ts
@@ -36,6 +36,7 @@ import {
   resolveUiConfiguredMainKey,
 } from "../../lib/sessions/session-key.ts";
 import { normalizeOptionalString } from "../../lib/string-coerce.ts";
+import { showToast } from "../../lib/toast.ts";
 import { captureSessionToWorkboard } from "../../lib/workboard/index.ts";
 import { OpenClawLightDomElement } from "../../lit/openclaw-element.ts";
 import { SubscriptionsController } from "../../lit/subscriptions-controller.ts";
@@ -67,6 +68,8 @@ type SessionsPageRequestScope = {
   client: GatewayBrowserClient;
 };
 
+type SessionsPageMutationResult = "completed" | "failed" | "stale";
+
 class SessionsPage extends OpenClawLightDomElement {
   @consume({ context: applicationContext, subscribe: true })
   private context?: ApplicationContext;
@@ -593,6 +596,22 @@ class SessionsPage extends OpenClawLightDomElement {
     void this.loadSessions();
   }
 
+  private updateArchivedView(showArchived: boolean) {
+    const context = this.context;
+    if (showArchived === this.showArchived || !context) {
+      return;
+    }
+    this.showArchived = showArchived;
+    this.page = 0;
+    this.selectedKeys = new Set();
+    this.deepLinkSessionKey = null;
+    // Route navigation refetches (showArchived is in loaderDeps); mask the old
+    // view's rows until the new result applies via applyRouteData.
+    this.loading = true;
+    this.error = null;
+    context.navigate("sessions", showArchived ? { search: "?showArchived=1" } : undefined);
+  }
+
   private async deleteSelected() {
     const keys = [...this.selectedKeys];
     if (keys.length === 0 || this.loading || this.sessionMutationPending) {
@@ -608,7 +627,10 @@ class SessionsPage extends OpenClawLightDomElement {
     await this.deleteSessions(keys);
   }
 
-  private async deleteSessions(keys: string[]) {
+  private async deleteSessions(
+    keys: string[],
+    options: { deleteTranscript?: boolean; archivedOnly?: boolean } = {},
+  ) {
     if (keys.length === 0 || this.loading || this.sessionMutationPending) {
       return;
     }
@@ -622,6 +644,7 @@ class SessionsPage extends OpenClawLightDomElement {
         keys.map((key) => ({
           key,
           agentId: this.sessionAgentId(key, scope.context),
+          ...options,
         })),
       );
       if (!this.isRequestScopeCurrent(scope)) {
@@ -690,6 +713,58 @@ class SessionsPage extends OpenClawLightDomElement {
     }
   }
 
+  private async deleteAllArchived() {
+    const scope = this.captureRequestScope();
+    if (!scope || this.loading || this.sessionMutationPending) {
+      return;
+    }
+    // The rendered list is bounded by the page's limit filter; re-enumerate the
+    // full archived set so "all archived" means all of them. Any abnormal page
+    // (failure, non-advancing offset) aborts: deleting a partial enumeration
+    // would silently violate the "all archived" contract.
+    const keys: string[] = [];
+    try {
+      // One options snapshot for every page: filter edits made while pages load
+      // must not mix enumeration populations.
+      const listOptions = this.sessionListOptions();
+      let offset = 0;
+      for (;;) {
+        const listed = await scope.sessions.list({ ...listOptions, limit: 1000, offset });
+        if (!this.isRequestScopeCurrent(scope)) {
+          return;
+        }
+        if (!listed) {
+          this.error = scope.sessions.state.error;
+          return;
+        }
+        for (const row of listed.sessions) {
+          if (row.archived === true) {
+            keys.push(row.key);
+          }
+        }
+        if (listed.hasMore !== true) {
+          break;
+        }
+        if (typeof listed.nextOffset !== "number" || listed.nextOffset <= offset) {
+          throw new Error("archived session enumeration did not advance");
+        }
+        offset = listed.nextOffset;
+      }
+    } catch (error) {
+      if (this.isRequestScopeCurrent(scope)) {
+        this.error = String(error);
+      }
+      return;
+    }
+    if (
+      keys.length === 0 ||
+      !window.confirm(t("sessionsView.deleteAllArchivedConfirm", { count: String(keys.length) }))
+    ) {
+      return;
+    }
+    await this.deleteSessions(keys, { deleteTranscript: true, archivedOnly: true });
+  }
+
   private async deleteSessionFromMenu(row: GatewaySessionRow) {
     const label = normalizeOptionalString(row.label) ?? row.key;
     if (!window.confirm(t("sessionsView.deleteSessionConfirm", { session: label }))) {
@@ -799,21 +874,24 @@ class SessionsPage extends OpenClawLightDomElement {
     void this.patchSession(row.key, { label: normalizeOptionalString(value) ?? null });
   }
 
-  private async patchSession(key: string, patch: Parameters<SessionsProps["onPatch"]>[1]) {
-    const scope = this.captureRequestScope();
+  private async patchSession(
+    key: string,
+    patch: Parameters<SessionsProps["onPatch"]>[1],
+    scope: SessionsPageRequestScope | null = this.captureRequestScope(),
+  ): Promise<SessionsPageMutationResult> {
     if (!scope) {
-      return;
+      return "stale";
     }
     try {
       const patched = await scope.sessions.patch(key, patch, {
         agentId: this.sessionAgentId(key, scope.context),
       });
       if (!this.isRequestScopeCurrent(scope)) {
-        return;
+        return "stale";
       }
       if (!patched) {
         this.error = scope.sessions.state.error;
-        return;
+        return "failed";
       }
       const selectedKeys = new Set(this.selectedKeys);
       selectedKeys.delete(key);
@@ -835,13 +913,47 @@ class SessionsPage extends OpenClawLightDomElement {
           }),
         );
       }
+      return "completed";
     } catch (error) {
       if (this.isRequestScopeCurrent(scope)) {
         this.error = String(error);
+        return "failed";
       }
+      return "stale";
     }
   }
 
+  private async archiveSessionWithUndo(row: GatewaySessionRow) {
+    const scope = this.captureRequestScope();
+    if (!scope) {
+      return;
+    }
+    const wasActive = areUiSessionKeysEquivalent(row.key, scope.gateway.snapshot.sessionKey);
+    const result = await this.patchSession(row.key, { archived: true }, scope);
+    if (result !== "completed" || !this.isRequestScopeCurrent(scope)) {
+      return;
+    }
+    showToast({
+      message: t("sessionsView.sessionArchived"),
+      actionLabel: t("common.undo"),
+      onAction: () => {
+        void (async () => {
+          if (!this.isRequestScopeCurrent(scope)) {
+            return;
+          }
+          const restored = await this.patchSession(
+            row.key,
+            { archived: false, ...(row.pinned === true ? { pinned: true } : {}) },
+            scope,
+          );
+          if (restored === "completed" && wasActive && this.isRequestScopeCurrent(scope)) {
+            scope.gateway.setSessionKey(row.key);
+          }
+        })();
+      },
+    });
+  }
+
   private async forkSession(key: string) {
     const scope = this.captureRequestScope();
     if (!scope) {
@@ -1125,7 +1237,11 @@ class SessionsPage extends OpenClawLightDomElement {
               this.requestNewCategory(row.key);
               break;
             case "toggle-archived":
-              void this.patchSession(row.key, { archived: row.archived !== true });
+              if (row.archived === true) {
+                void this.patchSession(row.key, { archived: false });
+              } else {
+                void this.archiveSessionWithUndo(row);
+              }
               break;
             case "stop-cloud-worker":
               void this.stopCloudWorker(row);
@@ -1231,6 +1347,8 @@ class SessionsPage extends OpenClawLightDomElement {
             this.page = 0;
           },
           onRefresh: () => void this.loadSessions(),
+          onArchivedViewChange: (showArchived) => this.updateArchivedView(showArchived),
+          onDeleteAllArchived: () => void this.deleteAllArchived(),
           onPatch: (key, patch) => void this.patchSession(key, patch),
           onToggleSelect: (key) => {
             const next = new Set(this.selectedKeys);
diff --git a/ui/src/pages/sessions/view.test.ts b/ui/src/pages/sessions/view.test.ts
index e6f39ed9b19..d478dbb01bf 100644
--- a/ui/src/pages/sessions/view.test.ts
+++ b/ui/src/pages/sessions/view.test.ts
@@ -70,6 +70,8 @@ function buildProps(result: SessionsListResult): SessionsProps {
     onPageChange: () => undefined,
     onPageSizeChange: () => undefined,
     onRefresh: () => undefined,
+    onArchivedViewChange: () => undefined,
+    onDeleteAllArchived: () => undefined,
     onPatch: () => undefined,
     onToggleSelect: () => undefined,
     onSelectPage: () => undefined,
@@ -212,33 +214,29 @@ describe("sessions view", () => {
     expect(onTranscriptSearch).not.toHaveBeenCalled();
   });
 
-  it("renders an explicit archived-session toggle", async () => {
+  it("renders an Active and Archived segment", async () => {
     const container = document.createElement("div");
-    const onFiltersChange = vi.fn();
+    const onArchivedViewChange = vi.fn();
     render(
       renderSessions({
         ...buildProps(buildMultiResult([])),
-        onFiltersChange,
+        onArchivedViewChange,
       }),
       container,
     );
     await Promise.resolve();
 
-    const archivedToggle = container.querySelector(
-      ".session-archive-toggle input",
-    ) as HTMLInputElement | null;
-    expect(archivedToggle?.checked).toBe(false);
+    const buttons = container.querySelectorAll<HTMLButtonElement>(".sessions-view-segment button");
+    expect([...buttons].map((button) => button.textContent?.trim())).toEqual([
+      "Active",
+      "Archived",
+    ]);
+    expect(buttons[0]?.getAttribute("aria-pressed")).toBe("true");
+    expect(buttons[1]?.getAttribute("aria-pressed")).toBe("false");
 
-    archivedToggle!.checked = true;
-    archivedToggle!.dispatchEvent(new Event("change", { bubbles: true }));
+    buttons[1]?.click();
 
-    expect(onFiltersChange).toHaveBeenCalledWith({
-      activeMinutes: "",
-      limit: "120",
-      includeGlobal: false,
-      includeUnknown: false,
-      showArchived: true,
-    });
+    expect(onArchivedViewChange).toHaveBeenCalledWith(true);
   });
 
   it("groups sessions by channel with section headers and no pagination", async () => {
@@ -441,7 +439,6 @@ describe("sessions view", () => {
       "Max sessions to load.",
       "Include global sessions.",
       "Include unknown sessions.",
-      "Show only archived sessions.",
     ]);
   });
 
@@ -469,7 +466,7 @@ describe("sessions view", () => {
     const toggleGroup = container.querySelector(".session-filter-toggle-group");
     expect(toggleGroup?.getAttribute("role")).toBe("group");
     expect(toggleGroup?.getAttribute("aria-label")).toBe("Session source filters");
-    expect(toggleGroup?.querySelectorAll(".session-filter-check")).toHaveLength(3);
+    expect(toggleGroup?.querySelectorAll(".session-filter-check")).toHaveLength(2);
     expect(
       Array.from(toggleGroup?.querySelectorAll(".session-filter-check") ?? []).map((toggle) => [
         toggle.querySelector("input")?.getAttribute("name"),
@@ -481,7 +478,6 @@ describe("sessions view", () => {
         ["session-filter-check", "session-filter-toggle", "session-filter-check--active"],
       ],
       ["includeUnknown", ["session-filter-check", "session-filter-toggle"]],
-      ["showArchived", ["session-filter-check", "session-filter-toggle", "session-archive-toggle"]],
     ]);
     expect(toggleGroup?.querySelector(".session-filter-check__box")).toBeNull();
   });
diff --git a/ui/src/pages/sessions/view.ts b/ui/src/pages/sessions/view.ts
index 32bfe355464..5af08f7943b 100644
--- a/ui/src/pages/sessions/view.ts
+++ b/ui/src/pages/sessions/view.ts
@@ -110,6 +110,8 @@ export type SessionsProps = {
   onPageChange: (page: number) => void;
   onPageSizeChange: (size: number) => void;
   onRefresh: () => void;
+  onArchivedViewChange: (showArchived: boolean) => void;
+  onDeleteAllArchived: () => void;
   onPatch: (
     key: string,
     patch: {
@@ -1074,6 +1076,7 @@ export function renderSessions(props: SessionsProps) {
   const emptyBecauseFiltered =
     rawRows.length === 0 ? hasActiveFilters(props) : filtered.length === 0;
   const liveCount = rawRows.filter((row) => isSessionRunActive(row)).length;
+  const archivedCount = rawRows.filter((row) => row.archived === true).length;
 
   const sortHeader = (
     col: "key" | "kind" | "updated" | "tokens",
@@ -1106,6 +1109,17 @@ export function renderSessions(props: SessionsProps) {
       : nothing}
   `;
   const refreshAction = html`
+    ${props.showArchived
+      ? html`
+          <button
+            class="btn danger"
+            ?disabled=${props.loading || archivedCount === 0}
+            @click=${props.onDeleteAllArchived}
+          >
+            ${icons.trash} ${t("sessionsView.deleteAllArchived")}
+          </button>
+        `
+      : nothing}
     <button class="btn" ?disabled=${props.loading} @click=${props.onRefresh}>
       ${props.loading ? t("common.loading") : t("common.refresh")}
     </button>
@@ -1166,7 +1180,6 @@ function renderSessionsTable(props: SessionsProps, ctx: SessionsTableContext) {
   const limitTooltip = t("sessionsView.limitTooltip");
   const globalTooltip = t("sessionsView.globalTooltip");
   const unknownTooltip = t("sessionsView.unknownTooltip");
-  const showArchivedTooltip = t("sessionsView.archivedOnlyTooltip");
   return html`
     <div
       class="sessions-toolbar sessions-filter-bar"
@@ -1252,21 +1265,33 @@ function renderSessionsTable(props: SessionsProps, ctx: SessionsTableContext) {
               showArchived: props.showArchived,
             }),
         })}
-        ${renderFilterToggle({
-          name: "showArchived",
-          checked: props.showArchived,
-          label: t("sessionsView.archivedOnly"),
-          title: showArchivedTooltip,
-          extraClass: "session-archive-toggle",
-          onChange: (checked) =>
-            props.onFiltersChange({
-              activeMinutes: props.activeMinutes,
-              limit: props.limit,
-              includeGlobal: props.includeGlobal,
-              includeUnknown: props.includeUnknown,
-              showArchived: checked,
-            }),
-        })}
+        <div
+          class="settings-segmented sessions-view-segment"
+          role="group"
+          aria-label=${t("sessionsView.sessionState")}
+        >
+          <button
+            type="button"
+            class="settings-segmented__btn ${props.showArchived
+              ? ""
+              : "settings-segmented__btn--active"}"
+            aria-pressed=${String(!props.showArchived)}
+            @click=${() => props.onArchivedViewChange(false)}
+          >
+            ${t("common.active")}
+          </button>
+          <button
+            type="button"
+            class="settings-segmented__btn ${props.showArchived
+              ? "settings-segmented__btn--active"
+              : ""}"
+            aria-pressed=${String(props.showArchived)}
+            title=${t("sessionsView.archivedOnlyTooltip")}
+            @click=${() => props.onArchivedViewChange(true)}
+          >
+            ${t("sessionsView.archived")}
+          </button>
+        </div>
       </div>
       <span class="sessions-toolbar__divider" aria-hidden="true"></span>
       <label class="session-groupby">
diff --git a/ui/src/styles/chat/layout.css b/ui/src/styles/chat/layout.css
index 2e4108a338f..0f3a3cc424e 100644
--- a/ui/src/styles/chat/layout.css
+++ b/ui/src/styles/chat/layout.css
@@ -1811,6 +1811,21 @@ openclaw-chat-page {
   padding: var(--chat-box-inset);
 }
 
+.agent-chat__disabled-reason {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  padding: 8px var(--chat-box-inset) 0;
+  color: var(--muted);
+  font-size: var(--control-ui-text-sm);
+  line-height: 1.4;
+}
+
+.agent-chat__disabled-reason .btn {
+  flex: 0 0 auto;
+}
+
 .agent-chat__composer-footer {
   display: flex;
   align-items: center;
diff --git a/ui/src/styles/components.css b/ui/src/styles/components.css
index d992600efee..38c69b8827a 100644
--- a/ui/src/styles/components.css
+++ b/ui/src/styles/components.css
@@ -795,6 +795,65 @@
   line-height: 1;
 }
 
+.app-toast {
+  position: fixed;
+  left: 50%;
+  bottom: calc(20px + var(--safe-area-bottom));
+  z-index: 2000;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  max-width: min(520px, calc(100vw - 32px));
+  padding: 10px 12px 10px 16px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius-md);
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: var(--shadow-lg);
+}
+
+.app-toast__message {
+  min-width: 0;
+  overflow: hidden;
+  font-size: var(--control-ui-text-md);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.app-toast__action,
+.app-toast__dismiss {
+  flex: 0 0 auto;
+  border: 0;
+  background: transparent;
+  color: inherit;
+}
+
+.app-toast__action {
+  color: var(--accent);
+  font-size: var(--control-ui-text-sm);
+  font-weight: 700;
+}
+
+.app-toast__dismiss {
+  display: grid;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  place-items: center;
+  border-radius: var(--radius-sm);
+  color: var(--muted);
+  font-size: 20px;
+  line-height: 1;
+}
+
+.app-toast__action:hover,
+.app-toast__action:focus-visible,
+.app-toast__dismiss:hover,
+.app-toast__dismiss:focus-visible {
+  color: var(--text-strong);
+}
+
 .btn--icon {
   padding: 8px;
   min-width: 36px;
diff --git a/ui/src/styles/layout.css b/ui/src/styles/layout.css
index c95d374aca5..f9fe1444f1a 100644
--- a/ui/src/styles/layout.css
+++ b/ui/src/styles/layout.css
@@ -1665,6 +1665,30 @@ html.openclaw-native-macos
   color: var(--text);
 }
 
+.sidebar-view-archived {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: -2px 10px 2px;
+  padding: 5px 0;
+  border: 0;
+  background: transparent;
+  color: var(--muted);
+  font-size: 11px;
+  text-align: left;
+}
+
+.sidebar-view-archived:hover,
+.sidebar-view-archived:focus-visible {
+  color: var(--text);
+}
+
+.sidebar-view-archived svg {
+  width: 12px;
+  height: 12px;
+  stroke: currentColor;
+}
+
 .sidebar-recent-session--dragging {
   opacity: 0.45;
 }
diff --git a/ui/src/test-helpers/app-sidebar-cases/basics.ts b/ui/src/test-helpers/app-sidebar-cases/basics.ts
index 479e5e1d7a8..04bc0b7bc4c 100644
--- a/ui/src/test-helpers/app-sidebar-cases/basics.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/basics.ts
@@ -74,6 +74,21 @@ describe("AppSidebar brand actions", () => {
     button?.click();
     expect(onOpenNewSession).toHaveBeenCalledExactlyOnceWith("research");
   });
+
+  it("opens the archived Sessions view from the sessions-zone footer", async () => {
+    const gateway = createGateway({} as GatewayBrowserClient);
+    const { sidebar } = await mountSidebar(
+      gateway,
+      createSessions("main", ["agent:main:main", "agent:main:work"]),
+    );
+    const onNavigate = vi.fn();
+    sidebar.onNavigate = onNavigate;
+    await sidebar.updateComplete;
+
+    sidebar.querySelector<HTMLButtonElement>(".sidebar-view-archived")?.click();
+
+    expect(onNavigate).toHaveBeenCalledWith("sessions", { search: "?showArchived=1" });
+  });
 });
 
 describe("AppSidebar agent chip", () => {
diff --git a/ui/src/test-helpers/app-sidebar-cases/sessions.ts b/ui/src/test-helpers/app-sidebar-cases/sessions.ts
index bb24395f2e6..79e240a9c6e 100644
--- a/ui/src/test-helpers/app-sidebar-cases/sessions.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/sessions.ts
@@ -509,6 +509,57 @@ describe("AppSidebar session mutation feedback", () => {
     link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, metaKey: true }));
   }
 
+  async function mountToastHost() {
+    const host = document.createElement("openclaw-toast-host");
+    document.body.append(host);
+    await host.updateComplete;
+    return host;
+  }
+
+  it("offers undo after archiving and restores a pinned active session", async () => {
+    const { gateway, harness, sidebar } = await mountMutationHarness();
+    const setSessionKey = vi.fn();
+    (gateway.gateway as { setSessionKey: (key: string) => void }).setSessionKey = setSessionKey;
+    const state = createSessionState("main", ["agent:main:main", "agent:main:a", "agent:main:b"]);
+    const archivedRow = state.result?.sessions.find((row) => row.key === "agent:main:a");
+    if (!archivedRow) {
+      throw new Error("expected archive row");
+    }
+    archivedRow.pinned = true;
+    harness.publishList({ result: state.result, agentId: state.agentId });
+    gateway.publish({ sessionKey: archivedRow.key });
+    sidebar.sessionKey = archivedRow.key;
+    (sidebar as unknown as { activeRouteId: string }).activeRouteId = "chat";
+    const navigate = vi.fn();
+    sidebar.onNavigate = navigate;
+    const toast = await mountToastHost();
+    await sidebar.updateComplete;
+
+    const menu = await openSessionMenu(sidebar, archivedRow.key);
+    menu.querySelector<HTMLButtonElement>('[data-shortcut="a"]')?.click();
+    await vi.waitFor(() => expect(harness.patch).toHaveBeenCalledOnce());
+    await vi.waitFor(() =>
+      expect(toast.querySelector(".app-toast__message")?.textContent).toBe("Session archived"),
+    );
+    expect(harness.patch).toHaveBeenCalledWith(
+      archivedRow.key,
+      { archived: true },
+      { agentId: "main" },
+    );
+    toast.querySelector<HTMLButtonElement>(".app-toast__action")?.click();
+
+    await vi.waitFor(() => expect(harness.patch).toHaveBeenCalledTimes(2));
+    await vi.waitFor(() => expect(setSessionKey).toHaveBeenLastCalledWith(archivedRow.key));
+    expect(harness.patch).toHaveBeenLastCalledWith(
+      archivedRow.key,
+      { archived: false, pinned: true },
+      { agentId: "main" },
+    );
+    expect(navigate).toHaveBeenLastCalledWith("chat", {
+      search: "?session=agent%3Amain%3Aa",
+    });
+  });
+
   it("reconciles and stops an idle active cloud worker through its session", async () => {
     const request = vi.fn(() => Promise.resolve({ ok: true }));
     const { gateway, harness, sidebar } = await mountMutationHarness({

From f6de912efec8f9643cde3528153a5a6713cfa6b0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:52:54 +0100
Subject: [PATCH 55/76] refactor(update): split update-runner into focused
 modules under the line limit (#110664)

---
 config/max-lines-baseline.txt              |    1 -
 src/infra/update-runner-command.ts         |   99 +
 src/infra/update-runner-doctor.ts          |   57 +
 src/infra/update-runner-git-commands.ts    |  141 ++
 src/infra/update-runner-git-preflight.ts   |  522 ++++++
 src/infra/update-runner-git-target.ts      |  107 ++
 src/infra/update-runner-git.ts             |  500 ++++++
 src/infra/update-runner-global.ts          |  170 ++
 src/infra/update-runner-install-surface.ts |  151 ++
 src/infra/update-runner-types.ts           |  152 ++
 src/infra/update-runner.ts                 | 1900 +-------------------
 11 files changed, 1937 insertions(+), 1863 deletions(-)
 create mode 100644 src/infra/update-runner-command.ts
 create mode 100644 src/infra/update-runner-doctor.ts
 create mode 100644 src/infra/update-runner-git-commands.ts
 create mode 100644 src/infra/update-runner-git-preflight.ts
 create mode 100644 src/infra/update-runner-git-target.ts
 create mode 100644 src/infra/update-runner-git.ts
 create mode 100644 src/infra/update-runner-global.ts
 create mode 100644 src/infra/update-runner-install-surface.ts
 create mode 100644 src/infra/update-runner-types.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 433a2aa64af..9a758d4cce5 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -944,7 +944,6 @@ src/infra/state-migrations.test.ts
 src/infra/update-global.ts
 src/infra/update-managed-service-handoff.ts
 src/infra/update-runner.test.ts
-src/infra/update-runner.ts
 src/infra/update-startup.test.ts
 src/infra/update-startup.ts
 src/infra/windows-gateway-firewall-diagnostics.ts
diff --git a/src/infra/update-runner-command.ts b/src/infra/update-runner-command.ts
new file mode 100644
index 00000000000..68fb82fc451
--- /dev/null
+++ b/src/infra/update-runner-command.ts
@@ -0,0 +1,99 @@
+import { runCommandWithTimeout } from "../process/exec.js";
+import { trimLogTail } from "./restart-sentinel.js";
+import { createGlobalInstallEnv } from "./update-global.js";
+import type {
+  CommandRunner,
+  RunStepOptions,
+  UpdateRunResult,
+  UpdateStepInfo,
+  UpdateStepResult,
+} from "./update-runner-types.js";
+
+export const DEFAULT_TIMEOUT_MS = 20 * 60_000;
+export const MAX_LOG_CHARS = 8000;
+
+function mergeCommandEnvironments(
+  baseEnv: NodeJS.ProcessEnv | undefined,
+  overrideEnv: NodeJS.ProcessEnv | undefined,
+): NodeJS.ProcessEnv | undefined {
+  if (!baseEnv) {
+    return overrideEnv;
+  }
+  if (!overrideEnv) {
+    return baseEnv;
+  }
+  return { ...baseEnv, ...overrideEnv };
+}
+
+export async function runStep(opts: RunStepOptions): Promise<UpdateStepResult> {
+  const { runCommand, name, argv, cwd, timeoutMs, env, progress, stepIndex, totalSteps } = opts;
+  const command = argv.join(" ");
+  const stepInfo: UpdateStepInfo = { name, command, index: stepIndex, total: totalSteps };
+  progress?.onStepStart?.(stepInfo);
+
+  const started = Date.now();
+  const result = await runCommand(argv, { cwd, timeoutMs, env });
+  const durationMs = Date.now() - started;
+  const stderrTail = trimLogTail(result.stderr, MAX_LOG_CHARS);
+
+  progress?.onStepComplete?.({
+    ...stepInfo,
+    durationMs,
+    exitCode: result.code,
+    stderrTail,
+    signal: result.signal,
+    killed: result.killed,
+    termination: result.termination,
+  });
+
+  return {
+    name,
+    command,
+    cwd,
+    durationMs,
+    exitCode: result.code,
+    stdoutTail: trimLogTail(result.stdout, MAX_LOG_CHARS),
+    stderrTail,
+    signal: result.signal,
+    killed: result.killed,
+    termination: result.termination,
+  };
+}
+
+export function normalizeFallbackFailureReason(
+  stepName: string,
+): NonNullable<UpdateRunResult["reason"]> {
+  switch (stepName) {
+    case "global update":
+    case "global update (omit optional)":
+    case "global install stage":
+    case "global install verify":
+    case "global install swap":
+      return "global-install-failed";
+    case "openclaw doctor":
+      return "doctor-failed";
+    case "ui:build (post-doctor repair)":
+      return "ui-build-failed";
+    default:
+      return "unexpected-error";
+  }
+}
+
+export async function buildUpdateCommandRunner(
+  runCommand?: CommandRunner,
+): Promise<{ defaultCommandEnv: NodeJS.ProcessEnv | undefined; runCommand: CommandRunner }> {
+  const defaultCommandEnv = await createGlobalInstallEnv();
+  if (runCommand) {
+    return { defaultCommandEnv, runCommand };
+  }
+  return {
+    defaultCommandEnv,
+    runCommand: async (argv, options) =>
+      await runCommandWithTimeout(argv, {
+        ...options,
+        env: mergeCommandEnvironments(defaultCommandEnv, options.env),
+        // Package-manager trees must not outlive a timed-out updater.
+        killProcessTree: true,
+      }),
+  };
+}
diff --git a/src/infra/update-runner-doctor.ts b/src/infra/update-runner-doctor.ts
new file mode 100644
index 00000000000..60bdb23b2ec
--- /dev/null
+++ b/src/infra/update-runner-doctor.ts
@@ -0,0 +1,57 @@
+import { compareSemverStrings } from "./update-check.js";
+
+const UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV =
+  "OPENCLAW_UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR";
+const UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV =
+  "OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE";
+const UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART_ENV =
+  "OPENCLAW_UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART";
+const UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR_ENV =
+  "OPENCLAW_UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR";
+const UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION_ENV =
+  "OPENCLAW_UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION";
+const UPDATE_DOCTOR_SERVICE_REPAIR_POLICY_ENV = "OPENCLAW_SERVICE_REPAIR_POLICY";
+const EXTERNAL_SERVICE_REPAIR_POLICY_MIN_VERSION = "2026.4.25-beta.1";
+
+export function resolveUpdateDoctorExecutionPolicy(params: {
+  targetVersion: string | null;
+  allowGatewayServiceRepair: boolean;
+}): { fix: boolean; serviceRepairPolicy?: "external" } {
+  if (params.allowGatewayServiceRepair) {
+    return { fix: true };
+  }
+  const support = compareSemverStrings(
+    params.targetVersion,
+    EXTERNAL_SERVICE_REPAIR_POLICY_MIN_VERSION,
+  );
+  if (support !== null && support >= 0) {
+    return { fix: true, serviceRepairPolicy: "external" };
+  }
+  // Older targets ignore ownership markers and the external-service policy.
+  return { fix: false };
+}
+
+export function buildUpdateDoctorEnv(params: {
+  allowGatewayServiceRepair: boolean;
+  allowGatewayActivation: boolean;
+  serviceRepairPolicy?: "external";
+  deferConfiguredPluginInstallRepair?: boolean;
+  compatibilityHostVersion?: string | null;
+}): NodeJS.ProcessEnv {
+  return {
+    OPENCLAW_UPDATE_IN_PROGRESS: "1",
+    ...(params.deferConfiguredPluginInstallRepair
+      ? { [UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV]: "1" }
+      : {}),
+    [UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV]: "1",
+    [UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART_ENV]: "1",
+    [UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR_ENV]: params.allowGatewayServiceRepair ? "1" : "0",
+    [UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION_ENV]: params.allowGatewayActivation ? "1" : "0",
+    ...(params.serviceRepairPolicy
+      ? { [UPDATE_DOCTOR_SERVICE_REPAIR_POLICY_ENV]: params.serviceRepairPolicy }
+      : {}),
+    ...(params.compatibilityHostVersion
+      ? { OPENCLAW_COMPATIBILITY_HOST_VERSION: params.compatibilityHostVersion }
+      : {}),
+  };
+}
diff --git a/src/infra/update-runner-git-commands.ts b/src/infra/update-runner-git-commands.ts
new file mode 100644
index 00000000000..987a0dca678
--- /dev/null
+++ b/src/infra/update-runner-git-commands.ts
@@ -0,0 +1,141 @@
+import { DEV_BRANCH } from "./update-channels.js";
+import {
+  managerInstallIgnoreScriptsArgs,
+  type UpdatePackageManagerFailureReason,
+} from "./update-package-manager.js";
+import type { UpdateRunResult, UpdateStepResult } from "./update-runner-types.js";
+
+const BUILD_MAX_OLD_SPACE_MB = 8192;
+const DEV_PREFLIGHT_LINT_ENV: NodeJS.ProcessEnv = {
+  OPENCLAW_LOCAL_CHECK: "1",
+  OPENCLAW_LOCAL_CHECK_MODE: "throttled",
+  OPENCLAW_OXLINT_SHARDS_SERIAL: "1",
+};
+const DEV_PREFLIGHT_LINT_OPT_IN_ENV = "OPENCLAW_UPDATE_PREFLIGHT_LINT";
+
+export function mapManagerResolutionFailure(
+  reason: UpdatePackageManagerFailureReason,
+): NonNullable<UpdateRunResult["reason"]> {
+  return reason;
+}
+
+export function shouldRetryWindowsInstallIgnoringScripts(manager: "pnpm" | "bun" | "npm"): boolean {
+  return process.platform === "win32" && manager === "pnpm";
+}
+
+export function shouldPreferIgnoreScriptsForWindowsPreflight(
+  manager: "pnpm" | "bun" | "npm",
+): boolean {
+  return process.platform === "win32" && manager === "pnpm";
+}
+
+function resolveBuildNodeOptions(baseOptions: string | undefined): string {
+  const current = baseOptions?.trim() ?? "";
+  const desired = `--max-old-space-size=${BUILD_MAX_OLD_SPACE_MB}`;
+  const existingMatch = /(?:^|\s)--max-old-space-size=(\d+)(?=\s|$)/.exec(current);
+  if (!existingMatch) {
+    return current ? `${current} ${desired}` : desired;
+  }
+  const existingValue = Number(existingMatch[1]);
+  if (Number.isFinite(existingValue) && existingValue >= BUILD_MAX_OLD_SPACE_MB) {
+    return current;
+  }
+  return current.replace(/(?:^|\s)--max-old-space-size=\d+(?=\s|$)/, ` ${desired}`).trim();
+}
+
+export function resolveBuildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv | undefined {
+  const currentNodeOptions = env?.NODE_OPTIONS ?? process.env.NODE_OPTIONS;
+  const nextNodeOptions = resolveBuildNodeOptions(currentNodeOptions);
+  if (nextNodeOptions === currentNodeOptions) {
+    return env;
+  }
+  return { ...env, NODE_OPTIONS: nextNodeOptions };
+}
+
+export function resolveInstallEnv(
+  manager: "pnpm" | "bun" | "npm",
+  env?: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv | undefined {
+  if (manager !== "pnpm") {
+    return env;
+  }
+  return {
+    ...env,
+    PNPM_CONFIG_RESOLUTION_MODE: env?.PNPM_CONFIG_RESOLUTION_MODE ?? "highest",
+    npm_config_resolution_mode: env?.npm_config_resolution_mode ?? "highest",
+    pnpm_config_resolution_mode: env?.pnpm_config_resolution_mode ?? "highest",
+  };
+}
+
+function isSupersededInstallFailure(
+  step: UpdateStepResult,
+  steps: readonly UpdateStepResult[],
+): boolean {
+  if (step.exitCode === 0) {
+    return false;
+  }
+  if (step.name === "deps install") {
+    return steps.some(
+      (candidate) => candidate.name === "deps install (ignore scripts)" && candidate.exitCode === 0,
+    );
+  }
+  const preflightMatch = /^preflight deps install \((.+)\)$/.exec(step.name);
+  if (!preflightMatch) {
+    return false;
+  }
+  const retryName = `preflight deps install (ignore scripts) (${preflightMatch[1]})`;
+  return steps.some((candidate) => candidate.name === retryName && candidate.exitCode === 0);
+}
+
+function isPreflightCandidateFailure(step: UpdateStepResult): boolean {
+  return /^preflight (?:checkout|package manager|deps install(?: \(ignore scripts\))?|build|lint) \(.+\)$/u.test(
+    step.name,
+  );
+}
+
+function isSupersededTargetRefFailure(
+  step: UpdateStepResult,
+  followingSteps: readonly UpdateStepResult[],
+): boolean {
+  const isTargetRefProbe = step.name.startsWith("git rev-parse ");
+  const isTargetTagFetch = step.name.startsWith("git fetch ") && step.name.includes(" refs/tags/");
+  const isUpstreamProbe = step.name === "upstream check";
+  const isLocalDevBranchProbe = step.name === `git show-ref ${DEV_BRANCH}`;
+  if (!isTargetRefProbe && !isTargetTagFetch && !isUpstreamProbe && !isLocalDevBranchProbe) {
+    return false;
+  }
+  if (isLocalDevBranchProbe) {
+    return followingSteps.some(
+      (candidate) =>
+        candidate.name.startsWith(`git checkout -B ${DEV_BRANCH} `) && candidate.exitCode === 0,
+    );
+  }
+  return followingSteps.some(
+    (candidate) => candidate.name.startsWith("git rev-parse ") && candidate.exitCode === 0,
+  );
+}
+
+export function findBlockingGitFailure(
+  steps: readonly UpdateStepResult[],
+): UpdateStepResult | undefined {
+  return steps.find(
+    (step, index) =>
+      step.exitCode !== 0 &&
+      !isPreflightCandidateFailure(step) &&
+      !isSupersededInstallFailure(step, steps) &&
+      !isSupersededTargetRefFailure(step, steps.slice(index + 1)),
+  );
+}
+
+export function shouldRunDevPreflightLint(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env[DEV_PREFLIGHT_LINT_OPT_IN_ENV]?.trim().toLowerCase();
+  return value === "1" || value === "true";
+}
+
+export function resolveDevPreflightLintEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
+  return { ...env, ...DEV_PREFLIGHT_LINT_ENV };
+}
+
+export function resolveRetryInstallArgs(manager: "pnpm" | "bun" | "npm") {
+  return managerInstallIgnoreScriptsArgs(manager);
+}
diff --git a/src/infra/update-runner-git-preflight.ts b/src/infra/update-runner-git-preflight.ts
new file mode 100644
index 00000000000..73fa7123c9f
--- /dev/null
+++ b/src/infra/update-runner-git-preflight.ts
@@ -0,0 +1,522 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
+import { trimLogTail } from "./restart-sentinel.js";
+import { DEV_BRANCH } from "./update-channels.js";
+import {
+  managerInstallArgs,
+  managerInstallIgnoreScriptsArgs,
+  managerScriptArgs,
+  resolveUpdateBuildManager,
+} from "./update-package-manager.js";
+import { MAX_LOG_CHARS, runStep } from "./update-runner-command.js";
+import {
+  mapManagerResolutionFailure,
+  resolveBuildEnv,
+  resolveDevPreflightLintEnv,
+  resolveInstallEnv,
+  resolveRetryInstallArgs,
+  shouldPreferIgnoreScriptsForWindowsPreflight,
+  shouldRetryWindowsInstallIgnoringScripts,
+  shouldRunDevPreflightLint,
+} from "./update-runner-git-commands.js";
+import type {
+  CommandRunner,
+  RunStepOptions,
+  UpdateRunResult,
+  UpdateStepResult,
+} from "./update-runner-types.js";
+
+const PREFLIGHT_MAX_COMMITS = 10;
+const PREFLIGHT_TEMP_PREFIX =
+  process.platform === "win32" ? "ocu-pf-" : "openclaw-update-preflight-";
+const PREFLIGHT_WORKTREE_DIRNAME = process.platform === "win32" ? "wt" : "worktree";
+const PREFLIGHT_CLEANUP_TIMEOUT_MS = 60_000;
+const WINDOWS_PREFLIGHT_BASE_DIR = "ocu";
+
+type StepFactory = (
+  name: string,
+  argv: string[],
+  cwd: string,
+  env?: NodeJS.ProcessEnv,
+) => RunStepOptions;
+
+type GitDevPreflightResult =
+  | {
+      status: "ok";
+      selectedSha: string;
+      selectedDevUpstream: string | null;
+      localDevBranchExists: boolean | null;
+    }
+  | { status: "error" | "skipped"; reason: NonNullable<UpdateRunResult["reason"]> };
+
+function normalizeDevTargetRef(value?: string | null): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function looksLikeFullCommitSha(value: string): boolean {
+  return /^[0-9a-f]{40}$/i.test(value.trim());
+}
+
+function resolveTagFetchRef(candidate: string): string | null {
+  const ref = candidate.endsWith("^{}") ? candidate.slice(0, -"^{}".length) : candidate;
+  return ref.startsWith("refs/tags/") ? ref : null;
+}
+
+function buildDevTargetRefResolutionCandidates(devTargetRef: string): string[] {
+  const trimmed = devTargetRef.trim();
+  const candidates: string[] = [];
+  const addCandidate = (candidate?: string | null) => {
+    if (candidate && !candidates.includes(candidate)) {
+      candidates.push(candidate);
+    }
+  };
+  if (looksLikeFullCommitSha(trimmed) || trimmed.startsWith("refs/remotes/")) {
+    addCandidate(trimmed);
+    return candidates;
+  }
+  if (trimmed.startsWith("refs/heads/")) {
+    addCandidate(`refs/remotes/origin/${trimmed.slice("refs/heads/".length)}`);
+    return candidates;
+  }
+  if (trimmed.startsWith("origin/")) {
+    addCandidate(`refs/remotes/${trimmed}`);
+    return candidates;
+  }
+  if (trimmed.startsWith("refs/tags/")) {
+    addCandidate(`${trimmed}^{}`);
+    addCandidate(trimmed);
+    return candidates;
+  }
+  // Plain branch names resolve from the freshly fetched remote ref.
+  addCandidate(`refs/remotes/origin/${trimmed}`);
+  addCandidate(`refs/tags/${trimmed}^{}`);
+  addCandidate(`refs/tags/${trimmed}`);
+  return candidates;
+}
+
+function resolvePreflightWorktreeDir(preflightRoot: string) {
+  return path.join(preflightRoot, PREFLIGHT_WORKTREE_DIRNAME);
+}
+
+async function createPreflightRoot() {
+  if (process.platform === "win32" && path.sep === "\\") {
+    const baseDir = path.win32.join(process.env.SystemDrive ?? "C:", WINDOWS_PREFLIGHT_BASE_DIR);
+    await fs.mkdir(baseDir, { recursive: true });
+    return fs.mkdtemp(path.win32.join(baseDir, PREFLIGHT_TEMP_PREFIX));
+  }
+  return fs.mkdtemp(path.join(os.tmpdir(), PREFLIGHT_TEMP_PREFIX));
+}
+
+async function removePathRecursive(target: string) {
+  await fs
+    .rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 })
+    .catch(() => {});
+}
+
+async function repairPreflightCleanup(worktreeDir: string, preflightRoot: string) {
+  try {
+    await fs.rm(worktreeDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+    await fs.rm(preflightRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveExplicitTarget(params: {
+  devTargetRef: string;
+  gitRoot: string;
+  steps: UpdateStepResult[];
+  step: StepFactory;
+}): Promise<string | null> {
+  for (const candidate of buildDevTargetRefResolutionCandidates(params.devTargetRef)) {
+    const tagFetchRef = resolveTagFetchRef(candidate);
+    if (tagFetchRef) {
+      const remoteStep = await runStep(
+        params.step("git remote", ["git", "-C", params.gitRoot, "remote"], params.gitRoot),
+      );
+      params.steps.push(remoteStep);
+      const remotes = normalizeStringEntries((remoteStep.stdoutTail ?? "").split("\n"));
+      let fetchedTag = false;
+      for (const remote of remotes) {
+        const fetchStep = await runStep(
+          params.step(
+            `git fetch ${remote} ${tagFetchRef}`,
+            ["git", "-C", params.gitRoot, "fetch", remote, `+${tagFetchRef}:${tagFetchRef}`],
+            params.gitRoot,
+          ),
+        );
+        params.steps.push(fetchStep);
+        if (fetchStep.exitCode === 0) {
+          fetchedTag = true;
+          break;
+        }
+      }
+      if (remotes.length > 0 && !fetchedTag) {
+        continue;
+      }
+    }
+    const shaStep = await runStep(
+      params.step(
+        `git rev-parse ${candidate}`,
+        ["git", "-C", params.gitRoot, "rev-parse", candidate],
+        params.gitRoot,
+      ),
+    );
+    params.steps.push(shaStep);
+    const sha = shaStep.stdoutTail?.trim();
+    if (shaStep.exitCode === 0 && sha) {
+      return sha;
+    }
+  }
+  return null;
+}
+
+async function resolveUpstreamCandidates(params: {
+  gitRoot: string;
+  needsCheckoutMain: boolean;
+  steps: UpdateStepResult[];
+  step: StepFactory;
+}): Promise<
+  | {
+      status: "ok";
+      sha: string;
+      candidates: string[];
+      selectedDevUpstream: string | null;
+      localDevBranchExists: boolean | null;
+    }
+  | { status: "error" | "skipped"; reason: NonNullable<UpdateRunResult["reason"]> }
+> {
+  let localDevBranchExists: boolean | null = null;
+  let remoteBranchRefs: string[] = [];
+  if (params.needsCheckoutMain) {
+    const localMainStep = await runStep(
+      params.step(
+        `git show-ref ${DEV_BRANCH}`,
+        ["git", "-C", params.gitRoot, "show-ref", "--verify", `refs/heads/${DEV_BRANCH}`],
+        params.gitRoot,
+      ),
+    );
+    params.steps.push(localMainStep);
+    localDevBranchExists = localMainStep.exitCode === 0;
+  }
+  if (params.needsCheckoutMain && localDevBranchExists === false) {
+    const remoteStep = await runStep(
+      params.step("git remote", ["git", "-C", params.gitRoot, "remote"], params.gitRoot),
+    );
+    params.steps.push(remoteStep);
+    if (remoteStep.exitCode === 0) {
+      remoteBranchRefs = normalizeStringEntries((remoteStep.stdoutTail ?? "").split("\n")).map(
+        (remote) => `refs/remotes/${remote}/${DEV_BRANCH}`,
+      );
+    }
+  }
+  const upstreamRefs = params.needsCheckoutMain
+    ? [`${DEV_BRANCH}@{upstream}`, ...remoteBranchRefs]
+    : ["@{upstream}"];
+  let upstreamSha: string | null = null;
+  let selectedDevUpstream: string | null = null;
+  let sawResolvableUpstreamRef = false;
+  for (const upstreamRef of upstreamRefs) {
+    if (upstreamRef.endsWith("@{upstream}")) {
+      const upstreamStep = await runStep(
+        params.step(
+          "upstream check",
+          [
+            "git",
+            "-C",
+            params.gitRoot,
+            "rev-parse",
+            "--abbrev-ref",
+            "--symbolic-full-name",
+            upstreamRef,
+          ],
+          params.gitRoot,
+        ),
+      );
+      params.steps.push(upstreamStep);
+      if (upstreamStep.exitCode !== 0) {
+        continue;
+      }
+      sawResolvableUpstreamRef = true;
+    }
+    const shaStep = await runStep(
+      params.step(
+        `git rev-parse ${upstreamRef}`,
+        ["git", "-C", params.gitRoot, "rev-parse", upstreamRef],
+        params.gitRoot,
+      ),
+    );
+    params.steps.push(shaStep);
+    const sha = shaStep.stdoutTail?.trim();
+    if (shaStep.exitCode === 0 && sha) {
+      upstreamSha = sha;
+      selectedDevUpstream = /^refs\/remotes\/(.+)$/u.exec(upstreamRef)?.[1] ?? null;
+      break;
+    }
+    if (shaStep.exitCode === 0) {
+      sawResolvableUpstreamRef = true;
+    }
+  }
+  if (!upstreamSha) {
+    return sawResolvableUpstreamRef
+      ? { status: "error", reason: "no-upstream-sha" }
+      : { status: "skipped", reason: "no-upstream" };
+  }
+  const revListStep = await runStep(
+    params.step(
+      "git rev-list",
+      [
+        "git",
+        "-C",
+        params.gitRoot,
+        "rev-list",
+        `--max-count=${PREFLIGHT_MAX_COMMITS}`,
+        upstreamSha,
+      ],
+      params.gitRoot,
+    ),
+  );
+  params.steps.push(revListStep);
+  if (revListStep.exitCode !== 0) {
+    return { status: "error", reason: "preflight-revlist-failed" };
+  }
+  const candidates = normalizeStringEntries((revListStep.stdoutTail ?? "").split("\n"));
+  if (candidates.length === 0) {
+    return { status: "error", reason: "preflight-no-candidates" };
+  }
+  return {
+    status: "ok",
+    sha: upstreamSha,
+    candidates,
+    selectedDevUpstream,
+    localDevBranchExists,
+  };
+}
+
+async function testPreflightCandidates(params: {
+  gitRoot: string;
+  worktreeDir: string;
+  candidates: string[];
+  runCommand: CommandRunner;
+  timeoutMs: number;
+  defaultCommandEnv: NodeJS.ProcessEnv | undefined;
+  steps: UpdateStepResult[];
+  step: StepFactory;
+}): Promise<{
+  selectedSha: string | null;
+  managerReason: string | null;
+  sawOtherFailure: boolean;
+}> {
+  let selectedSha: string | null = null;
+  let managerReason: string | null = null;
+  let sawOtherFailure = false;
+  for (const sha of params.candidates) {
+    const shortSha = sha.slice(0, 8);
+    const checkoutStep = await runStep(
+      params.step(
+        `preflight checkout (${shortSha})`,
+        ["git", "-C", params.worktreeDir, "checkout", "--detach", sha],
+        params.worktreeDir,
+      ),
+    );
+    params.steps.push(checkoutStep);
+    if (checkoutStep.exitCode !== 0) {
+      sawOtherFailure = true;
+      continue;
+    }
+    const manager = await resolveUpdateBuildManager(
+      (argv, options) =>
+        params.runCommand(argv, { timeoutMs: options.timeoutMs, env: options.env }),
+      params.worktreeDir,
+      params.timeoutMs,
+      params.defaultCommandEnv,
+      "require-preferred",
+    );
+    if (manager.kind === "missing-required") {
+      managerReason = mapManagerResolutionFailure(manager.reason);
+      params.steps.push({
+        name: `preflight package manager (${shortSha})`,
+        command: `resolve ${manager.preferred} package manager`,
+        cwd: params.worktreeDir,
+        durationMs: 0,
+        exitCode: 1,
+        stderrTail: managerReason,
+      });
+      continue;
+    }
+    try {
+      const preferIgnoreScripts = shouldPreferIgnoreScriptsForWindowsPreflight(manager.manager);
+      const ignoreScriptsArgv = managerInstallIgnoreScriptsArgs(manager.manager);
+      const installArgv =
+        preferIgnoreScripts && ignoreScriptsArgv
+          ? ignoreScriptsArgv
+          : managerInstallArgs(manager.manager, {
+              compatFallback: manager.fallback && manager.manager === "npm",
+            });
+      const installName = preferIgnoreScripts
+        ? `preflight deps install (ignore scripts) (${shortSha})`
+        : `preflight deps install (${shortSha})`;
+      const installEnv = resolveInstallEnv(manager.manager, manager.env);
+      let installStep = await runStep(
+        params.step(installName, installArgv, params.worktreeDir, installEnv),
+      );
+      params.steps.push(installStep);
+      if (
+        installStep.exitCode !== 0 &&
+        !preferIgnoreScripts &&
+        shouldRetryWindowsInstallIgnoringScripts(manager.manager)
+      ) {
+        const retryArgv = resolveRetryInstallArgs(manager.manager);
+        if (retryArgv) {
+          installStep = await runStep(
+            params.step(
+              `preflight deps install (ignore scripts) (${shortSha})`,
+              retryArgv,
+              params.worktreeDir,
+              installEnv,
+            ),
+          );
+          params.steps.push(installStep);
+        }
+      }
+      if (installStep.exitCode !== 0) {
+        sawOtherFailure = true;
+        continue;
+      }
+      const buildStep = await runStep(
+        params.step(
+          `preflight build (${shortSha})`,
+          managerScriptArgs(manager.manager, "build"),
+          params.worktreeDir,
+          resolveBuildEnv(manager.env),
+        ),
+      );
+      params.steps.push(buildStep);
+      if (buildStep.exitCode !== 0) {
+        sawOtherFailure = true;
+        continue;
+      }
+      if (shouldRunDevPreflightLint()) {
+        const lintStep = await runStep(
+          params.step(
+            `preflight lint (${shortSha})`,
+            managerScriptArgs(manager.manager, "lint"),
+            params.worktreeDir,
+            resolveDevPreflightLintEnv(manager.env),
+          ),
+        );
+        params.steps.push(lintStep);
+        if (lintStep.exitCode !== 0) {
+          sawOtherFailure = true;
+          continue;
+        }
+      }
+      selectedSha = sha;
+      break;
+    } finally {
+      await manager.cleanup?.();
+    }
+  }
+  return { selectedSha, managerReason, sawOtherFailure };
+}
+
+export async function runGitDevPreflight(params: {
+  gitRoot: string;
+  devTargetRef?: string;
+  needsCheckoutMain: boolean;
+  runCommand: CommandRunner;
+  timeoutMs: number;
+  defaultCommandEnv: NodeJS.ProcessEnv | undefined;
+  steps: UpdateStepResult[];
+  step: StepFactory;
+}): Promise<GitDevPreflightResult> {
+  const devTargetRef = normalizeDevTargetRef(params.devTargetRef);
+  let preflightBaseSha: string;
+  let candidates: string[];
+  let selectedDevUpstream: string | null = null;
+  let localDevBranchExists: boolean | null = null;
+  if (devTargetRef) {
+    const targetSha = await resolveExplicitTarget({ ...params, devTargetRef });
+    if (!targetSha) {
+      return { status: "error", reason: "no-target-sha" };
+    }
+    preflightBaseSha = targetSha;
+    candidates = [targetSha];
+  } else {
+    const upstream = await resolveUpstreamCandidates(params);
+    if (upstream.status !== "ok") {
+      return upstream;
+    }
+    preflightBaseSha = upstream.sha;
+    candidates = upstream.candidates;
+    selectedDevUpstream = upstream.selectedDevUpstream;
+    localDevBranchExists = upstream.localDevBranchExists;
+  }
+
+  const preflightRoot = await createPreflightRoot();
+  const worktreeDir = resolvePreflightWorktreeDir(preflightRoot);
+  const worktreeStep = await runStep(
+    params.step(
+      "preflight worktree",
+      ["git", "-C", params.gitRoot, "worktree", "add", "--detach", worktreeDir, preflightBaseSha],
+      params.gitRoot,
+    ),
+  );
+  params.steps.push(worktreeStep);
+  if (worktreeStep.exitCode !== 0) {
+    await removePathRecursive(preflightRoot);
+    return { status: "error", reason: "preflight-worktree-failed" };
+  }
+
+  let tested: Awaited<ReturnType<typeof testPreflightCandidates>>;
+  try {
+    tested = await testPreflightCandidates({ ...params, worktreeDir, candidates });
+  } finally {
+    const removeStep = await runStep({
+      ...params.step(
+        "preflight cleanup",
+        ["git", "-C", params.gitRoot, "worktree", "remove", "--force", worktreeDir],
+        params.gitRoot,
+      ),
+      timeoutMs: Math.min(params.timeoutMs, PREFLIGHT_CLEANUP_TIMEOUT_MS),
+    });
+    if (removeStep.exitCode !== 0 && (await repairPreflightCleanup(worktreeDir, preflightRoot))) {
+      removeStep.exitCode = 0;
+      const message =
+        process.platform === "win32"
+          ? "windows fallback cleanup removed preflight tree"
+          : "fallback cleanup removed preflight tree";
+      removeStep.stderrTail = trimLogTail(
+        [removeStep.stderrTail, message].filter(Boolean).join("\n"),
+        MAX_LOG_CHARS,
+      );
+    }
+    params.steps.push(removeStep);
+    await params
+      .runCommand(["git", "-C", params.gitRoot, "worktree", "prune"], {
+        cwd: params.gitRoot,
+        timeoutMs: params.timeoutMs,
+      })
+      .catch(() => null);
+    await removePathRecursive(preflightRoot);
+  }
+  if (!tested.selectedSha) {
+    return {
+      status: "error",
+      reason:
+        tested.managerReason && !tested.sawOtherFailure
+          ? tested.managerReason
+          : "preflight-no-good-commit",
+    };
+  }
+  return {
+    status: "ok",
+    selectedSha: tested.selectedSha,
+    selectedDevUpstream,
+    localDevBranchExists,
+  };
+}
diff --git a/src/infra/update-runner-git-target.ts b/src/infra/update-runner-git-target.ts
new file mode 100644
index 00000000000..22aeee2d23d
--- /dev/null
+++ b/src/infra/update-runner-git-target.ts
@@ -0,0 +1,107 @@
+import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
+import {
+  parsePackageOpenClawSchemaVersions,
+  type OpenClawSchemaVersions,
+} from "../state/openclaw-schema-versions.js";
+import { isBetaTag, isStableTag, type UpdateChannel } from "./update-channels.js";
+import { compareSemverStrings } from "./update-check.js";
+import type { CommandRunner, UpdateRunnerOptions } from "./update-runner-types.js";
+
+type GitTargetSchemaMetadata =
+  | { status: "ok"; schemaVersions?: OpenClawSchemaVersions }
+  | { status: "unreadable"; reason: string };
+
+async function readGitTargetSchemaVersions(params: {
+  runCommand: CommandRunner;
+  root: string;
+  revision: string;
+  timeoutMs: number;
+}): Promise<GitTargetSchemaMetadata> {
+  let result: Awaited<ReturnType<CommandRunner>>;
+  try {
+    result = await params.runCommand(
+      ["git", "-C", params.root, "show", `${params.revision}:package.json`],
+      { cwd: params.root, timeoutMs: params.timeoutMs },
+    );
+  } catch (error) {
+    return { status: "unreadable", reason: String(error) };
+  }
+  if (result.code !== 0) {
+    return {
+      status: "unreadable",
+      reason: `git show ${params.revision}:package.json exited ${result.code}`,
+    };
+  }
+  try {
+    const schemaVersions = parsePackageOpenClawSchemaVersions(JSON.parse(result.stdout) as unknown);
+    return { status: "ok", ...(schemaVersions ? { schemaVersions } : {}) };
+  } catch (error) {
+    return { status: "unreadable", reason: `target package.json unparseable: ${String(error)}` };
+  }
+}
+
+export async function prepareGitMutation(params: {
+  runCommand: CommandRunner;
+  root: string;
+  revision: string;
+  timeoutMs: number;
+  beforeGitMutation?: UpdateRunnerOptions["beforeGitMutation"];
+}): Promise<{
+  allowGatewayServiceRepair?: boolean;
+  allowGatewayActivation?: boolean;
+}> {
+  const target = await readGitTargetSchemaVersions(params);
+  const preparation = await params.beforeGitMutation?.(
+    target.status === "ok"
+      ? target.schemaVersions
+        ? { schemaVersions: target.schemaVersions }
+        : {}
+      : { metadataUnreadable: target.reason },
+  );
+  return preparation ?? {};
+}
+
+export async function readBranchName(
+  runCommand: CommandRunner,
+  root: string,
+  timeoutMs: number,
+): Promise<string | null> {
+  const result = await runCommand(["git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"], {
+    timeoutMs,
+  }).catch(() => null);
+  const branch = result?.code === 0 ? result.stdout.trim() : "";
+  return branch || null;
+}
+
+async function listGitTags(
+  runCommand: CommandRunner,
+  root: string,
+  timeoutMs: number,
+): Promise<string[]> {
+  const result = await runCommand(["git", "-C", root, "tag", "--list", "v*", "--sort=-v:refname"], {
+    timeoutMs,
+  }).catch(() => null);
+  return result?.code === 0 ? normalizeStringEntries(result.stdout.split("\n")) : [];
+}
+
+export async function resolveChannelTag(
+  runCommand: CommandRunner,
+  root: string,
+  timeoutMs: number,
+  channel: Exclude<UpdateChannel, "dev">,
+): Promise<string | null> {
+  const tags = await listGitTags(runCommand, root, timeoutMs);
+  if (channel === "beta") {
+    const betaTag = tags.find((tag) => isBetaTag(tag)) ?? null;
+    const stableTag = tags.find((tag) => isStableTag(tag)) ?? null;
+    if (!betaTag) {
+      return stableTag;
+    }
+    if (!stableTag) {
+      return betaTag;
+    }
+    const comparison = compareSemverStrings(betaTag, stableTag);
+    return comparison != null && comparison < 0 ? stableTag : betaTag;
+  }
+  return tags.find((tag) => isStableTag(tag)) ?? null;
+}
diff --git a/src/infra/update-runner-git.ts b/src/infra/update-runner-git.ts
new file mode 100644
index 00000000000..e5c674f9f35
--- /dev/null
+++ b/src/infra/update-runner-git.ts
@@ -0,0 +1,500 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  resolveControlUiDistIndexHealth,
+  resolveControlUiDistIndexPathForRoot,
+} from "./control-ui-assets.js";
+import { readPackageVersion } from "./package-json.js";
+import { trimLogTail } from "./restart-sentinel.js";
+import { resolveStableNodePath } from "./stable-node-path.js";
+import { DEV_BRANCH, type UpdateChannel } from "./update-channels.js";
+import {
+  managerInstallArgs,
+  managerScriptArgs,
+  resolveUpdateBuildManager,
+} from "./update-package-manager.js";
+import { MAX_LOG_CHARS, normalizeFallbackFailureReason, runStep } from "./update-runner-command.js";
+import {
+  buildUpdateDoctorEnv,
+  resolveUpdateDoctorExecutionPolicy,
+} from "./update-runner-doctor.js";
+import {
+  findBlockingGitFailure,
+  mapManagerResolutionFailure,
+  resolveBuildEnv,
+  resolveInstallEnv,
+  resolveRetryInstallArgs,
+  shouldRetryWindowsInstallIgnoringScripts,
+} from "./update-runner-git-commands.js";
+import { runGitDevPreflight } from "./update-runner-git-preflight.js";
+import {
+  prepareGitMutation,
+  readBranchName,
+  resolveChannelTag,
+} from "./update-runner-git-target.js";
+import type {
+  CommandRunner,
+  RunStepOptions,
+  UpdateRunResult,
+  UpdateRunnerOptions,
+  UpdateStepResult,
+} from "./update-runner-types.js";
+
+export async function runGitUpdate(params: {
+  opts: UpdateRunnerOptions;
+  gitRoot: string;
+  runCommand: CommandRunner;
+  defaultCommandEnv: NodeJS.ProcessEnv | undefined;
+  timeoutMs: number;
+  startedAt: number;
+}): Promise<UpdateRunResult> {
+  const { opts, gitRoot, runCommand, defaultCommandEnv, timeoutMs, startedAt } = params;
+  const channel: UpdateChannel = opts.channel ?? "dev";
+  if (channel === "extended-stable") {
+    return {
+      status: "error",
+      mode: "git",
+      root: gitRoot,
+      reason: "unsupported_git_channel",
+      steps: [],
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  const beforeShaResult = await runCommand(["git", "-C", gitRoot, "rev-parse", "HEAD"], {
+    cwd: gitRoot,
+    timeoutMs,
+  });
+  const beforeSha = beforeShaResult.stdout.trim() || null;
+  const beforeVersion = await readPackageVersion(gitRoot);
+  const branch = await readBranchName(runCommand, gitRoot, timeoutMs);
+  const hasDevTargetRef = channel === "dev" && Boolean(opts.devTargetRef?.trim());
+  const needsCheckoutMain = channel === "dev" && !hasDevTargetRef && branch !== DEV_BRANCH;
+  const totalSteps = channel === "dev" ? (needsCheckoutMain ? 11 : 10) : 9;
+  const steps: UpdateStepResult[] = [];
+  let stepIndex = 0;
+  const step = (
+    name: string,
+    argv: string[],
+    cwd: string,
+    env?: NodeJS.ProcessEnv,
+  ): RunStepOptions => ({
+    runCommand,
+    name,
+    argv,
+    cwd,
+    timeoutMs,
+    env,
+    progress: opts.progress,
+    stepIndex: stepIndex++,
+    totalSteps,
+  });
+
+  let allowGatewayServiceRepair = opts.allowGatewayServiceRepair !== false;
+  let allowGatewayActivation = opts.allowGatewayActivation === true;
+  let mutationPrepared = false;
+  let createdDevBranchDuringUpdate = false;
+  const prepareMutation = async (revision: string) => {
+    if (mutationPrepared) {
+      return;
+    }
+    const preparation = await prepareGitMutation({
+      runCommand,
+      root: gitRoot,
+      revision,
+      timeoutMs,
+      beforeGitMutation: opts.beforeGitMutation,
+    });
+    if (typeof preparation.allowGatewayServiceRepair === "boolean") {
+      allowGatewayServiceRepair = preparation.allowGatewayServiceRepair;
+    }
+    if (typeof preparation.allowGatewayActivation === "boolean") {
+      allowGatewayActivation = preparation.allowGatewayActivation;
+    }
+    mutationPrepared = true;
+  };
+  const buildError = (reason: string, status: "error" | "skipped" = "error"): UpdateRunResult => ({
+    status,
+    mode: "git",
+    root: gitRoot,
+    reason,
+    before: { sha: beforeSha, version: beforeVersion },
+    steps,
+    durationMs: Date.now() - startedAt,
+  });
+  const runRequiredStep = async (name: string, argv: string[], reason: string) => {
+    const result = await runStep(step(name, argv, gitRoot));
+    steps.push(result);
+    return result.exitCode === 0 ? null : buildError(reason);
+  };
+  const appendRecoveryStep = async (name: string, argv: string[]) => {
+    const started = Date.now();
+    const result = await runCommand(argv, { cwd: gitRoot, timeoutMs });
+    steps.push({
+      name,
+      command: argv.join(" "),
+      cwd: gitRoot,
+      durationMs: Date.now() - started,
+      exitCode: result.code,
+      stdoutTail: trimLogTail(result.stdout, MAX_LOG_CHARS),
+      stderrTail: trimLogTail(result.stderr, MAX_LOG_CHARS),
+    });
+    return result.code === 0;
+  };
+  const rollback = async () => {
+    if (!beforeSha) {
+      return;
+    }
+    await appendRecoveryStep("git rollback clean", ["git", "-C", gitRoot, "reset", "--hard"]);
+    if (branch && branch !== "HEAD") {
+      const checkedOut = await appendRecoveryStep("git rollback checkout", [
+        "git",
+        "-C",
+        gitRoot,
+        "checkout",
+        "--force",
+        branch,
+      ]);
+      if (checkedOut) {
+        await appendRecoveryStep("git rollback reset", [
+          "git",
+          "-C",
+          gitRoot,
+          "reset",
+          "--hard",
+          beforeSha,
+        ]);
+        if (createdDevBranchDuringUpdate) {
+          await appendRecoveryStep(`git rollback delete ${DEV_BRANCH}`, [
+            "git",
+            "-C",
+            gitRoot,
+            "branch",
+            "-D",
+            DEV_BRANCH,
+          ]);
+        }
+      }
+      return;
+    }
+    await appendRecoveryStep("git rollback checkout", [
+      "git",
+      "-C",
+      gitRoot,
+      "checkout",
+      "--detach",
+      beforeSha,
+    ]);
+    if (createdDevBranchDuringUpdate) {
+      await appendRecoveryStep(`git rollback delete ${DEV_BRANCH}`, [
+        "git",
+        "-C",
+        gitRoot,
+        "branch",
+        "-D",
+        DEV_BRANCH,
+      ]);
+    }
+  };
+  const rollbackError = async (reason: string) => {
+    await rollback();
+    return buildError(reason);
+  };
+
+  const statusCheck = await runStep(
+    step(
+      "clean check",
+      ["git", "-C", gitRoot, "status", "--porcelain", "--", ":!dist/control-ui/"],
+      gitRoot,
+    ),
+  );
+  steps.push(statusCheck);
+  if (statusCheck.stdoutTail?.trim()) {
+    return buildError("dirty", "skipped");
+  }
+
+  if (channel === "dev") {
+    const fetchFailure = await runRequiredStep(
+      "git fetch",
+      ["git", "-C", gitRoot, "fetch", "--all", "--prune", "--no-tags"],
+      "fetch-failed",
+    );
+    if (fetchFailure) {
+      return fetchFailure;
+    }
+    const preflight = await runGitDevPreflight({
+      gitRoot,
+      devTargetRef: opts.devTargetRef,
+      needsCheckoutMain,
+      runCommand,
+      timeoutMs,
+      defaultCommandEnv,
+      steps,
+      step,
+    });
+    if (preflight.status !== "ok") {
+      return buildError(preflight.reason, preflight.status);
+    }
+    await prepareMutation(preflight.selectedSha);
+    if (hasDevTargetRef) {
+      const failure = await runRequiredStep(
+        `git checkout ${preflight.selectedSha}`,
+        ["git", "-C", gitRoot, "checkout", "--detach", preflight.selectedSha],
+        "checkout-failed",
+      );
+      if (failure) {
+        return failure;
+      }
+    } else {
+      let createdAtSelectedSha = false;
+      if (needsCheckoutMain) {
+        const hasLocalMain = preflight.localDevBranchExists !== false;
+        const failure = await runRequiredStep(
+          hasLocalMain
+            ? `git checkout ${DEV_BRANCH}`
+            : `git checkout -B ${DEV_BRANCH} ${preflight.selectedSha}`,
+          hasLocalMain
+            ? ["git", "-C", gitRoot, "checkout", DEV_BRANCH]
+            : ["git", "-C", gitRoot, "checkout", "-B", DEV_BRANCH, preflight.selectedSha],
+          "checkout-failed",
+        );
+        if (failure) {
+          return failure;
+        }
+        createdAtSelectedSha = !hasLocalMain;
+        createdDevBranchDuringUpdate = createdAtSelectedSha;
+        if (createdAtSelectedSha && preflight.selectedDevUpstream) {
+          const upstreamFailure = await runRequiredStep(
+            `git branch --set-upstream-to ${preflight.selectedDevUpstream} ${DEV_BRANCH}`,
+            [
+              "git",
+              "-C",
+              gitRoot,
+              "branch",
+              "--set-upstream-to",
+              preflight.selectedDevUpstream,
+              DEV_BRANCH,
+            ],
+            "checkout-failed",
+          );
+          if (upstreamFailure) {
+            return await rollbackError("checkout-failed");
+          }
+        }
+      }
+      if (createdAtSelectedSha) {
+        steps.push({
+          name: "git rebase",
+          command: `git rebase ${preflight.selectedSha}`,
+          cwd: gitRoot,
+          durationMs: 0,
+          exitCode: 0,
+          stdoutTail: `skipped; ${DEV_BRANCH} was created at selected preflight SHA`,
+        });
+      } else {
+        const rebaseStep = await runStep(
+          step("git rebase", ["git", "-C", gitRoot, "rebase", preflight.selectedSha], gitRoot),
+        );
+        steps.push(rebaseStep);
+        if (rebaseStep.exitCode !== 0) {
+          const abort = await runCommand(["git", "-C", gitRoot, "rebase", "--abort"], {
+            cwd: gitRoot,
+            timeoutMs,
+          });
+          steps.push({
+            name: "git rebase --abort",
+            command: "git rebase --abort",
+            cwd: gitRoot,
+            durationMs: 0,
+            exitCode: abort.code,
+            stdoutTail: trimLogTail(abort.stdout, MAX_LOG_CHARS),
+            stderrTail: trimLogTail(abort.stderr, MAX_LOG_CHARS),
+          });
+          return buildError("rebase-failed");
+        }
+      }
+    }
+  } else {
+    const fetchFailure = await runRequiredStep(
+      "git fetch",
+      ["git", "-C", gitRoot, "fetch", "--all", "--prune", "--tags"],
+      "fetch-failed",
+    );
+    if (fetchFailure) {
+      return fetchFailure;
+    }
+    const tag = await resolveChannelTag(runCommand, gitRoot, timeoutMs, channel);
+    if (!tag) {
+      return buildError("no-release-tag");
+    }
+    await prepareMutation(tag);
+    const failure = await runRequiredStep(
+      `git checkout ${tag}`,
+      ["git", "-C", gitRoot, "checkout", "--detach", tag],
+      "checkout-failed",
+    );
+    if (failure) {
+      return failure;
+    }
+  }
+
+  const manager = await resolveUpdateBuildManager(
+    (argv, options) => runCommand(argv, { timeoutMs: options.timeoutMs, env: options.env }),
+    gitRoot,
+    timeoutMs,
+    defaultCommandEnv,
+    "require-preferred",
+  );
+  if (manager.kind === "missing-required") {
+    return await rollbackError(mapManagerResolutionFailure(manager.reason));
+  }
+  try {
+    const installEnv = resolveInstallEnv(manager.manager, manager.env);
+    let installStep = await runStep(
+      step(
+        "deps install",
+        managerInstallArgs(manager.manager, {
+          compatFallback: manager.fallback && manager.manager === "npm",
+        }),
+        gitRoot,
+        installEnv,
+      ),
+    );
+    steps.push(installStep);
+    if (installStep.exitCode !== 0 && shouldRetryWindowsInstallIgnoringScripts(manager.manager)) {
+      const retryArgv = resolveRetryInstallArgs(manager.manager);
+      if (retryArgv) {
+        installStep = await runStep(
+          step("deps install (ignore scripts)", retryArgv, gitRoot, installEnv),
+        );
+        steps.push(installStep);
+      }
+    }
+    if (installStep.exitCode !== 0) {
+      return await rollbackError("deps-install-failed");
+    }
+    const buildStep = await runStep(
+      step(
+        "build",
+        managerScriptArgs(manager.manager, "build"),
+        gitRoot,
+        resolveBuildEnv(manager.env),
+      ),
+    );
+    steps.push(buildStep);
+    if (buildStep.exitCode !== 0) {
+      return await rollbackError("build-failed");
+    }
+    const uiBuildStep = await runStep(
+      step("ui:build", managerScriptArgs(manager.manager, "ui:build"), gitRoot, manager.env),
+    );
+    steps.push(uiBuildStep);
+    if (uiBuildStep.exitCode !== 0) {
+      return await rollbackError("ui-build-failed");
+    }
+
+    const doctorEntry = path.join(gitRoot, "openclaw.mjs");
+    const doctorEntryExists = await fs.stat(doctorEntry).then(
+      () => true,
+      () => false,
+    );
+    if (!doctorEntryExists) {
+      steps.push({
+        name: "openclaw doctor entry",
+        command: `verify ${doctorEntry}`,
+        cwd: gitRoot,
+        durationMs: 0,
+        exitCode: 1,
+        stderrTail: `missing ${doctorEntry}`,
+      });
+      return await rollbackError("doctor-entry-missing");
+    }
+    const doctorNodePath = await resolveStableNodePath(process.execPath);
+    const doctorTargetVersion = await readPackageVersion(gitRoot);
+    const doctorPolicy = resolveUpdateDoctorExecutionPolicy({
+      targetVersion: doctorTargetVersion,
+      allowGatewayServiceRepair,
+    });
+    const doctorStep = await runStep(
+      step(
+        "openclaw doctor",
+        [
+          doctorNodePath,
+          doctorEntry,
+          "doctor",
+          "--non-interactive",
+          ...(doctorPolicy.fix ? ["--fix"] : []),
+        ],
+        gitRoot,
+        buildUpdateDoctorEnv({
+          allowGatewayServiceRepair,
+          allowGatewayActivation,
+          serviceRepairPolicy: doctorPolicy.serviceRepairPolicy,
+          deferConfiguredPluginInstallRepair: opts.deferConfiguredPluginInstallRepair,
+        }),
+      ),
+    );
+    steps.push(doctorStep);
+    if (doctorStep.exitCode !== 0) {
+      return await rollbackError("doctor-failed");
+    }
+
+    const uiIndexHealth = await resolveControlUiDistIndexHealth({ root: gitRoot });
+    if (!uiIndexHealth.exists) {
+      const repairArgv = managerScriptArgs(manager.manager, "ui:build");
+      const repairStarted = Date.now();
+      const repairResult = await runCommand(repairArgv, {
+        cwd: gitRoot,
+        timeoutMs,
+        env: manager.env,
+      });
+      steps.push({
+        name: "ui:build (post-doctor repair)",
+        command: repairArgv.join(" "),
+        cwd: gitRoot,
+        durationMs: Date.now() - repairStarted,
+        exitCode: repairResult.code,
+        stdoutTail: trimLogTail(repairResult.stdout, MAX_LOG_CHARS),
+        stderrTail: trimLogTail(repairResult.stderr, MAX_LOG_CHARS),
+      });
+      if (repairResult.code !== 0) {
+        return await rollbackError("ui-build-failed");
+      }
+      const repairedHealth = await resolveControlUiDistIndexHealth({ root: gitRoot });
+      if (!repairedHealth.exists) {
+        const uiIndexPath =
+          repairedHealth.indexPath ?? resolveControlUiDistIndexPathForRoot(gitRoot);
+        steps.push({
+          name: "ui assets verify",
+          command: `verify ${uiIndexPath}`,
+          cwd: gitRoot,
+          durationMs: 0,
+          exitCode: 1,
+          stderrTail: `missing ${uiIndexPath}`,
+        });
+        return await rollbackError("ui-assets-missing");
+      }
+    }
+
+    const failedStep = findBlockingGitFailure(steps);
+    const afterShaStep = await runStep(
+      step("git rev-parse HEAD (after)", ["git", "-C", gitRoot, "rev-parse", "HEAD"], gitRoot),
+    );
+    steps.push(afterShaStep);
+    return {
+      status: failedStep ? "error" : "ok",
+      mode: "git",
+      root: gitRoot,
+      reason: failedStep ? normalizeFallbackFailureReason(failedStep.name) : undefined,
+      before: { sha: beforeSha, version: beforeVersion },
+      after: {
+        sha: afterShaStep.stdoutTail?.trim() ?? null,
+        version: await readPackageVersion(gitRoot),
+      },
+      steps,
+      durationMs: Date.now() - startedAt,
+    };
+  } finally {
+    await manager.cleanup?.();
+  }
+}
diff --git a/src/infra/update-runner-global.ts b/src/infra/update-runner-global.ts
new file mode 100644
index 00000000000..ec32d580f35
--- /dev/null
+++ b/src/infra/update-runner-global.ts
@@ -0,0 +1,170 @@
+import path from "node:path";
+import { resolveGatewayInstallEntrypoint } from "../daemon/gateway-entrypoint.js";
+import { readPackageName, readPackageVersion } from "./package-json.js";
+import { normalizePackageTagInput } from "./package-tag.js";
+import { runGlobalPackageUpdateSteps } from "./package-update-steps.js";
+import { resolveStableNodePath } from "./stable-node-path.js";
+import {
+  channelToNpmTag,
+  DEFAULT_PACKAGE_CHANNEL,
+  EXTENDED_STABLE_TAG_UNSUPPORTED_REASON,
+} from "./update-channels.js";
+import { resolveExtendedStablePackage } from "./update-check.js";
+import {
+  cleanupGlobalRenameDirs,
+  createGlobalInstallEnv,
+  resolveGlobalInstallSpec,
+  resolveGlobalInstallTarget,
+  type GlobalInstallManager,
+} from "./update-global.js";
+import { normalizeFallbackFailureReason, runStep } from "./update-runner-command.js";
+import {
+  buildUpdateDoctorEnv,
+  resolveUpdateDoctorExecutionPolicy,
+} from "./update-runner-doctor.js";
+import type { CommandRunner, UpdateRunResult, UpdateRunnerOptions } from "./update-runner-types.js";
+
+const DEFAULT_PACKAGE_NAME = "openclaw";
+
+function normalizeTag(tag?: string) {
+  return normalizePackageTagInput(tag, ["openclaw", DEFAULT_PACKAGE_NAME]) ?? "latest";
+}
+
+export async function runGlobalUpdate(params: {
+  opts: UpdateRunnerOptions;
+  pkgRoot: string;
+  globalManager: GlobalInstallManager;
+  runCommand: CommandRunner;
+  timeoutMs: number;
+  startedAt: number;
+  beforeVersion: string | null;
+  allowGatewayServiceRepair: boolean;
+  allowGatewayActivation: boolean;
+}): Promise<UpdateRunResult> {
+  const {
+    opts,
+    pkgRoot,
+    globalManager,
+    runCommand,
+    timeoutMs,
+    startedAt,
+    beforeVersion,
+    allowGatewayServiceRepair,
+    allowGatewayActivation,
+  } = params;
+  const channel = opts.channel ?? DEFAULT_PACKAGE_CHANNEL;
+  if (channel === "extended-stable" && opts.tag !== undefined) {
+    return {
+      status: "error",
+      mode: globalManager,
+      root: pkgRoot,
+      reason: EXTENDED_STABLE_TAG_UNSUPPORTED_REASON,
+      before: { version: beforeVersion },
+      steps: [],
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  const packageName = (await readPackageName(pkgRoot)) ?? DEFAULT_PACKAGE_NAME;
+  const installTarget = await resolveGlobalInstallTarget({
+    manager: globalManager,
+    runCommand,
+    timeoutMs,
+    pkgRoot,
+    packageName,
+  });
+  await cleanupGlobalRenameDirs({ globalRoot: path.dirname(pkgRoot), packageName });
+  const extendedStable =
+    channel === "extended-stable"
+      ? await resolveExtendedStablePackage({ installKind: "package", timeoutMs, packageName })
+      : null;
+  if (extendedStable?.status === "failed") {
+    return {
+      status: "error",
+      mode: globalManager,
+      root: pkgRoot,
+      reason: extendedStable.reason,
+      before: { version: beforeVersion },
+      steps: [],
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  const tag = normalizeTag(
+    extendedStable?.status === "resolved"
+      ? extendedStable.version
+      : (opts.tag ?? channelToNpmTag(channel)),
+  );
+  const globalInstallEnv = await createGlobalInstallEnv();
+  const spec =
+    extendedStable?.status === "resolved"
+      ? extendedStable.packageSpec
+      : resolveGlobalInstallSpec({ packageName, tag, env: globalInstallEnv });
+
+  const packageUpdate = await runGlobalPackageUpdateSteps({
+    installTarget,
+    installSpec: spec,
+    packageName,
+    packageRoot: pkgRoot,
+    runCommand,
+    timeoutMs,
+    ...(globalInstallEnv === undefined ? {} : { env: globalInstallEnv }),
+    installCwd: pkgRoot,
+    runStep: (stepParams) =>
+      runStep({
+        runCommand,
+        ...stepParams,
+        cwd: stepParams.cwd ?? pkgRoot,
+        progress: opts.progress,
+        stepIndex: 0,
+        totalSteps: 1,
+      }),
+    postVerifyStep: async (verifiedPackageRoot) => {
+      const doctorEntry = await resolveGatewayInstallEntrypoint(verifiedPackageRoot);
+      if (!doctorEntry) {
+        return null;
+      }
+      const doctorNodePath = await resolveStableNodePath(process.execPath);
+      const candidateHostVersion = await readPackageVersion(verifiedPackageRoot);
+      const doctorPolicy = resolveUpdateDoctorExecutionPolicy({
+        targetVersion: candidateHostVersion,
+        allowGatewayServiceRepair,
+      });
+      return await runStep({
+        runCommand,
+        name: "openclaw doctor",
+        argv: [
+          doctorNodePath,
+          doctorEntry,
+          "doctor",
+          "--non-interactive",
+          ...(doctorPolicy.fix ? ["--fix"] : []),
+        ],
+        cwd: verifiedPackageRoot,
+        timeoutMs,
+        env: buildUpdateDoctorEnv({
+          allowGatewayServiceRepair,
+          allowGatewayActivation,
+          serviceRepairPolicy: doctorPolicy.serviceRepairPolicy,
+          compatibilityHostVersion: candidateHostVersion,
+        }),
+        progress: opts.progress,
+        stepIndex: 0,
+        totalSteps: 1,
+      });
+    },
+  });
+
+  return {
+    status: packageUpdate.failedStep ? "error" : "ok",
+    mode: globalManager,
+    root: packageUpdate.verifiedPackageRoot ?? pkgRoot,
+    reason: packageUpdate.failedStep
+      ? normalizeFallbackFailureReason(packageUpdate.failedStep.name)
+      : undefined,
+    before: { version: beforeVersion },
+    after: { version: packageUpdate.afterVersion },
+    steps: packageUpdate.steps,
+    durationMs: Date.now() - startedAt,
+  };
+}
diff --git a/src/infra/update-runner-install-surface.ts b/src/infra/update-runner-install-surface.ts
new file mode 100644
index 00000000000..83112e30ca7
--- /dev/null
+++ b/src/infra/update-runner-install-surface.ts
@@ -0,0 +1,151 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
+import { detectGlobalInstallManagerForRoot } from "./update-global.js";
+import { buildUpdateCommandRunner, DEFAULT_TIMEOUT_MS } from "./update-runner-command.js";
+import type {
+  CommandRunner,
+  UpdateInstallSurface,
+  UpdateRunnerOptions,
+} from "./update-runner-types.js";
+
+const DEFAULT_PACKAGE_NAME = "openclaw";
+const CORE_PACKAGE_NAMES = new Set([DEFAULT_PACKAGE_NAME]);
+
+export function normalizeDir(value?: string | null) {
+  if (!value) {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed ? path.resolve(trimmed) : null;
+}
+
+function resolveNodeModulesBinPackageRoot(argv1: string): string | null {
+  const normalized = path.resolve(argv1);
+  const parts = normalized.split(path.sep);
+  const binIndex = parts.lastIndexOf(".bin");
+  if (binIndex <= 0 || parts[binIndex - 1] !== "node_modules") {
+    return null;
+  }
+  const binName = path.basename(normalized);
+  const nodeModulesDir = parts.slice(0, binIndex).join(path.sep);
+  return path.join(nodeModulesDir, binName);
+}
+
+export function buildStartDirs(opts: UpdateRunnerOptions): string[] {
+  const dirs: string[] = [];
+  const argv1 = normalizeDir(opts.argv1);
+  if (argv1) {
+    // The lexical shim identifies its owner; pnpm store realpaths often do not.
+    dirs.push(path.dirname(argv1));
+    const packageRoot = resolveNodeModulesBinPackageRoot(argv1);
+    if (packageRoot) {
+      dirs.push(packageRoot);
+    }
+  }
+  const cwd = normalizeDir(opts.cwd);
+  if (cwd) {
+    dirs.push(cwd);
+  }
+  let processCwd: string | null;
+  try {
+    processCwd = normalizeDir(process.cwd());
+  } catch {
+    processCwd = null;
+  }
+  if (processCwd) {
+    dirs.push(processCwd);
+  }
+  return uniqueStrings(dirs);
+}
+
+export async function resolveGitRoot(
+  runCommand: CommandRunner,
+  candidates: string[],
+  timeoutMs: number,
+): Promise<string | null> {
+  for (const dir of candidates) {
+    const result = await runCommand(["git", "-C", dir, "rev-parse", "--show-toplevel"], {
+      timeoutMs,
+    }).catch(() => null);
+    const root = result?.code === 0 ? result.stdout.trim() : "";
+    if (root) {
+      return root;
+    }
+  }
+  return null;
+}
+
+export async function findPackageRoot(candidates: string[]) {
+  for (const dir of candidates) {
+    let current = dir;
+    for (let index = 0; index < 12; index += 1) {
+      try {
+        const raw = await fs.readFile(path.join(current, "package.json"), "utf-8");
+        const name = (JSON.parse(raw) as { name?: string }).name?.trim();
+        if (name && CORE_PACKAGE_NAMES.has(name)) {
+          return current;
+        }
+      } catch {
+        // Continue walking toward the filesystem root.
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+
+export async function resolveComparablePath(target: string): Promise<string> {
+  return await fs.realpath(target).catch(() => path.resolve(target));
+}
+
+export async function pathsReferToSameLocation(left: string, right: string): Promise<boolean> {
+  return (await resolveComparablePath(left)) === (await resolveComparablePath(right));
+}
+
+export async function looksLikeGitCheckout(root: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(root, ".git"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveUpdateInstallSurface(
+  opts: Pick<UpdateRunnerOptions, "cwd" | "argv1" | "timeoutMs" | "runCommand"> = {},
+): Promise<UpdateInstallSurface> {
+  const { runCommand } = await buildUpdateCommandRunner(opts.runCommand);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const candidates = buildStartDirs(opts);
+  const packageRoot = await findPackageRoot(candidates);
+
+  let gitRoot = await resolveGitRoot(runCommand, candidates, timeoutMs);
+  if (gitRoot && packageRoot && path.resolve(gitRoot) !== path.resolve(packageRoot)) {
+    gitRoot = null;
+  }
+  if (gitRoot && !packageRoot) {
+    return { kind: "missing", mode: "unknown", root: gitRoot };
+  }
+  if (gitRoot && packageRoot && path.resolve(gitRoot) === path.resolve(packageRoot)) {
+    return { kind: "git", mode: "git", root: gitRoot, packageRoot };
+  }
+  if (!packageRoot) {
+    return { kind: "missing", mode: "unknown" };
+  }
+
+  const globalManager = await detectGlobalInstallManagerForRoot(runCommand, packageRoot, timeoutMs);
+  if (globalManager) {
+    return {
+      kind: "global",
+      mode: globalManager,
+      root: packageRoot,
+      packageRoot,
+    };
+  }
+  return { kind: "package-root", mode: "unknown", root: packageRoot, packageRoot };
+}
diff --git a/src/infra/update-runner-types.ts b/src/infra/update-runner-types.ts
new file mode 100644
index 00000000000..78fe9632e97
--- /dev/null
+++ b/src/infra/update-runner-types.ts
@@ -0,0 +1,152 @@
+import type { CommandOptions } from "../process/exec.js";
+import type { OpenClawSchemaVersions } from "../state/openclaw-schema-versions.js";
+import type { PackageUpdateStepAdvisory } from "./package-update-steps.js";
+import type { UpdateChannel } from "./update-channels.js";
+import type { GlobalInstallManager } from "./update-global.js";
+
+export type UpdateStepAdvisory = PackageUpdateStepAdvisory;
+
+export type UpdateStepResult = {
+  name: string;
+  command: string;
+  cwd: string;
+  durationMs: number;
+  exitCode: number | null;
+  stdoutTail?: string | null;
+  stderrTail?: string | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
+  advisory?: UpdateStepAdvisory;
+};
+
+export type UpdateRunResult = {
+  status: "ok" | "error" | "skipped";
+  mode: "git" | "pnpm" | "bun" | "npm" | "unknown";
+  root?: string;
+  reason?: string;
+  before?: { sha?: string | null; version?: string | null };
+  after?: { sha?: string | null; version?: string | null };
+  steps: UpdateStepResult[];
+  durationMs: number;
+  postUpdate?: {
+    plugins?: {
+      status: "ok" | "warning" | "skipped" | "error";
+      reason?: string;
+      changed: boolean;
+      warnings?: Array<{
+        pluginId?: string;
+        reason: string;
+        message: string;
+        guidance: string[];
+      }>;
+      sync: {
+        changed: boolean;
+        switchedToBundled: string[];
+        switchedToNpm: string[];
+        warnings: string[];
+        errors: string[];
+      };
+      npm: {
+        changed: boolean;
+        outcomes: Array<{
+          pluginId: string;
+          status: "updated" | "unchanged" | "skipped" | "error";
+          message: string;
+          currentVersion?: string;
+          nextVersion?: string;
+          channelFallback?: {
+            requestedSpec: string;
+            usedSpec: string;
+            requestedLabel: string;
+            usedLabel: string;
+            reason: "unavailable" | "failed";
+            message: string;
+          };
+        }>;
+      };
+      integrityDrifts: Array<{
+        pluginId: string;
+        spec: string;
+        expectedIntegrity: string;
+        actualIntegrity: string;
+        resolvedSpec?: string;
+        resolvedVersion?: string;
+        action: "aborted";
+      }>;
+    };
+  };
+};
+
+export type CommandRunner = (
+  argv: string[],
+  options: CommandOptions,
+) => Promise<{
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
+}>;
+
+export type UpdateStepInfo = {
+  name: string;
+  command: string;
+  index: number;
+  total: number;
+};
+
+type UpdateStepCompletion = UpdateStepInfo & {
+  durationMs: number;
+  exitCode: number | null;
+  stderrTail?: string | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
+  advisory?: UpdateStepAdvisory;
+};
+
+export type UpdateStepProgress = {
+  onStepStart?: (step: UpdateStepInfo) => void;
+  onStepComplete?: (step: UpdateStepCompletion) => void;
+};
+
+export type UpdateRunnerOptions = {
+  cwd?: string;
+  argv1?: string;
+  tag?: string;
+  channel?: UpdateChannel;
+  devTargetRef?: string;
+  deferConfiguredPluginInstallRepair?: boolean;
+  allowGatewayServiceRepair?: boolean;
+  allowGatewayActivation?: boolean;
+  beforeGitMutation?: (target: {
+    schemaVersions?: OpenClawSchemaVersions;
+    metadataUnreadable?: string;
+  }) => Promise<{
+    allowGatewayServiceRepair?: boolean;
+    allowGatewayActivation?: boolean;
+  } | void>;
+  timeoutMs?: number;
+  runCommand?: CommandRunner;
+  progress?: UpdateStepProgress;
+};
+
+export type UpdateInstallSurface =
+  | { kind: "git"; mode: "git"; root: string; packageRoot: string }
+  | { kind: "global"; mode: GlobalInstallManager; root: string; packageRoot: string }
+  | { kind: "package-root"; mode: "unknown"; root: string; packageRoot: string }
+  | { kind: "missing"; mode: "unknown"; root?: string; packageRoot?: undefined };
+
+export type RunStepOptions = {
+  runCommand: CommandRunner;
+  name: string;
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  env?: NodeJS.ProcessEnv;
+  progress?: UpdateStepProgress;
+  stepIndex: number;
+  totalSteps: number;
+};
diff --git a/src/infra/update-runner.ts b/src/infra/update-runner.ts
index bc8e02bcb5b..6f59b34f294 100644
--- a/src/infra/update-runner.ts
+++ b/src/infra/update-runner.ts
@@ -1,889 +1,36 @@
+import { readPackageVersion } from "./package-json.js";
 // Runs OpenClaw package update checks, package steps, and restart handoff.
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
+import { detectGlobalInstallManagerForRoot } from "./update-global.js";
+import { buildUpdateCommandRunner, DEFAULT_TIMEOUT_MS } from "./update-runner-command.js";
+import { resolveUpdateDoctorExecutionPolicy } from "./update-runner-doctor.js";
+import { runGitUpdate } from "./update-runner-git.js";
+import { runGlobalUpdate } from "./update-runner-global.js";
 import {
-  normalizeStringEntries,
-  uniqueStrings,
-} from "@openclaw/normalization-core/string-normalization";
-import { resolveGatewayInstallEntrypoint } from "../daemon/gateway-entrypoint.js";
-import { type CommandOptions, runCommandWithTimeout } from "../process/exec.js";
-import {
-  parsePackageOpenClawSchemaVersions,
-  type OpenClawSchemaVersions,
-} from "../state/openclaw-schema-versions.js";
-import {
-  resolveControlUiDistIndexHealth,
-  resolveControlUiDistIndexPathForRoot,
-} from "./control-ui-assets.js";
-import { readPackageName, readPackageVersion } from "./package-json.js";
-import { normalizePackageTagInput } from "./package-tag.js";
-import {
-  runGlobalPackageUpdateSteps,
-  type PackageUpdateStepAdvisory,
-} from "./package-update-steps.js";
-import { trimLogTail } from "./restart-sentinel.js";
-import { resolveStableNodePath } from "./stable-node-path.js";
-import {
-  channelToNpmTag,
-  DEFAULT_PACKAGE_CHANNEL,
-  DEV_BRANCH,
-  EXTENDED_STABLE_TAG_UNSUPPORTED_REASON,
-  isBetaTag,
-  isStableTag,
-  type UpdateChannel,
-} from "./update-channels.js";
-import { compareSemverStrings, resolveExtendedStablePackage } from "./update-check.js";
-import {
-  cleanupGlobalRenameDirs,
-  createGlobalInstallEnv,
-  detectGlobalInstallManagerForRoot,
-  resolveGlobalInstallTarget,
-  resolveGlobalInstallSpec,
-  type GlobalInstallManager,
-} from "./update-global.js";
-import {
-  managerInstallIgnoreScriptsArgs,
-  managerInstallArgs,
-  managerScriptArgs,
-  resolveUpdateBuildManager,
-  type UpdatePackageManagerFailureReason,
-} from "./update-package-manager.js";
-
-export type UpdateStepAdvisory = PackageUpdateStepAdvisory;
-
-export type UpdateStepResult = {
-  name: string;
-  command: string;
-  cwd: string;
-  durationMs: number;
-  exitCode: number | null;
-  stdoutTail?: string | null;
-  stderrTail?: string | null;
-  signal?: NodeJS.Signals | null;
-  killed?: boolean;
-  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
-  advisory?: UpdateStepAdvisory;
-};
-
-export type UpdateRunResult = {
-  status: "ok" | "error" | "skipped";
-  mode: "git" | "pnpm" | "bun" | "npm" | "unknown";
-  root?: string;
-  reason?: string;
-  before?: { sha?: string | null; version?: string | null };
-  after?: { sha?: string | null; version?: string | null };
-  steps: UpdateStepResult[];
-  durationMs: number;
-  postUpdate?: {
-    plugins?: {
-      status: "ok" | "warning" | "skipped" | "error";
-      reason?: string;
-      changed: boolean;
-      warnings?: Array<{
-        pluginId?: string;
-        reason: string;
-        message: string;
-        guidance: string[];
-      }>;
-      sync: {
-        changed: boolean;
-        switchedToBundled: string[];
-        switchedToNpm: string[];
-        warnings: string[];
-        errors: string[];
-      };
-      npm: {
-        changed: boolean;
-        outcomes: Array<{
-          pluginId: string;
-          status: "updated" | "unchanged" | "skipped" | "error";
-          message: string;
-          currentVersion?: string;
-          nextVersion?: string;
-          channelFallback?: {
-            requestedSpec: string;
-            usedSpec: string;
-            requestedLabel: string;
-            usedLabel: string;
-            reason: "unavailable" | "failed";
-            message: string;
-          };
-        }>;
-      };
-      integrityDrifts: Array<{
-        pluginId: string;
-        spec: string;
-        expectedIntegrity: string;
-        actualIntegrity: string;
-        resolvedSpec?: string;
-        resolvedVersion?: string;
-        action: "aborted";
-      }>;
-    };
-  };
-};
-
-type CommandRunner = (
-  argv: string[],
-  options: CommandOptions,
-) => Promise<{
-  stdout: string;
-  stderr: string;
-  code: number | null;
-  signal?: NodeJS.Signals | null;
-  killed?: boolean;
-  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
-}>;
-
-export type UpdateStepInfo = {
-  name: string;
-  command: string;
-  index: number;
-  total: number;
-};
-
-type UpdateStepCompletion = UpdateStepInfo & {
-  durationMs: number;
-  exitCode: number | null;
-  stderrTail?: string | null;
-  signal?: NodeJS.Signals | null;
-  killed?: boolean;
-  termination?: "exit" | "timeout" | "no-output-timeout" | "signal";
-  advisory?: UpdateStepAdvisory;
-};
-
-export type UpdateStepProgress = {
-  onStepStart?: (step: UpdateStepInfo) => void;
-  onStepComplete?: (step: UpdateStepCompletion) => void;
-};
-
-type UpdateRunnerOptions = {
-  cwd?: string;
-  argv1?: string;
-  tag?: string;
-  channel?: UpdateChannel;
-  devTargetRef?: string;
-  deferConfiguredPluginInstallRepair?: boolean;
-  allowGatewayServiceRepair?: boolean;
-  allowGatewayActivation?: boolean;
-  beforeGitMutation?: (target: {
-    schemaVersions?: OpenClawSchemaVersions;
-    metadataUnreadable?: string;
-  }) => Promise<{
-    allowGatewayServiceRepair?: boolean;
-    allowGatewayActivation?: boolean;
-  } | void>;
-  timeoutMs?: number;
-  runCommand?: CommandRunner;
-  progress?: UpdateStepProgress;
-};
-
-type UpdateInstallSurface =
-  | {
-      kind: "git";
-      mode: "git";
-      root: string;
-      packageRoot: string;
-    }
-  | {
-      kind: "global";
-      mode: GlobalInstallManager;
-      root: string;
-      packageRoot: string;
-    }
-  | {
-      kind: "package-root";
-      mode: "unknown";
-      root: string;
-      packageRoot: string;
-    }
-  | {
-      kind: "missing";
-      mode: "unknown";
-      root?: string;
-      packageRoot?: undefined;
-    };
-
-// Only a target we actually read may skip the schema guard as legacy; a failed
-// read must abort before mutation or the guard is silently bypassed.
-type GitTargetSchemaMetadata =
-  | { status: "ok"; schemaVersions?: OpenClawSchemaVersions }
-  | { status: "unreadable"; reason: string };
-
-async function readGitTargetSchemaVersions(params: {
-  runCommand: CommandRunner;
-  root: string;
-  revision: string;
-  timeoutMs: number;
-}): Promise<GitTargetSchemaMetadata> {
-  let result: Awaited<ReturnType<CommandRunner>>;
-  try {
-    result = await params.runCommand(
-      ["git", "-C", params.root, "show", `${params.revision}:package.json`],
-      { cwd: params.root, timeoutMs: params.timeoutMs },
-    );
-  } catch (error) {
-    return { status: "unreadable", reason: String(error) };
-  }
-  if (result.code !== 0) {
-    return {
-      status: "unreadable",
-      reason: `git show ${params.revision}:package.json exited ${result.code}`,
-    };
-  }
-  try {
-    const schemaVersions = parsePackageOpenClawSchemaVersions(JSON.parse(result.stdout) as unknown);
-    return { status: "ok", ...(schemaVersions ? { schemaVersions } : {}) };
-  } catch (error) {
-    return { status: "unreadable", reason: `target package.json unparseable: ${String(error)}` };
-  }
-}
-
-function mapManagerResolutionFailure(
-  reason: UpdatePackageManagerFailureReason,
-): NonNullable<UpdateRunResult["reason"]> {
-  return reason;
-}
-
-const DEFAULT_TIMEOUT_MS = 20 * 60_000;
-const MAX_LOG_CHARS = 8000;
-const PREFLIGHT_MAX_COMMITS = 10;
-const DEFAULT_PACKAGE_NAME = "openclaw";
-const CORE_PACKAGE_NAMES = new Set([DEFAULT_PACKAGE_NAME]);
-const UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV =
-  "OPENCLAW_UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR";
-const UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV =
-  "OPENCLAW_UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE";
-const UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART_ENV =
-  "OPENCLAW_UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART";
-const UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR_ENV =
-  "OPENCLAW_UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR";
-const UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION_ENV =
-  "OPENCLAW_UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION";
-const UPDATE_DOCTOR_SERVICE_REPAIR_POLICY_ENV = "OPENCLAW_SERVICE_REPAIR_POLICY";
-const EXTERNAL_SERVICE_REPAIR_POLICY_MIN_VERSION = "2026.4.25-beta.1";
-const PREFLIGHT_TEMP_PREFIX =
-  process.platform === "win32" ? "ocu-pf-" : "openclaw-update-preflight-";
-const PREFLIGHT_WORKTREE_DIRNAME = process.platform === "win32" ? "wt" : "worktree";
-const PREFLIGHT_CLEANUP_TIMEOUT_MS = 60_000;
-const WINDOWS_PREFLIGHT_BASE_DIR = "ocu";
-const BUILD_MAX_OLD_SPACE_MB = 8192;
-const DEV_PREFLIGHT_LINT_ENV: NodeJS.ProcessEnv = {
-  OPENCLAW_LOCAL_CHECK: "1",
-  OPENCLAW_LOCAL_CHECK_MODE: "throttled",
-  OPENCLAW_OXLINT_SHARDS_SERIAL: "1",
-};
-const DEV_PREFLIGHT_LINT_OPT_IN_ENV = "OPENCLAW_UPDATE_PREFLIGHT_LINT";
-
-export function resolveUpdateDoctorExecutionPolicy(params: {
-  targetVersion: string | null;
-  allowGatewayServiceRepair: boolean;
-}): { fix: boolean; serviceRepairPolicy?: "external" } {
-  if (params.allowGatewayServiceRepair) {
-    return { fix: true };
-  }
-  const externalPolicySupport = compareSemverStrings(
-    params.targetVersion,
-    EXTERNAL_SERVICE_REPAIR_POLICY_MIN_VERSION,
-  );
-  if (externalPolicySupport !== null && externalPolicySupport >= 0) {
-    return { fix: true, serviceRepairPolicy: "external" };
-  }
-  // Older targets ignore both ownership markers and the external-service policy.
-  return { fix: false };
-}
-
-function normalizeDir(value?: string | null) {
-  if (!value) {
-    return null;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return path.resolve(trimmed);
-}
-
-function resolveNodeModulesBinPackageRoot(argv1: string): string | null {
-  const normalized = path.resolve(argv1);
-  const parts = normalized.split(path.sep);
-  const binIndex = parts.lastIndexOf(".bin");
-  if (binIndex <= 0) {
-    return null;
-  }
-  if (parts[binIndex - 1] !== "node_modules") {
-    return null;
-  }
-  const binName = path.basename(normalized);
-  const nodeModulesDir = parts.slice(0, binIndex).join(path.sep);
-  return path.join(nodeModulesDir, binName);
-}
-
-function buildStartDirs(opts: UpdateRunnerOptions): string[] {
-  const dirs: string[] = [];
-  const argv1 = normalizeDir(opts.argv1);
-  if (argv1) {
-    // Keep the lexical shim path ahead of a module-derived cwd. pnpm 11 module
-    // realpaths can point into a shared store that does not identify the owner.
-    dirs.push(path.dirname(argv1));
-    const packageRoot = resolveNodeModulesBinPackageRoot(argv1);
-    if (packageRoot) {
-      dirs.push(packageRoot);
-    }
-  }
-  const cwd = normalizeDir(opts.cwd);
-  if (cwd) {
-    dirs.push(cwd);
-  }
-  let proc: string | null;
-  try {
-    proc = normalizeDir(process.cwd());
-  } catch {
-    proc = null;
-  }
-  if (proc) {
-    dirs.push(proc);
-  }
-  return uniqueStrings(dirs);
-}
-
-function resolvePreflightTempRootPrefix() {
-  return path.join(os.tmpdir(), PREFLIGHT_TEMP_PREFIX);
-}
-
-function resolvePreflightWorktreeDir(preflightRoot: string) {
-  return path.join(preflightRoot, PREFLIGHT_WORKTREE_DIRNAME);
-}
-
-function shouldUseNativeWindowsTempRoot() {
-  return process.platform === "win32" && path.sep === "\\";
-}
-
-async function createPreflightRoot() {
-  if (shouldUseNativeWindowsTempRoot()) {
-    const baseDir = path.win32.join(process.env.SystemDrive ?? "C:", WINDOWS_PREFLIGHT_BASE_DIR);
-    await fs.mkdir(baseDir, { recursive: true });
-    return fs.mkdtemp(path.win32.join(baseDir, PREFLIGHT_TEMP_PREFIX));
-  }
-  return fs.mkdtemp(resolvePreflightTempRootPrefix());
-}
-
-async function removePathRecursive(target: string) {
-  await fs
-    .rm(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 })
-    .catch(() => {});
-}
-
-async function repairPreflightCleanup(worktreeDir: string, preflightRoot: string) {
-  try {
-    await fs.rm(worktreeDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
-    await fs.rm(preflightRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function readBranchName(
-  runCommand: CommandRunner,
-  root: string,
-  timeoutMs: number,
-): Promise<string | null> {
-  const res = await runCommand(["git", "-C", root, "rev-parse", "--abbrev-ref", "HEAD"], {
-    timeoutMs,
-  }).catch(() => null);
-  if (!res || res.code !== 0) {
-    return null;
-  }
-  const branch = res.stdout.trim();
-  return branch || null;
-}
-
-async function listGitTags(
-  runCommand: CommandRunner,
-  root: string,
-  timeoutMs: number,
-  pattern = "v*",
-): Promise<string[]> {
-  const res = await runCommand(["git", "-C", root, "tag", "--list", pattern, "--sort=-v:refname"], {
-    timeoutMs,
-  }).catch(() => null);
-  if (!res || res.code !== 0) {
-    return [];
-  }
-  return normalizeStringEntries(res.stdout.split("\n"));
-}
-
-async function resolveChannelTag(
-  runCommand: CommandRunner,
-  root: string,
-  timeoutMs: number,
-  channel: Exclude<UpdateChannel, "dev">,
-): Promise<string | null> {
-  const tags = await listGitTags(runCommand, root, timeoutMs);
-  if (channel === "beta") {
-    const betaTag = tags.find((tag) => isBetaTag(tag)) ?? null;
-    const stableTag = tags.find((tag) => isStableTag(tag)) ?? null;
-    if (!betaTag) {
-      return stableTag;
-    }
-    if (!stableTag) {
-      return betaTag;
-    }
-    const cmp = compareSemverStrings(betaTag, stableTag);
-    if (cmp != null && cmp < 0) {
-      return stableTag;
-    }
-    return betaTag;
-  }
-  return tags.find((tag) => isStableTag(tag)) ?? null;
-}
-
-async function resolveGitRoot(
-  runCommand: CommandRunner,
-  candidates: string[],
-  timeoutMs: number,
-): Promise<string | null> {
-  for (const dir of candidates) {
-    const res = await runCommand(["git", "-C", dir, "rev-parse", "--show-toplevel"], {
-      timeoutMs,
-    }).catch(() => null);
-    if (!res) {
-      continue;
-    }
-    if (res.code === 0) {
-      const root = res.stdout.trim();
-      if (root) {
-        return root;
-      }
-    }
-  }
-  return null;
-}
-
-async function findPackageRoot(candidates: string[]) {
-  for (const dir of candidates) {
-    let current = dir;
-    for (let i = 0; i < 12; i += 1) {
-      const pkgPath = path.join(current, "package.json");
-      try {
-        const raw = await fs.readFile(pkgPath, "utf-8");
-        const parsed = JSON.parse(raw) as { name?: string };
-        const name = parsed?.name?.trim();
-        if (name && CORE_PACKAGE_NAMES.has(name)) {
-          return current;
-        }
-      } catch {
-        // ignore
-      }
-      const parent = path.dirname(current);
-      if (parent === current) {
-        break;
-      }
-      current = parent;
-    }
-  }
-  return null;
-}
-
-type RunStepOptions = {
-  runCommand: CommandRunner;
-  name: string;
-  argv: string[];
-  cwd: string;
-  timeoutMs: number;
-  env?: NodeJS.ProcessEnv;
-  progress?: UpdateStepProgress;
-  stepIndex: number;
-  totalSteps: number;
-};
-
-async function runStep(opts: RunStepOptions): Promise<UpdateStepResult> {
-  const { runCommand, name, argv, cwd, timeoutMs, env, progress, stepIndex, totalSteps } = opts;
-  const command = argv.join(" ");
-
-  const stepInfo: UpdateStepInfo = {
-    name,
-    command,
-    index: stepIndex,
-    total: totalSteps,
-  };
-
-  progress?.onStepStart?.(stepInfo);
-
-  const started = Date.now();
-  const result = await runCommand(argv, { cwd, timeoutMs, env });
-  const durationMs = Date.now() - started;
-
-  const stderrTail = trimLogTail(result.stderr, MAX_LOG_CHARS);
-
-  progress?.onStepComplete?.({
-    ...stepInfo,
-    durationMs,
-    exitCode: result.code,
-    stderrTail,
-    signal: result.signal,
-    killed: result.killed,
-    termination: result.termination,
-  });
-
-  return {
-    name,
-    command,
-    cwd,
-    durationMs,
-    exitCode: result.code,
-    stdoutTail: trimLogTail(result.stdout, MAX_LOG_CHARS),
-    stderrTail: trimLogTail(result.stderr, MAX_LOG_CHARS),
-    signal: result.signal,
-    killed: result.killed,
-    termination: result.termination,
-  };
-}
-
-function normalizeTag(tag?: string) {
-  return normalizePackageTagInput(tag, ["openclaw", DEFAULT_PACKAGE_NAME]) ?? "latest";
-}
-
-function normalizeDevTargetRef(value?: string | null): string | null {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : null;
-}
-
-function looksLikeFullCommitSha(value: string): boolean {
-  return /^[0-9a-f]{40}$/i.test(value.trim());
-}
-
-function resolveTagFetchRef(candidate: string): string | null {
-  const ref = candidate.endsWith("^{}") ? candidate.slice(0, -"^{}".length) : candidate;
-  return ref.startsWith("refs/tags/") ? ref : null;
-}
-
-function buildDevTargetRefResolutionCandidates(devTargetRef: string): string[] {
-  const trimmed = devTargetRef.trim();
-  const candidates: string[] = [];
-  const addCandidate = (candidate?: string | null) => {
-    if (!candidate || candidates.includes(candidate)) {
-      return;
-    }
-    candidates.push(candidate);
-  };
-
-  if (looksLikeFullCommitSha(trimmed)) {
-    addCandidate(trimmed);
-    return candidates;
-  }
-
-  if (trimmed.startsWith("refs/remotes/")) {
-    addCandidate(trimmed);
-    return candidates;
-  }
-
-  if (trimmed.startsWith("refs/heads/")) {
-    addCandidate(`refs/remotes/origin/${trimmed.slice("refs/heads/".length)}`);
-    return candidates;
-  }
-
-  if (trimmed.startsWith("origin/")) {
-    addCandidate(`refs/remotes/${trimmed}`);
-    return candidates;
-  }
-
-  if (trimmed.startsWith("refs/tags/")) {
-    addCandidate(`${trimmed}^{}`);
-    addCandidate(trimmed);
-    return candidates;
-  }
-
-  // Resolve plain branch names from the freshly fetched remote ref instead of
-  // a possibly stale local branch checkout.
-  addCandidate(`refs/remotes/origin/${trimmed}`);
-  addCandidate(`refs/tags/${trimmed}^{}`);
-  addCandidate(`refs/tags/${trimmed}`);
-  return candidates;
-}
-
-async function resolveComparablePath(target: string): Promise<string> {
-  return await fs.realpath(target).catch(() => path.resolve(target));
-}
-
-async function pathsReferToSameLocation(left: string, right: string): Promise<boolean> {
-  return (await resolveComparablePath(left)) === (await resolveComparablePath(right));
-}
-
-async function looksLikeGitCheckout(root: string): Promise<boolean> {
-  try {
-    await fs.access(path.join(root, ".git"));
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function shouldRetryWindowsInstallIgnoringScripts(manager: "pnpm" | "bun" | "npm"): boolean {
-  return process.platform === "win32" && manager === "pnpm";
-}
-
-function shouldPreferIgnoreScriptsForWindowsPreflight(manager: "pnpm" | "bun" | "npm"): boolean {
-  return process.platform === "win32" && manager === "pnpm";
-}
-
-function resolveBuildNodeOptions(baseOptions: string | undefined): string {
-  const current = baseOptions?.trim() ?? "";
-  const desired = `--max-old-space-size=${BUILD_MAX_OLD_SPACE_MB}`;
-  const existingMatch = /(?:^|\s)--max-old-space-size=(\d+)(?=\s|$)/.exec(current);
-  if (!existingMatch) {
-    return current ? `${current} ${desired}` : desired;
-  }
-  const existingValue = Number(existingMatch[1]);
-  if (Number.isFinite(existingValue) && existingValue >= BUILD_MAX_OLD_SPACE_MB) {
-    return current;
-  }
-  return current.replace(/(?:^|\s)--max-old-space-size=\d+(?=\s|$)/, ` ${desired}`).trim();
-}
-
-function resolveBuildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv | undefined {
-  const currentNodeOptions = env?.NODE_OPTIONS ?? process.env.NODE_OPTIONS;
-  const nextNodeOptions = resolveBuildNodeOptions(currentNodeOptions);
-  if (nextNodeOptions === currentNodeOptions) {
-    return env;
-  }
-  return {
-    ...env,
-    NODE_OPTIONS: nextNodeOptions,
-  };
-}
-
-function resolveInstallEnv(
-  manager: "pnpm" | "bun" | "npm",
-  env?: NodeJS.ProcessEnv,
-): NodeJS.ProcessEnv | undefined {
-  if (manager !== "pnpm") {
-    return env;
-  }
-  return {
-    ...env,
-    PNPM_CONFIG_RESOLUTION_MODE: env?.PNPM_CONFIG_RESOLUTION_MODE ?? "highest",
-    npm_config_resolution_mode: env?.npm_config_resolution_mode ?? "highest",
-    pnpm_config_resolution_mode: env?.pnpm_config_resolution_mode ?? "highest",
-  };
-}
-
-function isSupersededInstallFailure(
-  step: UpdateStepResult,
-  steps: readonly UpdateStepResult[],
-): boolean {
-  if (step.exitCode === 0) {
-    return false;
-  }
-  if (step.name === "deps install") {
-    return steps.some(
-      (candidate) => candidate.name === "deps install (ignore scripts)" && candidate.exitCode === 0,
-    );
-  }
-  const preflightMatch = /^preflight deps install \((.+)\)$/.exec(step.name);
-  if (!preflightMatch) {
-    return false;
-  }
-  const retryName = `preflight deps install (ignore scripts) (${preflightMatch[1]})`;
-  return steps.some((candidate) => candidate.name === retryName && candidate.exitCode === 0);
-}
-
-function isPreflightCandidateFailure(step: UpdateStepResult): boolean {
-  return /^preflight (?:checkout|package manager|deps install(?: \(ignore scripts\))?|build|lint) \(.+\)$/u.test(
-    step.name,
-  );
-}
-
-function findBlockingGitFailure(steps: readonly UpdateStepResult[]): UpdateStepResult | undefined {
-  return steps.find(
-    (step, index) =>
-      step.exitCode !== 0 &&
-      !isPreflightCandidateFailure(step) &&
-      !isSupersededInstallFailure(step, steps) &&
-      !isSupersededTargetRefFailure(step, steps.slice(index + 1)),
-  );
-}
-
-function isSupersededTargetRefFailure(
-  step: UpdateStepResult,
-  followingSteps: readonly UpdateStepResult[],
-): boolean {
-  const isTargetRefProbe = step.name.startsWith("git rev-parse ");
-  const isTargetTagFetch = step.name.startsWith("git fetch ") && step.name.includes(" refs/tags/");
-  const isUpstreamProbe = step.name === "upstream check";
-  const isLocalDevBranchProbe = step.name === `git show-ref ${DEV_BRANCH}`;
-  if (!isTargetRefProbe && !isTargetTagFetch && !isUpstreamProbe && !isLocalDevBranchProbe) {
-    return false;
-  }
-  if (isLocalDevBranchProbe) {
-    return followingSteps.some(
-      (candidate) =>
-        candidate.name.startsWith(`git checkout -B ${DEV_BRANCH} `) && candidate.exitCode === 0,
-    );
-  }
-  return followingSteps.some(
-    (candidate) => candidate.name.startsWith("git rev-parse ") && candidate.exitCode === 0,
-  );
-}
-
-function mergeCommandEnvironments(
-  baseEnv: NodeJS.ProcessEnv | undefined,
-  overrideEnv: NodeJS.ProcessEnv | undefined,
-): NodeJS.ProcessEnv | undefined {
-  if (!baseEnv) {
-    return overrideEnv;
-  }
-  if (!overrideEnv) {
-    return baseEnv;
-  }
-  return {
-    ...baseEnv,
-    ...overrideEnv,
-  };
-}
-
-function shouldRunDevPreflightLint(env: NodeJS.ProcessEnv = process.env): boolean {
-  const value = env[DEV_PREFLIGHT_LINT_OPT_IN_ENV]?.trim().toLowerCase();
-  return value === "1" || value === "true";
-}
-
-function resolveDevPreflightLintEnv(env: NodeJS.ProcessEnv | undefined): NodeJS.ProcessEnv {
-  return {
-    ...env,
-    ...DEV_PREFLIGHT_LINT_ENV,
-  };
-}
-
-function normalizeFallbackFailureReason(stepName: string): NonNullable<UpdateRunResult["reason"]> {
-  switch (stepName) {
-    case "global update":
-    case "global update (omit optional)":
-    case "global install stage":
-    case "global install verify":
-    case "global install swap":
-      return "global-install-failed";
-    case "openclaw doctor":
-      return "doctor-failed";
-    case "ui:build (post-doctor repair)":
-      return "ui-build-failed";
-    default:
-      return "unexpected-error";
-  }
-}
-
-async function buildUpdateCommandRunner(
-  runCommand?: CommandRunner,
-): Promise<{ defaultCommandEnv: NodeJS.ProcessEnv | undefined; runCommand: CommandRunner }> {
-  const defaultCommandEnv = await createGlobalInstallEnv();
-  if (runCommand) {
-    return {
-      defaultCommandEnv,
-      runCommand,
-    };
-  }
-  return {
-    defaultCommandEnv,
-    runCommand: async (argv, options) => {
-      const res = await runCommandWithTimeout(argv, {
-        ...options,
-        env: mergeCommandEnvironments(defaultCommandEnv, options.env),
-        // Update steps invoke package-manager trees; timeout must retire the
-        // whole tree or detached build workers can outlive the updater.
-        killProcessTree: true,
-      });
-      return res;
-    },
-  };
-}
-
-export async function resolveUpdateInstallSurface(
-  opts: Pick<UpdateRunnerOptions, "cwd" | "argv1" | "timeoutMs" | "runCommand"> = {},
-): Promise<UpdateInstallSurface> {
-  const { runCommand } = await buildUpdateCommandRunner(opts.runCommand);
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const candidates = buildStartDirs(opts);
-  const pkgRoot = await findPackageRoot(candidates);
-
-  let gitRoot = await resolveGitRoot(runCommand, candidates, timeoutMs);
-  if (gitRoot && pkgRoot && path.resolve(gitRoot) !== path.resolve(pkgRoot)) {
-    gitRoot = null;
-  }
-  if (gitRoot && !pkgRoot) {
-    return {
-      kind: "missing",
-      mode: "unknown",
-      root: gitRoot,
-    };
-  }
-  if (gitRoot && pkgRoot && path.resolve(gitRoot) === path.resolve(pkgRoot)) {
-    return {
-      kind: "git",
-      mode: "git",
-      root: gitRoot,
-      packageRoot: pkgRoot,
-    };
-  }
-  if (!pkgRoot) {
-    return {
-      kind: "missing",
-      mode: "unknown",
-    };
-  }
-
-  const globalManager = await detectGlobalInstallManagerForRoot(runCommand, pkgRoot, timeoutMs);
-  if (globalManager) {
-    return {
-      kind: "global",
-      mode: globalManager,
-      root: pkgRoot,
-      packageRoot: pkgRoot,
-    };
-  }
-
-  return {
-    kind: "package-root",
-    mode: "unknown",
-    root: pkgRoot,
-    packageRoot: pkgRoot,
-  };
-}
+  buildStartDirs,
+  findPackageRoot,
+  looksLikeGitCheckout,
+  normalizeDir,
+  pathsReferToSameLocation,
+  resolveComparablePath,
+  resolveGitRoot,
+  resolveUpdateInstallSurface,
+} from "./update-runner-install-surface.js";
+import type { UpdateRunResult, UpdateRunnerOptions } from "./update-runner-types.js";
+
+export type {
+  UpdateRunResult,
+  UpdateStepAdvisory,
+  UpdateStepInfo,
+  UpdateStepProgress,
+  UpdateStepResult,
+} from "./update-runner-types.js";
+export { resolveUpdateDoctorExecutionPolicy, resolveUpdateInstallSurface };
 
 export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<UpdateRunResult> {
   const startedAt = Date.now();
   const { defaultCommandEnv, runCommand } = await buildUpdateCommandRunner(opts.runCommand);
   const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const progress = opts.progress;
-  const steps: UpdateStepResult[] = [];
   const candidates = buildStartDirs(opts);
-  let allowGatewayServiceRepair = opts.allowGatewayServiceRepair !== false;
-  let allowGatewayActivation = opts.allowGatewayActivation === true;
-
-  let stepIndex = 0;
-  let gitTotalSteps = 0;
-
-  const step = (
-    name: string,
-    argv: string[],
-    cwd: string,
-    env?: NodeJS.ProcessEnv,
-  ): RunStepOptions => {
-    const currentIndex = stepIndex;
-    stepIndex += 1;
-    return {
-      runCommand,
-      name,
-      argv,
-      cwd,
-      timeoutMs,
-      env,
-      progress,
-      stepIndex: currentIndex,
-      totalSteps: gitTotalSteps,
-    };
-  };
-
   const pkgRoot = await findPackageRoot(candidates);
 
   let gitRoot = await resolveGitRoot(runCommand, candidates, timeoutMs);
@@ -900,7 +47,6 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
   if (gitRoot && pkgRoot && !(await pathsReferToSameLocation(gitRoot, pkgRoot))) {
     gitRoot = null;
   }
-
   if (gitRoot && !pkgRoot) {
     return {
       status: "error",
@@ -911,864 +57,16 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
       durationMs: Date.now() - startedAt,
     };
   }
-
   if (gitRoot && pkgRoot && (await pathsReferToSameLocation(gitRoot, pkgRoot))) {
-    const channel: UpdateChannel = opts.channel ?? "dev";
-    if (channel === "extended-stable") {
-      return {
-        status: "error",
-        mode: "git",
-        root: gitRoot,
-        reason: "unsupported_git_channel",
-        steps: [],
-        durationMs: Date.now() - startedAt,
-      };
-    }
-    // Get current SHA (not a visible step, no progress)
-    const beforeShaResult = await runCommand(["git", "-C", gitRoot, "rev-parse", "HEAD"], {
-      cwd: gitRoot,
-      timeoutMs,
-    });
-    const beforeSha = beforeShaResult.stdout.trim() || null;
-    const beforeVersion = await readPackageVersion(gitRoot);
-    const devTargetRef = channel === "dev" ? normalizeDevTargetRef(opts.devTargetRef) : null;
-    const branch = await readBranchName(runCommand, gitRoot, timeoutMs);
-    const needsCheckoutMain = channel === "dev" && !devTargetRef && branch !== DEV_BRANCH;
-    gitTotalSteps = channel === "dev" ? (needsCheckoutMain ? 11 : 10) : 9;
-    let gitMutationPrepared = false;
-    let createdDevBranchDuringUpdate = false;
-    let localDevBranchExists: boolean | null = null;
-    const prepareGitMutation = async (targetRevision: string) => {
-      if (gitMutationPrepared) {
-        return;
-      }
-      const targetMetadata = await readGitTargetSchemaVersions({
-        runCommand,
-        root: gitRoot,
-        revision: targetRevision,
-        timeoutMs,
-      });
-      const preparation = await opts.beforeGitMutation?.(
-        targetMetadata.status === "ok"
-          ? targetMetadata.schemaVersions
-            ? { schemaVersions: targetMetadata.schemaVersions }
-            : {}
-          : { metadataUnreadable: targetMetadata.reason },
-      );
-      if (typeof preparation?.allowGatewayServiceRepair === "boolean") {
-        allowGatewayServiceRepair = preparation.allowGatewayServiceRepair;
-      }
-      if (typeof preparation?.allowGatewayActivation === "boolean") {
-        allowGatewayActivation = preparation.allowGatewayActivation;
-      }
-      gitMutationPrepared = true;
-    };
-    const buildGitErrorResult = (reason: string): UpdateRunResult => ({
-      status: "error",
-      mode: "git",
-      root: gitRoot,
-      reason,
-      before: { sha: beforeSha, version: beforeVersion },
-      steps,
-      durationMs: Date.now() - startedAt,
-    });
-    const runRequiredGitStep = async (name: string, argv: string[], reason: string) => {
-      const gitStep = await runStep(step(name, argv, gitRoot));
-      steps.push(gitStep);
-      if (gitStep.exitCode !== 0) {
-        return buildGitErrorResult(reason);
-      }
-      return null;
-    };
-    const appendRecoveryStep = async (name: string, argv: string[]) => {
-      const started = Date.now();
-      const result = await runCommand(argv, { cwd: gitRoot, timeoutMs });
-      const recoveryStep: UpdateStepResult = {
-        name,
-        command: argv.join(" "),
-        cwd: gitRoot,
-        durationMs: Date.now() - started,
-        exitCode: result.code,
-        stdoutTail: trimLogTail(result.stdout, MAX_LOG_CHARS),
-        stderrTail: trimLogTail(result.stderr, MAX_LOG_CHARS),
-      };
-      steps.push(recoveryStep);
-      return recoveryStep.exitCode === 0;
-    };
-    const rollbackGitCheckout = async () => {
-      if (!beforeSha) {
-        return;
-      }
-      await appendRecoveryStep("git rollback clean", ["git", "-C", gitRoot, "reset", "--hard"]);
-      if (branch && branch !== "HEAD") {
-        const checkedOutBranch = await appendRecoveryStep("git rollback checkout", [
-          "git",
-          "-C",
-          gitRoot,
-          "checkout",
-          "--force",
-          branch,
-        ]);
-        if (checkedOutBranch) {
-          await appendRecoveryStep("git rollback reset", [
-            "git",
-            "-C",
-            gitRoot,
-            "reset",
-            "--hard",
-            beforeSha,
-          ]);
-          if (createdDevBranchDuringUpdate) {
-            await appendRecoveryStep(`git rollback delete ${DEV_BRANCH}`, [
-              "git",
-              "-C",
-              gitRoot,
-              "branch",
-              "-D",
-              DEV_BRANCH,
-            ]);
-          }
-        }
-        return;
-      }
-      await appendRecoveryStep("git rollback checkout", [
-        "git",
-        "-C",
-        gitRoot,
-        "checkout",
-        "--detach",
-        beforeSha,
-      ]);
-      if (createdDevBranchDuringUpdate) {
-        await appendRecoveryStep(`git rollback delete ${DEV_BRANCH}`, [
-          "git",
-          "-C",
-          gitRoot,
-          "branch",
-          "-D",
-          DEV_BRANCH,
-        ]);
-      }
-    };
-    const buildGitErrorResultWithRollback = async (reason: string): Promise<UpdateRunResult> => {
-      await rollbackGitCheckout();
-      return buildGitErrorResult(reason);
-    };
-
-    const statusCheck = await runStep(
-      step(
-        "clean check",
-        ["git", "-C", gitRoot, "status", "--porcelain", "--", ":!dist/control-ui/"],
-        gitRoot,
-      ),
-    );
-    steps.push(statusCheck);
-    const hasUncommittedChanges =
-      statusCheck.stdoutTail && statusCheck.stdoutTail.trim().length > 0;
-    if (hasUncommittedChanges) {
-      return {
-        status: "skipped",
-        mode: "git",
-        root: gitRoot,
-        reason: "dirty",
-        before: { sha: beforeSha, version: beforeVersion },
-        steps,
-        durationMs: Date.now() - startedAt,
-      };
-    }
-
-    if (channel === "dev") {
-      const fetchFailure = await runRequiredGitStep(
-        "git fetch",
-        ["git", "-C", gitRoot, "fetch", "--all", "--prune", "--no-tags"],
-        "fetch-failed",
-      );
-      if (fetchFailure) {
-        return fetchFailure;
-      }
-      let preflightBaseSha: string | null;
-      let candidatesLocal: string[];
-      let selectedDevUpstream: string | null = null;
-      if (devTargetRef) {
-        let targetSha: string | null = null;
-        for (const targetRefCandidate of buildDevTargetRefResolutionCandidates(devTargetRef)) {
-          const tagFetchRef = resolveTagFetchRef(targetRefCandidate);
-          if (tagFetchRef) {
-            const remoteListStep = await runStep(
-              step("git remote", ["git", "-C", gitRoot, "remote"], gitRoot),
-            );
-            steps.push(remoteListStep);
-            const remotes = normalizeStringEntries((remoteListStep.stdoutTail ?? "").split("\n"));
-            let fetchedTag = false;
-            for (const remote of remotes) {
-              const targetTagFetchStep = await runStep(
-                step(
-                  `git fetch ${remote} ${tagFetchRef}`,
-                  ["git", "-C", gitRoot, "fetch", remote, `+${tagFetchRef}:${tagFetchRef}`],
-                  gitRoot,
-                ),
-              );
-              steps.push(targetTagFetchStep);
-              if (targetTagFetchStep.exitCode === 0) {
-                fetchedTag = true;
-                break;
-              }
-            }
-            if (remotes.length > 0 && !fetchedTag) {
-              continue;
-            }
-          }
-          const targetShaStep = await runStep(
-            step(
-              `git rev-parse ${targetRefCandidate}`,
-              ["git", "-C", gitRoot, "rev-parse", targetRefCandidate],
-              gitRoot,
-            ),
-          );
-          steps.push(targetShaStep);
-          const resolvedTargetSha = targetShaStep.stdoutTail?.trim();
-          if (targetShaStep.exitCode === 0 && resolvedTargetSha) {
-            targetSha = resolvedTargetSha;
-            break;
-          }
-        }
-        if (!targetSha) {
-          return {
-            status: "error",
-            mode: "git",
-            root: gitRoot,
-            reason: "no-target-sha",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
-        }
-        preflightBaseSha = targetSha;
-        candidatesLocal = [targetSha];
-      } else {
-        if (needsCheckoutMain) {
-          const localMainStep = await runStep(
-            step(
-              `git show-ref ${DEV_BRANCH}`,
-              ["git", "-C", gitRoot, "show-ref", "--verify", `refs/heads/${DEV_BRANCH}`],
-              gitRoot,
-            ),
-          );
-          steps.push(localMainStep);
-          localDevBranchExists = localMainStep.exitCode === 0;
-        }
-        let remoteBranchRefs: string[] = [];
-        if (needsCheckoutMain && localDevBranchExists === false) {
-          const remoteStep = await runStep(
-            step("git remote", ["git", "-C", gitRoot, "remote"], gitRoot),
-          );
-          steps.push(remoteStep);
-          if (remoteStep.exitCode === 0) {
-            remoteBranchRefs = normalizeStringEntries(
-              (remoteStep.stdoutTail ?? "").split("\n"),
-            ).map((remote) => `refs/remotes/${remote}/${DEV_BRANCH}`);
-          }
-        }
-        const upstreamRefs = needsCheckoutMain
-          ? [`${DEV_BRANCH}@{upstream}`, ...remoteBranchRefs]
-          : ["@{upstream}"];
-        let upstreamSha: string | null = null;
-        let sawResolvableUpstreamRef = false;
-        for (const upstreamRef of upstreamRefs) {
-          if (upstreamRef.endsWith("@{upstream}")) {
-            const upstreamStep = await runStep(
-              step(
-                "upstream check",
-                [
-                  "git",
-                  "-C",
-                  gitRoot,
-                  "rev-parse",
-                  "--abbrev-ref",
-                  "--symbolic-full-name",
-                  upstreamRef,
-                ],
-                gitRoot,
-              ),
-            );
-            steps.push(upstreamStep);
-            if (upstreamStep.exitCode !== 0) {
-              continue;
-            }
-            sawResolvableUpstreamRef = true;
-          }
-
-          const upstreamShaStep = await runStep(
-            step(
-              `git rev-parse ${upstreamRef}`,
-              ["git", "-C", gitRoot, "rev-parse", upstreamRef],
-              gitRoot,
-            ),
-          );
-          steps.push(upstreamShaStep);
-          const candidateSha = upstreamShaStep.stdoutTail?.trim();
-          if (upstreamShaStep.exitCode === 0 && candidateSha) {
-            upstreamSha = candidateSha;
-            const remoteBranchMatch = /^refs\/remotes\/(.+)$/u.exec(upstreamRef);
-            selectedDevUpstream = remoteBranchMatch?.[1] ?? null;
-            break;
-          }
-          if (upstreamShaStep.exitCode === 0) {
-            sawResolvableUpstreamRef = true;
-          }
-        }
-        if (!upstreamSha && !sawResolvableUpstreamRef) {
-          return {
-            status: "skipped",
-            mode: "git",
-            root: gitRoot,
-            reason: "no-upstream",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
-        }
-        if (!upstreamSha) {
-          return {
-            status: "error",
-            mode: "git",
-            root: gitRoot,
-            reason: "no-upstream-sha",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
-        }
-
-        const revListStep = await runStep(
-          step(
-            "git rev-list",
-            ["git", "-C", gitRoot, "rev-list", `--max-count=${PREFLIGHT_MAX_COMMITS}`, upstreamSha],
-            gitRoot,
-          ),
-        );
-        steps.push(revListStep);
-        if (revListStep.exitCode !== 0) {
-          return {
-            status: "error",
-            mode: "git",
-            root: gitRoot,
-            reason: "preflight-revlist-failed",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
-        }
-
-        candidatesLocal = normalizeStringEntries((revListStep.stdoutTail ?? "").split("\n"));
-        if (candidatesLocal.length === 0) {
-          return {
-            status: "error",
-            mode: "git",
-            root: gitRoot,
-            reason: "preflight-no-candidates",
-            before: { sha: beforeSha, version: beforeVersion },
-            steps,
-            durationMs: Date.now() - startedAt,
-          };
-        }
-        preflightBaseSha = upstreamSha;
-      }
-      if (!preflightBaseSha) {
-        return {
-          status: "error",
-          mode: "git",
-          root: gitRoot,
-          reason: "preflight-base-missing",
-          before: { sha: beforeSha, version: beforeVersion },
-          steps,
-          durationMs: Date.now() - startedAt,
-        };
-      }
-
-      const preflightRoot = await createPreflightRoot();
-      const worktreeDir = resolvePreflightWorktreeDir(preflightRoot);
-      const worktreeStep = await runStep(
-        step(
-          "preflight worktree",
-          ["git", "-C", gitRoot, "worktree", "add", "--detach", worktreeDir, preflightBaseSha],
-          gitRoot,
-        ),
-      );
-      steps.push(worktreeStep);
-      if (worktreeStep.exitCode !== 0) {
-        await removePathRecursive(preflightRoot);
-        return {
-          status: "error",
-          mode: "git",
-          root: gitRoot,
-          reason: "preflight-worktree-failed",
-          before: { sha: beforeSha, version: beforeVersion },
-          steps,
-          durationMs: Date.now() - startedAt,
-        };
-      }
-
-      let selectedSha: string | null = null;
-      let preflightManagerFailureReason: NonNullable<UpdateRunResult["reason"]> | null = null;
-      let sawNonManagerPreflightFailure = false;
-      try {
-        for (const sha of candidatesLocal) {
-          const shortSha = sha.slice(0, 8);
-          const checkoutStep = await runStep(
-            step(
-              `preflight checkout (${shortSha})`,
-              ["git", "-C", worktreeDir, "checkout", "--detach", sha],
-              worktreeDir,
-            ),
-          );
-          steps.push(checkoutStep);
-          if (checkoutStep.exitCode !== 0) {
-            sawNonManagerPreflightFailure = true;
-            continue;
-          }
-
-          const manager = await resolveUpdateBuildManager(
-            (argv, options) => runCommand(argv, { timeoutMs: options.timeoutMs, env: options.env }),
-            worktreeDir,
-            timeoutMs,
-            defaultCommandEnv,
-            "require-preferred",
-          );
-          if (manager.kind === "missing-required") {
-            preflightManagerFailureReason = mapManagerResolutionFailure(manager.reason);
-            steps.push({
-              name: `preflight package manager (${shortSha})`,
-              command: `resolve ${manager.preferred} package manager`,
-              cwd: worktreeDir,
-              durationMs: 0,
-              exitCode: 1,
-              stderrTail: preflightManagerFailureReason,
-            });
-            continue;
-          }
-          try {
-            const preflightIgnoreScripts = shouldPreferIgnoreScriptsForWindowsPreflight(
-              manager.manager,
-            );
-            const preflightIgnoreScriptsArgv = managerInstallIgnoreScriptsArgs(manager.manager);
-            const depsStepArgv =
-              preflightIgnoreScripts && preflightIgnoreScriptsArgv
-                ? preflightIgnoreScriptsArgv
-                : managerInstallArgs(manager.manager, {
-                    compatFallback: manager.fallback && manager.manager === "npm",
-                  });
-            const depsStepName = preflightIgnoreScripts
-              ? `preflight deps install (ignore scripts) (${shortSha})`
-              : `preflight deps install (${shortSha})`;
-            const installEnv = resolveInstallEnv(manager.manager, manager.env);
-            const depsStep = await runStep(
-              step(depsStepName, depsStepArgv, worktreeDir, installEnv),
-            );
-            steps.push(depsStep);
-            let finalDepsStep = depsStep;
-            if (
-              depsStep.exitCode !== 0 &&
-              !preflightIgnoreScripts &&
-              shouldRetryWindowsInstallIgnoringScripts(manager.manager)
-            ) {
-              const retryArgv = managerInstallIgnoreScriptsArgs(manager.manager);
-              if (retryArgv) {
-                const retryStep = await runStep(
-                  step(
-                    `preflight deps install (ignore scripts) (${shortSha})`,
-                    retryArgv,
-                    worktreeDir,
-                    installEnv,
-                  ),
-                );
-                steps.push(retryStep);
-                finalDepsStep = retryStep;
-              }
-            }
-            if (finalDepsStep.exitCode !== 0) {
-              sawNonManagerPreflightFailure = true;
-              continue;
-            }
-
-            const buildStep = await runStep(
-              step(
-                `preflight build (${shortSha})`,
-                managerScriptArgs(manager.manager, "build"),
-                worktreeDir,
-                resolveBuildEnv(manager.env),
-              ),
-            );
-            steps.push(buildStep);
-            if (buildStep.exitCode !== 0) {
-              sawNonManagerPreflightFailure = true;
-              continue;
-            }
-
-            if (shouldRunDevPreflightLint()) {
-              const lintStep = await runStep(
-                step(
-                  `preflight lint (${shortSha})`,
-                  managerScriptArgs(manager.manager, "lint"),
-                  worktreeDir,
-                  resolveDevPreflightLintEnv(manager.env),
-                ),
-              );
-              steps.push(lintStep);
-              if (lintStep.exitCode !== 0) {
-                sawNonManagerPreflightFailure = true;
-                continue;
-              }
-            }
-
-            selectedSha = sha;
-            break;
-          } finally {
-            await manager.cleanup?.();
-          }
-        }
-      } finally {
-        const removeStep = await runStep({
-          ...step(
-            "preflight cleanup",
-            ["git", "-C", gitRoot, "worktree", "remove", "--force", worktreeDir],
-            gitRoot,
-          ),
-          timeoutMs: Math.min(timeoutMs, PREFLIGHT_CLEANUP_TIMEOUT_MS),
-        });
-        if (
-          removeStep.exitCode !== 0 &&
-          (await repairPreflightCleanup(worktreeDir, preflightRoot))
-        ) {
-          removeStep.exitCode = 0;
-          const fallbackMessage =
-            process.platform === "win32"
-              ? "windows fallback cleanup removed preflight tree"
-              : "fallback cleanup removed preflight tree";
-          removeStep.stderrTail = trimLogTail(
-            [removeStep.stderrTail, fallbackMessage].filter(Boolean).join("\n"),
-            MAX_LOG_CHARS,
-          );
-        }
-        steps.push(removeStep);
-        await runCommand(["git", "-C", gitRoot, "worktree", "prune"], {
-          cwd: gitRoot,
-          timeoutMs,
-        }).catch(() => null);
-        await removePathRecursive(preflightRoot);
-      }
-
-      if (!selectedSha) {
-        return {
-          status: "error",
-          mode: "git",
-          root: gitRoot,
-          reason:
-            preflightManagerFailureReason && !sawNonManagerPreflightFailure
-              ? preflightManagerFailureReason
-              : "preflight-no-good-commit",
-          before: { sha: beforeSha, version: beforeVersion },
-          steps,
-          durationMs: Date.now() - startedAt,
-        };
-      }
-
-      if (devTargetRef) {
-        await prepareGitMutation(selectedSha);
-        const failure = await runRequiredGitStep(
-          `git checkout ${selectedSha}`,
-          ["git", "-C", gitRoot, "checkout", "--detach", selectedSha],
-          "checkout-failed",
-        );
-        if (failure) {
-          return failure;
-        }
-      } else {
-        await prepareGitMutation(selectedSha);
-        let checkedOutSelectedSha = false;
-        if (needsCheckoutMain) {
-          const hasLocalDevBranch = localDevBranchExists !== false;
-          const failure = await runRequiredGitStep(
-            hasLocalDevBranch
-              ? `git checkout ${DEV_BRANCH}`
-              : `git checkout -B ${DEV_BRANCH} ${selectedSha}`,
-            hasLocalDevBranch
-              ? ["git", "-C", gitRoot, "checkout", DEV_BRANCH]
-              : ["git", "-C", gitRoot, "checkout", "-B", DEV_BRANCH, selectedSha],
-            "checkout-failed",
-          );
-          if (failure) {
-            return failure;
-          }
-          checkedOutSelectedSha = !hasLocalDevBranch;
-          createdDevBranchDuringUpdate = checkedOutSelectedSha;
-          if (checkedOutSelectedSha && selectedDevUpstream) {
-            const upstreamFailure = await runRequiredGitStep(
-              `git branch --set-upstream-to ${selectedDevUpstream} ${DEV_BRANCH}`,
-              [
-                "git",
-                "-C",
-                gitRoot,
-                "branch",
-                "--set-upstream-to",
-                selectedDevUpstream,
-                DEV_BRANCH,
-              ],
-              "checkout-failed",
-            );
-            if (upstreamFailure) {
-              return await buildGitErrorResultWithRollback("checkout-failed");
-            }
-          }
-        }
-        if (checkedOutSelectedSha) {
-          steps.push({
-            name: "git rebase",
-            command: `git rebase ${selectedSha}`,
-            cwd: gitRoot,
-            durationMs: 0,
-            exitCode: 0,
-            stdoutTail: `skipped; ${DEV_BRANCH} was created at selected preflight SHA`,
-          });
-        } else {
-          const rebaseStep = await runStep(
-            step("git rebase", ["git", "-C", gitRoot, "rebase", selectedSha], gitRoot),
-          );
-          steps.push(rebaseStep);
-          if (rebaseStep.exitCode !== 0) {
-            const abortResult = await runCommand(["git", "-C", gitRoot, "rebase", "--abort"], {
-              cwd: gitRoot,
-              timeoutMs,
-            });
-            steps.push({
-              name: "git rebase --abort",
-              command: "git rebase --abort",
-              cwd: gitRoot,
-              durationMs: 0,
-              exitCode: abortResult.code,
-              stdoutTail: trimLogTail(abortResult.stdout, MAX_LOG_CHARS),
-              stderrTail: trimLogTail(abortResult.stderr, MAX_LOG_CHARS),
-            });
-            return {
-              status: "error",
-              mode: "git",
-              root: gitRoot,
-              reason: "rebase-failed",
-              before: { sha: beforeSha, version: beforeVersion },
-              steps,
-              durationMs: Date.now() - startedAt,
-            };
-          }
-        }
-      }
-    } else {
-      const fetchFailure = await runRequiredGitStep(
-        "git fetch",
-        ["git", "-C", gitRoot, "fetch", "--all", "--prune", "--tags"],
-        "fetch-failed",
-      );
-      if (fetchFailure) {
-        return fetchFailure;
-      }
-
-      const tag = await resolveChannelTag(runCommand, gitRoot, timeoutMs, channel);
-      if (!tag) {
-        return {
-          status: "error",
-          mode: "git",
-          root: gitRoot,
-          reason: "no-release-tag",
-          before: { sha: beforeSha, version: beforeVersion },
-          steps,
-          durationMs: Date.now() - startedAt,
-        };
-      }
-
-      await prepareGitMutation(tag);
-      const failure = await runRequiredGitStep(
-        `git checkout ${tag}`,
-        ["git", "-C", gitRoot, "checkout", "--detach", tag],
-        "checkout-failed",
-      );
-      if (failure) {
-        return failure;
-      }
-    }
-
-    const manager = await resolveUpdateBuildManager(
-      (argv, options) => runCommand(argv, { timeoutMs: options.timeoutMs, env: options.env }),
+    return await runGitUpdate({
+      opts,
       gitRoot,
-      timeoutMs,
+      runCommand,
       defaultCommandEnv,
-      "require-preferred",
-    );
-    if (manager.kind === "missing-required") {
-      return await buildGitErrorResultWithRollback(mapManagerResolutionFailure(manager.reason));
-    }
-    try {
-      const installEnv = resolveInstallEnv(manager.manager, manager.env);
-      const depsStep = await runStep(
-        step(
-          "deps install",
-          managerInstallArgs(manager.manager, {
-            compatFallback: manager.fallback && manager.manager === "npm",
-          }),
-          gitRoot,
-          installEnv,
-        ),
-      );
-      steps.push(depsStep);
-      let finalDepsStep = depsStep;
-      if (depsStep.exitCode !== 0 && shouldRetryWindowsInstallIgnoringScripts(manager.manager)) {
-        const retryArgv = managerInstallIgnoreScriptsArgs(manager.manager);
-        if (retryArgv) {
-          const retryStep = await runStep(
-            step("deps install (ignore scripts)", retryArgv, gitRoot, installEnv),
-          );
-          steps.push(retryStep);
-          finalDepsStep = retryStep;
-        }
-      }
-      if (finalDepsStep.exitCode !== 0) {
-        return await buildGitErrorResultWithRollback("deps-install-failed");
-      }
-
-      const buildStep = await runStep(
-        step(
-          "build",
-          managerScriptArgs(manager.manager, "build"),
-          gitRoot,
-          resolveBuildEnv(manager.env),
-        ),
-      );
-      steps.push(buildStep);
-      if (buildStep.exitCode !== 0) {
-        return await buildGitErrorResultWithRollback("build-failed");
-      }
-
-      const uiBuildStep = await runStep(
-        step("ui:build", managerScriptArgs(manager.manager, "ui:build"), gitRoot, manager.env),
-      );
-      steps.push(uiBuildStep);
-      if (uiBuildStep.exitCode !== 0) {
-        return await buildGitErrorResultWithRollback("ui-build-failed");
-      }
-
-      const doctorEntry = path.join(gitRoot, "openclaw.mjs");
-      const doctorEntryExists = await fs
-        .stat(doctorEntry)
-        .then(() => true)
-        .catch(() => false);
-      if (!doctorEntryExists) {
-        steps.push({
-          name: "openclaw doctor entry",
-          command: `verify ${doctorEntry}`,
-          cwd: gitRoot,
-          durationMs: 0,
-          exitCode: 1,
-          stderrTail: `missing ${doctorEntry}`,
-        });
-        return await buildGitErrorResultWithRollback("doctor-entry-missing");
-      }
-
-      const doctorNodePath = await resolveStableNodePath(process.execPath);
-      const doctorTargetVersion = await readPackageVersion(gitRoot);
-      const doctorPolicy = resolveUpdateDoctorExecutionPolicy({
-        targetVersion: doctorTargetVersion,
-        allowGatewayServiceRepair,
-      });
-      const doctorArgv = [
-        doctorNodePath,
-        doctorEntry,
-        "doctor",
-        "--non-interactive",
-        ...(doctorPolicy.fix ? ["--fix"] : []),
-      ];
-      const doctorStep = await runStep(
-        step("openclaw doctor", doctorArgv, gitRoot, {
-          OPENCLAW_UPDATE_IN_PROGRESS: "1",
-          ...(opts.deferConfiguredPluginInstallRepair
-            ? { [UPDATE_DEFER_CONFIGURED_PLUGIN_INSTALL_REPAIR_ENV]: "1" }
-            : {}),
-          [UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV]: "1",
-          [UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART_ENV]: "1",
-          [UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR_ENV]: allowGatewayServiceRepair ? "1" : "0",
-          [UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION_ENV]: allowGatewayActivation ? "1" : "0",
-          ...(doctorPolicy.serviceRepairPolicy
-            ? { [UPDATE_DOCTOR_SERVICE_REPAIR_POLICY_ENV]: doctorPolicy.serviceRepairPolicy }
-            : {}),
-        }),
-      );
-      steps.push(doctorStep);
-      if (doctorStep.exitCode !== 0) {
-        return await buildGitErrorResultWithRollback("doctor-failed");
-      }
-
-      const uiIndexHealth = await resolveControlUiDistIndexHealth({ root: gitRoot });
-      if (!uiIndexHealth.exists) {
-        const repairArgv = managerScriptArgs(manager.manager, "ui:build");
-        const started = Date.now();
-        const repairResult = await runCommand(repairArgv, {
-          cwd: gitRoot,
-          timeoutMs,
-          env: manager.env,
-        });
-        const repairStep: UpdateStepResult = {
-          name: "ui:build (post-doctor repair)",
-          command: repairArgv.join(" "),
-          cwd: gitRoot,
-          durationMs: Date.now() - started,
-          exitCode: repairResult.code,
-          stdoutTail: trimLogTail(repairResult.stdout, MAX_LOG_CHARS),
-          stderrTail: trimLogTail(repairResult.stderr, MAX_LOG_CHARS),
-        };
-        steps.push(repairStep);
-
-        if (repairResult.code !== 0) {
-          return await buildGitErrorResultWithRollback("ui-build-failed");
-        }
-
-        const repairedUiIndexHealth = await resolveControlUiDistIndexHealth({ root: gitRoot });
-        if (!repairedUiIndexHealth.exists) {
-          const uiIndexPath =
-            repairedUiIndexHealth.indexPath ?? resolveControlUiDistIndexPathForRoot(gitRoot);
-          steps.push({
-            name: "ui assets verify",
-            command: `verify ${uiIndexPath}`,
-            cwd: gitRoot,
-            durationMs: 0,
-            exitCode: 1,
-            stderrTail: `missing ${uiIndexPath}`,
-          });
-          return await buildGitErrorResultWithRollback("ui-assets-missing");
-        }
-      }
-
-      const failedStep = findBlockingGitFailure(steps);
-      const afterShaStep = await runStep(
-        step("git rev-parse HEAD (after)", ["git", "-C", gitRoot, "rev-parse", "HEAD"], gitRoot),
-      );
-      steps.push(afterShaStep);
-      const afterVersion = await readPackageVersion(gitRoot);
-
-      return {
-        status: failedStep ? "error" : "ok",
-        mode: "git",
-        root: gitRoot,
-        reason: failedStep ? normalizeFallbackFailureReason(failedStep.name) : undefined,
-        before: { sha: beforeSha, version: beforeVersion },
-        after: {
-          sha: afterShaStep.stdoutTail?.trim() ?? null,
-          version: afterVersion,
-        },
-        steps,
-        durationMs: Date.now() - startedAt,
-      };
-    } finally {
-      await manager.cleanup?.();
-    }
+      timeoutMs,
+      startedAt,
+    });
   }
-
   if (!pkgRoot) {
     return {
       status: "error",
@@ -1782,139 +80,18 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
   const beforeVersion = await readPackageVersion(pkgRoot);
   const globalManager = await detectGlobalInstallManagerForRoot(runCommand, pkgRoot, timeoutMs);
   if (globalManager) {
-    const channel = opts.channel ?? DEFAULT_PACKAGE_CHANNEL;
-    if (channel === "extended-stable" && opts.tag !== undefined) {
-      return {
-        status: "error",
-        mode: globalManager,
-        root: pkgRoot,
-        reason: EXTENDED_STABLE_TAG_UNSUPPORTED_REASON,
-        before: { version: beforeVersion },
-        steps: [],
-        durationMs: Date.now() - startedAt,
-      };
-    }
-    const packageName = (await readPackageName(pkgRoot)) ?? DEFAULT_PACKAGE_NAME;
-    const installTarget = await resolveGlobalInstallTarget({
-      manager: globalManager,
-      runCommand,
-      timeoutMs,
+    return await runGlobalUpdate({
+      opts,
       pkgRoot,
-      packageName,
-    });
-    await cleanupGlobalRenameDirs({
-      globalRoot: path.dirname(pkgRoot),
-      packageName,
-    });
-    const extendedStable =
-      channel === "extended-stable"
-        ? await resolveExtendedStablePackage({
-            installKind: "package",
-            timeoutMs,
-            packageName,
-          })
-        : null;
-    if (extendedStable?.status === "failed") {
-      return {
-        status: "error",
-        mode: globalManager,
-        root: pkgRoot,
-        reason: extendedStable.reason,
-        before: { version: beforeVersion },
-        steps: [],
-        durationMs: Date.now() - startedAt,
-      };
-    }
-    const tag = normalizeTag(
-      extendedStable?.status === "resolved"
-        ? extendedStable.version
-        : (opts.tag ?? channelToNpmTag(channel)),
-    );
-    const globalInstallEnv = await createGlobalInstallEnv();
-    const spec =
-      extendedStable?.status === "resolved"
-        ? extendedStable.packageSpec
-        : resolveGlobalInstallSpec({
-            packageName,
-            tag,
-            env: globalInstallEnv,
-          });
-    const packageUpdate = await runGlobalPackageUpdateSteps({
-      installTarget,
-      installSpec: spec,
-      packageName,
-      packageRoot: pkgRoot,
+      globalManager,
       runCommand,
       timeoutMs,
-      ...(globalInstallEnv === undefined ? {} : { env: globalInstallEnv }),
-      installCwd: pkgRoot,
-      runStep: (stepParams) =>
-        runStep({
-          runCommand,
-          ...stepParams,
-          cwd: stepParams.cwd ?? pkgRoot,
-          progress,
-          stepIndex: 0,
-          totalSteps: 1,
-        }),
-      postVerifyStep: async (verifiedPackageRoot) => {
-        const doctorEntry = await resolveGatewayInstallEntrypoint(verifiedPackageRoot);
-        if (!doctorEntry) {
-          return null;
-        }
-        const doctorNodePath = await resolveStableNodePath(process.execPath);
-        const candidateHostVersion = await readPackageVersion(verifiedPackageRoot);
-        const doctorPolicy = resolveUpdateDoctorExecutionPolicy({
-          targetVersion: candidateHostVersion,
-          allowGatewayServiceRepair,
-        });
-        return await runStep({
-          runCommand,
-          name: "openclaw doctor",
-          argv: [
-            doctorNodePath,
-            doctorEntry,
-            "doctor",
-            "--non-interactive",
-            ...(doctorPolicy.fix ? ["--fix"] : []),
-          ],
-          cwd: verifiedPackageRoot,
-          timeoutMs,
-          env: {
-            OPENCLAW_UPDATE_IN_PROGRESS: "1",
-            [UPDATE_PARENT_SUPPORTS_DOCTOR_CONFIG_WRITE_ENV]: "1",
-            [UPDATE_PARENT_SUPPORTS_GATEWAY_RESTART_ENV]: "1",
-            [UPDATE_PARENT_ALLOWS_GATEWAY_SERVICE_REPAIR_ENV]: allowGatewayServiceRepair
-              ? "1"
-              : "0",
-            [UPDATE_PARENT_ALLOWS_GATEWAY_ACTIVATION_ENV]: allowGatewayActivation ? "1" : "0",
-            ...(doctorPolicy.serviceRepairPolicy
-              ? { [UPDATE_DOCTOR_SERVICE_REPAIR_POLICY_ENV]: doctorPolicy.serviceRepairPolicy }
-              : {}),
-            ...(candidateHostVersion === null
-              ? {}
-              : { OPENCLAW_COMPATIBILITY_HOST_VERSION: candidateHostVersion }),
-          },
-          progress,
-          stepIndex: 0,
-          totalSteps: 1,
-        });
-      },
+      startedAt,
+      beforeVersion,
+      allowGatewayServiceRepair: opts.allowGatewayServiceRepair !== false,
+      allowGatewayActivation: opts.allowGatewayActivation === true,
     });
-    return {
-      status: packageUpdate.failedStep ? "error" : "ok",
-      mode: globalManager,
-      root: packageUpdate.verifiedPackageRoot ?? pkgRoot,
-      reason: packageUpdate.failedStep
-        ? normalizeFallbackFailureReason(packageUpdate.failedStep.name)
-        : undefined,
-      before: { version: beforeVersion },
-      after: { version: packageUpdate.afterVersion },
-      steps: packageUpdate.steps,
-      durationMs: Date.now() - startedAt,
-    };
   }
-
   return {
     status: "skipped",
     mode: "unknown",
@@ -1925,4 +102,3 @@ export async function runGatewayUpdate(opts: UpdateRunnerOptions = {}): Promise<
     durationMs: Date.now() - startedAt,
   };
 }
-/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */

From 74880cb56f9eb9d82ab838a14f001ee7b8a62294 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 12:54:05 +0100
Subject: [PATCH 56/76] =?UTF-8?q?feat(ui):=20manage=20MCP=20servers=20dire?=
 =?UTF-8?q?ctly=20from=20Settings=20=E2=86=92=20MCP=20(#110654)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(ui): manage MCP servers directly on the Settings MCP page

* refactor(ui): mcp config section owned by the MCP settings page only

* chore(ui): drop test-only McpServersCard export for knip
---
 docs/web/control-ui.md                     |  11 +-
 scripts/control-ui-mock-dev.ts             |  11 +
 ui/src/components/mcp-server-form.ts       |  71 +++++
 ui/src/components/mcp-servers-card.test.ts | 311 +++++++++++++++++++++
 ui/src/components/mcp-servers-card.ts      | 287 +++++++++++++++++++
 ui/src/i18n/.i18n/raw-copy-baseline.json   |  28 +-
 ui/src/i18n/locales/en.ts                  |  36 ++-
 ui/src/lib/config/mcp-servers.ts           | 137 +++++++++
 ui/src/pages/config/config-page.test.ts    |  27 ++
 ui/src/pages/config/config-page.ts         |   1 -
 ui/src/pages/config/config-sections.ts     |   6 +-
 ui/src/pages/config/mcp.test.ts            | 111 +-------
 ui/src/pages/config/mcp.ts                 | 104 +------
 ui/src/pages/config/settings-search.ts     |   4 +-
 ui/src/pages/plugins/plugins-page.test.ts  |   4 +-
 ui/src/pages/plugins/plugins-page.ts       | 115 ++------
 ui/src/pages/plugins/view.test.ts          |  16 +-
 ui/src/pages/plugins/view.ts               |  81 ++----
 ui/src/styles/config.css                   |  55 ++++
 ui/src/styles/plugins.css                  |  34 ---
 20 files changed, 1025 insertions(+), 425 deletions(-)
 create mode 100644 ui/src/components/mcp-server-form.ts
 create mode 100644 ui/src/components/mcp-servers-card.test.ts
 create mode 100644 ui/src/components/mcp-servers-card.ts
 create mode 100644 ui/src/lib/config/mcp-servers.ts

diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 8c578570a3d..9df3e47c303 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -135,9 +135,10 @@ The **Installed** tab shows the full local inventory grouped by category, with
 overview counts. Each row opens a detail view; its overflow (`…`) menu enables
 or disables the plugin and offers **Remove** for externally installed plugins.
 It also lists configured [MCP servers](/cli/mcp) and supports adding, disabling,
-and removing them inline. The **Discover** tab is the store: featured plugins
-included with OpenClaw, official external plugins, and one-click MCP connectors
-for popular services. Typing in the search box queries
+and removing them inline. The same server controls live on **Settings → MCP**.
+The **Discover** tab is the store: featured plugins included with OpenClaw,
+official external plugins, and one-click MCP connectors for popular services.
+Typing in the search box queries
 [ClawHub](https://clawhub.ai/plugins) inline and appends a **From ClawHub**
 section with download counts and source-verification badges. Deep links can
 target the store directly with `/settings/plugins?tab=discover`.
@@ -240,7 +241,7 @@ A **Search** field at the top of the sidebar opens the command palette (⌘K). C
     - Model Setup (`/settings/model-setup`) is a subpage of Model Providers, launched from its header.
     - Agents: a settings page (**Settings → Agents**, `/settings/agents`) with per-agent tabs (Overview, Files, Tools, Skills, Channels, Automations, Memory). The Overview tab edits the agent's identity — display name, emoji, and an avatar image that is downscaled and size-bounded in the browser before `agents.update`. Saving stores configured identity fields and mirrors them to the workspace `IDENTITY.md`; configured values take precedence over manual edits to the same file fields.
     - Profile: a settings page showing the default agent's identity with all-time usage stats — lifetime tokens, peak day, longest session, activity streaks, a year-long token heatmap, top tools, and channel highlights (`usage.cost`, `sessions.usage`).
-    - MCP has a dedicated settings page with read-only server rows (transport, enablement, OAuth/filter/parallel summaries), common operator commands, and the scoped `mcp` config editor; adding, enabling/disabling, and removing servers happens on the Plugins page.
+    - MCP has a dedicated settings page with server rows (transport, enablement, OAuth/filter/parallel summaries), direct add/enable/disable/remove controls, common operator commands, and the scoped `mcp` config editor. The Plugins page remains the home for one-click connectors and discovery.
     - Model Providers: a settings page listing every configured model provider with its brand icon, auth state (`models.authStatus`), model availability (`models.list`), live plan/quota/billing data where the provider reports it (`usage.status`), and local session spend for the last 30 days (`sessions.usage`). A Refresh action re-reads credential state and provider usage.
     - Connection: a settings page (under **Connections**) owning the dashboard's own gateway link — WebSocket URL, gateway token, password, and default session key — plus the latest handshake snapshot (status, uptime, tick interval, last channels refresh). The offline login gate handles the disconnected case; this page edits the connection while connected.
     - Apply and restart with validation (`config.apply`), then wake the last active session.
@@ -317,7 +318,7 @@ Typical workflow:
 1. Open **MCP** from the sidebar.
 2. Check the summary cards for total, enabled, OAuth, and filtered server counts.
 3. Review each server row for transport, enablement, auth, filters, timeouts, and command hints.
-4. Manage servers (add, enable/disable, remove) on the **Plugins** page, which is the single interactive writer of `mcp.servers`; the row list here links to it.
+4. Add, enable, disable, or remove servers directly on the MCP page. Use the **Plugins** page for one-click connectors and discovery.
 5. Edit the scoped `mcp` config section for server definitions, headers, TLS/mTLS paths, OAuth metadata, tool filters, and Codex projection metadata.
 6. Use **Save** for a config write, or **Save & Publish** when the running Gateway should apply the changed config.
 7. Run `openclaw mcp status --verbose`, `openclaw mcp doctor --probe`, or `openclaw mcp reload` from a terminal for static diagnostics, live proof, or cached-runtime disposal.
diff --git a/scripts/control-ui-mock-dev.ts b/scripts/control-ui-mock-dev.ts
index 7d7424a9975..44a85c36d44 100644
--- a/scripts/control-ui-mock-dev.ts
+++ b/scripts/control-ui-mock-dev.ts
@@ -550,6 +550,17 @@ function buildConfigMocks() {
     gateway: { port: 18789, bind: "127.0.0.1" },
     agents: { defaults: { thinkingDefault: "medium" } },
     models: { mode: "merge" },
+    mcp: {
+      servers: {
+        context7: { url: "https://mcp.context7.com/mcp", transport: "streamable-http" },
+        github: {
+          url: "https://api.githubcopilot.com/mcp/",
+          transport: "streamable-http",
+          auth: "oauth",
+        },
+        "local-tools": { command: "npx", args: ["some-mcp-server", "--stdio"], enabled: false },
+      },
+    },
   };
   const schema = {
     type: "object",
diff --git a/ui/src/components/mcp-server-form.ts b/ui/src/components/mcp-server-form.ts
new file mode 100644
index 00000000000..4d4ea9556bb
--- /dev/null
+++ b/ui/src/components/mcp-server-form.ts
@@ -0,0 +1,71 @@
+import { html, type TemplateResult } from "lit";
+import { t } from "../i18n/index.ts";
+
+export type McpServerForm = {
+  name: string;
+  target: string;
+};
+
+export function renderMcpServerForm(props: {
+  busy: boolean;
+  disabled?: boolean;
+  blockedReason?: string | null;
+  onSubmit: (form: McpServerForm) => void;
+  onCancel: () => void;
+}): TemplateResult {
+  const disabled = props.busy || props.disabled === true;
+  const submit = (event: Event) => {
+    event.preventDefault();
+    const form = event.currentTarget as HTMLFormElement;
+    const data = new FormData(form);
+    const name = data.get("mcp-name");
+    const target = data.get("mcp-target");
+    props.onSubmit({
+      name: typeof name === "string" ? name.trim() : "",
+      target: typeof target === "string" ? target.trim() : "",
+    });
+  };
+  return html`
+    <form class="mcp-server-form" @submit=${submit}>
+      <label>
+        <span>${t("mcpServers.nameLabel")}</span>
+        <input
+          name="mcp-name"
+          class="settings-input"
+          type="text"
+          required
+          placeholder="context7"
+          autocomplete="off"
+          title=${props.blockedReason ?? ""}
+          ?disabled=${disabled}
+        />
+      </label>
+      <label class="mcp-server-form__target">
+        <span>${t("mcpServers.targetLabel")}</span>
+        <input
+          name="mcp-target"
+          class="settings-input"
+          type="text"
+          required
+          placeholder="https://mcp.example.com/mcp  ·  npx some-mcp-server"
+          autocomplete="off"
+          title=${props.blockedReason ?? ""}
+          ?disabled=${disabled}
+        />
+      </label>
+      <div class="mcp-server-form__actions">
+        <button
+          type="submit"
+          class="btn btn--sm"
+          title=${props.blockedReason ?? ""}
+          ?disabled=${disabled}
+        >
+          ${props.busy ? t("mcpServers.adding") : t("mcpServers.add")}
+        </button>
+        <button type="button" class="btn btn--sm" ?disabled=${props.busy} @click=${props.onCancel}>
+          ${t("common.cancel")}
+        </button>
+      </div>
+    </form>
+  `;
+}
diff --git a/ui/src/components/mcp-servers-card.test.ts b/ui/src/components/mcp-servers-card.test.ts
new file mode 100644
index 00000000000..a57753d216e
--- /dev/null
+++ b/ui/src/components/mcp-servers-card.test.ts
@@ -0,0 +1,311 @@
+/* @vitest-environment jsdom */
+
+import { expectDefined } from "@openclaw/normalization-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ApplicationContext, ApplicationGateway } from "../app/context.ts";
+import { i18n } from "../i18n/index.ts";
+import {
+  createApplicationContextProvider,
+  type ApplicationContextProvider,
+} from "../test-helpers/application-context.ts";
+import { waitForFast } from "../test-helpers/wait-for.ts";
+import "./mcp-servers-card.ts";
+
+type McpServersCard = HTMLElementTagNameMap["openclaw-mcp-servers-card"];
+
+type RuntimeConfigHarness = {
+  runtimeConfig: ApplicationContext["runtimeConfig"];
+  ensureLoaded: ReturnType<typeof vi.fn<() => Promise<void>>>;
+  patch: ReturnType<
+    typeof vi.fn<(options: { raw: Record<string, unknown>; note: string }) => Promise<boolean>>
+  >;
+};
+
+function createGateway(options: { connected?: boolean; admin?: boolean } = {}): ApplicationGateway {
+  const connected = options.connected ?? true;
+  const admin = options.admin ?? true;
+  const snapshot = {
+    client: null,
+    connected,
+    reconnecting: !connected,
+    hello: {
+      type: "hello-ok" as const,
+      protocol: 1,
+      auth: {
+        role: "operator",
+        scopes: admin ? ["operator.read", "operator.admin"] : ["operator.read"],
+      },
+    },
+    assistantAgentId: "main",
+    sessionKey: "main",
+    lastError: null,
+    lastErrorCode: null,
+  };
+  return {
+    snapshot,
+    connection: { gatewayUrl: "ws://localhost", token: "", password: "", bootstrapToken: "" },
+    eventLog: [],
+    connect: () => undefined,
+    setSessionKey: () => undefined,
+    start: () => undefined,
+    stop: () => undefined,
+    subscribe: () => () => undefined,
+    subscribeEventLog: () => () => undefined,
+    subscribeEvents: () => () => undefined,
+  } as unknown as ApplicationGateway;
+}
+
+function createRuntimeConfig(config: Record<string, unknown>): RuntimeConfigHarness {
+  const ensureLoaded = vi.fn(async () => undefined);
+  const patch = vi.fn<
+    (options: { raw: Record<string, unknown>; note: string }) => Promise<boolean>
+  >(async () => true);
+  const listeners = new Set<() => void>();
+  const runtimeConfig = {
+    state: {
+      configSnapshot: { sourceConfig: config, hash: "base" },
+      lastError: null,
+    },
+    ensureLoaded,
+    patch,
+    refresh: vi.fn(async () => undefined),
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  } as unknown as ApplicationContext["runtimeConfig"];
+  return { runtimeConfig, ensureLoaded, patch };
+}
+
+async function mountCard(
+  options: {
+    config?: Record<string, unknown>;
+    connected?: boolean;
+    admin?: boolean;
+  } = {},
+): Promise<{
+  card: McpServersCard;
+  provider: ApplicationContextProvider;
+  harness: RuntimeConfigHarness;
+}> {
+  const harness = createRuntimeConfig(options.config ?? { mcp: { servers: {} } });
+  const context = {
+    gateway: createGateway({ connected: options.connected, admin: options.admin }),
+    runtimeConfig: harness.runtimeConfig,
+    basePath: "",
+  } as unknown as ApplicationContext;
+  const provider = createApplicationContextProvider(context);
+  const card = document.createElement("openclaw-mcp-servers-card");
+  card.pluginsHref = "/settings/plugins";
+  provider.append(card);
+  document.body.append(provider);
+  await card.updateComplete;
+  await waitForFast(() => expect(harness.ensureLoaded).toHaveBeenCalled());
+  await card.updateComplete;
+  return { card, provider, harness };
+}
+
+function actionButton(container: Element, label: string): HTMLButtonElement {
+  const button = [...container.querySelectorAll<HTMLButtonElement>("button")].find((candidate) =>
+    (candidate.getAttribute("aria-label") ?? candidate.textContent ?? "").includes(label),
+  );
+  return expectDefined(button, `${label} button`);
+}
+
+async function submitAddForm(card: McpServersCard, name: string, target: string) {
+  actionButton(card, "Add server").click();
+  await card.updateComplete;
+  const form = expectDefined(card.querySelector<HTMLFormElement>(".mcp-server-form"), "MCP form");
+  expectDefined(form.querySelector<HTMLInputElement>('[name="mcp-name"]'), "name input").value =
+    name;
+  expectDefined(form.querySelector<HTMLInputElement>('[name="mcp-target"]'), "target input").value =
+    target;
+  form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
+}
+
+function firstPatchCall(harness: RuntimeConfigHarness) {
+  return expectDefined(
+    expectDefined(harness.patch.mock.calls[0], "config patch call")[0],
+    "config patch payload",
+  );
+}
+
+describe("openclaw-mcp-servers-card", () => {
+  beforeEach(async () => {
+    await i18n.setLocale("en");
+  });
+
+  afterEach(() => {
+    document.body.replaceChildren();
+    vi.restoreAllMocks();
+  });
+
+  it("renders rich rows without exposing URL credentials or stdio arguments", async () => {
+    const { card } = await mountCard({
+      config: {
+        mcp: {
+          servers: {
+            docs: {
+              url: "https://mcp.example.com/mcp?keep=visible&token=test-token",
+              auth: "oauth",
+              toolFilter: { include: ["search"] },
+              sslVerify: false,
+            },
+            local: {
+              command: "node",
+              args: ["server.js", "--token", "test-token"],
+              enabled: false,
+              supportsParallelToolCalls: true,
+              clientCert: "/tmp/client.pem",
+            },
+            // Config files can carry names the add form would reject; the
+            // command snippet must stay shell-safe for copy/paste.
+            "docs; echo unsafe": { url: "https://mcp.example.com/mcp" },
+          },
+        },
+      },
+    });
+
+    const docs = expectDefined(card.querySelector('[data-mcp-name="docs"]'), "docs row");
+    expect(docs.textContent).toContain("https://mcp.example.com/mcp?keep=visible&token=***");
+    expect(docs.textContent).toContain("http · oauth · tool filter · TLS verify off");
+    expect(docs.textContent).toContain("openclaw mcp login docs");
+    expect(docs.textContent).not.toContain("test-token");
+
+    const local = expectDefined(card.querySelector('[data-mcp-name="local"]'), "local row");
+    expect(local.textContent).toContain("node");
+    expect(local.textContent).toContain("stdio · parallel · mTLS");
+    expect(local.textContent).toContain("openclaw mcp probe local");
+    expect(local.textContent).not.toContain("server.js");
+    expect(local.textContent).not.toContain("test-token");
+
+    const hostile = expectDefined(
+      card.querySelector('[data-mcp-name="docs; echo unsafe"]'),
+      "hostile-name row",
+    );
+    expect(hostile.textContent).toContain("openclaw mcp probe 'docs; echo unsafe'");
+  });
+
+  it("renders the empty state when no servers are configured", async () => {
+    const { card } = await mountCard();
+
+    expect(card.querySelector(".settings-empty")?.textContent).toContain(
+      "No MCP servers configured.",
+    );
+  });
+
+  it.each([
+    {
+      label: "streamable HTTP URL",
+      target: "https://mcp.context7.com/mcp",
+      expected: { url: "https://mcp.context7.com/mcp", transport: "streamable-http" },
+    },
+    {
+      label: "SSE URL",
+      target: "https://mcp.example.com/sse?token=test",
+      expected: { url: "https://mcp.example.com/sse?token=test", transport: "sse" },
+    },
+    {
+      label: "stdio command",
+      target: "npx some-mcp-server --stdio",
+      expected: { command: "npx", args: ["some-mcp-server", "--stdio"] },
+    },
+  ])("adds a server from a $label", async ({ target, expected }) => {
+    const { card, harness } = await mountCard();
+
+    await submitAddForm(card, "context7", target);
+
+    await waitForFast(() => expect(harness.patch).toHaveBeenCalledOnce());
+    expect(firstPatchCall(harness)).toEqual({
+      raw: { mcp: { servers: { context7: expected } } },
+      note: "mcp settings: add server context7",
+    });
+    await waitForFast(() =>
+      expect(card.querySelector('[role="status"]')?.textContent).toContain(
+        "Added MCP server context7.",
+      ),
+    );
+    expect(card.querySelector(".mcp-server-form")).toBeNull();
+  });
+
+  it("rejects an invalid name before patching", async () => {
+    const { card, harness } = await mountCard();
+
+    await submitAddForm(card, "bad name!", "https://mcp.example.com/mcp");
+
+    await waitForFast(() =>
+      expect(card.querySelector('[role="alert"]')?.textContent).toContain("Server names use"),
+    );
+    expect(harness.patch).not.toHaveBeenCalled();
+  });
+
+  it("rejects a duplicate name before patching", async () => {
+    const { card, harness } = await mountCard({
+      config: { mcp: { servers: { docs: { url: "https://mcp.example.com/mcp" } } } },
+    });
+
+    await submitAddForm(card, "docs", "https://other.example.com/mcp");
+
+    await waitForFast(() =>
+      expect(card.querySelector('[role="alert"]')?.textContent).toContain(
+        "An MCP server named “docs” already exists.",
+      ),
+    );
+    expect(harness.patch).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    {
+      current: { command: "node", enabled: false },
+      action: "Enable",
+      expected: { enabled: null },
+      note: "mcp settings: enable server local",
+    },
+    {
+      current: { command: "node" },
+      action: "Disable",
+      expected: { enabled: false },
+      note: "mcp settings: disable server local",
+    },
+  ])("writes the exact merge patch for $action", async ({ current, action, expected, note }) => {
+    const { card, harness } = await mountCard({
+      config: { mcp: { servers: { local: current } } },
+    });
+
+    actionButton(card, action).click();
+
+    await waitForFast(() => expect(harness.patch).toHaveBeenCalledOnce());
+    expect(firstPatchCall(harness)).toEqual({
+      raw: { mcp: { servers: { local: expected } } },
+      note,
+    });
+  });
+
+  it("removes a server with an explicit merge-patch null", async () => {
+    const { card, harness } = await mountCard({
+      config: { mcp: { servers: { docs: { url: "https://mcp.example.com/mcp" } } } },
+    });
+
+    actionButton(card, "Remove docs").click();
+
+    await waitForFast(() => expect(harness.patch).toHaveBeenCalledOnce());
+    expect(firstPatchCall(harness)).toEqual({
+      raw: { mcp: { servers: { docs: null } } },
+      note: "mcp settings: remove server docs",
+    });
+  });
+
+  it("disables mutation controls without operator.admin access", async () => {
+    const { card, harness } = await mountCard({
+      admin: false,
+      config: { mcp: { servers: { docs: { url: "https://mcp.example.com/mcp" } } } },
+    });
+
+    const controls = [...card.querySelectorAll<HTMLButtonElement>("button")];
+    expect(controls.length).toBeGreaterThan(0);
+    expect(controls.every((button) => button.disabled)).toBe(true);
+    expect(controls.every((button) => button.title.includes("operator.admin"))).toBe(true);
+    actionButton(card, "Disable").click();
+    expect(harness.patch).not.toHaveBeenCalled();
+  });
+});
diff --git a/ui/src/components/mcp-servers-card.ts b/ui/src/components/mcp-servers-card.ts
new file mode 100644
index 00000000000..d2b49db21da
--- /dev/null
+++ b/ui/src/components/mcp-servers-card.ts
@@ -0,0 +1,287 @@
+import { consume } from "@lit/context";
+import { html, nothing, type TemplateResult } from "lit";
+import { property, state } from "lit/decorators.js";
+import { applicationContext, type ApplicationContext } from "../app/context.ts";
+import { hasOperatorAdminAccess } from "../app/operator-access.ts";
+import { t } from "../i18n/index.ts";
+import { resolveEditableSnapshotConfig } from "../lib/config/index.ts";
+import {
+  buildAddMcpServerPatch,
+  buildRemoveMcpServerPatch,
+  buildToggleMcpServerPatch,
+  MCP_SERVER_NAME_PATTERN,
+  parseMcpTarget,
+  patchMcpServers,
+  summarizeMcpServers,
+  type McpServerSummary,
+  type McpServersPatchBuildResult,
+} from "../lib/config/mcp-servers.ts";
+import { OpenClawLightDomElement } from "../lit/openclaw-element.ts";
+import { SubscriptionsController } from "../lit/subscriptions-controller.ts";
+import { icons } from "./icons.ts";
+import { renderMcpServerForm, type McpServerForm } from "./mcp-server-form.ts";
+import { renderSettingsEmpty, renderSettingsSection, renderSettingsStatus } from "./settings-ui.ts";
+
+type McpServerMessage = { kind: "error" | "success"; text: string };
+
+function quoteShellArg(value: string): string {
+  return /^[A-Za-z0-9._:/-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function tlsLabel(tls: McpServerSummary["tls"]): string | null {
+  switch (tls) {
+    case "verify-off":
+      return t("mcpPage.tlsVerifyOff");
+    case "mtls":
+      return t("mcpPage.mtls");
+    default:
+      return null;
+  }
+}
+
+class McpServersCard extends OpenClawLightDomElement {
+  @consume({ context: applicationContext, subscribe: true })
+  private context?: ApplicationContext;
+
+  @property() pluginsHref = "";
+
+  @state() private rows: McpServerSummary[] | null = null;
+  @state() private busy = false;
+  @state() private message: McpServerMessage | null = null;
+  @state() private formOpen = false;
+
+  private readonly subscriptions = new SubscriptionsController(this)
+    .effect(
+      () => this.context?.runtimeConfig,
+      (runtimeConfig) => {
+        this.syncRows();
+        void runtimeConfig
+          .ensureLoaded()
+          .then(() => this.syncRows())
+          .catch((error: unknown) => {
+            this.message = {
+              kind: "error",
+              text: error instanceof Error ? error.message : String(error),
+            };
+          });
+        return runtimeConfig.subscribe(() => this.syncRows());
+      },
+    )
+    .effect(
+      () => this.context?.gateway,
+      (gateway) => gateway.subscribe(() => this.requestUpdate()),
+    );
+
+  override disconnectedCallback() {
+    this.subscriptions.clear();
+    super.disconnectedCallback();
+  }
+
+  private syncRows() {
+    const snapshot = this.context?.runtimeConfig.state.configSnapshot;
+    this.rows = summarizeMcpServers(resolveEditableSnapshotConfig(snapshot));
+  }
+
+  private mutationBlockedReason(): string | null {
+    const gateway = this.context?.gateway;
+    if (!gateway?.snapshot.connected) {
+      return t("mcpServers.connectRequired");
+    }
+    if (!hasOperatorAdminAccess(gateway.snapshot.hello?.auth ?? null)) {
+      return t("mcpServers.adminRequired");
+    }
+    return null;
+  }
+
+  private canMutate(): boolean {
+    return this.context !== undefined && this.mutationBlockedReason() === null;
+  }
+
+  private async mutate(options: {
+    buildPatch: (servers: Readonly<Record<string, unknown>>) => McpServersPatchBuildResult;
+    note: string;
+    successText: string;
+  }): Promise<boolean> {
+    if (!this.context || !this.canMutate() || this.busy) {
+      return false;
+    }
+    this.busy = true;
+    this.message = null;
+    const result = await patchMcpServers(this.context.runtimeConfig, options);
+    this.busy = false;
+    if (!result.ok) {
+      this.message = { kind: "error", text: result.error };
+      return false;
+    }
+    this.syncRows();
+    this.message = { kind: "success", text: options.successText };
+    return true;
+  }
+
+  private async addServer(form: McpServerForm) {
+    const name = form.name.trim();
+    if (!MCP_SERVER_NAME_PATTERN.test(name)) {
+      this.message = { kind: "error", text: t("mcpServers.nameInvalid") };
+      return;
+    }
+    const config = parseMcpTarget(form.target);
+    if (!config) {
+      this.message = { kind: "error", text: t("mcpServers.targetInvalid") };
+      return;
+    }
+    const added = await this.mutate({
+      buildPatch: (servers) => buildAddMcpServerPatch(servers, name, config),
+      note: `mcp settings: add server ${name}`,
+      successText: t("mcpServers.addedSuccess", { name }),
+    });
+    if (added) {
+      this.formOpen = false;
+    }
+  }
+
+  private async toggleServer(name: string, enabled: boolean) {
+    await this.mutate({
+      buildPatch: (servers) => buildToggleMcpServerPatch(servers, name, enabled),
+      note: `mcp settings: ${enabled ? "enable" : "disable"} server ${name}`,
+      successText: t(enabled ? "mcpServers.enabledSuccess" : "mcpServers.disabledSuccess", {
+        name,
+      }),
+    });
+  }
+
+  private async removeServer(name: string) {
+    await this.mutate({
+      buildPatch: (servers) => buildRemoveMcpServerPatch(servers, name),
+      note: `mcp settings: remove server ${name}`,
+      successText: t("mcpServers.removedSuccess", { name }),
+    });
+  }
+
+  private renderRow(server: McpServerSummary): TemplateResult {
+    const command = `openclaw mcp ${server.auth === "oauth" ? "login" : "probe"} ${quoteShellArg(
+      server.name,
+    )}`;
+    const meta = [
+      server.transport,
+      server.auth,
+      server.toolFilter ? t("mcpPage.toolFilter") : null,
+      server.parallel ? t("mcpPage.parallel") : null,
+      tlsLabel(server.tls),
+    ].filter((part): part is string => Boolean(part));
+    const blockedReason = this.mutationBlockedReason();
+    const disabled = this.busy || !this.canMutate();
+    return html`
+      <div class="settings-row mcp-server-row" data-mcp-name=${server.name}>
+        <div class="settings-row__text">
+          <span class="settings-row__title">${server.name}</span>
+          <span class="settings-row__desc mcp-server-row__launch">
+            ${server.target || t("mcpServers.missingTransport")}
+          </span>
+          <span class="settings-row__desc">${meta.join(" · ")}</span>
+        </div>
+        <div class="settings-row__control">
+          ${renderSettingsStatus({
+            kind: server.enabled ? "ok" : "muted",
+            label: server.enabled ? t("common.enabled") : t("common.disabled"),
+          })}
+          <code>${command}</code>
+          <button
+            type="button"
+            class="btn btn--sm"
+            title=${blockedReason ?? ""}
+            ?disabled=${disabled}
+            @click=${() => void this.toggleServer(server.name, !server.enabled)}
+          >
+            ${this.busy
+              ? t("mcpServers.working")
+              : server.enabled
+                ? t("mcpServers.disable")
+                : t("mcpServers.enable")}
+          </button>
+          <button
+            type="button"
+            class="btn btn--sm btn--icon mcp-server-remove"
+            aria-label=${t("mcpServers.removeNamed", { name: server.name })}
+            title=${blockedReason ?? t("mcpServers.removeNamed", { name: server.name })}
+            ?disabled=${disabled}
+            @click=${() => void this.removeServer(server.name)}
+          >
+            ${icons.trash}
+          </button>
+        </div>
+      </div>
+    `;
+  }
+
+  override render() {
+    const blockedReason = this.mutationBlockedReason();
+    const rows = this.rows;
+    const body = !rows
+      ? html`<div class="mcp-server-loading" role="status">${t("common.loading")}</div>`
+      : rows.length === 0
+        ? renderSettingsEmpty(t("mcpPage.noServers"))
+        : rows.map((server) => this.renderRow(server));
+    return html`
+      <div class="mcp-server-list">
+        ${renderSettingsSection(
+          {
+            title: t("mcpPage.configuredServers"),
+            description: html`
+              ${t("mcpPage.runtimeHint")}
+              <a href=${this.pluginsHref}>${t("mcpPage.connectorsLink")}</a>
+            `,
+            actions: html`
+              <button
+                type="button"
+                class="btn btn--sm"
+                title=${blockedReason ?? ""}
+                ?disabled=${this.busy || !this.canMutate()}
+                @click=${() => {
+                  this.formOpen = !this.formOpen;
+                  if (this.formOpen) {
+                    this.message = null;
+                  }
+                }}
+              >
+                <span aria-hidden="true">${icons.plus}</span>
+                ${t("mcpServers.add")}
+              </button>
+            `,
+          },
+          html`
+            ${this.formOpen
+              ? renderMcpServerForm({
+                  busy: this.busy,
+                  disabled: !this.canMutate(),
+                  blockedReason,
+                  onSubmit: (form) => void this.addServer(form),
+                  onCancel: () => {
+                    this.formOpen = false;
+                  },
+                })
+              : nothing}
+            ${this.message
+              ? html`<div
+                  class="mcp-server-message mcp-server-message--${this.message.kind}"
+                  role=${this.message.kind === "error" ? "alert" : "status"}
+                >
+                  ${this.message.text}
+                </div>`
+              : nothing}
+            ${body}
+          `,
+        )}
+      </div>
+    `;
+  }
+}
+
+if (!customElements.get("openclaw-mcp-servers-card")) {
+  customElements.define("openclaw-mcp-servers-card", McpServersCard);
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "openclaw-mcp-servers-card": McpServersCard;
+  }
+}
diff --git a/ui/src/i18n/.i18n/raw-copy-baseline.json b/ui/src/i18n/.i18n/raw-copy-baseline.json
index 2422ac6dfde..ac21cb69192 100644
--- a/ui/src/i18n/.i18n/raw-copy-baseline.json
+++ b/ui/src/i18n/.i18n/raw-copy-baseline.json
@@ -99,6 +99,20 @@
       "path": "ui/src/components/login-gate.ts",
       "text": "OpenClaw"
     },
+    {
+      "count": 1,
+      "kind": "html-attribute",
+      "name": "placeholder",
+      "path": "ui/src/components/mcp-server-form.ts",
+      "text": "context7"
+    },
+    {
+      "count": 1,
+      "kind": "html-attribute",
+      "name": "placeholder",
+      "path": "ui/src/components/mcp-server-form.ts",
+      "text": "https://mcp.example.com/mcp · npx some-mcp-server"
+    },
     {
       "count": 1,
       "kind": "html-text",
@@ -610,20 +624,6 @@
       "path": "ui/src/pages/nodes/view-exec-approvals.ts",
       "text": "exec host=gateway/node"
     },
-    {
-      "count": 1,
-      "kind": "html-attribute",
-      "name": "placeholder",
-      "path": "ui/src/pages/plugins/view.ts",
-      "text": "context7"
-    },
-    {
-      "count": 1,
-      "kind": "html-attribute",
-      "name": "placeholder",
-      "path": "ui/src/pages/plugins/view.ts",
-      "text": "https://mcp.example.com/mcp · npx some-mcp-server"
-    },
     {
       "count": 4,
       "kind": "html-text",
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 8ad97b84c24..3a5f8e393e4 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -1861,8 +1861,30 @@ export const en: TranslationMap = {
     connectionChanged: "The Gateway connection changed. Retry to continue this setup.",
     unsupportedGateway: "Update the Gateway to continue setup with OpenClaw.",
   },
+  mcpServers: {
+    add: "Add server",
+    adding: "Adding…",
+    nameLabel: "Name",
+    targetLabel: "URL or command",
+    nameInvalid: "Server names use letters, numbers, dots, dashes, or underscores.",
+    targetInvalid: "Enter an http(s) URL or a command line.",
+    nameTaken: "An MCP server named “{name}” already exists.",
+    missing: "MCP server “{name}” was not found in the configuration.",
+    missingTransport: "missing transport",
+    addedSuccess: "Added MCP server {name}.",
+    enabledSuccess: "Enabled MCP server {name}.",
+    disabledSuccess: "Disabled MCP server {name}.",
+    removedSuccess: "Removed MCP server {name}.",
+    configUnavailable: "Configuration is unavailable; refresh and try again.",
+    connectRequired: "Connect to the gateway to change MCP servers.",
+    adminRequired: "MCP server changes require operator.admin access.",
+    enable: "Enable",
+    disable: "Disable",
+    removeNamed: "Remove {name}",
+    working: "Working…",
+  },
   mcpPage: {
-    manageServersLink: "Manage servers on the Plugins page.",
+    connectorsLink: "Discover one-click connectors on the Plugins page.",
     servers: "Servers",
     oauth: "OAuth",
     filtered: "Filtered",
@@ -1874,7 +1896,6 @@ export const en: TranslationMap = {
       "Edits save automatically; runtime changes apply after a gateway restart, and active agents rebuild MCP runtimes on next use.",
     toolFilter: "tool filter",
     parallel: "parallel",
-    missingTransport: "missing transport",
     tlsVerifyOff: "TLS verify off",
     mtls: "mTLS",
   },
@@ -1963,18 +1984,7 @@ export const en: TranslationMap = {
     mcpSettingsLink: "MCP settings",
     mcpHint:
       "Connect Model Context Protocol servers to give your agent extra tools. Changes apply to new agent sessions.",
-    mcpAdd: "Add server",
-    mcpAdding: "Adding…",
     mcpEmpty: "No MCP servers configured yet. Add one here or pick a connector from Discover.",
-    mcpNameLabel: "Name",
-    mcpTargetLabel: "URL or command",
-    mcpNameInvalid: "Server names use letters, numbers, dots, dashes, or underscores.",
-    mcpTargetInvalid: "Enter an http(s) URL or a command line.",
-    mcpNameTaken: "An MCP server named “{name}” already exists.",
-    mcpMissing: "MCP server “{name}” was not found in the configuration.",
-    mcpAddedSuccess: "Added MCP server {name}.",
-    mcpRemovedSuccess: "Removed MCP server {name}.",
-    mcpConfigUnavailable: "Configuration is unavailable; refresh and try again.",
     remove: "Remove",
     removing: "Removing…",
     removeNamed: "Remove {name}",
diff --git a/ui/src/lib/config/mcp-servers.ts b/ui/src/lib/config/mcp-servers.ts
new file mode 100644
index 00000000000..9c636ab711d
--- /dev/null
+++ b/ui/src/lib/config/mcp-servers.ts
@@ -0,0 +1,137 @@
+import { redactSensitiveUrlLikeString } from "@openclaw/net-policy/redact-sensitive-url";
+import { asNullableRecord as asRecord } from "@openclaw/normalization-core/record-coerce";
+import { t } from "../../i18n/index.ts";
+import { resolveEditableSnapshotConfig, type RuntimeConfigCapability } from "./index.ts";
+
+export const MCP_SERVER_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+export type McpServerSummary = {
+  name: string;
+  enabled: boolean;
+  transport: "http" | "stdio" | "invalid";
+  target: string;
+  auth: string | null;
+  toolFilter: boolean;
+  parallel: boolean;
+  tls: "verify-off" | "mtls" | null;
+};
+
+export type McpServersPatchBuildResult = { patch: Record<string, unknown> } | { error: string };
+
+export function parseMcpTarget(target: string): Record<string, unknown> | null {
+  if (/^https?:\/\//i.test(target)) {
+    // The runtime defaults URL-only servers to SSE; modern MCP endpoints are
+    // streamable HTTP unless the /sse path convention says otherwise.
+    const transport = /\/sse\/?$/i.test(target.split("?")[0] ?? target) ? "sse" : "streamable-http";
+    return { url: target, transport };
+  }
+  const [command, ...args] = target.trim().split(/\s+/u);
+  if (!command) {
+    return null;
+  }
+  return args.length > 0 ? { command, args } : { command };
+}
+
+export function summarizeMcpServers(
+  config: Record<string, unknown> | null,
+): McpServerSummary[] | null {
+  if (!config) {
+    return null;
+  }
+  const servers = asRecord(asRecord(config.mcp)?.servers) ?? {};
+  return Object.entries(servers)
+    .map(([name, value]) => {
+      const server = asRecord(value) ?? {};
+      const url = typeof server.url === "string" ? server.url : "";
+      // Command only: stdio args routinely carry tokens, and this projection
+      // is visible to read-only operators.
+      const command = typeof server.command === "string" ? server.command : "";
+      return {
+        name,
+        enabled: server.enabled !== false,
+        transport: url ? ("http" as const) : command ? ("stdio" as const) : ("invalid" as const),
+        target: url ? redactSensitiveUrlLikeString(url) : command,
+        auth: typeof server.auth === "string" ? server.auth : null,
+        toolFilter: Boolean(server.toolFilter),
+        parallel: server.supportsParallelToolCalls === true,
+        tls:
+          server.sslVerify === false
+            ? ("verify-off" as const)
+            : server.clientCert || server.clientKey
+              ? ("mtls" as const)
+              : null,
+      };
+    })
+    .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+export function buildAddMcpServerPatch(
+  servers: Readonly<Record<string, unknown>>,
+  name: string,
+  config: Record<string, unknown>,
+): McpServersPatchBuildResult {
+  return Object.hasOwn(servers, name)
+    ? { error: t("mcpServers.nameTaken", { name }) }
+    : { patch: { [name]: config } };
+}
+
+export function buildToggleMcpServerPatch(
+  servers: Readonly<Record<string, unknown>>,
+  name: string,
+  enabled: boolean,
+): McpServersPatchBuildResult {
+  if (!Object.hasOwn(servers, name)) {
+    return { error: t("mcpServers.missing", { name }) };
+  }
+  // Enabling deletes the key so the config keeps its enabled-by-default shape.
+  return { patch: { [name]: { enabled: enabled ? null : false } } };
+}
+
+export function buildRemoveMcpServerPatch(
+  servers: Readonly<Record<string, unknown>>,
+  name: string,
+): McpServersPatchBuildResult {
+  return Object.hasOwn(servers, name)
+    ? { patch: { [name]: null } }
+    : { error: t("mcpServers.missing", { name }) };
+}
+
+/**
+ * Apply one mutation to config.mcp.servers through the shared config seam.
+ * config.patch uses RFC 7396 merge semantics, so `buildPatch` must return a
+ * minimal fragment (with explicit nulls for deletions), never a full config.
+ */
+export async function patchMcpServers(
+  runtimeConfig: RuntimeConfigCapability,
+  options: {
+    buildPatch: (servers: Readonly<Record<string, unknown>>) => McpServersPatchBuildResult;
+    note: string;
+  },
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    await runtimeConfig.ensureLoaded();
+    const base = resolveEditableSnapshotConfig(runtimeConfig.state.configSnapshot);
+    if (!base) {
+      return { ok: false, error: t("mcpServers.configUnavailable") };
+    }
+    const servers = asRecord(asRecord(base.mcp)?.servers) ?? {};
+    const built = options.buildPatch(servers);
+    if ("error" in built) {
+      return { ok: false, error: built.error };
+    }
+    const patched = await runtimeConfig.patch({
+      raw: { mcp: { servers: built.patch } },
+      note: options.note,
+    });
+    if (!patched) {
+      return {
+        ok: false,
+        error: runtimeConfig.state.lastError ?? t("mcpServers.configUnavailable"),
+      };
+    }
+    await runtimeConfig.refresh();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
diff --git a/ui/src/pages/config/config-page.test.ts b/ui/src/pages/config/config-page.test.ts
index dd38a70a963..bebe881ab81 100644
--- a/ui/src/pages/config/config-page.test.ts
+++ b/ui/src/pages/config/config-page.test.ts
@@ -11,6 +11,7 @@ import type {
 } from "../../app/context.ts";
 import { createStorageMock } from "../../test-helpers/storage.ts";
 import { ConfigPage, configSelectionFromSearch, supportsSystemInfo } from "./config-page.ts";
+import { configSectionKeysForPage } from "./config-sections.ts";
 import type { ConfigViewState } from "./view.ts";
 
 function deferred<T>() {
@@ -48,6 +49,28 @@ describe("configSelectionFromSearch", () => {
       activeSubsection: null,
     });
   });
+
+  it("keeps MCP separate from Infrastructure", () => {
+    expect(configSectionKeysForPage("mcp")).toEqual(["mcp"]);
+    expect(configSectionKeysForPage("infrastructure")).toEqual([
+      "gateway",
+      "web",
+      "browser",
+      "nodeHost",
+      "canvasHost",
+      "discovery",
+      "media",
+      "acp",
+    ]);
+    expect(configSelectionFromSearch("mcp", "?section=browser")).toEqual({
+      activeSection: "mcp",
+      activeSubsection: null,
+    });
+    expect(configSelectionFromSearch("infrastructure", "?section=mcp")).toEqual({
+      activeSection: "gateway",
+      activeSubsection: null,
+    });
+  });
 });
 
 describe("supportsSystemInfo", () => {
@@ -75,6 +98,10 @@ describe("ConfigPage advanced selection guard", () => {
       activeSection: "env",
       activeSubsection: null,
     });
+    expect(configSelectionFromSearch("advanced", "?section=mcp")).toEqual({
+      activeSection: null,
+      activeSubsection: null,
+    });
   });
 });
 
diff --git a/ui/src/pages/config/config-page.ts b/ui/src/pages/config/config-page.ts
index 469219f9e7d..24be7ec0c72 100644
--- a/ui/src/pages/config/config-page.ts
+++ b/ui/src/pages/config/config-page.ts
@@ -825,7 +825,6 @@ export class ConfigPage extends OpenClawLightDomElement {
           activeSection: "mcp",
           activeSubsection: null,
           showModeToggle: false,
-          includeSections: ["mcp"],
           navRootLabel: "MCP",
         }),
       });
diff --git a/ui/src/pages/config/config-sections.ts b/ui/src/pages/config/config-sections.ts
index 088e66be574..dbae94d7250 100644
--- a/ui/src/pages/config/config-sections.ts
+++ b/ui/src/pages/config/config-sections.ts
@@ -43,9 +43,10 @@ export const INFRASTRUCTURE_SECTION_KEYS = [
   "discovery",
   "media",
   "acp",
-  "mcp",
 ] as const;
 
+export const MCP_SECTION_KEYS = ["mcp"] as const;
+
 export const AI_AGENTS_SECTION_KEYS = [
   "agents",
   "models",
@@ -62,6 +63,7 @@ export const SCOPED_CONFIG_SECTION_KEYS = new Set<string>([
   ...SECURITY_SECTION_KEYS,
   ...AUTOMATION_SECTION_KEYS,
   ...INFRASTRUCTURE_SECTION_KEYS,
+  ...MCP_SECTION_KEYS,
   ...AI_AGENTS_SECTION_KEYS,
 ]);
 
@@ -75,7 +77,7 @@ const CONFIG_SECTION_KEYS_BY_PAGE = {
   notifications: NOTIFICATION_SECTION_KEYS,
   security: SECURITY_SECTION_KEYS,
   automation: AUTOMATION_SECTION_KEYS,
-  mcp: INFRASTRUCTURE_SECTION_KEYS,
+  mcp: MCP_SECTION_KEYS,
   infrastructure: INFRASTRUCTURE_SECTION_KEYS,
   "ai-agents": AI_AGENTS_SECTION_KEYS,
   advanced: undefined,
diff --git a/ui/src/pages/config/mcp.test.ts b/ui/src/pages/config/mcp.test.ts
index ce9dddfab47..acd7e427cbb 100644
--- a/ui/src/pages/config/mcp.test.ts
+++ b/ui/src/pages/config/mcp.test.ts
@@ -41,36 +41,25 @@ function buttonByText(container: Element, text: string): HTMLButtonElement {
 }
 
 describe("renderMcp", () => {
-  it("summarizes configured MCP servers and links management to Plugins", () => {
+  it("renders summary counts, operator commands, and the managed servers card", () => {
     const container = document.createElement("div");
 
     render(renderMcp(createProps()), container);
 
-    expect(container.querySelector(".mcp-page__summary")?.textContent).toContain("Servers");
-    expect(container.querySelector(".mcp-server-list")?.textContent).toContain("docs");
-    expect(container.querySelector(".mcp-server-list")?.textContent).toContain("local");
-    expect(container.querySelector(".mcp-server-list")?.textContent).toContain(
-      "openclaw mcp login docs",
-    );
-
-    expect(
-      container.querySelector<HTMLAnchorElement>('a[href="/settings/plugins"]')?.textContent,
-    ).toContain("Manage servers on the Plugins page.");
-    expect(buttonByText.bind(null, container, "Enable")).toThrow();
-    expect(buttonByText.bind(null, container, "Disable")).toThrow();
-  });
-
-  it("renders an empty state when no MCP servers are configured", () => {
-    const container = document.createElement("div");
-
-    render(renderMcp(createProps({ configObject: {} })), container);
-
-    expect(container.querySelector(".settings-empty")?.textContent).toContain(
-      "No MCP servers configured.",
-    );
+    const summary = container.querySelector(".mcp-page__summary");
+    expect(summary?.textContent).toContain("Servers");
+    expect(summary?.textContent?.replace(/\s+/gu, " ")).toContain("Servers 2");
+    expect(summary?.textContent?.replace(/\s+/gu, " ")).toContain("Enabled 1");
+    expect(summary?.textContent?.replace(/\s+/gu, " ")).toContain("OAuth 1");
+    expect(summary?.textContent?.replace(/\s+/gu, " ")).toContain("Filtered 1");
+    expect(container.textContent).toContain("openclaw mcp doctor --probe");
+
+    const card = container.querySelector("openclaw-mcp-servers-card");
+    expect(card).not.toBeNull();
+    expect(card?.pluginsHref).toBe("/settings/plugins");
   });
 
-  it("keeps the summary free of save/publish actions (autosave owns them)", () => {
+  it("keeps the summary free of save actions and preserves the embedded editor", () => {
     const container = document.createElement("div");
 
     render(renderMcp(createProps()), container);
@@ -79,78 +68,4 @@ describe("renderMcp", () => {
     expect(buttonByText.bind(null, container, "Save & Publish")).toThrow();
     expect(container.querySelector(".test-editor")).not.toBeNull();
   });
-
-  it("quotes MCP server names in command snippets", () => {
-    const container = document.createElement("div");
-
-    render(
-      renderMcp(
-        createProps({
-          configObject: {
-            mcp: {
-              servers: {
-                "docs; echo unsafe": {
-                  url: "https://mcp.example.com/mcp",
-                },
-              },
-            },
-          },
-        }),
-      ),
-      container,
-    );
-
-    const text = container.querySelector(".mcp-server-list")?.textContent ?? "";
-    expect(text).toContain("openclaw mcp probe 'docs; echo unsafe'");
-  });
-
-  it("redacts sensitive URL values in server summaries", () => {
-    const container = document.createElement("div");
-
-    render(
-      renderMcp(
-        createProps({
-          configObject: {
-            mcp: {
-              servers: {
-                docs: {
-                  url: "https://user:secret@mcp.example.com/mcp?token=query-secret&keep=visible",
-                },
-              },
-            },
-          },
-        }),
-      ),
-      container,
-    );
-
-    const text = container.querySelector(".mcp-server-list")?.textContent ?? "";
-    expect(text).toContain("https://***:***@mcp.example.com/mcp?token=***&keep=visible");
-    expect(text).not.toContain("secret");
-  });
-
-  it("redacts sensitive malformed URL-like values in server summaries", () => {
-    const container = document.createElement("div");
-
-    render(
-      renderMcp(
-        createProps({
-          configObject: {
-            mcp: {
-              servers: {
-                docs: {
-                  url: "//user:secret@mcp.example.com/mcp?token=query-secret&keep=visible",
-                },
-              },
-            },
-          },
-        }),
-      ),
-      container,
-    );
-
-    const text = container.querySelector(".mcp-server-list")?.textContent ?? "";
-    expect(text).toContain("//***:***@mcp.example.com/mcp?token=***&keep=visible");
-    expect(text).not.toContain("secret");
-  });
 });
diff --git a/ui/src/pages/config/mcp.ts b/ui/src/pages/config/mcp.ts
index 9a5b3262665..433ab01f5c4 100644
--- a/ui/src/pages/config/mcp.ts
+++ b/ui/src/pages/config/mcp.ts
@@ -1,25 +1,8 @@
-// Control UI MCP Settings page presentation.
-import { redactSensitiveUrlLikeString } from "@openclaw/net-policy/redact-sensitive-url";
-import { asNullableRecord as asRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, type TemplateResult } from "lit";
-import {
-  renderSettingsEmpty,
-  renderSettingsRow,
-  renderSettingsStatus,
-  renderSettingsValue,
-} from "../../components/settings-ui.ts";
+import "../../components/mcp-servers-card.ts";
+import { renderSettingsRow, renderSettingsValue } from "../../components/settings-ui.ts";
 import { t } from "../../i18n/index.ts";
-
-type McpServerRow = {
-  name: string;
-  enabled: boolean;
-  transport: "stdio" | "http" | "invalid";
-  auth: string | null;
-  launch: string;
-  toolFilter: boolean;
-  parallel: boolean;
-  tls: string | null;
-};
+import { summarizeMcpServers } from "../../lib/config/mcp-servers.ts";
 
 type McpViewProps = {
   configObject: Record<string, unknown>;
@@ -28,72 +11,8 @@ type McpViewProps = {
   editor: TemplateResult;
 };
 
-function getMcpServers(configObject: Record<string, unknown>): Record<string, unknown> {
-  return asRecord(asRecord(configObject.mcp)?.servers) ?? {};
-}
-
-function summarizeServer(name: string, value: unknown): McpServerRow {
-  const server = asRecord(value) ?? {};
-  const url = typeof server.url === "string" ? server.url : "";
-  const command = typeof server.command === "string" ? server.command : "";
-  const transport = url ? "http" : command ? "stdio" : "invalid";
-  const auth = typeof server.auth === "string" ? server.auth : null;
-  const launch = url || command || t("mcpPage.missingTransport");
-  const tls =
-    server.sslVerify === false
-      ? t("mcpPage.tlsVerifyOff")
-      : server.clientCert || server.clientKey
-        ? t("mcpPage.mtls")
-        : null;
-  return {
-    name,
-    enabled: server.enabled !== false,
-    transport,
-    auth,
-    launch: url ? redactSensitiveUrlLikeString(launch) : launch,
-    toolFilter: Boolean(server.toolFilter),
-    parallel: server.supportsParallelToolCalls === true,
-    tls,
-  };
-}
-
-function quoteShellArg(value: string): string {
-  return /^[A-Za-z0-9._:/-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
-}
-
-function renderServerRow(server: McpServerRow) {
-  const quotedName = quoteShellArg(server.name);
-  const probeCommand = `openclaw mcp probe ${quotedName}`;
-  const loginCommand = `openclaw mcp login ${quotedName}`;
-  const meta = [
-    server.transport,
-    server.auth,
-    server.toolFilter ? t("mcpPage.toolFilter") : null,
-    server.parallel ? t("mcpPage.parallel") : null,
-    server.tls,
-  ].filter((part): part is string => Boolean(part));
-  return html`
-    <div class="settings-row mcp-server-row">
-      <div class="settings-row__text">
-        <span class="settings-row__title">${server.name}</span>
-        <span class="settings-row__desc mcp-server-row__launch">${server.launch}</span>
-        <span class="settings-row__desc">${meta.join(" · ")}</span>
-      </div>
-      <div class="settings-row__control">
-        ${renderSettingsStatus({
-          kind: server.enabled ? "ok" : "muted",
-          label: server.enabled ? t("common.enabled") : t("common.disabled"),
-        })}
-        <code>${server.auth === "oauth" ? loginCommand : probeCommand}</code>
-      </div>
-    </div>
-  `;
-}
-
 export function renderMcp(props: McpViewProps) {
-  const rows = Object.entries(getMcpServers(props.configObject))
-    .map(([name, server]) => summarizeServer(name, server))
-    .toSorted((a, b) => a.name.localeCompare(b.name));
+  const rows = summarizeMcpServers(props.configObject) ?? [];
   const enabledCount = rows.filter((row) => row.enabled).length;
   const oauthCount = rows.filter((row) => row.auth === "oauth").length;
   const filteredCount = rows.filter((row) => row.toolFilter).length;
@@ -141,20 +60,7 @@ export function renderMcp(props: McpViewProps) {
           </div>
         </section>
 
-        <section class="settings-section mcp-server-list">
-          <div class="settings-section__header">
-            <h2 class="settings-section__heading">${t("mcpPage.configuredServers")}</h2>
-          </div>
-          <p class="settings-section__desc">
-            ${t("mcpPage.runtimeHint")}
-            <a href=${props.pluginsHref}>${t("mcpPage.manageServersLink")}</a>
-          </p>
-          <div class="settings-group">
-            ${rows.length
-              ? rows.map((row) => renderServerRow(row))
-              : renderSettingsEmpty(t("mcpPage.noServers"))}
-          </div>
-        </section>
+        <openclaw-mcp-servers-card .pluginsHref=${props.pluginsHref}></openclaw-mcp-servers-card>
       </div>
 
       ${props.editor}
diff --git a/ui/src/pages/config/settings-search.ts b/ui/src/pages/config/settings-search.ts
index 05e15aa1765..1cddf93e3d9 100644
--- a/ui/src/pages/config/settings-search.ts
+++ b/ui/src/pages/config/settings-search.ts
@@ -14,6 +14,7 @@ import {
   AUTOMATION_SECTION_KEYS,
   COMMUNICATION_SECTION_KEYS,
   INFRASTRUCTURE_SECTION_KEYS,
+  MCP_SECTION_KEYS,
   SECURITY_SECTION_KEYS,
 } from "./config-sections.ts";
 import {
@@ -222,6 +223,7 @@ const COMMUNICATION_SECTIONS = new Set<string>(COMMUNICATION_SECTION_KEYS);
 const APPEARANCE_SECTIONS = new Set<string>(APPEARANCE_SECTION_KEYS);
 const SECURITY_SECTIONS = new Set<string>(SECURITY_SECTION_KEYS);
 const AUTOMATION_SECTIONS = new Set<string>(AUTOMATION_SECTION_KEYS);
+const MCP_SECTIONS = new Set<string>(MCP_SECTION_KEYS);
 const INFRASTRUCTURE_SECTIONS = new Set<string>(INFRASTRUCTURE_SECTION_KEYS);
 const AI_AGENTS_SECTIONS = new Set<string>(AI_AGENTS_SECTION_KEYS);
 
@@ -236,7 +238,7 @@ function resolveStaticSettingsBlock(block: StaticSettingsBlockDescriptor): Stati
 }
 
 function routeForConfigSection(key: string): RouteId {
-  if (key === "mcp") {
+  if (MCP_SECTIONS.has(key)) {
     return "mcp";
   }
   if (COMMUNICATION_SECTIONS.has(key)) {
diff --git a/ui/src/pages/plugins/plugins-page.test.ts b/ui/src/pages/plugins/plugins-page.test.ts
index dbc72fa9a5e..f424a5b30b4 100644
--- a/ui/src/pages/plugins/plugins-page.test.ts
+++ b/ui/src/pages/plugins/plugins-page.test.ts
@@ -869,7 +869,7 @@ describe("PluginsPage", () => {
     addButton?.click();
     await page.updateComplete;
 
-    const form = page.querySelector<HTMLFormElement>(".plugins-mcp-form")!;
+    const form = page.querySelector<HTMLFormElement>(".mcp-server-form")!;
     form.querySelector<HTMLInputElement>('[name="mcp-name"]')!.value = "context7";
     form.querySelector<HTMLInputElement>('[name="mcp-target"]')!.value =
       "https://mcp.context7.com/mcp";
@@ -1021,7 +1021,7 @@ describe("PluginsPage", () => {
     ].find((button) => button.textContent?.includes("Add server"));
     addButton?.click();
     await page.updateComplete;
-    const form = page.querySelector<HTMLFormElement>(".plugins-mcp-form")!;
+    const form = page.querySelector<HTMLFormElement>(".mcp-server-form")!;
     form.querySelector<HTMLInputElement>('[name="mcp-name"]')!.value = "bad name!";
     form.querySelector<HTMLInputElement>('[name="mcp-target"]')!.value = "https://x.example/mcp";
     form.dispatchEvent(new Event("submit", { bubbles: true, cancelable: true }));
diff --git a/ui/src/pages/plugins/plugins-page.ts b/ui/src/pages/plugins/plugins-page.ts
index a14ba78f940..bda3e45a620 100644
--- a/ui/src/pages/plugins/plugins-page.ts
+++ b/ui/src/pages/plugins/plugins-page.ts
@@ -1,6 +1,4 @@
 import { consume } from "@lit/context";
-import { redactSensitiveUrlLikeString } from "@openclaw/net-policy/redact-sensitive-url";
-import { asNullableRecord as asRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, type PropertyValues } from "lit";
 import { property, state } from "lit/decorators.js";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
@@ -13,10 +11,22 @@ import {
 } from "../../app/context.ts";
 import { resolveControlUiAuthCandidates } from "../../app/control-ui-auth.ts";
 import { hasOperatorAdminAccess } from "../../app/operator-access.ts";
+import type { McpServerForm } from "../../components/mcp-server-form.ts";
 import { renderPluginsHubTabs, type PluginsHubTab } from "../../components/plugins-hub-tabs.ts";
 import { renderSettingsWorkspace } from "../../components/settings-workspace.ts";
 import { t } from "../../i18n/index.ts";
 import { resolveEditableSnapshotConfig } from "../../lib/config/index.ts";
+import {
+  buildAddMcpServerPatch,
+  buildRemoveMcpServerPatch,
+  buildToggleMcpServerPatch,
+  MCP_SERVER_NAME_PATTERN,
+  parseMcpTarget,
+  patchMcpServers,
+  summarizeMcpServers,
+  type McpServerSummary,
+  type McpServersPatchBuildResult,
+} from "../../lib/config/mcp-servers.ts";
 import {
   installPlugin,
   loadPluginCatalog,
@@ -41,8 +51,6 @@ import {
   pluginRowKey,
   renderPlugins,
   type InstalledFilter,
-  type McpServerForm,
-  type McpServerSummary,
   type PluginRowMessage,
   type PluginsTab,
 } from "./view.ts";
@@ -89,47 +97,6 @@ function mutationSuccessMessage(
   return lines.filter(Boolean).join("\n");
 }
 
-/** Cold MCP server summary mirroring the config page's row projection. */
-function summarizeMcpServers(config: Record<string, unknown> | null): McpServerSummary[] | null {
-  if (!config) {
-    return null;
-  }
-  const servers = asRecord(asRecord(config.mcp)?.servers) ?? {};
-  return Object.entries(servers)
-    .map(([name, value]) => {
-      const server = asRecord(value) ?? {};
-      const url = typeof server.url === "string" ? server.url : "";
-      // Command only, mirroring the config page: stdio args routinely carry
-      // tokens and this surface is visible to read-only operators.
-      const command = typeof server.command === "string" ? server.command : "";
-      const launch = url || command || "missing transport";
-      return {
-        name,
-        enabled: server.enabled !== false,
-        transport: url ? ("http" as const) : command ? ("stdio" as const) : ("invalid" as const),
-        target: url ? redactSensitiveUrlLikeString(launch) : launch,
-        auth: typeof server.auth === "string" ? server.auth : null,
-      };
-    })
-    .toSorted((left, right) => left.name.localeCompare(right.name));
-}
-
-const MCP_SERVER_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-
-function parseMcpTarget(target: string): Record<string, unknown> | null {
-  if (/^https?:\/\//i.test(target)) {
-    // The runtime defaults URL-only servers to SSE; modern MCP endpoints are
-    // streamable HTTP unless the /sse path convention says otherwise.
-    const transport = /\/sse\/?$/i.test(target.split("?")[0] ?? target) ? "sse" : "streamable-http";
-    return { url: target, transport };
-  }
-  const [command, ...args] = target.trim().split(/\s+/u);
-  if (!command) {
-    return null;
-  }
-  return args.length > 0 ? { command, args } : { command };
-}
-
 class PluginsPage extends OpenClawLightDomElement {
   @consume({ context: applicationContext, subscribe: true })
   private context!: ApplicationContext;
@@ -849,15 +816,8 @@ class PluginsPage extends OpenClawLightDomElement {
     }
   }
 
-  /**
-   * Apply one mutation to config.mcp.servers through the shared config seam.
-   * config.patch uses RFC 7396 merge semantics, so `buildPatch` must return a
-   * minimal fragment (with explicit nulls for deletions), never a full config.
-   */
   private async mutateMcpServers(params: {
-    buildPatch: (
-      servers: Readonly<Record<string, unknown>>,
-    ) => { patch: Record<string, unknown> } | { error: string };
+    buildPatch: (servers: Readonly<Record<string, unknown>>) => McpServersPatchBuildResult;
     note: string;
     successText: string;
     busyKey?: string;
@@ -883,24 +843,13 @@ class PluginsPage extends OpenClawLightDomElement {
       return false;
     };
     try {
-      await runtimeConfig.ensureLoaded();
-      const base = resolveEditableSnapshotConfig(runtimeConfig.state.configSnapshot);
-      if (!base) {
-        return fail(t("pluginsPage.mcpConfigUnavailable"));
-      }
-      const servers = asRecord(asRecord(base.mcp)?.servers) ?? {};
-      const built = params.buildPatch(servers);
-      if ("error" in built) {
-        return fail(built.error);
-      }
-      const patched = await runtimeConfig.patch({
-        raw: { mcp: { servers: built.patch } },
+      const result = await patchMcpServers(runtimeConfig, {
+        buildPatch: params.buildPatch,
         note: params.note,
       });
-      if (!patched) {
-        return fail(runtimeConfig.state.lastError ?? t("pluginsPage.mcpConfigUnavailable"));
+      if (!result.ok) {
+        return fail(result.error);
       }
-      await runtimeConfig.refresh();
       this.syncMcpServers();
       this.mcpMessage = { kind: "success", text: params.successText };
       return true;
@@ -917,21 +866,18 @@ class PluginsPage extends OpenClawLightDomElement {
   private async addMcpServer(form: McpServerForm) {
     const name = form.name.trim();
     if (!MCP_SERVER_NAME_PATTERN.test(name)) {
-      this.mcpMessage = { kind: "error", text: t("pluginsPage.mcpNameInvalid") };
+      this.mcpMessage = { kind: "error", text: t("mcpServers.nameInvalid") };
       return;
     }
     const config = parseMcpTarget(form.target);
     if (!config) {
-      this.mcpMessage = { kind: "error", text: t("pluginsPage.mcpTargetInvalid") };
+      this.mcpMessage = { kind: "error", text: t("mcpServers.targetInvalid") };
       return;
     }
     const added = await this.mutateMcpServers({
-      buildPatch: (servers) =>
-        servers[name]
-          ? { error: t("pluginsPage.mcpNameTaken", { name }) }
-          : { patch: { [name]: config } },
+      buildPatch: (servers) => buildAddMcpServerPatch(servers, name, config),
       note: `plugins: add MCP server ${name}`,
-      successText: t("pluginsPage.mcpAddedSuccess", { name }),
+      successText: t("mcpServers.addedSuccess", { name }),
     });
     if (added) {
       this.mcpFormOpen = false;
@@ -940,13 +886,9 @@ class PluginsPage extends OpenClawLightDomElement {
 
   private async toggleMcpServer(name: string, enabled: boolean) {
     await this.mutateMcpServers({
-      buildPatch: (servers) =>
-        servers[name]
-          ? // Enabling deletes the key so the config keeps its enabled-by-default shape.
-            { patch: { [name]: { enabled: enabled ? null : false } } }
-          : { error: t("pluginsPage.mcpMissing", { name }) },
+      buildPatch: (servers) => buildToggleMcpServerPatch(servers, name, enabled),
       note: `plugins: ${enabled ? "enable" : "disable"} MCP server ${name}`,
-      successText: t(enabled ? "pluginsPage.enabledSuccess" : "pluginsPage.disabledSuccess", {
+      successText: t(enabled ? "mcpServers.enabledSuccess" : "mcpServers.disabledSuccess", {
         name,
       }),
     });
@@ -954,12 +896,9 @@ class PluginsPage extends OpenClawLightDomElement {
 
   private async removeMcpServer(name: string) {
     await this.mutateMcpServers({
-      buildPatch: (servers) =>
-        servers[name]
-          ? { patch: { [name]: null } }
-          : { error: t("pluginsPage.mcpMissing", { name }) },
+      buildPatch: (servers) => buildRemoveMcpServerPatch(servers, name),
       note: `plugins: remove MCP server ${name}`,
-      successText: t("pluginsPage.mcpRemovedSuccess", { name }),
+      successText: t("mcpServers.removedSuccess", { name }),
     });
   }
 
@@ -980,9 +919,7 @@ class PluginsPage extends OpenClawLightDomElement {
           : t("pluginsPage.connectorAddedReady", { name: connector.name });
     const added = await this.mutateMcpServers({
       buildPatch: (servers) =>
-        servers[mcp.serverName]
-          ? { error: t("pluginsPage.mcpNameTaken", { name: mcp.serverName }) }
-          : { patch: { [mcp.serverName]: structuredClone(mcp.config) } },
+        buildAddMcpServerPatch(servers, mcp.serverName, structuredClone(mcp.config)),
       note: `plugins: add MCP connector ${mcp.serverName}`,
       successText,
       busyKey: rowKey,
diff --git a/ui/src/pages/plugins/view.test.ts b/ui/src/pages/plugins/view.test.ts
index b93f29da805..9b36198996e 100644
--- a/ui/src/pages/plugins/view.test.ts
+++ b/ui/src/pages/plugins/view.test.ts
@@ -331,6 +331,9 @@ describe("renderPlugins", () => {
             transport: "http",
             target: "https://api.githubcopilot.com/mcp/",
             auth: "oauth",
+            toolFilter: false,
+            parallel: false,
+            tls: null,
           },
         ],
         onMcpToggle,
@@ -347,7 +350,7 @@ describe("renderPlugins", () => {
     actionButton(row, "Remove github")?.click();
     expect(onMcpRemove).toHaveBeenCalledWith("github");
 
-    const form = container.querySelector<HTMLFormElement>(".plugins-mcp-form")!;
+    const form = container.querySelector<HTMLFormElement>(".mcp-server-form")!;
     form.querySelector<HTMLInputElement>('[name="mcp-name"]')!.value = "context7";
     form.querySelector<HTMLInputElement>('[name="mcp-target"]')!.value =
       "https://mcp.context7.com/mcp";
@@ -449,7 +452,16 @@ describe("renderPlugins", () => {
       createProps({
         activeTab: "discover",
         mcpServers: [
-          { name: "github", enabled: true, transport: "http", target: "https://x", auth: "oauth" },
+          {
+            name: "github",
+            enabled: true,
+            transport: "http",
+            target: "https://x",
+            auth: "oauth",
+            toolFilter: false,
+            parallel: false,
+            tls: null,
+          },
         ],
       }),
     );
diff --git a/ui/src/pages/plugins/view.ts b/ui/src/pages/plugins/view.ts
index 586d35193d6..94d2dbeb59f 100644
--- a/ui/src/pages/plugins/view.ts
+++ b/ui/src/pages/plugins/view.ts
@@ -7,6 +7,7 @@ import { html, nothing, type TemplateResult } from "lit";
 import { live } from "lit/directives/live.js";
 import { repeat } from "lit/directives/repeat.js";
 import { icons } from "../../components/icons.ts";
+import { renderMcpServerForm, type McpServerForm } from "../../components/mcp-server-form.ts";
 import "../../components/modal-dialog.ts";
 import "../../components/openclaw-mascot.ts";
 import {
@@ -17,6 +18,7 @@ import {
   renderSettingsStatus,
 } from "../../components/settings-ui.ts";
 import { t } from "../../i18n/index.ts";
+import type { McpServerSummary } from "../../lib/config/mcp-servers.ts";
 import { EXTERNAL_LINK_TARGET, buildExternalLinkRel } from "../../lib/external-link.ts";
 import "../../styles/plugins.css";
 import {
@@ -48,19 +50,6 @@ export type PluginRowMessage = {
   acknowledge?: { packageName: string; version?: string };
 };
 
-export type McpServerSummary = {
-  name: string;
-  enabled: boolean;
-  transport: "stdio" | "http" | "invalid";
-  target: string;
-  auth: string | null;
-};
-
-export type McpServerForm = {
-  name: string;
-  target: string;
-};
-
 type PluginsViewProps = {
   connected: boolean;
   loading: boolean;
@@ -669,12 +658,20 @@ function renderMcpSection(props: PluginsViewProps) {
           @click=${() => props.onMcpFormToggle(!props.mcpFormOpen)}
         >
           <span aria-hidden="true">${icons.plus}</span>
-          ${t("pluginsPage.mcpAdd")}
+          ${t("mcpServers.add")}
         </button>
       `,
     },
     html`
-      ${props.mcpFormOpen ? renderMcpForm(props) : nothing}
+      ${props.mcpFormOpen
+        ? renderMcpServerForm({
+            busy: props.mcpBusy,
+            disabled: !props.canMutate,
+            blockedReason: props.mutationBlockedReason,
+            onSubmit: props.onMcpAdd,
+            onCancel: () => props.onMcpFormToggle(false),
+          })
+        : nothing}
       ${props.mcpMessage
         ? html`<div
             class="plugins-row-message plugins-row-message--${props.mcpMessage
@@ -695,7 +692,9 @@ function renderMcpRow(server: McpServerSummary, props: PluginsViewProps): Templa
       ${renderArtTile(server.name, server.name)}
       <div class="settings-row__text">
         <h3 class="settings-row__title">${server.name}</h3>
-        <span class="settings-row__desc plugins-meta__mono">${server.target}</span>
+        <span class="settings-row__desc plugins-meta__mono">
+          ${server.target || t("mcpServers.missingTransport")}
+        </span>
         ${renderMetaLine([
           t("pluginsPage.mcp"),
           server.transport,
@@ -715,54 +714,6 @@ function renderMcpRow(server: McpServerSummary, props: PluginsViewProps): Templa
   `;
 }
 
-function renderMcpForm(props: PluginsViewProps) {
-  const submit = (event: Event) => {
-    event.preventDefault();
-    const form = event.currentTarget as HTMLFormElement;
-    const data = new FormData(form);
-    const name = data.get("mcp-name");
-    const target = data.get("mcp-target");
-    props.onMcpAdd({
-      name: typeof name === "string" ? name.trim() : "",
-      target: typeof target === "string" ? target.trim() : "",
-    });
-  };
-  return html`
-    <form class="plugins-mcp-form" @submit=${submit}>
-      <label>
-        <span>${t("pluginsPage.mcpNameLabel")}</span>
-        <input
-          name="mcp-name"
-          class="settings-input"
-          type="text"
-          required
-          placeholder="context7"
-          autocomplete="off"
-        />
-      </label>
-      <label class="plugins-mcp-form__target">
-        <span>${t("pluginsPage.mcpTargetLabel")}</span>
-        <input
-          name="mcp-target"
-          class="settings-input"
-          type="text"
-          required
-          placeholder="https://mcp.example.com/mcp  ·  npx some-mcp-server"
-          autocomplete="off"
-        />
-      </label>
-      <div class="plugins-mcp-form__actions">
-        <button type="submit" class="btn btn--sm" ?disabled=${props.mcpBusy}>
-          ${props.mcpBusy ? t("pluginsPage.mcpAdding") : t("pluginsPage.mcpAdd")}
-        </button>
-        <button type="button" class="btn btn--sm" @click=${() => props.onMcpFormToggle(false)}>
-          ${t("pluginsPage.cancel")}
-        </button>
-      </div>
-    </form>
-  `;
-}
-
 function renderInstalled(props: PluginsViewProps) {
   const plugins = installedPlugins(props.result?.plugins ?? [], props.query, props.installedFilter);
   const groups = groupInstalledByCategory(plugins);
@@ -878,7 +829,7 @@ function renderConnectorRow(
                   ?disabled=${!props.canMutate || busy}
                   @click=${() => props.onAddConnector(connector)}
                 >
-                  ${busy ? t("pluginsPage.mcpAdding") : t("pluginsPage.connectorAdd")}
+                  ${busy ? t("mcpServers.adding") : t("pluginsPage.connectorAdd")}
                 </button>
               `
           : html`
diff --git a/ui/src/styles/config.css b/ui/src/styles/config.css
index 7df8c43dfd5..ff7ef44dab4 100644
--- a/ui/src/styles/config.css
+++ b/ui/src/styles/config.css
@@ -700,10 +700,65 @@
   font-family: var(--mono);
 }
 
+/* Shared inline form stays in config.css because the app-wide stylesheet
+ * serves both the MCP settings page and the Plugins inventory. */
+.mcp-server-form {
+  display: grid;
+  grid-template-columns: minmax(140px, 220px) minmax(0, 1fr) auto;
+  gap: var(--space-2);
+  align-items: end;
+  padding: var(--space-3) var(--space-4);
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+}
+
+.mcp-server-form label {
+  display: grid;
+  gap: 5px;
+  min-width: 0;
+}
+
+.mcp-server-form label span {
+  color: var(--muted);
+  font-size: var(--control-ui-text-xs);
+  font-weight: 580;
+}
+
+.mcp-server-form__actions {
+  display: flex;
+  gap: var(--space-2);
+}
+
+.mcp-server-message {
+  margin: var(--space-3) var(--space-4);
+  padding: var(--space-2) var(--space-3);
+  border-radius: var(--radius-md);
+  background: var(--ok-subtle);
+  color: var(--ok);
+  font-size: var(--control-ui-text-xs);
+  line-height: 1.45;
+  white-space: pre-wrap;
+}
+
+.mcp-server-message--error {
+  background: var(--danger-subtle);
+  color: var(--danger);
+}
+
+.mcp-server-loading {
+  padding: var(--space-4);
+  color: var(--muted);
+  font-size: var(--control-ui-text-sm);
+}
+
 @media (max-width: 820px) {
   .mcp-command-card__grid {
     grid-template-columns: 1fr;
   }
+
+  .mcp-server-form {
+    grid-template-columns: minmax(0, 1fr);
+    align-items: stretch;
+  }
 }
 
 /* ===========================================
diff --git a/ui/src/styles/plugins.css b/ui/src/styles/plugins.css
index 302cb25d01f..fd9598666ce 100644
--- a/ui/src/styles/plugins.css
+++ b/ui/src/styles/plugins.css
@@ -530,35 +530,6 @@ h3.plugins-subheader {
   color: var(--danger);
 }
 
-/* ---------- MCP inline form ---------- */
-
-/* Lives inside the MCP group surface; hairline divider instead of a nested card. */
-.plugins-mcp-form {
-  display: grid;
-  grid-template-columns: minmax(140px, 220px) minmax(0, 1fr) auto;
-  gap: var(--space-2);
-  align-items: end;
-  padding: var(--space-3) var(--space-4);
-  border-bottom: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
-}
-
-.plugins-mcp-form label {
-  display: grid;
-  gap: 5px;
-  min-width: 0;
-}
-
-.plugins-mcp-form label span {
-  color: var(--muted);
-  font-size: var(--control-ui-text-xs);
-  font-weight: 580;
-}
-
-.plugins-mcp-form__actions {
-  display: flex;
-  gap: var(--space-2);
-}
-
 /* ---------- detail overlay ---------- */
 
 .plugins-detail-backdrop {
@@ -739,11 +710,6 @@ h3.plugins-subheader {
   .plugins-content-header {
     display: flex;
   }
-
-  .plugins-mcp-form {
-    grid-template-columns: minmax(0, 1fr);
-    align-items: stretch;
-  }
 }
 
 @media (max-width: 560px) {

From bc8d0da0924d8d56d1950cfcec8aa48ede7b3bd8 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:22:48 +0100
Subject: [PATCH 57/76] feat(linux): Quick Chat streamed replies and precise
 pairing states (#110632)

* feat(linux): stream Quick Chat gateway events

* feat(linux): render streamed Quick Chat replies

* fix(linux): correlate Quick Chat streams by run

* style(linux): rustfmt

* test(linux): move Quick Chat stream helper tests into the tooling vitest project

* test: type the Linux quickchat stream harness for strict checks

* test: explicit harness shape for the root test typecheck
---
 .../src-tauri/src/gateway_device_identity.rs  |   2 +
 apps/linux/src-tauri/src/gateway_ws.rs        | 519 ++++++++++++++----
 apps/linux/src-tauri/src/quickchat.rs         |   5 +-
 apps/linux/ui/quickchat.css                   | 104 +++-
 apps/linux/ui/quickchat.html                  |  14 +
 apps/linux/ui/quickchat.js                    | 284 +++++++++-
 docs/platforms/linux.md                       |  13 +-
 test/linux-quickchat-stream.test.ts           | 270 +++++++++
 8 files changed, 1088 insertions(+), 123 deletions(-)
 create mode 100644 test/linux-quickchat-stream.test.ts

diff --git a/apps/linux/src-tauri/src/gateway_device_identity.rs b/apps/linux/src-tauri/src/gateway_device_identity.rs
index 0094981f1bb..0657a86e78a 100644
--- a/apps/linux/src-tauri/src/gateway_device_identity.rs
+++ b/apps/linux/src-tauri/src/gateway_device_identity.rs
@@ -61,6 +61,8 @@ pub(crate) struct GatewayDeviceIdentityStore {
     identity: GatewayDeviceIdentity,
 }
 
+// This credential boundary (gateway_device_identity.rs:65-98) intentionally excludes setup-code
+// and bootstrapToken redemption; those require a dedicated product UI and remain follow-up work.
 #[derive(Clone, Eq, PartialEq)]
 pub(crate) enum GatewayAuth {
     DeviceToken(String),
diff --git a/apps/linux/src-tauri/src/gateway_ws.rs b/apps/linux/src-tauri/src/gateway_ws.rs
index cf701a03406..f6da2924e04 100644
--- a/apps/linux/src-tauri/src/gateway_ws.rs
+++ b/apps/linux/src-tauri/src/gateway_ws.rs
@@ -26,6 +26,7 @@ use tokio_tungstenite::{
 use uuid::Uuid;
 
 const GATEWAY_STATE_EVENT: &str = "quickchat:gateway-state";
+const CHAT_EVENT: &str = "quickchat:chat-event";
 const GATEWAY_DEVICE_IDENTITY_FILE: &str = "quickchat-gateway-device.json";
 const AGENTS_CACHE_TTL: Duration = Duration::from_secs(60);
 const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
@@ -35,6 +36,8 @@ const COMMAND_TIMEOUT: Duration = Duration::from_secs(35);
 const DRIVER_TICK: Duration = Duration::from_secs(1);
 const MAX_RECONNECT_DELAY: Duration = Duration::from_secs(30);
 const PAIRING_REQUIRED_DETAIL_CODE: &str = "PAIRING_REQUIRED";
+const AUTH_TOKEN_MISSING_DETAIL_CODE: &str = "AUTH_TOKEN_MISSING";
+const AUTH_PASSWORD_MISSING_DETAIL_CODE: &str = "AUTH_PASSWORD_MISSING";
 const AUTH_DEVICE_TOKEN_MISMATCH_DETAIL_CODE: &str = "AUTH_DEVICE_TOKEN_MISMATCH";
 const TLS_PIN_MISMATCH_ERROR: &str = "Gateway TLS certificate fingerprint mismatch";
 
@@ -212,6 +215,7 @@ struct ChatSendParams {
 #[derive(Deserialize)]
 #[serde(rename_all = "camelCase")]
 struct ChatSendAck {
+    run_id: String,
     status: String,
     #[serde(default)]
     error: Option<Value>,
@@ -219,10 +223,19 @@ struct ChatSendAck {
     message: Option<String>,
 }
 
-#[derive(Clone, Debug, Eq, PartialEq)]
-struct ChatRoutingTarget {
-    session_key: String,
-    agent_id: Option<String>,
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ChatRoutingTarget {
+    pub(crate) session_key: String,
+    pub(crate) agent_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ChatSendResult {
+    #[serde(flatten)]
+    pub(crate) target: ChatRoutingTarget,
+    pub(crate) run_id: String,
 }
 
 enum GatewayRequest {
@@ -243,11 +256,66 @@ enum DriverCommand {
     Reconfigure,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum GatewayConnectionState {
+    Down = 0,
+    Up = 1,
+    PairingRequired = 2,
+    CredentialRequired = 3,
+    TlsFailure = 4,
+}
+
+impl GatewayConnectionState {
+    fn from_u64(value: u64) -> Self {
+        match value {
+            1 => Self::Up,
+            2 => Self::PairingRequired,
+            3 => Self::CredentialRequired,
+            4 => Self::TlsFailure,
+            _ => Self::Down,
+        }
+    }
+
+    fn event_name(self) -> &'static str {
+        match self {
+            Self::Down => "down",
+            Self::Up => "up",
+            Self::PairingRequired => "pairing-required",
+            Self::CredentialRequired => "credential-required",
+            Self::TlsFailure => "tls-failure",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+struct ConnectErrorDetails {
+    code: Option<String>,
+    device_id: Option<String>,
+    remediation_hint: Option<String>,
+    retryable: Option<bool>,
+    pause_reconnect: Option<bool>,
+}
+
+impl ConnectErrorDetails {
+    fn from_value(value: Option<&Value>) -> Self {
+        let Some(value) = value else {
+            return Self::default();
+        };
+        Self {
+            code: connect_detail_text(value.get("code"), 80),
+            device_id: connect_detail_text(value.get("deviceId"), 128),
+            remediation_hint: connect_detail_text(value.get("remediationHint"), 240),
+            retryable: value.get("retryable").and_then(Value::as_bool),
+            pause_reconnect: value.get("pauseReconnect").and_then(Value::as_bool),
+        }
+    }
+}
+
 struct RequestFailure {
     message: String,
     disconnect: bool,
-    detail_code: Option<String>,
-    pairing_required: bool,
+    connect_details: ConnectErrorDetails,
+    connect_state: Option<GatewayConnectionState>,
     tls_failure: bool,
 }
 
@@ -256,8 +324,8 @@ impl RequestFailure {
         Self {
             message: message.into(),
             disconnect: true,
-            detail_code: None,
-            pairing_required: false,
+            connect_details: ConnectErrorDetails::default(),
+            connect_state: None,
             tls_failure: false,
         }
     }
@@ -266,69 +334,38 @@ impl RequestFailure {
         Self {
             message: message.into(),
             disconnect: true,
-            detail_code: None,
-            pairing_required: false,
+            connect_details: ConnectErrorDetails::default(),
+            connect_state: None,
             tls_failure: true,
         }
     }
 
-    fn method_with_detail(message: impl Into<String>, detail_code: Option<String>) -> Self {
+    fn method_with_details(message: impl Into<String>, details: Option<&Value>) -> Self {
         Self {
             message: message.into(),
             disconnect: false,
-            detail_code,
-            pairing_required: false,
+            connect_details: ConnectErrorDetails::from_value(details),
+            connect_state: None,
             tls_failure: false,
         }
     }
 
     fn classify_connect(mut self, auth: &GatewayAuth) -> Self {
-        let pairing_required = self.detail_code.as_deref() == Some(PAIRING_REQUIRED_DETAIL_CODE);
-        let missing_bootstrap_auth = auth.is_none()
-            && self
-                .detail_code
-                .as_deref()
-                .is_some_and(|code| code.starts_with("AUTH_"));
-        self.pairing_required = pairing_required || missing_bootstrap_auth;
+        self.connect_state =
+            classify_connect_failure(self.connect_details.code.as_deref(), !auth.is_none());
         self
     }
 }
 
-#[derive(Clone, Copy, Eq, PartialEq)]
-enum GatewayConnectionState {
-    Down = 0,
-    Up = 1,
-    PairingRequired = 2,
-    TlsFailure = 3,
-}
-
-impl GatewayConnectionState {
-    fn from_u64(value: u64) -> Self {
-        match value {
-            1 => Self::Up,
-            2 => Self::PairingRequired,
-            3 => Self::TlsFailure,
-            _ => Self::Down,
-        }
-    }
-
-    fn event_name(self) -> &'static str {
-        match self {
-            Self::Down => "down",
-            Self::Up => "up",
-            Self::PairingRequired => "pairing-required",
-            Self::TlsFailure => "tls-failure",
-        }
-    }
-}
-
 struct GatewayClientInner {
     config: Mutex<Option<GatewayWsConfig>>,
     config_generation: AtomicU64,
     commands: Mutex<Option<mpsc::Sender<DriverCommand>>>,
     agents_cache: Mutex<Option<CachedAgents>>,
     identity: Mutex<Option<GatewayDeviceIdentityStore>>,
+    connection_notice: Mutex<Option<String>>,
     connection_state: AtomicU64,
+    reconnect_paused: AtomicBool,
     running: AtomicBool,
 }
 
@@ -346,7 +383,9 @@ impl GatewayClient {
                 commands: Mutex::new(None),
                 agents_cache: Mutex::new(None),
                 identity: Mutex::new(None),
+                connection_notice: Mutex::new(None),
                 connection_state: AtomicU64::new(GatewayConnectionState::Down as u64),
+                reconnect_paused: AtomicBool::new(false),
                 running: AtomicBool::new(false),
             }),
         }
@@ -364,7 +403,8 @@ impl GatewayClient {
             .lock()
             .expect("gateway agents cache mutex poisoned") = None;
         self.inner.config_generation.fetch_add(1, Ordering::SeqCst);
-        self.set_connection_state(app, GatewayConnectionState::Down);
+        self.inner.reconnect_paused.store(false, Ordering::SeqCst);
+        self.set_connection_state(app, GatewayConnectionState::Down, None);
         if let Some(commands) = self
             .inner
             .commands
@@ -388,7 +428,8 @@ impl GatewayClient {
             .lock()
             .expect("gateway agents cache mutex poisoned") = None;
         self.inner.config_generation.fetch_add(1, Ordering::SeqCst);
-        self.set_connection_state(app, GatewayConnectionState::Down);
+        self.inner.reconnect_paused.store(false, Ordering::SeqCst);
+        self.set_connection_state(app, GatewayConnectionState::Down, None);
         if let Some(commands) = self
             .inner
             .commands
@@ -417,10 +458,16 @@ impl GatewayClient {
     }
 
     pub fn emit_current_state(&self, window: &WebviewWindow) -> Result<(), String> {
+        let notice = self
+            .inner
+            .connection_notice
+            .lock()
+            .map_err(|_| "Gateway connection notice is unavailable.".to_string())?
+            .clone();
         window
             .emit(
                 GATEWAY_STATE_EVENT,
-                GatewayStateEvent::new(self.connection_state()),
+                GatewayStateEvent::new(self.connection_state(), notice),
             )
             .map_err(|error| format!("Could not report Gateway connectivity: {error}"))
     }
@@ -456,12 +503,12 @@ impl GatewayClient {
         scope: &str,
         main_key: &str,
         idempotency_key: &str,
-    ) -> Result<(), String> {
+    ) -> Result<ChatSendResult, String> {
         let target = routing_target(scope, selected_agent_id, main_key);
         let response = self
             .request(GatewayRequest::ChatSend(ChatSendParams {
-                session_key: target.session_key,
-                agent_id: target.agent_id,
+                session_key: target.session_key.clone(),
+                agent_id: target.agent_id.clone(),
                 message,
                 idempotency_key: idempotency_key.to_string(),
             }))
@@ -469,7 +516,26 @@ impl GatewayClient {
         let GatewayResponse::ChatSend(ack) = response else {
             return Err("Gateway returned the wrong response for chat.send.".to_string());
         };
-        classify_chat_ack(&ack)
+        classify_chat_ack(&ack)?;
+        Ok(ChatSendResult {
+            target,
+            run_id: ack.run_id,
+        })
+    }
+
+    pub fn resume_reconnect(&self) {
+        if !self.inner.reconnect_paused.load(Ordering::SeqCst) {
+            return;
+        }
+        if let Some(commands) = self
+            .inner
+            .commands
+            .lock()
+            .expect("gateway command mutex poisoned")
+            .as_ref()
+        {
+            let _ = commands.try_send(DriverCommand::Reconfigure);
+        }
     }
 
     async fn request(&self, request: GatewayRequest) -> Result<GatewayResponse, String> {
@@ -498,7 +564,8 @@ impl GatewayClient {
         let mut reconnect_attempt = 0_u32;
         loop {
             if app.get_webview_window(QUICKCHAT_LABEL).is_none() {
-                self.set_connection_state(&app, GatewayConnectionState::Down);
+                self.inner.reconnect_paused.store(false, Ordering::SeqCst);
+                self.set_connection_state(&app, GatewayConnectionState::Down, None);
                 tokio::time::sleep(DRIVER_TICK).await;
                 reconnect_attempt = 0;
                 continue;
@@ -510,7 +577,8 @@ impl GatewayClient {
                 .expect("gateway config mutex poisoned")
                 .clone();
             let Some(config) = config else {
-                self.set_connection_state(&app, GatewayConnectionState::Down);
+                self.inner.reconnect_paused.store(false, Ordering::SeqCst);
+                self.set_connection_state(&app, GatewayConnectionState::Down, None);
                 tokio::time::sleep(DRIVER_TICK).await;
                 continue;
             };
@@ -522,12 +590,45 @@ impl GatewayClient {
                 .connect_and_serve(&app, &config, generation, &mut receiver)
                 .await;
             let reached_hello = self.is_connected();
-            let disconnected_state = match connection_result.as_ref() {
-                Err(failure) if failure.pairing_required => GatewayConnectionState::PairingRequired,
-                Err(failure) if failure.tls_failure => GatewayConnectionState::TlsFailure,
-                _ => GatewayConnectionState::Down,
-            };
-            self.set_connection_state(&app, disconnected_state);
+            let failure = connection_result.as_ref().err();
+            let disconnected_state = failure
+                .and_then(|failure| failure.connect_state)
+                .or_else(|| {
+                    failure
+                        .is_some_and(|failure| failure.tls_failure)
+                        .then_some(GatewayConnectionState::TlsFailure)
+                })
+                .unwrap_or(GatewayConnectionState::Down);
+            let pause_reconnect = failure
+                .map(|failure| should_pause_reconnect(&failure.connect_details))
+                .unwrap_or(false);
+            let notice = failure.and_then(|failure| {
+                connection_notice(
+                    disconnected_state,
+                    &failure.connect_details,
+                    pause_reconnect,
+                )
+            });
+            self.inner
+                .reconnect_paused
+                .store(pause_reconnect, Ordering::SeqCst);
+            self.set_connection_state(&app, disconnected_state, notice);
+            if pause_reconnect {
+                // Server retry policy is authoritative: explicit pauseReconnect or retryable=false
+                // waits for a fresh user summon instead of burning the capped backoff loop.
+                loop {
+                    let Some(command) = receiver.recv().await else {
+                        return;
+                    };
+                    match command {
+                        DriverCommand::Reconfigure => break,
+                        command => reject_disconnected_command(command),
+                    }
+                }
+                self.inner.reconnect_paused.store(false, Ordering::SeqCst);
+                reconnect_attempt = 0;
+                continue;
+            }
             reconnect_attempt = if reached_hello {
                 1
             } else {
@@ -566,7 +667,7 @@ impl GatewayClient {
         let signed_at_ms = unix_time_ms().map_err(RequestFailure::transport)?;
         let params = connect_params(&identity, &auth, &nonce, signed_at_ms)
             .map_err(RequestFailure::transport)?;
-        let hello = match request_on_socket(&mut socket, "connect", params).await {
+        let hello = match request_on_socket(app, &mut socket, "connect", params).await {
             Ok(hello) => hello,
             Err(failure) => {
                 let failure = failure.classify_connect(&auth);
@@ -582,12 +683,12 @@ impl GatewayClient {
             self.persist_device_token(&config.ws_url, device_token)?;
         }
 
-        let agents = request_agents_list(&mut socket).await?;
+        let agents = request_agents_list(app, &mut socket).await?;
         if self.inner.config_generation.load(Ordering::SeqCst) != generation {
             return Ok(());
         }
         self.cache_agents(agents);
-        self.set_connection_state(app, GatewayConnectionState::Up);
+        self.set_connection_state(app, GatewayConnectionState::Up, None);
         let mut last_gateway_activity = Instant::now();
 
         loop {
@@ -604,7 +705,7 @@ impl GatewayClient {
                     match command {
                         DriverCommand::Reconfigure => return Ok(()),
                         DriverCommand::Request { request, reply } => {
-                            let result = perform_request(&mut socket, request).await;
+                            let result = perform_request(app, &mut socket, request).await;
                             last_gateway_activity = Instant::now();
                             match result {
                                 Ok(response) => {
@@ -623,7 +724,7 @@ impl GatewayClient {
                     }
                 }
                 incoming = socket.next() => {
-                    handle_idle_message(&mut socket, incoming).await?;
+                    handle_idle_message(app, &mut socket, incoming).await?;
                     last_gateway_activity = Instant::now();
                 }
                 _ = tokio::time::sleep(DRIVER_TICK) => {
@@ -719,7 +820,12 @@ impl GatewayClient {
         GatewayConnectionState::from_u64(self.inner.connection_state.load(Ordering::SeqCst))
     }
 
-    fn set_connection_state(&self, app: &AppHandle, state: GatewayConnectionState) {
+    fn set_connection_state(
+        &self,
+        app: &AppHandle,
+        state: GatewayConnectionState,
+        notice: Option<String>,
+    ) {
         if state != GatewayConnectionState::Up {
             *self
                 .inner
@@ -727,18 +833,31 @@ impl GatewayClient {
                 .lock()
                 .expect("gateway agents cache mutex poisoned") = None;
         }
-        if self
+        let notice_changed = {
+            let mut current = self
+                .inner
+                .connection_notice
+                .lock()
+                .expect("gateway connection notice mutex poisoned");
+            if *current == notice {
+                false
+            } else {
+                *current = notice.clone();
+                true
+            }
+        };
+        let state_changed = self
             .inner
             .connection_state
             .swap(state as u64, Ordering::SeqCst)
-            == state as u64
-        {
+            != state as u64;
+        if !state_changed && !notice_changed {
             return;
         }
         let _ = app.emit_to(
             QUICKCHAT_LABEL,
             GATEWAY_STATE_EVENT,
-            GatewayStateEvent::new(state),
+            GatewayStateEvent::new(state, notice),
         );
     }
 }
@@ -746,12 +865,15 @@ impl GatewayClient {
 #[derive(Clone, Serialize)]
 struct GatewayStateEvent {
     state: &'static str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    notice: Option<String>,
 }
 
 impl GatewayStateEvent {
-    fn new(state: GatewayConnectionState) -> Self {
+    fn new(state: GatewayConnectionState, notice: Option<String>) -> Self {
         Self {
             state: state.event_name(),
+            notice,
         }
     }
 }
@@ -777,6 +899,75 @@ fn routing_target(scope: &str, selected_agent_id: &str, main_key: &str) -> ChatR
     }
 }
 
+fn connect_detail_text(value: Option<&Value>, max_chars: usize) -> Option<String> {
+    let normalized = value
+        .and_then(Value::as_str)?
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ");
+    if normalized.is_empty() {
+        return None;
+    }
+    Some(normalized.chars().take(max_chars).collect())
+}
+
+fn classify_connect_failure(
+    detail_code: Option<&str>,
+    has_local_credential: bool,
+) -> Option<GatewayConnectionState> {
+    if detail_code == Some(PAIRING_REQUIRED_DETAIL_CODE) {
+        return Some(GatewayConnectionState::PairingRequired);
+    }
+    let credential_required = !has_local_credential
+        && detail_code.is_some_and(|code| {
+            code == AUTH_TOKEN_MISSING_DETAIL_CODE
+                || code == AUTH_PASSWORD_MISSING_DETAIL_CODE
+                || (code.starts_with("AUTH_") && code.ends_with("_MISMATCH"))
+        });
+    credential_required.then_some(GatewayConnectionState::CredentialRequired)
+}
+
+fn should_pause_reconnect(details: &ConnectErrorDetails) -> bool {
+    details.pause_reconnect == Some(true) || details.retryable == Some(false)
+}
+
+fn short_device_id(device_id: &str) -> Option<String> {
+    let short = device_id
+        .chars()
+        .filter(|character| character.is_ascii_alphanumeric())
+        .take(8)
+        .collect::<String>();
+    (!short.is_empty()).then_some(short)
+}
+
+fn connection_notice(
+    state: GatewayConnectionState,
+    details: &ConnectErrorDetails,
+    reconnect_paused: bool,
+) -> Option<String> {
+    let fallback = match state {
+        GatewayConnectionState::PairingRequired => "Approve this device in the dashboard (Nodes)",
+        GatewayConnectionState::CredentialRequired => {
+            "Gateway requires a credential — open the dashboard on the gateway host"
+        }
+        _ if reconnect_paused => "Gateway connection paused — reopen Quick Chat to retry",
+        _ => return None,
+    };
+    // The Gateway owns recovery semantics and can give more precise operator guidance than this
+    // client. Keep only its bounded plain-text hint, then add the safe pairing identifier.
+    let mut notice = details
+        .remediation_hint
+        .clone()
+        .unwrap_or_else(|| fallback.to_string());
+    if state == GatewayConnectionState::PairingRequired {
+        if let Some(device_id) = details.device_id.as_deref().and_then(short_device_id) {
+            notice.push_str(" · Device ");
+            notice.push_str(&device_id);
+        }
+    }
+    Some(notice)
+}
+
 fn reconnect_backoff(attempt: u32) -> Duration {
     let shift = attempt.saturating_sub(1).min(5);
     Duration::from_secs((1_u64 << shift).min(MAX_RECONNECT_DELAY.as_secs()))
@@ -784,7 +975,7 @@ fn reconnect_backoff(attempt: u32) -> Duration {
 
 fn should_clear_stored_device_token(failure: &RequestFailure, auth: &GatewayAuth) -> bool {
     matches!(auth, GatewayAuth::DeviceToken(_))
-        && failure.detail_code.as_deref() == Some(AUTH_DEVICE_TOKEN_MISMATCH_DETAIL_CODE)
+        && failure.connect_details.code.as_deref() == Some(AUTH_DEVICE_TOKEN_MISMATCH_DETAIL_CODE)
 }
 
 fn connect_params(
@@ -849,6 +1040,7 @@ async fn wait_for_connect_challenge(socket: &mut GatewaySocket) -> Result<String
 }
 
 async fn request_on_socket(
+    app: &AppHandle,
     socket: &mut GatewaySocket,
     method: &str,
     params: Value,
@@ -865,10 +1057,10 @@ async fn request_on_socket(
     tokio::time::timeout(REQUEST_TIMEOUT, async {
         loop {
             let value = next_json(socket).await?;
+            dispatch_chat_event(app, &value);
             if value.get("type").and_then(Value::as_str) != Some("res")
                 || value.get("id").and_then(Value::as_str) != Some(id.as_str())
             {
-                // Streamed chat events are a deliberate follow-up; this client only consumes RPC acks.
                 continue;
             }
             if value.get("ok").and_then(Value::as_bool) == Some(true) {
@@ -879,13 +1071,11 @@ async fn request_on_socket(
                 .and_then(|error| error.get("message"))
                 .and_then(Value::as_str)
                 .unwrap_or("Gateway request failed.");
-            let detail_code = value
+            let details = value
                 .get("error")
                 .and_then(|error| error.get("details"))
-                .and_then(|details| details.get("code"))
-                .and_then(Value::as_str)
-                .map(ToOwned::to_owned);
-            return Err(RequestFailure::method_with_detail(message, detail_code));
+                .filter(|details| details.is_object());
+            return Err(RequestFailure::method_with_details(message, details));
         }
     })
     .await
@@ -893,18 +1083,19 @@ async fn request_on_socket(
 }
 
 async fn perform_request(
+    app: &AppHandle,
     socket: &mut GatewaySocket,
     request: GatewayRequest,
 ) -> Result<GatewayResponse, RequestFailure> {
     match request {
-        GatewayRequest::AgentsList => request_agents_list(socket)
+        GatewayRequest::AgentsList => request_agents_list(app, socket)
             .await
             .map(GatewayResponse::AgentsList),
         GatewayRequest::ChatSend(params) => {
             let params = serde_json::to_value(params).map_err(|error| {
                 RequestFailure::transport(format!("Could not encode chat.send: {error}"))
             })?;
-            let payload = request_on_socket(socket, "chat.send", params).await?;
+            let payload = request_on_socket(app, socket, "chat.send", params).await?;
             serde_json::from_value(payload)
                 .map(GatewayResponse::ChatSend)
                 .map_err(|error| {
@@ -915,9 +1106,10 @@ async fn perform_request(
 }
 
 async fn request_agents_list(
+    app: &AppHandle,
     socket: &mut GatewaySocket,
 ) -> Result<AgentsListResult, RequestFailure> {
-    let payload = request_on_socket(socket, "agents.list", json!({})).await?;
+    let payload = request_on_socket(app, socket, "agents.list", json!({})).await?;
     serde_json::from_value(payload).map_err(|error| {
         RequestFailure::transport(format!("Invalid agents.list response: {error}"))
     })
@@ -1089,6 +1281,7 @@ async fn next_json(socket: &mut GatewaySocket) -> Result<Value, RequestFailure>
 }
 
 async fn handle_idle_message(
+    app: &AppHandle,
     socket: &mut GatewaySocket,
     incoming: Option<Result<Message, tokio_tungstenite::tungstenite::Error>>,
 ) -> Result<(), RequestFailure> {
@@ -1098,6 +1291,12 @@ async fn handle_idle_message(
             RequestFailure::transport(format!("Gateway connection failed: {error}"))
         })?;
     match message {
+        Message::Text(text) => {
+            if let Ok(value) = serde_json::from_str::<Value>(text.as_ref()) {
+                dispatch_chat_event(app, &value);
+            }
+            Ok(())
+        }
         Message::Ping(payload) => socket.send(Message::Pong(payload)).await.map_err(|error| {
             RequestFailure::transport(format!("Could not answer Gateway ping: {error}"))
         }),
@@ -1106,6 +1305,18 @@ async fn handle_idle_message(
     }
 }
 
+fn dispatch_chat_event(app: &AppHandle, frame: &Value) {
+    if frame.get("type").and_then(Value::as_str) != Some("event")
+        || frame.get("event").and_then(Value::as_str) != Some("chat")
+    {
+        return;
+    }
+    if let Some(payload) = frame.get("payload") {
+        // Payload stays raw so the WebView can mirror Gateway delta assembly without native drift.
+        let _ = app.emit_to(QUICKCHAT_LABEL, CHAT_EVENT, payload.clone());
+    }
+}
+
 fn unix_time_ms() -> Result<u64, String> {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -1133,6 +1344,11 @@ mod tests {
                 agent_id: None,
             }
         );
+        assert_eq!(
+            serde_json::to_value(routing_target("global", "work", "main"))
+                .expect("serialized routing target"),
+            json!({ "sessionKey": "global", "agentId": "work" })
+        );
     }
 
     #[test]
@@ -1169,6 +1385,7 @@ mod tests {
     fn chat_ack_acceptance_is_explicit() {
         for status in ["ok", "started", "in_flight"] {
             assert!(classify_chat_ack(&ChatSendAck {
+                run_id: "run-1".to_string(),
                 status: status.to_string(),
                 error: None,
                 message: None,
@@ -1177,6 +1394,7 @@ mod tests {
         }
         for status in ["error", "timeout", "queued"] {
             assert!(classify_chat_ack(&ChatSendAck {
+                run_id: "run-1".to_string(),
                 status: status.to_string(),
                 error: Some(json!({ "message": "not accepted" })),
                 message: None,
@@ -1291,33 +1509,122 @@ mod tests {
     }
 
     #[test]
-    fn pairing_failures_map_to_the_pairing_strip_state() {
-        let pending = RequestFailure::method_with_detail(
-            "pairing required",
-            Some(PAIRING_REQUIRED_DETAIL_CODE.to_string()),
-        )
-        .classify_connect(&GatewayAuth::SharedToken("bootstrap".to_string()));
-        assert!(pending.pairing_required);
+    fn connect_classification_separates_pairing_and_missing_credentials() {
+        assert_eq!(
+            classify_connect_failure(Some(PAIRING_REQUIRED_DETAIL_CODE), true),
+            Some(GatewayConnectionState::PairingRequired)
+        );
+        assert_eq!(
+            classify_connect_failure(Some(AUTH_TOKEN_MISSING_DETAIL_CODE), false),
+            Some(GatewayConnectionState::CredentialRequired)
+        );
+        assert_eq!(
+            classify_connect_failure(Some("AUTH_TOKEN_MISMATCH"), false),
+            Some(GatewayConnectionState::CredentialRequired)
+        );
+        assert_eq!(
+            classify_connect_failure(Some("AUTH_TOKEN_MISMATCH"), true),
+            None
+        );
+        assert_eq!(
+            GatewayConnectionState::CredentialRequired.event_name(),
+            "credential-required"
+        );
 
-        let missing_bootstrap = RequestFailure::method_with_detail(
-            "token missing",
-            Some("AUTH_TOKEN_MISSING".to_string()),
-        )
-        .classify_connect(&GatewayAuth::None);
-        assert!(missing_bootstrap.pairing_required);
+        let pairing_details = json!({ "code": PAIRING_REQUIRED_DETAIL_CODE });
+        let pending =
+            RequestFailure::method_with_details("pairing required", Some(&pairing_details))
+                .classify_connect(&GatewayAuth::SharedToken("bootstrap".to_string()));
+        assert_eq!(
+            pending.connect_state,
+            Some(GatewayConnectionState::PairingRequired)
+        );
+
+        let missing_details = json!({ "code": AUTH_TOKEN_MISSING_DETAIL_CODE });
+        let missing_auth_failure =
+            RequestFailure::method_with_details("token missing", Some(&missing_details))
+                .classify_connect(&GatewayAuth::None);
+        assert_eq!(
+            missing_auth_failure.connect_state,
+            Some(GatewayConnectionState::CredentialRequired)
+        );
+
+        let mismatch_details = json!({ "code": "AUTH_TOKEN_MISMATCH" });
+        let mismatch_without_auth =
+            RequestFailure::method_with_details("token mismatch", Some(&mismatch_details))
+                .classify_connect(&GatewayAuth::None);
+        assert_eq!(
+            mismatch_without_auth.connect_state,
+            Some(GatewayConnectionState::CredentialRequired)
+        );
+        let mismatch_with_auth =
+            RequestFailure::method_with_details("token mismatch", Some(&mismatch_details))
+                .classify_connect(&GatewayAuth::SharedToken("configured".to_string()));
+        assert_eq!(mismatch_with_auth.connect_state, None);
 
-        let stale_device_auth = RequestFailure::method_with_detail(
+        let stale_device_details = json!({ "code": AUTH_DEVICE_TOKEN_MISMATCH_DETAIL_CODE });
+        let stale_device_auth = RequestFailure::method_with_details(
             "device token mismatch",
-            Some(AUTH_DEVICE_TOKEN_MISMATCH_DETAIL_CODE.to_string()),
+            Some(&stale_device_details),
         )
         .classify_connect(&GatewayAuth::DeviceToken("stale".to_string()));
-        assert!(!stale_device_auth.pairing_required);
+        assert_eq!(stale_device_auth.connect_state, None);
         assert!(should_clear_stored_device_token(
             &stale_device_auth,
             &GatewayAuth::DeviceToken("stale".to_string())
         ));
     }
 
+    #[test]
+    fn reconnect_pause_requires_explicit_server_policy() {
+        let pause_details = json!({ "pauseReconnect": true });
+        let paused = RequestFailure::method_with_details("pause", Some(&pause_details));
+        assert!(should_pause_reconnect(&paused.connect_details));
+
+        let terminal_details = json!({ "retryable": false });
+        let terminal = RequestFailure::method_with_details("terminal", Some(&terminal_details));
+        assert!(should_pause_reconnect(&terminal.connect_details));
+
+        let retry_details = json!({ "retryable": true, "pauseReconnect": false });
+        let retry = RequestFailure::method_with_details("retry", Some(&retry_details));
+        assert!(!should_pause_reconnect(&retry.connect_details));
+        assert!(!should_pause_reconnect(
+            &RequestFailure::transport("transport").connect_details
+        ));
+    }
+
+    #[test]
+    fn connection_notices_prefer_server_guidance_and_shorten_device_ids() {
+        let details = ConnectErrorDetails::from_value(Some(&json!({
+            "remediationHint": "Use the Nodes approval queue.",
+            "deviceId": "abcdef1234567890"
+        })));
+        assert_eq!(
+            connection_notice(GatewayConnectionState::PairingRequired, &details, true).as_deref(),
+            Some("Use the Nodes approval queue. · Device abcdef12")
+        );
+        assert_eq!(
+            connection_notice(
+                GatewayConnectionState::CredentialRequired,
+                &ConnectErrorDetails::default(),
+                true,
+            )
+            .as_deref(),
+            Some("Gateway requires a credential — open the dashboard on the gateway host")
+        );
+        assert_eq!(
+            connection_notice(
+                GatewayConnectionState::Down,
+                &ConnectErrorDetails::from_value(Some(&json!({
+                    "remediationHint": "Replace the configured credential."
+                }))),
+                true,
+            )
+            .as_deref(),
+            Some("Replace the configured credential.")
+        );
+    }
+
     #[test]
     fn chat_send_frame_matches_gateway_schema() {
         let params = ChatSendParams {
@@ -1344,4 +1651,16 @@ mod tests {
             })
         );
     }
+
+    #[test]
+    fn chat_send_result_flattens_route_and_ack_run_id() {
+        let result = ChatSendResult {
+            target: routing_target("global", "work", "main"),
+            run_id: "run-1".to_string(),
+        };
+        assert_eq!(
+            serde_json::to_value(result).expect("serialized chat send result"),
+            json!({ "sessionKey": "global", "agentId": "work", "runId": "run-1" })
+        );
+    }
 }
diff --git a/apps/linux/src-tauri/src/quickchat.rs b/apps/linux/src-tauri/src/quickchat.rs
index 724fb801874..ec3d8e7563b 100644
--- a/apps/linux/src-tauri/src/quickchat.rs
+++ b/apps/linux/src-tauri/src/quickchat.rs
@@ -1,4 +1,4 @@
-use crate::gateway_ws::{AgentsListResult, GatewayClient};
+use crate::gateway_ws::{AgentsListResult, ChatSendResult, GatewayClient};
 use crate::{tray, DesktopState};
 use serde::Serialize;
 use std::fs;
@@ -513,6 +513,7 @@ pub fn toggle_quickchat(app: &AppHandle) {
 
 fn show_quickchat(app: &AppHandle) -> Result<(), String> {
     let window = ensure_quickchat_window(app)?;
+    app.state::<GatewayClient>().resume_reconnect();
     window
         .set_size(LogicalSize::new(QUICKCHAT_WIDTH, QUICKCHAT_HEIGHT))
         .map_err(|error| format!("Could not reset Quick Chat size: {error}"))?;
@@ -588,7 +589,7 @@ pub async fn quickchat_send(
     gateway: State<'_, GatewayClient>,
     state: State<'_, QuickChatState>,
     message: String,
-) -> Result<(), String> {
+) -> Result<ChatSendResult, String> {
     require_quickchat_window(&window)?;
     let message = message.trim().to_string();
     if message.is_empty() {
diff --git a/apps/linux/ui/quickchat.css b/apps/linux/ui/quickchat.css
index b1f06abbd65..21f7d9c2124 100644
--- a/apps/linux/ui/quickchat.css
+++ b/apps/linux/ui/quickchat.css
@@ -220,11 +220,98 @@ body.shown .composer {
     opacity 120ms ease;
 }
 
-.composer.has-error .status {
+.composer.has-error > .status,
+.reply.has-error .reply-error {
   max-height: 16px;
   opacity: 1;
 }
 
+.reply {
+  padding: 10px 3px 2px 46px;
+  border-top: 1px solid rgb(255 255 255 / 7%);
+  margin-top: 9px;
+}
+
+.reply-header {
+  display: flex;
+  min-height: 24px;
+  margin-bottom: 6px;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.reply-agent {
+  display: inline-flex;
+  min-width: 0;
+  padding: 2px 7px 2px 2px;
+  gap: 6px;
+  align-items: center;
+  border: 1px solid rgb(255 255 255 / 8%);
+  border-radius: 999px;
+  color: #d7d7da;
+  background: rgb(255 255 255 / 4%);
+}
+
+.reply-agent .agent-avatar-mini {
+  flex-basis: 20px;
+  width: 20px;
+  height: 20px;
+  font-size: 10px;
+}
+
+.reply-agent-name {
+  overflow: hidden;
+  font-size: 11px;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.reply-state {
+  padding-right: 3px;
+  color: #7f7f84;
+  font-size: 10px;
+  letter-spacing: 0.02em;
+  opacity: 0;
+  text-transform: uppercase;
+  transition: opacity 120ms ease;
+}
+
+.reply.is-terminal .reply-state {
+  opacity: 1;
+}
+
+.reply-scroll {
+  max-height: 228px;
+  padding-right: 5px;
+  overflow-y: auto;
+  scrollbar-color: rgb(255 255 255 / 16%) transparent;
+  scrollbar-width: thin;
+}
+
+.reply-text {
+  overflow-wrap: anywhere;
+  color: #ededee;
+  font: 400 13px/1.5 inherit;
+  white-space: pre-wrap;
+}
+
+.reply-thinking {
+  display: inline-block;
+  color: transparent;
+  font-size: 12px;
+  background: linear-gradient(100deg, #777 20%, #d2d2d4 48%, #777 76%);
+  -webkit-background-clip: text;
+  background-clip: text;
+  background-size: 220% 100%;
+  animation: shimmer 1.35s ease-in-out infinite;
+}
+
+.reply-error {
+  margin-left: 0;
+  white-space: normal;
+}
+
 .popover {
   position: absolute;
   z-index: 2;
@@ -356,6 +443,16 @@ body.shown .popover:not([hidden]) {
   }
 }
 
+@keyframes shimmer {
+  from {
+    background-position: 100% 0;
+  }
+
+  to {
+    background-position: -100% 0;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   *,
   *::before,
@@ -369,4 +466,9 @@ body.shown .popover:not([hidden]) {
   body.shown .composer {
     transform: none;
   }
+
+  .reply-thinking {
+    color: #8e8e93;
+    background: none;
+  }
 }
diff --git a/apps/linux/ui/quickchat.html b/apps/linux/ui/quickchat.html
index feb757aade1..b3048cfaa89 100644
--- a/apps/linux/ui/quickchat.html
+++ b/apps/linux/ui/quickchat.html
@@ -43,6 +43,20 @@
         </button>
       </div>
       <p id="status" class="status" role="alert"></p>
+      <section id="reply" class="reply" aria-label="Agent reply" aria-live="polite" hidden>
+        <div class="reply-header">
+          <div class="reply-agent">
+            <span id="reply-agent-avatar" class="agent-avatar-mini" aria-hidden="true">A</span>
+            <span id="reply-agent-name" class="reply-agent-name">Agent</span>
+          </div>
+          <span id="reply-state" class="reply-state" aria-hidden="true"></span>
+        </div>
+        <div id="reply-scroll" class="reply-scroll">
+          <div id="reply-text" class="reply-text"></div>
+          <span id="reply-thinking" class="reply-thinking">Thinking…</span>
+          <p id="reply-error" class="status reply-error" role="alert"></p>
+        </div>
+      </section>
     </main>
     <section id="agent-menu" class="popover" aria-label="Choose agent" hidden>
       <div class="popover-title">Agents</div>
diff --git a/apps/linux/ui/quickchat.js b/apps/linux/ui/quickchat.js
index 5d86af04c8a..68162618aa1 100644
--- a/apps/linux/ui/quickchat.js
+++ b/apps/linux/ui/quickchat.js
@@ -1,3 +1,46 @@
+// Pure stream helpers stay above browser bindings so the Node regression test can exercise the
+// Gateway-compatible assembler without constructing a WebView.
+function chatMessageText(message) {
+  const content = message?.content;
+  if (Array.isArray(content)) {
+    const textBlocks = content
+      .filter((block) => block?.type === "text" && typeof block.text === "string")
+      .map((block) => block.text);
+    if (textBlocks.length > 0) {
+      return textBlocks.join("\n\n");
+    }
+  }
+  // Match the Control UI fallback contract in ui/src/lib/chat/message-extract.ts: typed content
+  // blocks, then plain-string content, then top-level message.text.
+  if (typeof content === "string") {
+    return content;
+  }
+  return typeof message?.text === "string" ? message.text : null;
+}
+
+function assembleChatDelta(currentText, payload) {
+  const snapshot = chatMessageText(payload?.message);
+  if (typeof payload?.deltaText === "string") {
+    if (payload.replace === true) {
+      return payload.deltaText;
+    }
+    if (currentText === null) {
+      return snapshot ?? payload.deltaText;
+    }
+    if (snapshot !== null) {
+      const prefixLength = snapshot.length - payload.deltaText.length;
+      if (
+        prefixLength !== currentText.length ||
+        snapshot.slice(0, prefixLength) !== currentText
+      ) {
+        return snapshot;
+      }
+    }
+    return `${currentText}${payload.deltaText}`;
+  }
+  return snapshot;
+}
+
 const tauri = window["__TAURI__"];
 const { invoke } = tauri.core;
 const { listen } = tauri.event;
@@ -9,6 +52,14 @@ const elements = {
   agentMenu: document.querySelector("#agent-menu"),
   composer: document.querySelector("#composer"),
   input: document.querySelector("#message"),
+  reply: document.querySelector("#reply"),
+  replyAgentAvatar: document.querySelector("#reply-agent-avatar"),
+  replyAgentName: document.querySelector("#reply-agent-name"),
+  replyError: document.querySelector("#reply-error"),
+  replyScroll: document.querySelector("#reply-scroll"),
+  replyState: document.querySelector("#reply-state"),
+  replyText: document.querySelector("#reply-text"),
+  replyThinking: document.querySelector("#reply-thinking"),
   send: document.querySelector("#send"),
   sendIcon: document.querySelector("#send-icon"),
   shortcutCapture: document.querySelector("#shortcut-capture"),
@@ -33,9 +84,15 @@ let visibilitySequence = 0;
 let popoverSequence = 0;
 let sendError = "";
 let gatewayState = "down";
+let gatewayNotice = "";
+let gatewayDisconnectSequence = 0;
 let openPopover = null;
 let menuIndex = 0;
 let capturingShortcut = false;
+let activeReply = null;
+let pendingChatEvents = [];
+
+const MAX_PENDING_CHAT_EVENTS = 64;
 
 function friendlyError(error, fallback = "Could not send the message.") {
   if (typeof error === "string") {
@@ -51,19 +108,32 @@ function setError(message = "") {
 
 function renderStatus() {
   if (gatewayState === "pairing-required") {
-    setError("Pair this device from the dashboard");
+    setError(gatewayNotice || "Approve this device in the dashboard (Nodes)");
+    return;
+  }
+  if (gatewayState === "credential-required") {
+    setError(
+      gatewayNotice || "Gateway requires a credential — open the dashboard on the gateway host",
+    );
     return;
   }
   if (gatewayState === "tls-failure") {
     setError("Gateway TLS trust failed — check the certificate fingerprint");
     return;
   }
-  setError(gatewayState === "up" ? sendError : "Gateway unreachable — retrying");
+  setError(
+    gatewayState === "up" ? sendError : gatewayNotice || "Gateway unreachable — retrying",
+  );
 }
 
 function setGatewayState(payload) {
   const wasUp = gatewayState === "up";
   gatewayState = payload?.state || "down";
+  gatewayNotice = typeof payload?.notice === "string" ? payload.notice : "";
+  if (gatewayState !== "up") {
+    gatewayDisconnectSequence += 1;
+    terminalizeDisconnectedReply();
+  }
   renderStatus();
   updateSendButton();
   if (gatewayState === "up" && !wasUp) {
@@ -73,12 +143,13 @@ function setGatewayState(payload) {
 
 function updateSendButton() {
   const empty = !elements.input.value.trim();
+  const streaming = activeReply !== null && !activeReply.terminal;
   elements.send.disabled =
-    gatewayState !== "up" || empty || selectingAgent || sending || accepted;
+    gatewayState !== "up" || empty || selectingAgent || sending || accepted || streaming;
   elements.send.classList.toggle("sending", sending);
   elements.send.classList.toggle("accepted", accepted);
   elements.sendIcon.textContent = sending ? "" : accepted ? "✓" : "↑";
-  elements.input.readOnly = sending || accepted;
+  elements.input.readOnly = sending || accepted || streaming;
 }
 
 function nameHue(name) {
@@ -115,6 +186,150 @@ function renderAvatar(target, identity) {
   target.replaceChildren(image);
 }
 
+function resetAccepted() {
+  window.clearTimeout(acceptedTimer);
+  acceptedTimer = null;
+  accepted = false;
+}
+
+function clearReply() {
+  activeReply = null;
+  elements.reply.hidden = true;
+  elements.reply.classList.remove("has-error", "is-terminal");
+  elements.replyError.textContent = "";
+  elements.replyState.textContent = "";
+  elements.replyText.textContent = "";
+  elements.replyThinking.hidden = true;
+}
+
+function scrollReplyToEnd() {
+  window.requestAnimationFrame(() => {
+    elements.replyScroll.scrollTop = elements.replyScroll.scrollHeight;
+  });
+}
+
+function renderReplyText() {
+  // Deliberately plain text: this small native surface avoids a Markdown dependency and preserves
+  // whitespace, leaving Markdown punctuation visible instead of interpreting agent output.
+  elements.replyText.textContent = activeReply?.text || "";
+  scrollReplyToEnd();
+}
+
+function stopReplyThinking() {
+  elements.replyThinking.hidden = true;
+}
+
+function terminalizeDisconnectedReply() {
+  if (!activeReply || activeReply.terminal) {
+    return;
+  }
+  // Chat events are not replayed after a socket gap. Unlock the composer instead of leaving a
+  // reply waiting forever for a terminal frame that may have been lost while disconnected.
+  activeReply.terminal = true;
+  stopReplyThinking();
+  elements.reply.classList.add("has-error", "is-terminal");
+  elements.replyState.textContent = "Interrupted";
+  elements.replyError.textContent = "Connection lost before the reply completed.";
+  scrollReplyToEnd();
+}
+
+function replyTargetMatches(target, payload) {
+  if (!target || payload?.sessionKey !== target.sessionKey) {
+    return false;
+  }
+  return target.agentId == null || payload?.agentId === target.agentId;
+}
+
+function startReply(target, identity, runId) {
+  activeReply = {
+    runId,
+    target: {
+      sessionKey: target.sessionKey,
+      agentId: typeof target.agentId === "string" ? target.agentId : null,
+    },
+    terminal: false,
+    text: null,
+  };
+  elements.reply.hidden = false;
+  elements.reply.classList.remove("has-error", "is-terminal");
+  elements.replyError.textContent = "";
+  elements.replyState.textContent = "";
+  elements.replyText.textContent = "";
+  elements.replyThinking.textContent = reducedMotion.matches ? "…" : "Thinking…";
+  elements.replyThinking.hidden = false;
+  renderAvatar(elements.replyAgentAvatar, identity);
+  elements.replyAgentName.textContent = identity?.name?.trim() || "Agent";
+  void invoke("quickchat_set_expanded", { expanded: true });
+}
+
+function applyChatEvent(payload) {
+  if (!activeReply) {
+    return;
+  }
+  // The chat.send ACK owns this reply. Exact runId equality is primary; the routing target remains
+  // a secondary guard so concurrent turns from other surfaces never enter this reply area.
+  if (payload?.runId !== activeReply.runId || !replyTargetMatches(activeReply.target, payload)) {
+    return;
+  }
+  if (activeReply.terminal) {
+    return;
+  }
+
+  const hasTextUpdate =
+    typeof payload?.deltaText === "string" || chatMessageText(payload?.message) !== null;
+  if (hasTextUpdate) {
+    const nextText = assembleChatDelta(activeReply.text, payload);
+    if (nextText !== null) {
+      activeReply.text = nextText;
+      renderReplyText();
+    }
+  }
+
+  if (payload?.state === "delta") {
+    stopReplyThinking();
+    return;
+  }
+  if (!["final", "aborted", "error"].includes(payload?.state)) {
+    return;
+  }
+
+  activeReply.terminal = true;
+  pendingChatEvents = [];
+  stopReplyThinking();
+  elements.reply.classList.add("is-terminal");
+  if (payload.state === "final") {
+    elements.replyState.textContent = "Done";
+  } else if (payload.state === "aborted") {
+    activeReply.text = `${activeReply.text || ""}${activeReply.text ? "\n\n" : ""}(stopped)`;
+    elements.replyState.textContent = "Stopped";
+    renderReplyText();
+  } else {
+    elements.reply.classList.add("has-error");
+    elements.replyState.textContent = "Error";
+    elements.replyError.textContent =
+      typeof payload.errorMessage === "string" && payload.errorMessage.trim()
+        ? payload.errorMessage
+        : "Gateway reply failed.";
+    scrollReplyToEnd();
+  }
+  updateSendButton();
+}
+
+function handleChatEvent(payload) {
+  if (activeReply) {
+    applyChatEvent(payload);
+    return;
+  }
+  if (sending) {
+    // The Gateway may stream before the chat.send ack reaches invoke; replay only after the native
+    // command returns the accepted routing target, then apply the same session/run filters.
+    if (pendingChatEvents.length === MAX_PENDING_CHAT_EVENTS) {
+      pendingChatEvents.shift();
+    }
+    pendingChatEvents.push(payload);
+  }
+}
+
 function renderIdentity(identity) {
   const name = identity?.name?.trim() || "Agent";
   activeIdentity = { ...identity, name };
@@ -240,7 +455,7 @@ function closePopover(focusInput = true, compact = true) {
   ++popoverSequence;
   setPopoverVisibility(null);
   if (compact) {
-    void invoke("quickchat_set_expanded", { expanded: false });
+    void invoke("quickchat_set_expanded", { expanded: !elements.reply.hidden });
   }
   if (focusInput) {
     elements.input.focus();
@@ -318,13 +533,14 @@ async function saveShortcut(accelerator) {
   }
 }
 
-async function requestHide(force = false) {
-  if ((accepted && !force) || hiding) {
+async function requestHide() {
+  if (hiding) {
     return;
   }
   visibilitySequence += 1;
   const hideSequence = visibilitySequence;
   hiding = true;
+  pendingChatEvents = [];
   closePopover(false, false);
   document.body.classList.remove("shown");
   window.clearTimeout(hideTimer);
@@ -332,6 +548,8 @@ async function requestHide(force = false) {
     async () => {
       try {
         await invoke("quickchat_hide");
+        resetAccepted();
+        clearReply();
       } catch (error) {
         if (visibilitySequence === hideSequence) {
           sendError = friendlyError(error);
@@ -351,11 +569,7 @@ async function requestHide(force = false) {
 
 function reveal() {
   window.clearTimeout(hideTimer);
-  if (accepted) {
-    window.clearTimeout(acceptedTimer);
-    acceptedTimer = null;
-    accepted = false;
-  }
+  resetAccepted();
   hiding = false;
   setPopoverVisibility(null);
   renderStatus();
@@ -377,26 +591,57 @@ async function send(openDashboard) {
     return;
   }
   sending = true;
+  const sendDisconnectSequence = gatewayDisconnectSequence;
+  const sendVisibilitySequence = visibilitySequence;
+  clearReply();
+  pendingChatEvents = [];
+  void invoke("quickchat_set_expanded", { expanded: false });
   sendError = "";
   renderStatus();
   updateSendButton();
   try {
-    await invoke("quickchat_send", { message });
+    const sentIdentity = { ...activeIdentity };
+    const result = await invoke("quickchat_send", { message });
+    if (!result || typeof result.sessionKey !== "string") {
+      throw new Error("Gateway accepted the message without a routing target.");
+    }
+    if (typeof result.runId !== "string" || !result.runId) {
+      throw new Error("Gateway accepted the message without a run ID.");
+    }
     sending = false;
-    accepted = true;
     sendError = "";
     elements.input.value = "";
+    if (visibilitySequence !== sendVisibilitySequence || hiding) {
+      pendingChatEvents = [];
+      updateSendButton();
+      return;
+    }
+    accepted = true;
+    startReply(result, sentIdentity, result.runId);
+    const bufferedEvents = pendingChatEvents;
+    pendingChatEvents = [];
+    for (const payload of bufferedEvents) {
+      applyChatEvent(payload);
+    }
+    if (gatewayDisconnectSequence !== sendDisconnectSequence || gatewayState !== "up") {
+      terminalizeDisconnectedReply();
+    }
     updateSendButton();
     if (openDashboard) {
       void invoke("quickchat_show_dashboard");
     }
     acceptedTimer = window.setTimeout(() => {
       accepted = false;
+      acceptedTimer = null;
       updateSendButton();
-      void requestHide(true);
     }, 450);
   } catch (error) {
     sending = false;
+    pendingChatEvents = [];
+    if (visibilitySequence !== sendVisibilitySequence || hiding) {
+      updateSendButton();
+      return;
+    }
     sendError = friendlyError(error);
     renderStatus();
     updateSendButton();
@@ -426,7 +671,7 @@ elements.input.addEventListener("keydown", (event) => {
   }
   if (event.key === "Enter" && !openPopover) {
     event.preventDefault();
-    void send(event.ctrlKey);
+    void send(event.ctrlKey || event.metaKey);
   }
 });
 elements.agentChip.addEventListener("click", () => {
@@ -510,6 +755,9 @@ await listen("quickchat:hide-requested", () => {
 await listen("quickchat:gateway-state", (event) => {
   setGatewayState(event.payload);
 });
+await listen("quickchat:chat-event", (event) => {
+  handleChatEvent(event.payload);
+});
 
 const readySequence = visibilitySequence;
 try {
@@ -518,9 +766,9 @@ try {
     if (shouldShow) {
       reveal();
     } else {
-      void requestHide(true);
+      void requestHide();
     }
   }
 } catch {
-  void requestHide(true);
+  void requestHide();
 }
diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md
index 300d4e99497..3dc852681aa 100644
--- a/docs/platforms/linux.md
+++ b/docs/platforms/linux.md
@@ -62,7 +62,12 @@ Chat's WebView receives neither credentials nor the WebSocket.
 
 When the native connection is unavailable, Quick Chat shows **Gateway
 unreachable — retrying** and disables send until reconnection. A remote device
-that needs approval shows **Pair this device from the dashboard** instead.
+that has reached the pairing phase shows **Approve this device in the dashboard
+(Nodes)** instead, with a short device ID when the Gateway provides one. A
+Gateway that requires a missing shared credential shows **Gateway requires a
+credential — open the dashboard on the gateway host**; no pairing request is
+waiting for approval in that state. Server-provided remediation guidance
+replaces these fallback notices when it is more specific.
 For TLS Gateways, the CLI hands the app the Gateway certificate's SHA-256
 fingerprint; the native client pins that certificate and reports **Gateway TLS
 trust failed — check the certificate fingerprint** separately from downtime.
@@ -70,12 +75,16 @@ Gateways whose shared secret is configured through a SecretRef omit it from the
 CLI handoff. Existing paired installs keep working through their stored device
 token, but a fresh install cannot create a pending pairing request under shared-secret
 authentication without that bootstrap credential.
+Setup-code and `bootstrapToken` redemption need dedicated product UI and remain
+a follow-up; Quick Chat does not attempt either flow.
 
 On X11, use the gear in Quick Chat to record or reset a custom shortcut. The
 **Quick Chat shortcut** tray toggle enables or disables it without disabling the
 plain **Quick Chat** tray item. Global shortcuts are not available on Wayland, so
 the shortcut settings are hidden and the tray item remains the entry point.
-Replies remain in the normal session; open the dashboard to read them.
+After an accepted send, Quick Chat stays open and streams the selected agent's
+plain-text reply below the composer. Press `Esc` to dismiss the bar and its reply;
+`Ctrl+Enter` still opens the dashboard.
 
 ### Canvas
 
diff --git a/test/linux-quickchat-stream.test.ts b/test/linux-quickchat-stream.test.ts
new file mode 100644
index 00000000000..66a777e5c6e
--- /dev/null
+++ b/test/linux-quickchat-stream.test.ts
@@ -0,0 +1,270 @@
+// Exercises the pure stream-assembly helpers extracted from the Linux Quick Chat webview script.
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import vm from "node:vm";
+import { it as test } from "vitest";
+
+const quickchatSource = readFileSync(
+  new URL("../apps/linux/ui/quickchat.js", import.meta.url),
+  "utf8",
+);
+const browserBindingsStart = quickchatSource.indexOf("const tauri = window");
+assert.notEqual(browserBindingsStart, -1, "quickchat pure-helper boundary");
+
+const context: Record<
+  string,
+  {
+    assembleChatDelta: (state: unknown, payload: unknown) => unknown;
+    chatMessageText: (message: unknown) => string;
+  }
+> &
+  Record<string, unknown> = {};
+vm.runInNewContext(
+  `${quickchatSource.slice(0, browserBindingsStart)}\nthis.helpers = { assembleChatDelta, chatMessageText };`,
+  context,
+);
+const { assembleChatDelta, chatMessageText } = context.helpers as {
+  assembleChatDelta: (state: unknown, payload: unknown) => { text: string; runId?: string };
+  chatMessageText: (message: unknown) => string;
+};
+
+function createFakeElement() {
+  const classes = new Set();
+  return {
+    classList: {
+      add: (...names: string[]) => names.forEach((name) => classes.add(name)),
+      remove: (...names: string[]) => names.forEach((name) => classes.delete(name)),
+      toggle(name: string, force?: boolean) {
+        const enabled = force ?? !classes.has(name);
+        if (enabled) {
+          classes.add(name);
+        } else {
+          classes.delete(name);
+        }
+        return enabled;
+      },
+    },
+    style: { setProperty() {} },
+    value: "",
+    textContent: "",
+    hidden: false,
+    disabled: false,
+    readOnly: false,
+    scrollHeight: 0,
+    scrollTop: 0,
+    addEventListener() {},
+    contains() {
+      return false;
+    },
+    focus() {},
+    querySelectorAll() {
+      return [];
+    },
+    replaceChildren() {},
+    setAttribute() {},
+  };
+}
+
+function createQuickChatHarness(): Record<string, any> {
+  const browserBindingsEnd = quickchatSource.indexOf("elements.input.addEventListener");
+  assert.notEqual(browserBindingsEnd, -1, "quickchat browser binding boundary");
+  const elements = new Map();
+  let resolveSend;
+  const sendResult = new Promise((resolve) => {
+    resolveSend = resolve;
+  });
+  const window = {
+    __TAURI__: {
+      core: {
+        invoke(method: string) {
+          return method === "quickchat_send" ? sendResult : Promise.resolve(null);
+        },
+      },
+      event: { listen: async () => () => {} },
+    },
+    clearTimeout() {},
+    matchMedia: () => ({ matches: true }),
+    requestAnimationFrame(callback: () => void) {
+      callback();
+    },
+    setTimeout: () => 1,
+  };
+  const document = {
+    body: createFakeElement(),
+    createElement: () => createFakeElement(),
+    createTextNode: (text: string) => ({ textContent: text }),
+    querySelector(selector: string) {
+      if (!elements.has(selector)) {
+        elements.set(selector, createFakeElement());
+      }
+      return elements.get(selector);
+    },
+  };
+  const browserContext: Record<string, any> = { document, window };
+  vm.runInNewContext(
+    `${quickchatSource.slice(0, browserBindingsEnd)}
+this.harness = {
+  send,
+  handleChatEvent,
+  requestHide,
+  setGatewayUp() { gatewayState = "up"; },
+  setMessage(value) { elements.input.value = value; },
+  pendingCount() { return pendingChatEvents.length; },
+  activeRunId() { return activeReply?.runId ?? null; },
+  replyText() { return elements.replyText.textContent; },
+};`,
+    browserContext,
+  );
+  return { ...(browserContext.harness as Record<string, (...args: any[]) => any>), resolveSend };
+}
+
+test("replace deltas are authoritative", () => {
+  assert.equal(
+    assembleChatDelta("stale", {
+      deltaText: "replacement",
+      replace: true,
+      message: { content: [{ type: "text", text: "ignored snapshot" }] },
+    }),
+    "replacement",
+  );
+});
+
+test("the first delta seeds from its message snapshot", () => {
+  assert.equal(
+    assembleChatDelta(null, {
+      deltaText: "lo",
+      message: { content: [{ type: "text", text: "Hello" }] },
+    }),
+    "Hello",
+  );
+  assert.equal(assembleChatDelta(null, { deltaText: "Hi" }), "Hi");
+});
+
+test("matching deltas append and mismatched snapshots self-heal", () => {
+  assert.equal(
+    assembleChatDelta("Hello", {
+      deltaText: "!",
+      message: { content: [{ type: "text", text: "Hello!" }] },
+    }),
+    "Hello!",
+  );
+  assert.equal(
+    assembleChatDelta("Hellx", {
+      deltaText: "!",
+      message: { content: [{ type: "text", text: "Hello!" }] },
+    }),
+    "Hello!",
+  );
+});
+
+test("snapshot-only terminal frames replace the assembled text", () => {
+  assert.equal(
+    assembleChatDelta("partial", {
+      message: { content: [{ type: "text", text: "complete" }] },
+    }),
+    "complete",
+  );
+});
+
+test("snapshot extraction joins every text block", () => {
+  assert.equal(
+    chatMessageText({
+      content: [
+        { type: "text", text: "first" },
+        { type: "image", url: "data:image/png;base64,AA==" },
+        { type: "text", text: "second" },
+      ],
+    }),
+    "first\n\nsecond",
+  );
+});
+
+test("snapshot extraction skips a leading non-text block", () => {
+  assert.equal(
+    chatMessageText({
+      content: [
+        { type: "thinking", thinking: "hidden" },
+        { type: "text", text: "visible" },
+      ],
+    }),
+    "visible",
+  );
+});
+
+test("snapshot extraction falls back through string content and top-level text", () => {
+  assert.equal(chatMessageText({ content: "string content", text: "top-level" }), "string content");
+  assert.equal(chatMessageText({ content: [], text: "top-level" }), "top-level");
+});
+
+test("pre-ack frames replay once for only the acknowledged run", async () => {
+  const harness = createQuickChatHarness();
+  harness.setGatewayUp();
+  harness.setMessage("hello");
+  const sending = harness.send(false);
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "work",
+    runId: "wrong-run",
+    state: "delta",
+    deltaText: "wrong",
+  });
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "work",
+    runId: "right-run",
+    state: "delta",
+    deltaText: "right",
+  });
+  assert.equal(harness.pendingCount(), 2);
+
+  harness.resolveSend({ sessionKey: "global", agentId: "work", runId: "right-run" });
+  await sending;
+
+  assert.equal(harness.pendingCount(), 0);
+  assert.equal(harness.activeRunId(), "right-run");
+  assert.equal(harness.replyText(), "right");
+
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "work",
+    runId: " right-run ",
+    state: "delta",
+    deltaText: " whitespace-id",
+  });
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "other-agent",
+    runId: "right-run",
+    state: "delta",
+    deltaText: " wrong-agent",
+  });
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "work",
+    runId: "right-run",
+    state: "delta",
+    deltaText: "!",
+  });
+  assert.equal(harness.replyText(), "right!");
+});
+
+test("hiding clears buffered pre-ack frames", async () => {
+  const harness = createQuickChatHarness();
+  harness.setGatewayUp();
+  harness.setMessage("hello");
+  const sending = harness.send(false);
+  harness.handleChatEvent({
+    sessionKey: "global",
+    agentId: "work",
+    runId: "right-run",
+    state: "delta",
+    deltaText: "buffered",
+  });
+  assert.equal(harness.pendingCount(), 1);
+
+  await harness.requestHide();
+  assert.equal(harness.pendingCount(), 0);
+  harness.resolveSend({ sessionKey: "global", agentId: "work", runId: "right-run" });
+  await sending;
+  assert.equal(harness.replyText(), "");
+});

From 28069db63aad2cc92d367fd441eec6d3e8c77041 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:23:59 +0100
Subject: [PATCH 58/76] feat(macos): render system chat option cards (#110584)

* feat(macos): render system chat option cards

* fix(macos): localize question card controls

* test(macos): stabilize main actor attachment tests
---
 apps/.i18n/native-source.json                 |  32 ++-
 apps/.i18n/native/ar.json                     |  10 +
 apps/.i18n/native/de.json                     |  10 +
 apps/.i18n/native/es.json                     |  10 +
 apps/.i18n/native/fa.json                     |  10 +
 apps/.i18n/native/fr.json                     |  10 +
 apps/.i18n/native/hi.json                     |  10 +
 apps/.i18n/native/id.json                     |  10 +
 apps/.i18n/native/it.json                     |  10 +
 apps/.i18n/native/ja-JP.json                  |  10 +
 apps/.i18n/native/ko.json                     |  10 +
 apps/.i18n/native/nl.json                     |  10 +
 apps/.i18n/native/pl.json                     |  10 +
 apps/.i18n/native/pt-BR.json                  |  10 +
 apps/.i18n/native/ru.json                     |  10 +
 apps/.i18n/native/sv.json                     |  10 +
 apps/.i18n/native/th.json                     |  10 +
 apps/.i18n/native/tr.json                     |  10 +
 apps/.i18n/native/uk.json                     |  10 +
 apps/.i18n/native/vi.json                     |  10 +
 apps/.i18n/native/zh-CN.json                  |  10 +
 apps/.i18n/native/zh-TW.json                  |  10 +
 .../OpenClaw/OnboardingSystemAgentChat.swift  | 186 ++++++++++++++++--
 .../OnboardingSystemAgentChatTests.swift      | 140 ++++++++++++-
 .../OpenClawKit/SystemAgentChatQuestion.swift |  63 ++++++
 .../ChatViewModelAttachmentTests.swift        |   6 +-
 .../SystemAgentChatQuestionTests.swift        | 104 ++++++++++
 docs/start/onboarding.md                      |   5 +-
 28 files changed, 716 insertions(+), 30 deletions(-)
 create mode 100644 apps/shared/OpenClawKit/Sources/OpenClawKit/SystemAgentChatQuestion.swift
 create mode 100644 apps/shared/OpenClawKit/Tests/OpenClawKitTests/SystemAgentChatQuestionTests.swift

diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json
index 5a9304050e0..9b72511f992 100644
--- a/apps/.i18n/native-source.json
+++ b/apps/.i18n/native-source.json
@@ -32243,7 +32243,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 10,
+      "line": 11,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "Wake up, my friend!",
       "surface": "apple",
@@ -32251,7 +32251,7 @@
     },
     {
       "kind": "conditional-branch",
-      "line": 129,
+      "line": 229,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "<redacted secret>",
       "surface": "apple",
@@ -32259,7 +32259,7 @@
     },
     {
       "kind": "conditional-branch",
-      "line": 228,
+      "line": 288,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "OpenClaw was interrupted. Restart to try again.",
       "surface": "apple",
@@ -32267,7 +32267,7 @@
     },
     {
       "kind": "conditional-branch",
-      "line": 229,
+      "line": 289,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "The Gateway connection changed. Restart OpenClaw to reconnect.",
       "surface": "apple",
@@ -32275,7 +32275,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 253,
+      "line": 331,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "OpenClaw is working…",
       "surface": "apple",
@@ -32283,7 +32283,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 278,
+      "line": 356,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "Restart",
       "surface": "apple",
@@ -32291,7 +32291,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 289,
+      "line": 367,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "Enter secret…",
       "surface": "apple",
@@ -32299,12 +32299,28 @@
     },
     {
       "kind": "ui-call",
-      "line": 291,
+      "line": 369,
       "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "surface": "apple",
       "id": "native.apple.35a542956f4f5497"
     },
+    {
+      "kind": "ui-call",
+      "line": 409,
+      "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
+      "source": "Skip for now",
+      "surface": "apple",
+      "id": "native.apple.134b9ae1d8a543df"
+    },
+    {
+      "kind": "ui-call",
+      "line": 444,
+      "path": "apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift",
+      "source": "Recommended",
+      "surface": "apple",
+      "id": "native.apple.5435391fa338f227"
+    },
     {
       "kind": "ui-call",
       "line": 10,
diff --git a/apps/.i18n/native/ar.json b/apps/.i18n/native/ar.json
index 2698e247d00..9c72e30e546 100644
--- a/apps/.i18n/native/ar.json
+++ b/apps/.i18n/native/ar.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "رد على OpenClaw… (تؤدي الإجابة بنعم إلى إعداد كل شيء)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "تخطي الآن"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "موصى به"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/de.json b/apps/.i18n/native/de.json
index 5f93ae8c189..6936c497922 100644
--- a/apps/.i18n/native/de.json
+++ b/apps/.i18n/native/de.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "OpenClaw antworten… („yes“ richtet alles ein)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Vorerst überspringen"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Empfohlen"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/es.json b/apps/.i18n/native/es.json
index 3fc69f9e398..6aa37f60f72 100644
--- a/apps/.i18n/native/es.json
+++ b/apps/.i18n/native/es.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Responde a OpenClaw… («sí» lo configura todo)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Omitir por ahora"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Recomendado"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/fa.json b/apps/.i18n/native/fa.json
index 0d73f0b9ab2..216e7830794 100644
--- a/apps/.i18n/native/fa.json
+++ b/apps/.i18n/native/fa.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "به OpenClaw پاسخ دهید… (با «بله» همه‌چیز راه‌اندازی می‌شود)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "فعلاً رد شود"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "پیشنهادشده"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/fr.json b/apps/.i18n/native/fr.json
index 578fd210a50..9afa88f674f 100644
--- a/apps/.i18n/native/fr.json
+++ b/apps/.i18n/native/fr.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Répondre à OpenClaw… (« yes » configure tout)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Ignorer pour l’instant"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Recommandé"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/hi.json b/apps/.i18n/native/hi.json
index 9d0e2e93564..1756e77d771 100644
--- a/apps/.i18n/native/hi.json
+++ b/apps/.i18n/native/hi.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "OpenClaw को जवाब दें… (हाँ कहने पर सब कुछ सेट हो जाएगा)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "अभी के लिए छोड़ें"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "अनुशंसित"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/id.json b/apps/.i18n/native/id.json
index 6d8c5fae09d..8bd4df8cd41 100644
--- a/apps/.i18n/native/id.json
+++ b/apps/.i18n/native/id.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Balas OpenClaw… (yes menyiapkan semuanya)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Lewati untuk sekarang"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Direkomendasikan"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/it.json b/apps/.i18n/native/it.json
index 395dff367e6..e9165565695 100644
--- a/apps/.i18n/native/it.json
+++ b/apps/.i18n/native/it.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Rispondi a OpenClaw… (sì configura tutto)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Salta per ora"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Consigliato"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/ja-JP.json b/apps/.i18n/native/ja-JP.json
index 0f711b64b8c..b9e31674c2c 100644
--- a/apps/.i18n/native/ja-JP.json
+++ b/apps/.i18n/native/ja-JP.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "OpenClawに返信…（yesですべてセットアップされます）"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "今はスキップ"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "おすすめ"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/ko.json b/apps/.i18n/native/ko.json
index e3aea0e9edb..652b5c3e550 100644
--- a/apps/.i18n/native/ko.json
+++ b/apps/.i18n/native/ko.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "OpenClaw에 답장… (yes를 입력하면 모든 설정이 완료됩니다)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "지금은 건너뛰기"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "권장"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/nl.json b/apps/.i18n/native/nl.json
index ebeacd69de1..ac55f7b12f3 100644
--- a/apps/.i18n/native/nl.json
+++ b/apps/.i18n/native/nl.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Antwoord aan OpenClaw… (met ja wordt alles ingesteld)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Voor nu overslaan"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Aanbevolen"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/pl.json b/apps/.i18n/native/pl.json
index f8c52040a94..fc9772e9b76 100644
--- a/apps/.i18n/native/pl.json
+++ b/apps/.i18n/native/pl.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Odpowiedz OpenClaw… („yes” skonfiguruje wszystko)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Pomiń na razie"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Zalecane"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/pt-BR.json b/apps/.i18n/native/pt-BR.json
index 19157fc44a0..4f46705ec54 100644
--- a/apps/.i18n/native/pt-BR.json
+++ b/apps/.i18n/native/pt-BR.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Responda ao OpenClaw… (sim configura tudo)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Pular por enquanto"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Recomendado"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/ru.json b/apps/.i18n/native/ru.json
index b85d5701a5c..93b72c61f39 100644
--- a/apps/.i18n/native/ru.json
+++ b/apps/.i18n/native/ru.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Ответьте OpenClaw… (yes настроит всё)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Пропустить пока"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Рекомендуется"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/sv.json b/apps/.i18n/native/sv.json
index 82875ddfbac..055980b9650 100644
--- a/apps/.i18n/native/sv.json
+++ b/apps/.i18n/native/sv.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Svara OpenClaw… (ja konfigurerar allt)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Hoppa över tills vidare"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Rekommenderas"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/th.json b/apps/.i18n/native/th.json
index 5bf285935c3..f04d133b26b 100644
--- a/apps/.i18n/native/th.json
+++ b/apps/.i18n/native/th.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "ตอบกลับ OpenClaw… (พิมพ์ yes เพื่อตั้งค่าทุกอย่าง)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "ข้ามไปก่อน"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "แนะนำ"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/tr.json b/apps/.i18n/native/tr.json
index a34847d4884..3acba5e8713 100644
--- a/apps/.i18n/native/tr.json
+++ b/apps/.i18n/native/tr.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "OpenClaw'a yanıt verin… (evet, her şeyi ayarlar)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Şimdilik atla"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Önerilen"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/uk.json b/apps/.i18n/native/uk.json
index bbdbab70e4d..afc99d27cdd 100644
--- a/apps/.i18n/native/uk.json
+++ b/apps/.i18n/native/uk.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Відповісти OpenClaw… (так налаштує все)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Пропустити зараз"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Рекомендовано"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/vi.json b/apps/.i18n/native/vi.json
index 1e4200348a2..9652f177c89 100644
--- a/apps/.i18n/native/vi.json
+++ b/apps/.i18n/native/vi.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "Trả lời OpenClaw… (chọn có để thiết lập mọi thứ)"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "Bỏ qua lúc này"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "Được đề xuất"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/zh-CN.json b/apps/.i18n/native/zh-CN.json
index 59c85e46326..02ae28184cc 100644
--- a/apps/.i18n/native/zh-CN.json
+++ b/apps/.i18n/native/zh-CN.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "回复 OpenClaw…（回复 yes 即可完成所有设置）"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "暂时跳过"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "推荐"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/.i18n/native/zh-TW.json b/apps/.i18n/native/zh-TW.json
index 5456d8f418e..7099064c50c 100644
--- a/apps/.i18n/native/zh-TW.json
+++ b/apps/.i18n/native/zh-TW.json
@@ -20193,6 +20193,16 @@
       "source": "Reply to OpenClaw… (yes sets everything up)",
       "translated": "回覆 OpenClaw…（輸入 yes 即可完成所有設定）"
     },
+    {
+      "id": "native.apple.134b9ae1d8a543df",
+      "source": "Skip for now",
+      "translated": "暫時略過"
+    },
+    {
+      "id": "native.apple.5435391fa338f227",
+      "source": "Recommended",
+      "translated": "建議"
+    },
     {
       "id": "native.apple.78d1ad73762a7ce8",
       "source": "Connect your AI",
diff --git a/apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift b/apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift
index da3412de170..66dff302560 100644
--- a/apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift
+++ b/apps/macos/Sources/OpenClaw/OnboardingSystemAgentChat.swift
@@ -1,5 +1,6 @@
 import Foundation
 import Observation
+import OpenClawKit
 import SwiftUI
 
 enum SystemAgentDraft: String, Decodable {
@@ -60,12 +61,21 @@ final class SystemAgentOnboardingChatModel {
         let id = UUID()
         let role: Role
         let text: String
+        let question: SystemAgentChatQuestion?
+
+        init(role: Role, text: String, question: SystemAgentChatQuestion? = nil) {
+            self.role = role
+            self.text = text
+            self.question = question
+        }
     }
 
     private(set) var messages: [Message] = []
     private(set) var isSending = false
     private(set) var errorMessage: String?
     private(set) var expectsSensitiveReply = false
+    private(set) var dismissedQuestionMessageIDs: Set<UUID> = []
+    private(set) var retiredQuestionMessageIDs: Set<UUID> = []
     var input = ""
     /// Set when OpenClaw hands off to the normal agent ("talk to agent").
     var onAgentHandoff: ((SystemAgentDraft?) -> Void)?
@@ -100,6 +110,7 @@ final class SystemAgentOnboardingChatModel {
         let action: String
         let sensitive: Bool?
         let agentDraft: SystemAgentDraft?
+        let question: AnyCodable?
     }
 
     func startIfNeeded() async {
@@ -118,23 +129,42 @@ final class SystemAgentOnboardingChatModel {
     @discardableResult
     func send() -> Task<Void, Never>? {
         let text = self.input.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard let generation = self.requestGeneration,
-              !text.isEmpty,
-              !self.isSending,
-              self.errorMessage == nil
+        return self.send(message: text)
+    }
+
+    @discardableResult
+    func answerQuestion(messageID: UUID, optionLabel: String) -> Task<Void, Never>? {
+        guard let message = self.messages.first(where: { $0.id == messageID }),
+              let question = message.question,
+              let option = question.options.first(where: { $0.label == optionLabel }),
+              self.canAnswerQuestion(message)
         else { return nil }
-        self.input = ""
-        self.messages.append(Message(
-            role: .user,
-            text: self.expectsSensitiveReply ? "<redacted secret>" : text))
-        let task = Task { [weak self] in
-            guard let self else { return }
-            await self.requestReply(message: text, generation: generation)
-        }
-        self.requestTask = task
+        // The typed Gateway contract separates the visible label from its canonical reply.
+        // Keep the transcript human-readable while returning the machine-facing value.
+        return self.send(message: option.reply ?? option.label, displayText: option.label)
+    }
+
+    @discardableResult
+    func skipQuestion(messageID: UUID) -> Task<Void, Never>? {
+        guard let message = self.messages.first(where: { $0.id == messageID }),
+              self.canAnswerQuestion(message),
+              let task = self.send(message: "Skip for now", displayText: "Skip for now")
+        else { return nil }
+        self.dismissedQuestionMessageIDs.insert(messageID)
         return task
     }
 
+    func isQuestionVisible(_ message: Message) -> Bool {
+        message.question != nil && !self.dismissedQuestionMessageIDs.contains(message.id)
+    }
+
+    func canAnswerQuestion(_ message: Message) -> Bool {
+        self.isQuestionVisible(message) &&
+            !self.retiredQuestionMessageIDs.contains(message.id) &&
+            !self.isSending &&
+            self.errorMessage == nil
+    }
+
     @discardableResult
     func restartAfterError() -> Task<Void, Never>? {
         guard let previousGeneration = self.requestGeneration else { return nil }
@@ -145,6 +175,8 @@ final class SystemAgentOnboardingChatModel {
         self.route = nil
         self.started = true
         self.messages.removeAll()
+        self.dismissedQuestionMessageIDs.removeAll()
+        self.retiredQuestionMessageIDs.removeAll()
         self.input = ""
         self.expectsSensitiveReply = false
         let task = Task { [weak self] in
@@ -184,6 +216,31 @@ final class SystemAgentOnboardingChatModel {
         return route
     }
 
+    private func send(message: String, displayText: String? = nil) -> Task<Void, Never>? {
+        guard let generation = self.requestGeneration,
+              !message.isEmpty,
+              !self.isSending,
+              self.errorMessage == nil
+        else { return nil }
+        self.retireQuestions()
+        self.input = ""
+        self.messages.append(Message(
+            role: .user,
+            text: displayText ?? (self.expectsSensitiveReply ? "<redacted secret>" : message)))
+        let task = Task { [weak self] in
+            guard let self else { return }
+            await self.requestReply(message: message, generation: generation)
+        }
+        self.requestTask = task
+        return task
+    }
+
+    private func retireQuestions() {
+        for message in self.messages where message.question != nil {
+            self.retiredQuestionMessageIDs.insert(message.id)
+        }
+    }
+
     private func requestReply(message: String?, generation: UInt64) async {
         guard self.isCurrentRequest(generation) else { return }
         self.isSending = true
@@ -215,7 +272,10 @@ final class SystemAgentOnboardingChatModel {
             let result = try JSONDecoder().decode(ChatResult.self, from: data)
             guard self.isCurrentRequest(generation) else { return }
             self.expectsSensitiveReply = result.sensitive == true
-            self.messages.append(Message(role: .assistant, text: result.reply))
+            self.messages.append(Message(
+                role: .assistant,
+                text: result.reply,
+                question: SystemAgentChatQuestion.parse(result.question?.dictionaryValue)))
             self.onReplyReceived?()
             if result.action == "open-agent" {
                 self.onAgentHandoff?(result.agentDraft)
@@ -243,8 +303,26 @@ struct SystemAgentOnboardingChatView: View {
                 ScrollView {
                     LazyVStack(alignment: .leading, spacing: 10) {
                         ForEach(self.model.messages) { message in
-                            SystemAgentChatBubble(message: message)
-                                .id(message.id)
+                            VStack(alignment: .leading, spacing: 8) {
+                                SystemAgentChatBubble(message: message)
+                                if let question = message.question,
+                                   self.model.isQuestionVisible(message)
+                                {
+                                    SystemAgentChatQuestionCard(
+                                        question: question,
+                                        isEnabled: self.model.canAnswerQuestion(message),
+                                        onSelect: { option in
+                                            self.model.answerQuestion(
+                                                messageID: message.id,
+                                                optionLabel: option.label)
+                                        },
+                                        onSkip: {
+                                            self.model.skipQuestion(messageID: message.id)
+                                        })
+                                        .padding(.trailing, 40)
+                                }
+                            }
+                            .id(message.id)
                         }
                         if self.model.isSending {
                             HStack(spacing: 8) {
@@ -312,6 +390,82 @@ struct SystemAgentOnboardingChatView: View {
     }
 }
 
+private struct SystemAgentChatQuestionCard: View {
+    let question: SystemAgentChatQuestion
+    let isEnabled: Bool
+    let onSelect: (SystemAgentChatQuestion.Option) -> Void
+    let onSkip: () -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Text(self.question.header.uppercased())
+                .font(.caption2.weight(.semibold))
+                .foregroundStyle(Color.accentColor)
+            Text(self.question.question)
+                .font(.callout.weight(.semibold))
+            ForEach(self.question.options, id: \.label) { option in
+                self.optionButton(option)
+            }
+            Button("Skip for now", action: self.onSkip)
+                .buttonStyle(.plain)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+                .disabled(!self.isEnabled)
+        }
+        .padding(12)
+        .frame(maxWidth: 460, alignment: .leading)
+        .background(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .fill(Color(NSColor.controlBackgroundColor)))
+        .overlay(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .stroke(.secondary.opacity(0.2)))
+        .accessibilityElement(children: .contain)
+        .accessibilityLabel(self.question.question)
+    }
+
+    private func optionButton(_ option: SystemAgentChatQuestion.Option) -> some View {
+        Button {
+            self.onSelect(option)
+        } label: {
+            HStack(alignment: .top, spacing: 10) {
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(option.label)
+                        .font(.callout.weight(.medium))
+                        .foregroundStyle(.primary)
+                    if let description = option.description {
+                        Text(description)
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                Spacer(minLength: 8)
+                if option.recommended {
+                    Text("Recommended")
+                        .font(.caption2.weight(.semibold))
+                        .foregroundStyle(Color.accentColor)
+                }
+            }
+            .padding(.horizontal, 10)
+            .padding(.vertical, 8)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .background(
+                RoundedRectangle(cornerRadius: 9, style: .continuous)
+                    .fill(option.recommended
+                        ? Color.accentColor.opacity(0.12)
+                        : Color(NSColor.windowBackgroundColor)))
+            .overlay(
+                RoundedRectangle(cornerRadius: 9, style: .continuous)
+                    .stroke(option.recommended
+                        ? Color.accentColor.opacity(0.55)
+                        : Color.secondary.opacity(0.16)))
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .disabled(!self.isEnabled)
+    }
+}
+
 private struct SystemAgentChatBubble: View {
     let message: SystemAgentOnboardingChatModel.Message
 
diff --git a/apps/macos/Tests/OpenClawIPCTests/OnboardingSystemAgentChatTests.swift b/apps/macos/Tests/OpenClawIPCTests/OnboardingSystemAgentChatTests.swift
index bebffb435ea..25dcc50a34e 100644
--- a/apps/macos/Tests/OpenClawIPCTests/OnboardingSystemAgentChatTests.swift
+++ b/apps/macos/Tests/OpenClawIPCTests/OnboardingSystemAgentChatTests.swift
@@ -27,6 +27,18 @@ private actor SystemAgentSessionRecorder {
     }
 }
 
+private actor SystemAgentMessageRecorder {
+    private var messages: [String] = []
+
+    func record(_ message: String) {
+        self.messages.append(message)
+    }
+
+    func snapshot() -> [String] {
+        self.messages
+    }
+}
+
 private actor SystemAgentMethodRecorder {
     private var methods: [String] = []
 
@@ -88,6 +100,20 @@ private func systemAgentRequestMethod(from message: URLSessionWebSocketTask.Mess
     return object["method"] as? String
 }
 
+private func systemAgentChatMessage(from message: URLSessionWebSocketTask.Message) -> String? {
+    let data: Data? = switch message {
+    case let .data(data): data
+    case let .string(string): string.data(using: .utf8)
+    @unknown default: nil
+    }
+    guard let data,
+          let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+          object["method"] as? String == "openclaw.chat",
+          let params = object["params"] as? [String: Any]
+    else { return nil }
+    return params["message"] as? String
+}
+
 private func respondToSystemAgentHealth(
     task: GatewayTestWebSocketTask,
     id: String,
@@ -101,9 +127,11 @@ private func respondToSystemAgentHealth(
 private func systemAgentResponse(
     id: String,
     action: String = "none",
-    agentDraft: String? = nil) -> Data
+    agentDraft: String? = nil,
+    questionJSON: String? = nil) -> Data
 {
     let agentDraftField = agentDraft.map { ",\n            \"agentDraft\": \"\($0)\"" } ?? ""
+    let questionField = questionJSON.map { ",\n            \"question\": \($0)" } ?? ""
     return Data(
         """
         {
@@ -114,7 +142,7 @@ private func systemAgentResponse(
             "sessionId": "test-session",
             "reply": "ready",
             "action": "\(action)",
-            "sensitive": false\(agentDraftField)
+            "sensitive": false\(agentDraftField)\(questionField)
           }
         }
         """.utf8)
@@ -482,6 +510,114 @@ struct OnboardingSystemAgentChatTests {
         #expect(session.latestTask()?.snapshotSendCount() == 2)
     }
 
+    @Test func `typed question sends reply while transcript shows label`() async throws {
+        let recordedMessages = SystemAgentMessageRecorder()
+        let questionJSON =
+            """
+            {"id":"next","header":"Next step","question":"What now?","options":[
+              {"label":"Talk to my agent","reply":"talk to agent","recommended":true},
+              {"label":"Connect WhatsApp","reply":"connect whatsapp","description":"Chat there."}
+            ],"isOther":true}
+            """
+        let session = GatewayTestWebSocketSession(taskFactory: {
+            GatewayTestWebSocketTask(sendHook: { task, message, sendIndex in
+                guard sendIndex > 0,
+                      let id = GatewayWebSocketTestSupport.requestID(from: message)
+                else { return }
+                if let message = systemAgentChatMessage(from: message) {
+                    await recordedMessages.record(message)
+                    task.emitReceiveSuccess(.data(systemAgentResponse(id: id)))
+                } else {
+                    task.emitReceiveSuccess(.data(systemAgentResponse(
+                        id: id,
+                        questionJSON: questionJSON)))
+                }
+            })
+        })
+        let url = try #require(URL(string: "ws://example.invalid"))
+        let gateway = GatewayConnection(
+            configProvider: { (url: url, token: nil, password: nil) },
+            sessionBox: WebSocketSessionBox(session: session))
+        let chat = SystemAgentOnboardingChatModel(gateway: gateway)
+
+        await chat.startIfNeeded()
+        let assistant = try #require(chat.messages.first)
+        let question = try #require(assistant.question)
+        #expect(question.options.first?.recommended == true)
+
+        let task = try #require(chat.answerQuestion(
+            messageID: assistant.id,
+            optionLabel: "Connect WhatsApp"))
+        await task.value
+
+        #expect(await recordedMessages.snapshot() == ["connect whatsapp"])
+        #expect(chat.messages.map(\.text) == ["ready", "Connect WhatsApp", "ready"])
+        #expect(!chat.canAnswerQuestion(assistant))
+    }
+
+    @Test func `typed question skip sends fixed reply and dismisses cards`() async throws {
+        let recordedMessages = SystemAgentMessageRecorder()
+        let questionJSON =
+            #"{"id":"next","header":"Next step","question":"What now?","options":[{"label":"A"},{"label":"B"}]}"#
+        let session = GatewayTestWebSocketSession(taskFactory: {
+            GatewayTestWebSocketTask(sendHook: { task, message, sendIndex in
+                guard sendIndex > 0,
+                      let id = GatewayWebSocketTestSupport.requestID(from: message)
+                else { return }
+                if let message = systemAgentChatMessage(from: message) {
+                    await recordedMessages.record(message)
+                    task.emitReceiveSuccess(.data(systemAgentResponse(id: id)))
+                } else {
+                    task.emitReceiveSuccess(.data(systemAgentResponse(
+                        id: id,
+                        questionJSON: questionJSON)))
+                }
+            })
+        })
+        let url = try #require(URL(string: "ws://example.invalid"))
+        let gateway = GatewayConnection(
+            configProvider: { (url: url, token: nil, password: nil) },
+            sessionBox: WebSocketSessionBox(session: session))
+        let chat = SystemAgentOnboardingChatModel(gateway: gateway)
+
+        await chat.startIfNeeded()
+        let assistant = try #require(chat.messages.first)
+        let task = try #require(chat.skipQuestion(messageID: assistant.id))
+        await task.value
+
+        #expect(await recordedMessages.snapshot() == ["Skip for now"])
+        #expect(chat.messages.map(\.text) == ["ready", "Skip for now", "ready"])
+        #expect(!chat.isQuestionVisible(assistant))
+    }
+
+    @Test(arguments: [
+        #"{"id":"dupes","header":"Next step","question":"What now?","options":[{"label":"Same"},{"label":"same"}]}"#,
+        #""invalid""#,
+        #"[]"#,
+    ])
+    func `malformed typed question keeps prose reply only`(questionJSON: String) async throws {
+        let session = GatewayTestWebSocketSession(taskFactory: {
+            GatewayTestWebSocketTask(sendHook: { task, message, sendIndex in
+                guard sendIndex > 0,
+                      let id = GatewayWebSocketTestSupport.requestID(from: message)
+                else { return }
+                task.emitReceiveSuccess(.data(systemAgentResponse(
+                    id: id,
+                    questionJSON: questionJSON)))
+            })
+        })
+        let url = try #require(URL(string: "ws://example.invalid"))
+        let gateway = GatewayConnection(
+            configProvider: { (url: url, token: nil, password: nil) },
+            sessionBox: WebSocketSessionBox(session: session))
+        let chat = SystemAgentOnboardingChatModel(gateway: gateway)
+
+        await chat.startIfNeeded()
+
+        #expect(chat.messages.map(\.text) == ["ready"])
+        #expect(chat.messages.first?.question == nil)
+    }
+
     @Test func `agent handoff carries the hatch draft intent`() async throws {
         let session = GatewayTestWebSocketSession(taskFactory: {
             GatewayTestWebSocketTask(sendHook: { task, message, sendIndex in
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/SystemAgentChatQuestion.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/SystemAgentChatQuestion.swift
new file mode 100644
index 00000000000..2039af3fa6d
--- /dev/null
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/SystemAgentChatQuestion.swift
@@ -0,0 +1,63 @@
+import Foundation
+
+public struct SystemAgentChatQuestion: Equatable, Sendable {
+    public struct Option: Equatable, Sendable {
+        public let label: String
+        public let description: String?
+        public let recommended: Bool
+        public let reply: String?
+    }
+
+    public let id: String
+    public let header: String
+    public let question: String
+    public let options: [Option]
+    public let isOther: Bool
+
+    /// Card-capable clients validate the open payload before turning values into actions.
+    /// Invalid questions stay prose-only instead of exposing partial or ambiguous choices.
+    public static func parse(_ value: [String: AnyCodable]?) -> Self? {
+        guard let value,
+              let id = nonEmptyString(value["id"]),
+              let header = nonEmptyString(value["header"]),
+              let question = nonEmptyString(value["question"]),
+              let rawOptions = value["options"]?.arrayValue,
+              (2...4).contains(rawOptions.count)
+        else { return nil }
+
+        var labels = Set<String>()
+        var recommendedCount = 0
+        var options: [Option] = []
+        options.reserveCapacity(rawOptions.count)
+
+        for rawOption in rawOptions {
+            guard let option = rawOption.dictionaryValue,
+                  let label = Self.nonEmptyString(option["label"]),
+                  labels.insert(label.lowercased()).inserted
+            else { return nil }
+
+            let recommended = option["recommended"]?.boolValue == true
+            recommendedCount += recommended ? 1 : 0
+            guard recommendedCount <= 1 else { return nil }
+            options.append(Option(
+                label: label,
+                description: Self.nonEmptyString(option["description"]),
+                recommended: recommended,
+                reply: Self.nonEmptyString(option["reply"])))
+        }
+
+        return Self(
+            id: id,
+            header: header,
+            question: question,
+            options: options,
+            isOther: value["isOther"]?.boolValue == true)
+    }
+
+    private static func nonEmptyString(_ value: AnyCodable?) -> String? {
+        guard let string = value?.stringValue?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !string.isEmpty
+        else { return nil }
+        return string
+    }
+}
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelAttachmentTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelAttachmentTests.swift
index c411c87e666..57a3d152f8b 100644
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelAttachmentTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelAttachmentTests.swift
@@ -297,7 +297,7 @@ final class ChatViewModelAttachmentTests: XCTestCase {
     }
 
     @MainActor
-    func testPartialIdentitySyncPreservesTheOtherDeferredComponent() {
+    func testPartialIdentitySyncPreservesTheOtherDeferredComponent() async {
         let oldContract = "per-sender|main|main"
         let newContract = "per-sender|work-main|main"
         let contractViewModel = OpenClawChatViewModel(
@@ -342,7 +342,7 @@ final class ChatViewModelAttachmentTests: XCTestCase {
     }
 
     @MainActor
-    func testAttachmentStagingPinsSessionAndIdentityUntilItFinishes() {
+    func testAttachmentStagingPinsSessionAndIdentityUntilItFinishes() async {
         let viewModel = OpenClawChatViewModel(
             sessionKey: "main",
             transport: AttachmentProcessingTransport(),
@@ -369,7 +369,7 @@ final class ChatViewModelAttachmentTests: XCTestCase {
     }
 
     @MainActor
-    func testRecordingPinsSessionAndIdentityUntilItEnds() {
+    func testRecordingPinsSessionAndIdentityUntilItEnds() async {
         let ownerActivity = AttachmentOwnerActivity()
         let viewModel = OpenClawChatViewModel(
             sessionKey: "main",
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/SystemAgentChatQuestionTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/SystemAgentChatQuestionTests.swift
new file mode 100644
index 00000000000..f1159d0d674
--- /dev/null
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/SystemAgentChatQuestionTests.swift
@@ -0,0 +1,104 @@
+import Foundation
+import OpenClawKit
+import OpenClawProtocol
+import Testing
+
+struct SystemAgentChatQuestionTests {
+    @Test
+    func `valid gateway question keeps display and reply fields`() throws {
+        let decoded = try Self.parse(
+            """
+            {
+              "id": " onboarding-next-step ",
+              "header": " Next step ",
+              "question": " What would you like to do first? ",
+              "options": [
+                {
+                  "label": " Talk to my agent ",
+                  "reply": " talk to agent ",
+                  "recommended": true
+                },
+                {
+                  "label": "Connect WhatsApp",
+                  "reply": "connect whatsapp",
+                  "description": " Chat there. "
+                }
+              ],
+              "isOther": true
+            }
+            """)
+        let parsed = try #require(decoded)
+
+        #expect(parsed.id == "onboarding-next-step")
+        #expect(parsed.header == "Next step")
+        #expect(parsed.question == "What would you like to do first?")
+        #expect(parsed.isOther)
+        #expect(parsed.options.count == 2)
+        #expect(parsed.options[0].label == "Talk to my agent")
+        #expect(parsed.options[0].reply == "talk to agent")
+        #expect(parsed.options[0].recommended)
+        #expect(parsed.options[1].description == "Chat there.")
+        #expect(!parsed.options[1].recommended)
+    }
+
+    @Test
+    func `optional malformed metadata is ignored`() throws {
+        let decoded = try Self.parse(
+            """
+            {
+              "id": "channel",
+              "header": "Channel",
+              "question": "Which channel?",
+              "options": [
+                {"label": "WhatsApp", "description": 42, "reply": "   ", "recommended": "yes"},
+                {"label": "Telegram"}
+              ],
+              "isOther": "yes"
+            }
+            """)
+        let parsed = try #require(decoded)
+
+        #expect(parsed.options[0].description == nil)
+        #expect(parsed.options[0].reply == nil)
+        #expect(!parsed.options[0].recommended)
+        #expect(!parsed.isOther)
+    }
+
+    @Test
+    func `malformed gateway questions degrade to nil`() throws {
+        let malformedQuestions = [
+            #"{"id":"one","header":"H","question":"Q","options":[{"label":"Only"}]}"#,
+            """
+            {"id":"five","header":"H","question":"Q","options":\
+            [{"label":"A"},{"label":"B"},{"label":"C"},{"label":"D"},{"label":"E"}]}
+            """,
+            #"{"id":"dupes","header":"H","question":"Q","options":[{"label":"Same"},{"label":"same"}]}"#,
+            """
+            {"id":"recommended","header":"H","question":"Q","options":\
+            [{"label":"A","recommended":true},{"label":"B","recommended":true}]}
+            """,
+            #"{"id":"blank","header":"H","question":"Q","options":[{"label":"A"},{"label":"   "}]}"#,
+            #"{"id":"missing-header","question":"Q","options":[{"label":"A"},{"label":"B"}]}"#,
+            #"{"id":"bad-option","header":"H","question":"Q","options":[{"label":"A"},"B"]}"#,
+        ]
+
+        for json in malformedQuestions {
+            #expect(try Self.parse(json) == nil)
+        }
+    }
+
+    private static func parse(_ questionJSON: String) throws -> SystemAgentChatQuestion? {
+        let result = try JSONDecoder().decode(
+            SystemAgentChatResult.self,
+            from: Data(
+                """
+                {
+                  "sessionId": "test-session",
+                  "reply": "The prose reply stands alone.",
+                  "action": "none",
+                  "question": \(questionJSON)
+                }
+                """.utf8))
+        return SystemAgentChatQuestion.parse(result.question)
+    }
+}
diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md
index 0fbfe5f2667..758e569bd63 100644
--- a/docs/start/onboarding.md
+++ b/docs/start/onboarding.md
@@ -103,7 +103,10 @@ the credential with the same live test before storing its auth profile. Next
 remains locked until one backend has passed, so the first agent chat cannot
 start without working inference. After that live check passes, OpenClaw becomes
 available to help configure the remaining workspace, Gateway, channels, and
-other optional features; it is also available later under Settings → OpenClaw.
+other optional features. When OpenClaw offers a short list of choices, the app
+shows native option cards; choosing one sends the selection, and **Skip for
+now** always leaves the choice optional. OpenClaw is also available later under
+Settings → OpenClaw.
 </Step>
 <Step title="Import memories (shown when detected)">
 For a local Gateway, onboarding checks the Mac for memories from supported AI

From d3173f6f9184cb429d691ce07659296f653be5ac Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:26:21 +0100
Subject: [PATCH 59/76] perf(ui): keep lazy-page CSS out of the Control UI
 entry stylesheet (#110687)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The entry stylesheet aggregated approval, config, config-quick, and
lobster-pet styles even though every consumer is a lazy route chunk or
lazily defined element, and two small UI landings tipped startup CSS to
exactly the 42.0 KiB budget, failing all QA Smoke profiles on main (run
29643357786). Move each stylesheet to its owning lazy module — pages
already own their CSS this way (chat, agents, cron) — and keep only the
shell's pre-hydration approval booting subset in the entry via the new
approval-boot.css. Startup CSS drops 42.0 -> 36.0 KiB gzip; tighten the
budget 42 -> 38 KiB to lock in the recovery, matching the startup-JS
precedent from #110528.
---
 scripts/check-control-ui-performance.mjs |  2 +-
 ui/src/components/lobster-pet.ts         |  1 +
 ui/src/pages/about/view.ts               |  1 +
 ui/src/pages/agents/memory/view.ts       |  1 +
 ui/src/pages/approval/approval-page.ts   |  1 +
 ui/src/pages/config/config-page.ts       |  2 +
 ui/src/pages/config/view.ts              |  1 +
 ui/src/pages/profile/profile-page.ts     |  1 +
 ui/src/styles.css                        |  5 +--
 ui/src/styles/approval-boot.css          | 49 ++++++++++++++++++++++++
 ui/src/styles/approval.css               | 48 +----------------------
 11 files changed, 61 insertions(+), 51 deletions(-)
 create mode 100644 ui/src/styles/approval-boot.css

diff --git a/scripts/check-control-ui-performance.mjs b/scripts/check-control-ui-performance.mjs
index 4c20d03ce22..1d3819eb96c 100644
--- a/scripts/check-control-ui-performance.mjs
+++ b/scripts/check-control-ui-performance.mjs
@@ -13,7 +13,7 @@ export const CONTROL_UI_PERFORMANCE_BUDGETS = Object.freeze({
   startupJsRequests: 18,
   startupCssRequests: 1,
   startupJsGzipBytes: 310 * KIB,
-  startupCssGzipBytes: 42 * KIB,
+  startupCssGzipBytes: 38 * KIB,
   largestJsGzipBytes: 215 * KIB,
   largestCssGzipBytes: 42 * KIB,
 });
diff --git a/ui/src/components/lobster-pet.ts b/ui/src/components/lobster-pet.ts
index 9795a58c327..d2ad4f1eec0 100644
--- a/ui/src/components/lobster-pet.ts
+++ b/ui/src/components/lobster-pet.ts
@@ -4,6 +4,7 @@
 // Drawn in the smooth OpenClaw lobster style (see the dreams scene and
 // icons.lobster). Look and personality are seeded per session + page load so
 // every new session hatches a slightly different lobster.
+import "../styles/lobster-pet.css";
 import { expectDefined } from "@openclaw/normalization-core";
 import { html, LitElement, nothing, svg, type TemplateResult } from "lit";
 import { property, state } from "lit/decorators.js";
diff --git a/ui/src/pages/about/view.ts b/ui/src/pages/about/view.ts
index b9fe90869af..f1c0582bf3b 100644
--- a/ui/src/pages/about/view.ts
+++ b/ui/src/pages/about/view.ts
@@ -1,3 +1,4 @@
+import "../../styles/lobster-pet.css";
 import { expectDefined } from "@openclaw/normalization-core";
 import { html, nothing, type TemplateResult } from "lit";
 import type { ControlUiBuildInfo } from "../../build-info.ts";
diff --git a/ui/src/pages/agents/memory/view.ts b/ui/src/pages/agents/memory/view.ts
index 64db66b38c0..85dc707cb38 100644
--- a/ui/src/pages/agents/memory/view.ts
+++ b/ui/src/pages/agents/memory/view.ts
@@ -1,4 +1,5 @@
 // Control UI view renders dreaming screen content.
+import "../../../styles/lobster-pet.css";
 import { expectDefined } from "@openclaw/normalization-core";
 import { html, nothing } from "lit";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
diff --git a/ui/src/pages/approval/approval-page.ts b/ui/src/pages/approval/approval-page.ts
index 4bf8065fdbd..ef8feb3c888 100644
--- a/ui/src/pages/approval/approval-page.ts
+++ b/ui/src/pages/approval/approval-page.ts
@@ -1,3 +1,4 @@
+import "../../styles/approval.css";
 import { consume } from "@lit/context";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, nothing, type PropertyValues } from "lit";
diff --git a/ui/src/pages/config/config-page.ts b/ui/src/pages/config/config-page.ts
index 24be7ec0c72..d74d9782c84 100644
--- a/ui/src/pages/config/config-page.ts
+++ b/ui/src/pages/config/config-page.ts
@@ -1,3 +1,5 @@
+import "../../styles/config.css";
+import "../../styles/config-quick.css";
 import { consume } from "@lit/context";
 import { asNullableRecord as asConfigRecord } from "@openclaw/normalization-core/record-coerce";
 import { html, type PropertyValues } from "lit";
diff --git a/ui/src/pages/config/view.ts b/ui/src/pages/config/view.ts
index 1922cfd2ba6..c7e6e23b07c 100644
--- a/ui/src/pages/config/view.ts
+++ b/ui/src/pages/config/view.ts
@@ -1,4 +1,5 @@
 // Control UI view renders config screen content.
+import "../../styles/lobster-pet.css";
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { html, nothing } from "lit";
 import type { QueueMode } from "../../../../src/auto-reply/reply/queue/types.js";
diff --git a/ui/src/pages/profile/profile-page.ts b/ui/src/pages/profile/profile-page.ts
index 1348c547801..1ed4cab2c46 100644
--- a/ui/src/pages/profile/profile-page.ts
+++ b/ui/src/pages/profile/profile-page.ts
@@ -1,3 +1,4 @@
+import "../../styles/config-quick.css";
 import { consume } from "@lit/context";
 import { html, nothing, svg } from "lit";
 import { state } from "lit/decorators.js";
diff --git a/ui/src/styles.css b/ui/src/styles.css
index bd5f049fa02..a2c77cf9a1b 100644
--- a/ui/src/styles.css
+++ b/ui/src/styles.css
@@ -3,11 +3,8 @@
 @import "./styles/layout.css";
 @import "./styles/layout.mobile.css";
 @import "./styles/components.css";
-@import "./styles/approval.css";
-@import "./styles/config.css";
-@import "./styles/config-quick.css";
+@import "./styles/approval-boot.css";
 @import "./styles/settings.css";
-@import "./styles/lobster-pet.css";
 @import "@create-markdown/preview/themes/system.css";
 
 /* Contract read by stale-chunk-reload.ts to detect a failed entry stylesheet load.
diff --git a/ui/src/styles/approval-boot.css b/ui/src/styles/approval-boot.css
new file mode 100644
index 00000000000..7ea7392b1f4
--- /dev/null
+++ b/ui/src/styles/approval-boot.css
@@ -0,0 +1,49 @@
+openclaw-approval-page {
+  display: block;
+  height: 100vh;
+  height: 100dvh;
+  min-height: 100vh;
+  min-height: 100svh;
+  overflow: hidden;
+}
+
+.approval-page {
+  position: relative;
+  isolation: isolate;
+  display: grid;
+  grid-template-columns: minmax(0, 720px);
+  grid-template-rows: max-content max-content;
+  grid-auto-rows: max-content;
+  height: 100%;
+  min-height: 100vh;
+  min-height: 100svh;
+  align-content: start;
+  align-content: safe center;
+  justify-content: center;
+  place-items: center;
+  gap: 18px;
+  overflow: hidden auto;
+  padding: max(32px, var(--safe-area-top)) max(22px, var(--safe-area-right))
+    max(24px, var(--safe-area-bottom)) max(22px, var(--safe-area-left));
+  background: var(--bg);
+  color: var(--text);
+}
+
+@media (display-mode: standalone) {
+  openclaw-approval-page {
+    height: 100%;
+    min-height: 0;
+  }
+
+  .approval-page {
+    min-height: 100%;
+  }
+}
+
+.approval-page--booting {
+  align-content: center;
+  color: var(--muted);
+}
+
+/* Only the shell's pre-hydration booting state lives here; the full approval
+ * page styles load with the lazy page chunk (see approval-page.ts). */
diff --git a/ui/src/styles/approval.css b/ui/src/styles/approval.css
index 744065472b0..2c6a915f5c8 100644
--- a/ui/src/styles/approval.css
+++ b/ui/src/styles/approval.css
@@ -1,49 +1,5 @@
-openclaw-approval-page {
-  display: block;
-  height: 100vh;
-  height: 100dvh;
-  min-height: 100vh;
-  min-height: 100svh;
-  overflow: hidden;
-}
-
-.approval-page {
-  position: relative;
-  isolation: isolate;
-  display: grid;
-  grid-template-columns: minmax(0, 720px);
-  grid-template-rows: max-content max-content;
-  grid-auto-rows: max-content;
-  height: 100%;
-  min-height: 100vh;
-  min-height: 100svh;
-  align-content: start;
-  align-content: safe center;
-  justify-content: center;
-  place-items: center;
-  gap: 18px;
-  overflow: hidden auto;
-  padding: max(32px, var(--safe-area-top)) max(22px, var(--safe-area-right))
-    max(24px, var(--safe-area-bottom)) max(22px, var(--safe-area-left));
-  background: var(--bg);
-  color: var(--text);
-}
-
-@media (display-mode: standalone) {
-  openclaw-approval-page {
-    height: 100%;
-    min-height: 0;
-  }
-
-  .approval-page {
-    min-height: 100%;
-  }
-}
-
-.approval-page--booting {
-  align-content: center;
-  color: var(--muted);
-}
+/* Full approval-page styles; loaded with the lazy page chunk. The shell boot
+ * subset lives in approval-boot.css and must stay in the entry stylesheet. */
 
 .approval-page__backdrop {
   position: fixed;

From 7994c44b0699cec7263349873ba028f457bd2d24 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:26:26 +0100
Subject: [PATCH 60/76] fix(ios): shrink the chat "Jump to latest" pill to a
 compact icon button (#110651)

* fix(ios): shrink chat jump-to-latest pill to a compact icon button

* fix(ios): drop removed jump-to-latest string from native locale artifacts
---
 apps/.i18n/native-source.json                 |  26 ++--
 apps/.i18n/native/ar.json                     |   5 -
 apps/.i18n/native/de.json                     |   5 -
 apps/.i18n/native/es.json                     |   5 -
 apps/.i18n/native/fa.json                     |   5 -
 apps/.i18n/native/fr.json                     |   5 -
 apps/.i18n/native/hi.json                     |   5 -
 apps/.i18n/native/id.json                     |   5 -
 apps/.i18n/native/it.json                     |   5 -
 apps/.i18n/native/ja-JP.json                  |   5 -
 apps/.i18n/native/ko.json                     |   5 -
 apps/.i18n/native/nl.json                     |   5 -
 apps/.i18n/native/pl.json                     |   5 -
 apps/.i18n/native/pt-BR.json                  |   5 -
 apps/.i18n/native/ru.json                     |   5 -
 apps/.i18n/native/sv.json                     |   5 -
 apps/.i18n/native/th.json                     |   5 -
 apps/.i18n/native/tr.json                     |   5 -
 apps/.i18n/native/uk.json                     |   5 -
 apps/.i18n/native/vi.json                     |   5 -
 apps/.i18n/native/zh-CN.json                  |   5 -
 apps/.i18n/native/zh-TW.json                  |   5 -
 apps/ios/Resources/Localizable.xcstrings      | 136 ------------------
 apps/ios/Tests/Info.plist                     |   2 +-
 .../Sources/OpenClawChatUI/ChatView.swift     |  18 +--
 25 files changed, 20 insertions(+), 267 deletions(-)

diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json
index 9b72511f992..90e2d6f7697 100644
--- a/apps/.i18n/native-source.json
+++ b/apps/.i18n/native-source.json
@@ -37289,17 +37289,9 @@
       "surface": "apple",
       "id": "native.apple.99df7de891c8235f"
     },
-    {
-      "kind": "ui-call",
-      "line": 618,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
-      "source": "Jump to latest",
-      "surface": "apple",
-      "id": "native.apple.f84b674ad395b694"
-    },
     {
       "kind": "ui-modifier",
-      "line": 629,
+      "line": 631,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Jump to latest reply",
       "surface": "apple",
@@ -37307,7 +37299,7 @@
     },
     {
       "kind": "ui-named-argument",
-      "line": 649,
+      "line": 651,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Refresh",
       "surface": "apple",
@@ -37315,7 +37307,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 1036,
+      "line": 1038,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Copy Message",
       "surface": "apple",
@@ -37323,7 +37315,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 1059,
+      "line": 1061,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Open Full Message",
       "surface": "apple",
@@ -37331,7 +37323,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 1080,
+      "line": 1082,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Reply",
       "surface": "apple",
@@ -37339,7 +37331,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 1090,
+      "line": 1092,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "You",
       "surface": "apple",
@@ -37347,7 +37339,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 1092,
+      "line": 1094,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Assistant",
       "surface": "apple",
@@ -37355,7 +37347,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 1158,
+      "line": 1160,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Loading chat",
       "surface": "apple",
@@ -37363,7 +37355,7 @@
     },
     {
       "kind": "ui-modifier",
-      "line": 1238,
+      "line": 1240,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift",
       "source": "Dismiss",
       "surface": "apple",
diff --git a/apps/.i18n/native/ar.json b/apps/.i18n/native/ar.json
index 9c72e30e546..bdc68a35d7e 100644
--- a/apps/.i18n/native/ar.json
+++ b/apps/.i18n/native/ar.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "استمع"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "الانتقال إلى الأحدث"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/de.json b/apps/.i18n/native/de.json
index 6936c497922..8c510faeef4 100644
--- a/apps/.i18n/native/de.json
+++ b/apps/.i18n/native/de.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Zuhören"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Zum neuesten springen"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/es.json b/apps/.i18n/native/es.json
index 6aa37f60f72..e07df840c5e 100644
--- a/apps/.i18n/native/es.json
+++ b/apps/.i18n/native/es.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Escuchar"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Ir a lo más reciente"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/fa.json b/apps/.i18n/native/fa.json
index 216e7830794..6f19b11908e 100644
--- a/apps/.i18n/native/fa.json
+++ b/apps/.i18n/native/fa.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "گوش دادن"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "پرش به آخرین مورد"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/fr.json b/apps/.i18n/native/fr.json
index 9afa88f674f..7c3ceb43676 100644
--- a/apps/.i18n/native/fr.json
+++ b/apps/.i18n/native/fr.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Écouter"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Aller au plus récent"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/hi.json b/apps/.i18n/native/hi.json
index 1756e77d771..4903d9928f0 100644
--- a/apps/.i18n/native/hi.json
+++ b/apps/.i18n/native/hi.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "सुनें"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "नवीनतम पर जाएँ"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/id.json b/apps/.i18n/native/id.json
index 8bd4df8cd41..c5f7ceeecfd 100644
--- a/apps/.i18n/native/id.json
+++ b/apps/.i18n/native/id.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Dengarkan"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Lompat ke terbaru"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/it.json b/apps/.i18n/native/it.json
index e9165565695..fd91454d974 100644
--- a/apps/.i18n/native/it.json
+++ b/apps/.i18n/native/it.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Ascolta"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Vai all'ultimo"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/ja-JP.json b/apps/.i18n/native/ja-JP.json
index b9e31674c2c..6bcaa809dce 100644
--- a/apps/.i18n/native/ja-JP.json
+++ b/apps/.i18n/native/ja-JP.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "聞く"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "最新に移動"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/ko.json b/apps/.i18n/native/ko.json
index 652b5c3e550..b3b25c582ba 100644
--- a/apps/.i18n/native/ko.json
+++ b/apps/.i18n/native/ko.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "듣기"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "최신 항목으로 이동"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/nl.json b/apps/.i18n/native/nl.json
index ac55f7b12f3..c04764803fc 100644
--- a/apps/.i18n/native/nl.json
+++ b/apps/.i18n/native/nl.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Luisteren"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Naar nieuwste springen"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/pl.json b/apps/.i18n/native/pl.json
index fc9772e9b76..1c571e23d63 100644
--- a/apps/.i18n/native/pl.json
+++ b/apps/.i18n/native/pl.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Słuchaj"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Przejdź do najnowszych"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/pt-BR.json b/apps/.i18n/native/pt-BR.json
index 4f46705ec54..ce4630b53e5 100644
--- a/apps/.i18n/native/pt-BR.json
+++ b/apps/.i18n/native/pt-BR.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Ouvir"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Ir para a mais recente"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/ru.json b/apps/.i18n/native/ru.json
index 93b72c61f39..5090db37b6f 100644
--- a/apps/.i18n/native/ru.json
+++ b/apps/.i18n/native/ru.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Слушать"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Перейти к последнему"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/sv.json b/apps/.i18n/native/sv.json
index 055980b9650..04e0ce7a598 100644
--- a/apps/.i18n/native/sv.json
+++ b/apps/.i18n/native/sv.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Lyssna"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Hoppa till senaste"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/th.json b/apps/.i18n/native/th.json
index f04d133b26b..d9d55e6e7bb 100644
--- a/apps/.i18n/native/th.json
+++ b/apps/.i18n/native/th.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "ฟัง"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "ข้ามไปยังล่าสุด"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/tr.json b/apps/.i18n/native/tr.json
index 3acba5e8713..755de2c2d6f 100644
--- a/apps/.i18n/native/tr.json
+++ b/apps/.i18n/native/tr.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Dinle"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "En yeniye atla"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/uk.json b/apps/.i18n/native/uk.json
index afc99d27cdd..ffe30eee470 100644
--- a/apps/.i18n/native/uk.json
+++ b/apps/.i18n/native/uk.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Слухати"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Перейти до останнього"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/vi.json b/apps/.i18n/native/vi.json
index 9652f177c89..e0e65baa6a8 100644
--- a/apps/.i18n/native/vi.json
+++ b/apps/.i18n/native/vi.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "Nghe"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "Chuyển đến mới nhất"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/zh-CN.json b/apps/.i18n/native/zh-CN.json
index 02ae28184cc..fd3b78b4d62 100644
--- a/apps/.i18n/native/zh-CN.json
+++ b/apps/.i18n/native/zh-CN.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "聆听"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "跳转到最新"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/.i18n/native/zh-TW.json b/apps/.i18n/native/zh-TW.json
index 7099064c50c..4ed108a5a9e 100644
--- a/apps/.i18n/native/zh-TW.json
+++ b/apps/.i18n/native/zh-TW.json
@@ -23308,11 +23308,6 @@
       "source": "Listen",
       "translated": "聆聽"
     },
-    {
-      "id": "native.apple.f84b674ad395b694",
-      "source": "Jump to latest",
-      "translated": "跳至最新內容"
-    },
     {
       "id": "native.apple.429d825201b2cb85",
       "source": "Jump to latest reply",
diff --git a/apps/ios/Resources/Localizable.xcstrings b/apps/ios/Resources/Localizable.xcstrings
index 4def5447c0e..ff6f9453250 100644
--- a/apps/ios/Resources/Localizable.xcstrings
+++ b/apps/ios/Resources/Localizable.xcstrings
@@ -80921,142 +80921,6 @@
         }
       }
     },
-    "Jump to latest": {
-      "localizations": {
-        "en": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Jump to latest"
-          }
-        },
-        "zh-CN": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "跳转到最新"
-          }
-        },
-        "zh-TW": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "跳至最新內容"
-          }
-        },
-        "pt-BR": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Ir para a mais recente"
-          }
-        },
-        "de": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Zum neuesten springen"
-          }
-        },
-        "es": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Ir a lo más reciente"
-          }
-        },
-        "ja-JP": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "最新に移動"
-          }
-        },
-        "ko": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "최신 항목으로 이동"
-          }
-        },
-        "fr": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Aller au plus récent"
-          }
-        },
-        "hi": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "नवीनतम पर जाएँ"
-          }
-        },
-        "ar": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "الانتقال إلى الأحدث"
-          }
-        },
-        "it": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Vai all'ultimo"
-          }
-        },
-        "tr": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "En yeniye atla"
-          }
-        },
-        "uk": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Перейти до останнього"
-          }
-        },
-        "id": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Lompat ke terbaru"
-          }
-        },
-        "pl": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Przejdź do najnowszych"
-          }
-        },
-        "th": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "ข้ามไปยังล่าสุด"
-          }
-        },
-        "vi": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Chuyển đến mới nhất"
-          }
-        },
-        "nl": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Naar nieuwste springen"
-          }
-        },
-        "fa": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "پرش به آخرین مورد"
-          }
-        },
-        "ru": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Перейти к последнему"
-          }
-        },
-        "sv": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Hoppa till senaste"
-          }
-        }
-      }
-    },
     "Jump to latest reply": {
       "localizations": {
         "en": {
diff --git a/apps/ios/Tests/Info.plist b/apps/ios/Tests/Info.plist
index 5bcf88ff5ad..7b5a9804f20 100644
--- a/apps/ios/Tests/Info.plist
+++ b/apps/ios/Tests/Info.plist
@@ -5,7 +5,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
-	<string>OpenClawTests</string>
+	<string>OpenClawLogicTests</string>
 	<key>CFBundleExecutable</key>
 	<string>$(EXECUTABLE_NAME)</string>
 	<key>CFBundleIdentifier</key>
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift
index e1f62bef082..557acd51e69 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift
@@ -615,17 +615,19 @@ public struct OpenClawChatView: View {
             self.hasNewerContentBelow = false
             self.moveScrollPosition(to: self.scrollerBottomID)
         } label: {
-            Label("Jump to latest", systemImage: "arrow.down")
-                .font(OpenClawChatTypography.body(size: 16, weight: .semibold, relativeTo: .callout))
-                .padding(.horizontal, 13)
-                .padding(.vertical, 8)
+            Image(systemName: "arrow.down")
+                .font(.system(size: 15, weight: .semibold))
+                .frame(width: 36, height: 36)
+                .background(
+                    Circle()
+                        .fill(OpenClawChatTheme.subtleCard)
+                        .shadow(color: .black.opacity(0.16), radius: 8, y: 3))
+                // Padding keeps a ~44pt tap target around the compact visual circle.
+                .padding(4)
+                .contentShape(Circle())
         }
         .buttonStyle(.plain)
         .foregroundStyle(OpenClawChatTheme.assistantText)
-        .background(
-            Capsule()
-                .fill(OpenClawChatTheme.subtleCard)
-                .shadow(color: .black.opacity(0.16), radius: 10, y: 4))
         .accessibilityLabel("Jump to latest reply")
     }
 

From af2662f25a8503ecf17c306b10636de4ab15549b Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 20:28:32 +0800
Subject: [PATCH 61/76] fix(reef): add timeout and bounded JSON reads to relay
 transport (#108333)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(reef): bound relay request duration

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

* test(reef): satisfy timeout fixture lint

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 extensions/reef/src/transport.timeout.test.ts | 80 +++++++++++++++++++
 extensions/reef/src/transport.ts              | 69 ++++++++++------
 2 files changed, 124 insertions(+), 25 deletions(-)
 create mode 100644 extensions/reef/src/transport.timeout.test.ts

diff --git a/extensions/reef/src/transport.timeout.test.ts b/extensions/reef/src/transport.timeout.test.ts
new file mode 100644
index 00000000000..2d909ef5f77
--- /dev/null
+++ b/extensions/reef/src/transport.timeout.test.ts
@@ -0,0 +1,80 @@
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { describe, expect, it } from "vitest";
+import { ReefTransportClient } from "./transport.js";
+import type { ReefKeys } from "./types.js";
+
+const keys: ReefKeys = {
+  signing: {
+    secretKey: "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8",
+    publicKey: "A6EHv_POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg",
+  },
+  encryption: {
+    secretKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+    publicKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+  },
+  auditKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+  replayKey: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+  keyEpoch: 1,
+};
+
+async function listen(server: http.Server): Promise<string> {
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  return `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+}
+
+async function close(server: http.Server): Promise<void> {
+  server.closeAllConnections?.();
+  await new Promise<void>((resolve) => {
+    server.close(() => resolve());
+  });
+}
+
+function client(relayUrl: string): ReefTransportClient {
+  return new ReefTransportClient(relayUrl, "alice", keys, fetch, () => 1_752_300_000, 50);
+}
+
+describe("ReefTransportClient relay request timeout", () => {
+  it("times out when the relay stalls before returning headers", async () => {
+    const server = http.createServer();
+    server.on("connection", () => {});
+    const relayUrl = await listen(server);
+
+    try {
+      await expect(client(relayUrl).pull(0)).rejects.toMatchObject({ name: "TimeoutError" });
+    } finally {
+      await close(server);
+    }
+  });
+
+  it("times out when the relay stalls after returning headers", async () => {
+    const server = http.createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.flushHeaders();
+    });
+    const relayUrl = await listen(server);
+
+    try {
+      await expect(client(relayUrl).pull(0)).rejects.toMatchObject({ name: "TimeoutError" });
+    } finally {
+      await close(server);
+    }
+  });
+
+  it("preserves the timeout error when an HTTP error body stalls", async () => {
+    const server = http.createServer((_request, response) => {
+      response.writeHead(503, { "content-type": "application/json" });
+      response.flushHeaders();
+    });
+    const relayUrl = await listen(server);
+
+    try {
+      await expect(client(relayUrl).pull(0)).rejects.toMatchObject({ name: "TimeoutError" });
+    } finally {
+      await close(server);
+    }
+  });
+});
diff --git a/extensions/reef/src/transport.ts b/extensions/reef/src/transport.ts
index 3d49e0aa210..a397fca065f 100644
--- a/extensions/reef/src/transport.ts
+++ b/extensions/reef/src/transport.ts
@@ -1,3 +1,4 @@
+import { buildTimeoutAbortSignal } from "openclaw/plugin-sdk/extension-shared";
 import { readProviderJsonResponse } from "openclaw/plugin-sdk/provider-http";
 import WebSocket from "ws";
 import { sha256Hex, signDeviceRequest, utf8 } from "../protocol/index.js";
@@ -21,6 +22,9 @@ const REEF_INBOX_LIVE_BUFFER_MAX_ENTRIES = 256;
 // Stalled TCP peers that never complete the HTTP upgrade would otherwise hang
 // forever — ws defaults to no handshakeTimeout. Match sibling channel WS budgets.
 const REEF_WS_HANDSHAKE_MS = 30_000;
+// Cover headers and body consumption. A relay that accepts the request but
+// stops producing bytes must not pin inbox recovery forever.
+const REEF_RELAY_REQUEST_TIMEOUT_MS = 15_000;
 
 export class ReefRelayError extends Error {
   constructor(
@@ -58,6 +62,7 @@ export class ReefTransportClient {
     readonly keys: ReefKeys,
     readonly fetcher: FetchLike = fetch,
     readonly clock: () => number = () => Math.floor(Date.now() / 1000),
+    readonly requestTimeoutMs: number = REEF_RELAY_REQUEST_TIMEOUT_MS,
   ) {}
 
   async authStart(email: string): Promise<{ status: string; magicLink?: string }> {
@@ -181,35 +186,49 @@ export class ReefTransportClient {
     headers: Record<string, string>,
     signal?: AbortSignal,
   ): Promise<T> {
-    const response = await this.fetcher(new URL(path, this.relayUrl), {
-      method,
-      headers: { ...headers, ...(bytes.length ? { "content-type": "application/json" } : {}) },
-      ...(bytes.length ? { body: bytes as BodyInit } : {}),
-      ...(signal ? { signal } : {}),
+    const url = new URL(path, this.relayUrl).toString();
+    const timeout = buildTimeoutAbortSignal({
+      timeoutMs: this.requestTimeoutMs,
+      signal,
+      operation: "reef.relay",
+      url,
     });
-    if (!response.ok) {
-      let message = `relay HTTP ${response.status}`;
-      try {
-        const parsed = await readProviderJsonResponse<{ error?: string }>(
-          response,
-          "reef.relay.error",
-          { maxBytes: REEF_RELAY_ERROR_JSON_MAX_BYTES },
-        );
-        if (typeof parsed.error === "string" && parsed.error) {
-          message = parsed.error;
+    try {
+      const response = await this.fetcher(url, {
+        method,
+        headers: { ...headers, ...(bytes.length ? { "content-type": "application/json" } : {}) },
+        ...(bytes.length ? { body: bytes as BodyInit } : {}),
+        signal: timeout.signal,
+      });
+      if (!response.ok) {
+        let message = `relay HTTP ${response.status}`;
+        try {
+          const parsed = await readProviderJsonResponse<{ error?: string }>(
+            response,
+            "reef.relay.error",
+            { maxBytes: REEF_RELAY_ERROR_JSON_MAX_BYTES },
+          );
+          if (typeof parsed.error === "string" && parsed.error) {
+            message = parsed.error;
+          }
+        } catch {
+          if (timeout.signal?.aborted) {
+            throw timeout.signal.reason;
+          }
+          // Keep the status fallback when the error body is missing, malformed,
+          // or oversized; callers still get a typed ReefRelayError.
         }
-      } catch {
-        // Keep the status fallback when the error body is missing, malformed,
-        // or oversized; callers still get a typed ReefRelayError.
+        throw new ReefRelayError(response.status, message);
       }
-      throw new ReefRelayError(response.status, message);
-    }
-    if (response.status === 204) {
-      return undefined as T;
+      if (response.status === 204) {
+        return undefined as T;
+      }
+      return await readProviderJsonResponse<T>(response, "reef.relay", {
+        maxBytes: REEF_RELAY_JSON_MAX_BYTES,
+      });
+    } finally {
+      timeout.cleanup();
     }
-    return await readProviderJsonResponse<T>(response, "reef.relay", {
-      maxBytes: REEF_RELAY_JSON_MAX_BYTES,
-    });
   }
 }
 

From e01a880084dc1fe2e795e260bcc2d1ac90e88686 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:47:57 +0100
Subject: [PATCH 62/76] refactor(state): split openclaw-state-db into focused
 modules under the line limit (#110666)

---
 config/max-lines-baseline.txt                 |    1 -
 scripts/check-kysely-guardrails.mjs           |    6 +
 .../openclaw-state-db-audit-migration.ts      |  342 ++++
 src/state/openclaw-state-db-contract.ts       |   32 +
 .../openclaw-state-db-legacy-backfills.ts     |  549 ++++++
 src/state/openclaw-state-db-maintenance.ts    |  121 ++
 src/state/openclaw-state-db-permissions.ts    |   54 +
 .../openclaw-state-db-schema-additive.ts      |  256 +++
 src/state/openclaw-state-db-schema-repair.ts  |  153 ++
 .../openclaw-state-db-startup-checkpoint.ts   |   80 +
 src/state/openclaw-state-db.ts                | 1558 +----------------
 11 files changed, 1637 insertions(+), 1515 deletions(-)
 create mode 100644 src/state/openclaw-state-db-audit-migration.ts
 create mode 100644 src/state/openclaw-state-db-contract.ts
 create mode 100644 src/state/openclaw-state-db-legacy-backfills.ts
 create mode 100644 src/state/openclaw-state-db-maintenance.ts
 create mode 100644 src/state/openclaw-state-db-permissions.ts
 create mode 100644 src/state/openclaw-state-db-schema-additive.ts
 create mode 100644 src/state/openclaw-state-db-schema-repair.ts
 create mode 100644 src/state/openclaw-state-db-startup-checkpoint.ts

diff --git a/config/max-lines-baseline.txt b/config/max-lines-baseline.txt
index 9a758d4cce5..cc8de7f82cc 100644
--- a/config/max-lines-baseline.txt
+++ b/config/max-lines-baseline.txt
@@ -1065,7 +1065,6 @@ src/snapshot/local-repository.ts
 src/state/openclaw-agent-db.test.ts
 src/state/openclaw-agent-db.ts
 src/state/openclaw-state-db.test.ts
-src/state/openclaw-state-db.ts
 src/status/status-message.ts
 src/system-agent/agent-turn.test.ts
 src/system-agent/chat-engine.test.ts
diff --git a/scripts/check-kysely-guardrails.mjs b/scripts/check-kysely-guardrails.mjs
index eeb346273e7..90f9e88f343 100644
--- a/scripts/check-kysely-guardrails.mjs
+++ b/scripts/check-kysely-guardrails.mjs
@@ -41,8 +41,14 @@ const rawSqliteAllowPathGroups = {
     "src/state/openclaw-agent-db-session-migrations.ts",
     "src/state/openclaw-agent-db-session-provenance.ts",
     "src/state/openclaw-agent-db.ts",
+    "src/state/openclaw-state-db-audit-migration.ts",
+    "src/state/openclaw-state-db-legacy-backfills.ts",
+    "src/state/openclaw-state-db-maintenance.ts",
     "src/state/openclaw-state-db-operator-approval-migration.ts",
+    "src/state/openclaw-state-db-schema-additive.ts",
     "src/state/openclaw-state-db-schema-helpers.ts",
+    "src/state/openclaw-state-db-schema-repair.ts",
+    "src/state/openclaw-state-db-startup-checkpoint.ts",
     "src/state/openclaw-state-db.ts",
     "src/state/sqlite-schema-shape.test-support.ts",
   ],
diff --git a/src/state/openclaw-state-db-audit-migration.ts b/src/state/openclaw-state-db-audit-migration.ts
new file mode 100644
index 00000000000..05f1bb28491
--- /dev/null
+++ b/src/state/openclaw-state-db-audit-migration.ts
@@ -0,0 +1,342 @@
+import type { DatabaseSync } from "node:sqlite";
+import { readSqliteUserVersion } from "../infra/sqlite-user-version.js";
+import {
+  tableExists,
+  tableHasColumn,
+  tablePrimaryKeyColumns,
+} from "./openclaw-state-db-schema-helpers.js";
+
+const AUDIT_EVENT_STATE_SCHEMA_VERSION = 2;
+
+const AUDIT_EVENT_LEGACY_COLUMNS = [
+  "sequence",
+  "event_id",
+  "source_id",
+  "source_sequence",
+  "occurred_at",
+  "kind",
+  "action",
+  "status",
+  "error_code",
+  "actor_type",
+  "actor_id",
+  "agent_id",
+  "session_key",
+  "session_id",
+  "run_id",
+  "tool_call_id",
+  "tool_name",
+] as const;
+
+const AUDIT_EVENT_V2_COLUMNS = [
+  "sequence",
+  "event_id",
+  "source_id",
+  "schema_version",
+  "source_sequence",
+  "occurred_at",
+  "kind",
+  "action",
+  "status",
+  "error_code",
+  "actor_type",
+  "actor_id",
+  "agent_id",
+  "session_key",
+  "session_id",
+  "run_id",
+  "tool_call_id",
+  "tool_name",
+  "direction",
+  "channel",
+  "conversation_kind",
+  "message_outcome",
+  "reason_code",
+  "delivery_kind",
+  "failure_stage",
+  "duration_ms",
+  "result_count",
+  "account_ref",
+  "conversation_ref",
+  "message_ref",
+  "target_ref",
+] as const;
+
+type TableColumnInfo = {
+  name?: unknown;
+  notnull?: unknown;
+  pk?: unknown;
+};
+
+function tableColumnInfo(db: DatabaseSync, tableName: string): TableColumnInfo[] {
+  return db.prepare(`PRAGMA table_info(${tableName})`).all() as TableColumnInfo[];
+}
+
+function tableHasExactColumns(
+  db: DatabaseSync,
+  tableName: string,
+  expected: readonly string[],
+): boolean {
+  const names = tableColumnInfo(db, tableName).map((column) => column.name);
+  return names.length === expected.length && names.every((name, index) => name === expected[index]);
+}
+
+function tableHasRequiredColumns(
+  db: DatabaseSync,
+  tableName: string,
+  required: readonly string[],
+): boolean {
+  const columns = new Map(tableColumnInfo(db, tableName).map((column) => [column.name, column]));
+  return required.every((name) => Number(columns.get(name)?.notnull ?? 0) === 1);
+}
+
+function tableSql(db: DatabaseSync, tableName: string): string | undefined {
+  const row = db
+    .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get(tableName) as { sql?: unknown } | undefined;
+  return typeof row?.sql === "string" ? row.sql : undefined;
+}
+
+function tableHasUniqueColumn(db: DatabaseSync, tableName: string, columnName: string): boolean {
+  const indexes = db.prepare(`PRAGMA index_list(${tableName})`).all() as Array<{
+    name?: unknown;
+    unique?: unknown;
+  }>;
+  return indexes.some((index) => {
+    if (Number(index.unique ?? 0) !== 1 || typeof index.name !== "string") {
+      return false;
+    }
+    const escaped = index.name.replaceAll("'", "''");
+    const columns = db.prepare(`PRAGMA index_info('${escaped}')`).all() as Array<{
+      name?: unknown;
+    }>;
+    return columns.length === 1 && columns[0]?.name === columnName;
+  });
+}
+
+function hasCanonicalAuditEventTable(
+  db: DatabaseSync,
+  expectedColumns: readonly string[],
+  requiredColumns: readonly string[],
+): boolean {
+  const sql = tableSql(db, "audit_events")?.toLowerCase();
+  return (
+    tableHasExactColumns(db, "audit_events", expectedColumns) &&
+    tablePrimaryKeyColumns(db, "audit_events").join(",") === "sequence" &&
+    tableHasRequiredColumns(db, "audit_events", requiredColumns) &&
+    typeof sql === "string" &&
+    /\bsequence\s+integer\s+primary\s+key\s+autoincrement\b/.test(sql) &&
+    tableHasUniqueColumn(db, "audit_events", "event_id") &&
+    tableHasUniqueColumn(db, "audit_events", "source_id")
+  );
+}
+
+function hasCanonicalAuditIdentityKeyTable(db: DatabaseSync): boolean {
+  if (!tableExists(db, "audit_identity_keys")) {
+    return false;
+  }
+  const sql = tableSql(db, "audit_identity_keys")?.toLowerCase();
+  return (
+    tableHasExactColumns(db, "audit_identity_keys", ["id", "key_id", "key", "created_at"]) &&
+    tablePrimaryKeyColumns(db, "audit_identity_keys").join(",") === "id" &&
+    tableHasRequiredColumns(db, "audit_identity_keys", ["id", "key_id", "key", "created_at"]) &&
+    typeof sql === "string" &&
+    /\bcheck\s*\(\s*id\s*=\s*1\s*\)/.test(sql)
+  );
+}
+
+export function hasCanonicalAuditEventsSchema(db: DatabaseSync): boolean {
+  if (!tableExists(db, "audit_events")) {
+    return (
+      readSqliteUserVersion(db) < AUDIT_EVENT_STATE_SCHEMA_VERSION &&
+      !tableExists(db, "audit_identity_keys")
+    );
+  }
+  return (
+    hasCanonicalAuditEventTable(db, AUDIT_EVENT_V2_COLUMNS, [
+      "event_id",
+      "source_id",
+      "schema_version",
+      "source_sequence",
+      "occurred_at",
+      "kind",
+      "action",
+      "status",
+      "actor_type",
+      "actor_id",
+    ]) && hasCanonicalAuditIdentityKeyTable(db)
+  );
+}
+
+export function canRepairLegacyAuditEventsSchema(db: DatabaseSync): boolean {
+  // Our own transactional repair cannot leave audit_events_migration_new
+  // behind, so an existing one is foreign data; fail closed rather than let
+  // repair silently drop it.
+  if (
+    !tableExists(db, "audit_events") ||
+    tableExists(db, "audit_events_migration_new") ||
+    tableHasColumn(db, "audit_events", "schema_version")
+  ) {
+    return false;
+  }
+  const identityTableIsSafe =
+    !tableExists(db, "audit_identity_keys") || hasCanonicalAuditIdentityKeyTable(db);
+  return (
+    identityTableIsSafe &&
+    hasCanonicalAuditEventTable(db, AUDIT_EVENT_LEGACY_COLUMNS, [
+      "event_id",
+      "source_id",
+      "source_sequence",
+      "occurred_at",
+      "kind",
+      "action",
+      "status",
+      "actor_type",
+      "actor_id",
+      "agent_id",
+      "run_id",
+    ])
+  );
+}
+
+function readAuditEventSequenceHighWater(db: DatabaseSync): number | undefined {
+  if (!tableExists(db, "sqlite_sequence")) {
+    return undefined;
+  }
+  const row = db
+    .prepare("SELECT CAST(seq AS TEXT) AS seq FROM sqlite_sequence WHERE name = 'audit_events'")
+    .get() as { seq?: unknown } | undefined;
+  if (row === undefined) {
+    return undefined;
+  }
+  if (typeof row.seq !== "string" || !/^\d+$/.test(row.seq)) {
+    throw new Error("audit event sequence high-water mark is invalid");
+  }
+  const sequence = BigInt(row.seq);
+  if (sequence > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error("audit event sequence high-water mark exceeds the supported integer range");
+  }
+  return Number(sequence);
+}
+
+function restoreAuditEventSequenceHighWater(db: DatabaseSync, sequence: number | undefined): void {
+  if (sequence === undefined) {
+    return;
+  }
+  db.prepare("DELETE FROM sqlite_sequence WHERE name = 'audit_events'").run();
+  db.prepare("INSERT INTO sqlite_sequence (name, seq) VALUES ('audit_events', ?)").run(sequence);
+}
+
+export function repairAuditEventsSchema(db: DatabaseSync): boolean {
+  if (hasCanonicalAuditEventsSchema(db) || !canRepairLegacyAuditEventsSchema(db)) {
+    return false;
+  }
+  const sequenceHighWater = readAuditEventSequenceHighWater(db);
+  // This is the only shipped legacy shape. The surrounding doctor transaction
+  // rolls back the table swap and sequence restore together on any bad row.
+  // canRepairLegacyAuditEventsSchema refuses foreign audit_events_migration_new
+  // tables, so this CREATE never clobbers existing data.
+  db.exec(`
+    CREATE TABLE audit_events_migration_new (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+      event_id TEXT NOT NULL UNIQUE,
+      source_id TEXT NOT NULL UNIQUE,
+      schema_version INTEGER NOT NULL DEFAULT 1,
+      source_sequence INTEGER NOT NULL,
+      occurred_at INTEGER NOT NULL,
+      kind TEXT NOT NULL,
+      action TEXT NOT NULL,
+      status TEXT NOT NULL,
+      error_code TEXT,
+      actor_type TEXT NOT NULL,
+      actor_id TEXT NOT NULL,
+      agent_id TEXT,
+      session_key TEXT,
+      session_id TEXT,
+      run_id TEXT,
+      tool_call_id TEXT,
+      tool_name TEXT,
+      direction TEXT,
+      channel TEXT,
+      conversation_kind TEXT,
+      message_outcome TEXT,
+      reason_code TEXT,
+      delivery_kind TEXT,
+      failure_stage TEXT,
+      duration_ms INTEGER,
+      result_count INTEGER,
+      account_ref TEXT,
+      conversation_ref TEXT,
+      message_ref TEXT,
+      target_ref TEXT
+    );
+    INSERT INTO audit_events_migration_new (
+      sequence,
+      event_id,
+      source_id,
+      schema_version,
+      source_sequence,
+      occurred_at,
+      kind,
+      action,
+      status,
+      error_code,
+      actor_type,
+      actor_id,
+      agent_id,
+      session_key,
+      session_id,
+      run_id,
+      tool_call_id,
+      tool_name
+    )
+    SELECT
+      sequence,
+      event_id,
+      source_id,
+      1,
+      source_sequence,
+      occurred_at,
+      kind,
+      action,
+      status,
+      error_code,
+      actor_type,
+      actor_id,
+      agent_id,
+      session_key,
+      session_id,
+      run_id,
+      tool_call_id,
+      tool_name
+    FROM audit_events;
+    DROP TABLE audit_events;
+    ALTER TABLE audit_events_migration_new RENAME TO audit_events;
+    CREATE INDEX idx_audit_events_time
+      ON audit_events(occurred_at DESC, sequence DESC);
+    CREATE INDEX idx_audit_events_agent_sequence
+      ON audit_events(agent_id, sequence DESC);
+    CREATE INDEX idx_audit_events_session_sequence
+      ON audit_events(session_key, sequence DESC);
+    CREATE INDEX idx_audit_events_run_sequence
+      ON audit_events(run_id, sequence DESC);
+    CREATE INDEX idx_audit_events_kind_sequence
+      ON audit_events(kind, sequence DESC);
+    CREATE INDEX idx_audit_events_status_sequence
+      ON audit_events(status, sequence DESC);
+    CREATE INDEX idx_audit_events_channel_sequence
+      ON audit_events(channel, sequence DESC);
+    CREATE INDEX idx_audit_events_direction_sequence
+      ON audit_events(direction, sequence DESC);
+    CREATE TABLE IF NOT EXISTS audit_identity_keys (
+      id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
+      key_id TEXT NOT NULL,
+      key BLOB NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+  `);
+  // AUTOINCREMENT is part of the stable cursor contract. Rebuilding an empty
+  // or sparsely retained table must not reuse a sequence already handed out.
+  restoreAuditEventSequenceHighWater(db, sequenceHighWater);
+  return true;
+}
diff --git a/src/state/openclaw-state-db-contract.ts b/src/state/openclaw-state-db-contract.ts
new file mode 100644
index 00000000000..8373e6d6f39
--- /dev/null
+++ b/src/state/openclaw-state-db-contract.ts
@@ -0,0 +1,32 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { SqliteWalMaintenance } from "../infra/sqlite-wal.js";
+
+// v4 replaces ambient session-watch sentinel rows with cursor provenance.
+export const OPENCLAW_STATE_SCHEMA_VERSION = 4;
+export const OPENCLAW_STATE_STRICT_SCHEMA_VERSION = 3;
+/** Maximum time one synchronous SQLite call may wait for a lock. */
+export const OPENCLAW_SQLITE_BUSY_TIMEOUT_MS = 5_000;
+/** User-facing guide for schema refusals; lives here so error sites avoid import cycles. */
+export const OPENCLAW_DATABASE_SCHEMA_DOCS_URL =
+  "https://docs.openclaw.ai/reference/database-schemas";
+
+/** Open shared SQLite database handle plus WAL maintenance lifecycle. */
+export type OpenClawStateDatabase = {
+  db: DatabaseSync;
+  path: string;
+  walMaintenance: SqliteWalMaintenance;
+};
+/** Options for resolving or overriding the shared state database path. */
+export type OpenClawStateDatabaseOptions = {
+  env?: NodeJS.ProcessEnv;
+  path?: string;
+};
+export type OpenClawStateDatabaseSchemaMigration = {
+  kind:
+    | "agent-databases-composite-primary-key"
+    | "audit-events-v2"
+    | "operator-approvals-system-agent"
+    | "session-watch-cursor-provenance-v4"
+    | "strict-tables-v3";
+  path: string;
+};
diff --git a/src/state/openclaw-state-db-legacy-backfills.ts b/src/state/openclaw-state-db-legacy-backfills.ts
new file mode 100644
index 00000000000..1b943bdea8c
--- /dev/null
+++ b/src/state/openclaw-state-db-legacy-backfills.ts
@@ -0,0 +1,549 @@
+import type { DatabaseSync } from "node:sqlite";
+import { buildApprovalResolutionRef } from "../infra/approval-resolution-ref.js";
+import { runSqliteImmediateTransactionSync } from "../infra/sqlite-transaction.js";
+import * as operatorApprovalMigration from "./openclaw-state-db-operator-approval-migration.js";
+import { ensureColumn, tableExists, tableHasColumn } from "./openclaw-state-db-schema-helpers.js";
+
+export function ensureOperatorApprovalResolutionRefs(db: DatabaseSync): void {
+  if (!tableExists(db, "operator_approvals")) {
+    return;
+  }
+  runSqliteImmediateTransactionSync(db, () => {
+    ensureColumn(db, "operator_approvals", "resolution_ref TEXT");
+    const rows = db
+      .prepare("SELECT approval_id, kind, resolution_ref FROM operator_approvals")
+      .all() as Array<{
+      approval_id?: unknown;
+      kind?: unknown;
+      resolution_ref?: unknown;
+    }>;
+    const update = db.prepare(
+      "UPDATE operator_approvals SET resolution_ref = ? WHERE approval_id = ?",
+    );
+    for (const row of rows) {
+      if (
+        typeof row.approval_id !== "string" ||
+        !operatorApprovalMigration.isCanonicalOperatorApprovalKind(row.kind)
+      ) {
+        throw new Error("operator approval row cannot be assigned a transport reference");
+      }
+      const resolutionRef = buildApprovalResolutionRef({
+        approvalId: row.approval_id,
+        approvalKind: row.kind,
+      });
+      if (row.resolution_ref !== resolutionRef) {
+        update.run(resolutionRef, row.approval_id);
+      }
+    }
+    const namespaceConflict = db
+      .prepare(
+        `SELECT canonical.approval_id
+         FROM operator_approvals AS canonical
+         JOIN operator_approvals AS referenced
+           ON canonical.approval_id = referenced.resolution_ref
+         WHERE canonical.approval_id <> referenced.approval_id
+         LIMIT 1`,
+      )
+      .get();
+    if (namespaceConflict) {
+      throw new Error("operator approval ids conflict with durable transport references");
+    }
+    db.exec(`
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_operator_approvals_resolution_ref
+        ON operator_approvals(resolution_ref);
+    `);
+  });
+}
+
+export function repairLegacyTaskAgentAttribution(db: DatabaseSync): void {
+  if (!tableExists(db, "task_runs") || !tableHasColumn(db, "task_runs", "requester_agent_id")) {
+    return;
+  }
+  // Before requester_agent_id existed, scoped subagent/ACP rows stored the
+  // requester in agent_id. Repair only rows with recoverable requester
+  // provenance; global legacy rows must keep the existing fallback behavior.
+  db.exec(`
+    UPDATE task_runs
+    SET
+      requester_agent_id = CASE
+        WHEN owner_key GLOB 'agent:*:*' THEN substr(
+          owner_key,
+          7,
+          instr(substr(owner_key, 7), ':') - 1
+        )
+        WHEN requester_session_key GLOB 'agent:*:*' THEN substr(
+          requester_session_key,
+          7,
+          instr(substr(requester_session_key, 7), ':') - 1
+        )
+        WHEN agent_id <> substr(
+          child_session_key,
+          7,
+          instr(substr(child_session_key, 7), ':') - 1
+        ) THEN agent_id
+        ELSE NULL
+      END,
+      agent_id = substr(
+        child_session_key,
+        7,
+        instr(substr(child_session_key, 7), ':') - 1
+      )
+    WHERE requester_agent_id IS NULL
+      AND runtime IN ('subagent', 'acp')
+      AND child_session_key GLOB 'agent:*:*'
+      AND instr(substr(child_session_key, 7), ':') > 1
+      AND (
+        owner_key GLOB 'agent:*:*'
+        OR requester_session_key GLOB 'agent:*:*'
+        OR (
+          agent_id IS NOT NULL
+          AND agent_id <> substr(
+            child_session_key,
+            7,
+            instr(substr(child_session_key, 7), ':') - 1
+          )
+        )
+      );
+  `);
+}
+
+export function repairLegacyTaskDeliveryStatuses(db: DatabaseSync): void {
+  if (!tableExists(db, "task_runs") || !tableHasColumn(db, "task_runs", "delivery_status")) {
+    return;
+  }
+  // Successful sidecar imports archive their source, so database open must
+  // also canonicalize rows already copied by released migrations.
+  db.exec(`
+    UPDATE task_runs
+    SET delivery_status = 'not_applicable'
+    WHERE delivery_status = 'not-requested';
+  `);
+}
+
+export function backfillAcpReplayEstimatedBytes(db: DatabaseSync): void {
+  if (
+    !tableExists(db, "acp_replay_events") ||
+    !tableHasColumn(db, "acp_replay_events", "estimated_bytes")
+  ) {
+    return;
+  }
+  const pendingEvent = db
+    .prepare("SELECT 1 FROM acp_replay_events WHERE estimated_bytes = 0 LIMIT 1")
+    .get();
+  const pendingSession = db
+    .prepare("SELECT 1 FROM acp_replay_sessions WHERE estimated_bytes = 0 LIMIT 1")
+    .get();
+  if (!pendingEvent && !pendingSession) {
+    return;
+  }
+  db.exec(`
+    UPDATE acp_replay_events
+       SET estimated_bytes = length(session_id) + length(session_key) + length(update_json)
+             + COALESCE(length(run_id), 0) + 32
+     WHERE estimated_bytes = 0;
+    UPDATE acp_replay_sessions
+       SET estimated_bytes = length(session_id) + length(session_key) + length(cwd) + 32
+             + COALESCE((SELECT SUM(e.estimated_bytes) FROM acp_replay_events e
+                          WHERE e.session_id = acp_replay_sessions.session_id), 0)
+     WHERE estimated_bytes = 0;
+  `);
+}
+
+export function backfillCronRunLogEntryJson(db: DatabaseSync): void {
+  if (!tableExists(db, "cron_run_logs") || !tableHasColumn(db, "cron_run_logs", "entry_json")) {
+    return;
+  }
+  const rows = db
+    .prepare(
+      `SELECT store_key, job_id, seq, ts
+         FROM cron_run_logs
+        WHERE entry_json = '{}'`,
+    )
+    .all() as Array<{
+    store_key: string;
+    job_id: string;
+    seq: number | bigint;
+    ts: number | bigint;
+  }>;
+  if (rows.length === 0) {
+    return;
+  }
+  const update = db.prepare(
+    `UPDATE cron_run_logs
+        SET entry_json = ?
+      WHERE store_key = ? AND job_id = ? AND seq = ?`,
+  );
+  for (const row of rows) {
+    update.run(
+      JSON.stringify({ ts: Number(row.ts), jobId: row.job_id, action: "finished" }),
+      row.store_key,
+      row.job_id,
+      row.seq,
+    );
+  }
+}
+
+function parseJsonRecord(value: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function textField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+function numberField(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function recordField(record: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const value = record[key];
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function jsonField(value: unknown): string | null {
+  return value === undefined ? null : JSON.stringify(value);
+}
+
+function cronSessionTargetField(record: Record<string, unknown>): string | null {
+  const value = textField(record, "sessionTarget");
+  if (!value) {
+    return null;
+  }
+  return value === "main" ||
+    value === "isolated" ||
+    value === "current" ||
+    value.startsWith("session:")
+    ? value
+    : null;
+}
+
+function cronWakeModeField(record: Record<string, unknown>): string | null {
+  const value = textField(record, "wakeMode");
+  return value === "now" || value === "next-heartbeat" ? value : null;
+}
+
+function booleanField(record: Record<string, unknown>, key: string): number | null {
+  const value = record[key];
+  return typeof value === "boolean" ? (value ? 1 : 0) : null;
+}
+
+function failureDestinationField(
+  record: Record<string, unknown> | null,
+  key: "accountId" | "channel" | "mode" | "to",
+): string | null {
+  if (!record || !Object.hasOwn(record, key)) {
+    return null;
+  }
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value : "";
+}
+
+export function migrateLegacyCronDeliveryThreadIds(db: DatabaseSync): void {
+  const rows = db
+    .prepare(
+      `SELECT store_key, job_id, job_json, delivery_thread_id
+         FROM cron_jobs
+        WHERE delivery_thread_id_type IS NULL`,
+    )
+    .all() as Array<{
+    store_key: string;
+    job_id: string;
+    job_json: string;
+    delivery_thread_id: string | null;
+  }>;
+  const update = db.prepare(
+    `UPDATE cron_jobs
+        SET delivery_thread_id = ?, delivery_thread_id_type = ?
+      WHERE store_key = ? AND job_id = ? AND delivery_thread_id_type IS NULL`,
+  );
+  for (const row of rows) {
+    const job = parseJsonRecord(row.job_json);
+    const delivery = job ? recordField(job, "delivery") : null;
+    const typed = delivery?.threadId;
+    if (row.delivery_thread_id === null) {
+      // The first normalized cron migration could not project numeric thread IDs.
+      // Recover only that known lost shape while this type column is first added.
+      if (typeof typed === "number" && Number.isFinite(typed)) {
+        update.run(String(typed), "number", row.store_key, row.job_id);
+      }
+      continue;
+    }
+    const type =
+      typeof typed === "number" &&
+      Number.isFinite(typed) &&
+      String(typed) === row.delivery_thread_id
+        ? "number"
+        : "string";
+    update.run(row.delivery_thread_id, type, row.store_key, row.job_id);
+  }
+}
+
+export function backfillCronJobsFromJobJson(db: DatabaseSync): void {
+  if (
+    !tableExists(db, "cron_jobs") ||
+    !tableHasColumn(db, "cron_jobs", "job_json") ||
+    !tableHasColumn(db, "cron_jobs", "schedule_kind") ||
+    !tableHasColumn(db, "cron_jobs", "payload_kind")
+  ) {
+    return;
+  }
+  const rows = db
+    .prepare(
+      `SELECT store_key, job_id, job_json, updated_at
+         FROM cron_jobs
+        WHERE schedule_kind = 'manual'
+           OR payload_kind = 'message'
+           OR name = ''`,
+    )
+    .all() as Array<{
+    store_key: string;
+    job_id: string;
+    job_json: string;
+    updated_at: number | bigint;
+  }>;
+  if (rows.length === 0) {
+    return;
+  }
+  const update = db.prepare(
+    `UPDATE cron_jobs
+        SET name = ?,
+            enabled = ?,
+            delete_after_run = ?,
+            created_at_ms = ?,
+            agent_id = ?,
+            session_key = ?,
+            schedule_kind = ?,
+            schedule_expr = ?,
+            schedule_tz = ?,
+            every_ms = ?,
+            anchor_ms = ?,
+            at = ?,
+            stagger_ms = ?,
+            session_target = ?,
+            wake_mode = ?,
+            payload_kind = ?,
+            payload_message = ?,
+            payload_model = ?,
+            payload_fallbacks_json = ?,
+            payload_thinking = ?,
+            payload_timeout_seconds = ?,
+            payload_allow_unsafe_external_content = ?,
+            payload_external_content_source_json = ?,
+            payload_light_context = ?,
+            payload_tools_allow_json = ?,
+            delivery_mode = ?,
+            delivery_channel = ?,
+            delivery_to = ?,
+            delivery_thread_id = ?,
+            delivery_account_id = ?,
+            delivery_best_effort = ?,
+            delivery_completion_mode = ?,
+            delivery_completion_to = ?,
+            failure_delivery_mode = ?,
+            failure_delivery_channel = ?,
+            failure_delivery_to = ?,
+            failure_delivery_account_id = ?,
+            failure_alert_disabled = ?,
+            failure_alert_after = ?,
+            failure_alert_channel = ?,
+            failure_alert_to = ?,
+            failure_alert_cooldown_ms = ?,
+            failure_alert_include_skipped = ?,
+            failure_alert_mode = ?,
+            failure_alert_account_id = ?,
+            runtime_updated_at_ms = ?
+      WHERE store_key = ?
+        AND job_id = ?`,
+  );
+  for (const row of rows) {
+    const job = parseJsonRecord(row.job_json);
+    if (!job) {
+      continue;
+    }
+    // Legacy cron rows kept the contract in job_json; columns are a queryable projection of it.
+    const schedule = recordField(job, "schedule");
+    const payload = recordField(job, "payload");
+    const scheduleKind = textField(schedule ?? {}, "kind");
+    const payloadKind = textField(payload ?? {}, "kind");
+    const isAt = scheduleKind === "at" && textField(schedule ?? {}, "at");
+    const isEvery = scheduleKind === "every" && numberField(schedule ?? {}, "everyMs") != null;
+    const isCron = scheduleKind === "cron" && textField(schedule ?? {}, "expr");
+    const isSystemEvent = payloadKind === "systemEvent" && textField(payload ?? {}, "text");
+    const isAgentTurn = payloadKind === "agentTurn" && textField(payload ?? {}, "message");
+    if (
+      !schedule ||
+      !payload ||
+      (!isAt && !isEvery && !isCron) ||
+      (!isSystemEvent && !isAgentTurn)
+    ) {
+      continue;
+    }
+    const fallbackTime = Number(row.updated_at) || 0;
+    const delivery = recordField(job, "delivery");
+    const completionDestination = delivery ? recordField(delivery, "completionDestination") : null;
+    const failureDestination = delivery ? recordField(delivery, "failureDestination") : null;
+    const failureAlertValue = job.failureAlert;
+    const failureAlert =
+      failureAlertValue &&
+      typeof failureAlertValue === "object" &&
+      !Array.isArray(failureAlertValue)
+        ? (failureAlertValue as Record<string, unknown>)
+        : null;
+    update.run(
+      textField(job, "name") ?? row.job_id,
+      job.enabled === false ? 0 : 1,
+      booleanField(job, "deleteAfterRun"),
+      numberField(job, "createdAtMs") ?? fallbackTime,
+      textField(job, "agentId"),
+      textField(job, "sessionKey"),
+      scheduleKind,
+      isCron ? textField(schedule, "expr") : null,
+      isCron ? textField(schedule, "tz") : null,
+      isEvery ? numberField(schedule, "everyMs") : null,
+      isEvery ? numberField(schedule, "anchorMs") : null,
+      isAt ? textField(schedule, "at") : null,
+      isCron ? numberField(schedule, "staggerMs") : null,
+      cronSessionTargetField(job) ?? (payloadKind === "agentTurn" ? "isolated" : "main"),
+      cronWakeModeField(job) ?? "now",
+      payloadKind,
+      isSystemEvent ? textField(payload, "text") : textField(payload, "message"),
+      isAgentTurn ? textField(payload, "model") : null,
+      isAgentTurn ? jsonField(payload.fallbacks) : null,
+      isAgentTurn ? textField(payload, "thinking") : null,
+      isAgentTurn ? numberField(payload, "timeoutSeconds") : null,
+      isAgentTurn && typeof payload.allowUnsafeExternalContent === "boolean"
+        ? payload.allowUnsafeExternalContent
+          ? 1
+          : 0
+        : null,
+      isAgentTurn ? jsonField(payload.externalContentSource) : null,
+      isAgentTurn && typeof payload.lightContext === "boolean"
+        ? payload.lightContext
+          ? 1
+          : 0
+        : null,
+      isAgentTurn ? jsonField(payload.toolsAllow) : null,
+      delivery ? textField(delivery, "mode") : null,
+      delivery ? textField(delivery, "channel") : null,
+      delivery ? textField(delivery, "to") : null,
+      delivery ? textField(delivery, "threadId") : null,
+      delivery ? textField(delivery, "accountId") : null,
+      delivery && typeof delivery.bestEffort === "boolean" ? (delivery.bestEffort ? 1 : 0) : null,
+      completionDestination ? textField(completionDestination, "mode") : null,
+      completionDestination ? textField(completionDestination, "to") : null,
+      failureDestinationField(failureDestination, "mode"),
+      failureDestinationField(failureDestination, "channel"),
+      failureDestinationField(failureDestination, "to"),
+      failureDestinationField(failureDestination, "accountId"),
+      failureAlertValue === false ? 1 : failureAlert ? 0 : null,
+      failureAlert ? numberField(failureAlert, "after") : null,
+      failureAlert ? textField(failureAlert, "channel") : null,
+      failureAlert ? textField(failureAlert, "to") : null,
+      failureAlert ? numberField(failureAlert, "cooldownMs") : null,
+      failureAlert && typeof failureAlert.includeSkipped === "boolean"
+        ? failureAlert.includeSkipped
+          ? 1
+          : 0
+        : null,
+      failureAlert ? textField(failureAlert, "mode") : null,
+      failureAlert ? textField(failureAlert, "accountId") : null,
+      numberField(job, "updatedAtMs") ?? fallbackTime,
+      row.store_key,
+      row.job_id,
+    );
+  }
+}
+
+function metadataStringField(record: Record<string, unknown>, key: string): string | null {
+  return textField(record, key);
+}
+
+export function backfillDeliveryQueueEntriesFromEntryJson(db: DatabaseSync): void {
+  if (
+    !tableExists(db, "delivery_queue_entries") ||
+    !tableHasColumn(db, "delivery_queue_entries", "entry_json") ||
+    !tableHasColumn(db, "delivery_queue_entries", "retry_count")
+  ) {
+    return;
+  }
+  const rows = db
+    .prepare(
+      `SELECT queue_name, id, entry_json
+         FROM delivery_queue_entries
+        WHERE status <> 'completed'
+          AND (retry_count = 0
+            OR last_attempt_at IS NULL
+            OR last_error IS NULL
+            OR recovery_state IS NULL
+            OR platform_send_started_at IS NULL
+            OR entry_kind IS NULL
+            OR session_key IS NULL
+            OR channel IS NULL
+            OR target IS NULL
+            OR account_id IS NULL)`,
+    )
+    .all() as Array<{ queue_name: string; id: string; entry_json: string }>;
+  if (rows.length === 0) {
+    return;
+  }
+  const update = db.prepare(
+    `UPDATE delivery_queue_entries
+        SET entry_kind = COALESCE(?, entry_kind),
+            session_key = COALESCE(?, session_key),
+            channel = COALESCE(?, channel),
+            target = COALESCE(?, target),
+            account_id = COALESCE(?, account_id),
+            retry_count = ?,
+            last_attempt_at = COALESCE(?, last_attempt_at),
+            last_error = COALESCE(?, last_error),
+            recovery_state = COALESCE(?, recovery_state),
+            platform_send_started_at = COALESCE(?, platform_send_started_at)
+      WHERE queue_name = ?
+        AND id = ?`,
+  );
+  for (const row of rows) {
+    const entry = parseJsonRecord(row.entry_json);
+    if (!entry) {
+      continue;
+    }
+    // Queue metadata is denormalized for recovery queries but entry_json remains source of truth.
+    const session = recordField(entry, "session");
+    const route = recordField(entry, "route");
+    const deliveryContext = recordField(entry, "deliveryContext");
+    update.run(
+      metadataStringField(entry, "kind"),
+      metadataStringField(entry, "sessionKey") ??
+        (session ? metadataStringField(session, "key") : null),
+      metadataStringField(entry, "channel") ??
+        (route ? metadataStringField(route, "channel") : null) ??
+        (deliveryContext ? metadataStringField(deliveryContext, "channel") : null),
+      metadataStringField(entry, "to") ??
+        (route ? metadataStringField(route, "to") : null) ??
+        (deliveryContext ? metadataStringField(deliveryContext, "to") : null),
+      metadataStringField(entry, "accountId") ??
+        (route ? metadataStringField(route, "accountId") : null) ??
+        (deliveryContext ? metadataStringField(deliveryContext, "accountId") : null),
+      numberField(entry, "retryCount") ?? 0,
+      numberField(entry, "lastAttemptAt"),
+      metadataStringField(entry, "lastError"),
+      metadataStringField(entry, "recoveryState"),
+      numberField(entry, "platformSendStartedAt"),
+      row.queue_name,
+      row.id,
+    );
+  }
+}
+
+// The caller owns the state.schema.ensure transaction so every probe, DDL
+// change, and backfill observes one authoritative schema across processes.
diff --git a/src/state/openclaw-state-db-maintenance.ts b/src/state/openclaw-state-db-maintenance.ts
new file mode 100644
index 00000000000..47b7328ba8b
--- /dev/null
+++ b/src/state/openclaw-state-db-maintenance.ts
@@ -0,0 +1,121 @@
+import path from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import {
+  assertSqliteSchemaContains,
+  type SqliteSchemaCompatibility,
+} from "../infra/sqlite-schema-contract.js";
+import {
+  createNewerSqliteSchemaVersionError,
+  readSqliteUserVersion,
+} from "../infra/sqlite-user-version.js";
+import {
+  OPENCLAW_DATABASE_SCHEMA_DOCS_URL,
+  OPENCLAW_STATE_SCHEMA_VERSION,
+  type OpenClawStateDatabaseOptions,
+} from "./openclaw-state-db-contract.js";
+import { resolveOpenClawStateSqlitePath } from "./openclaw-state-db.paths.js";
+import { OPENCLAW_STATE_SCHEMA_SQL } from "./openclaw-state-schema.generated.js";
+
+const OPENCLAW_STATE_MAINTENANCE_SCHEMA_COMPATIBILITY = {
+  allowedColumnDefinitions: {
+    "diagnostic_events.sequence": ["sequence INTEGER NOT NULL DEFAULT 0"],
+    "commitments.attempts": ["attempts INTEGER NOT NULL DEFAULT 0"],
+    "commitments.confidence": ["confidence REAL NOT NULL DEFAULT 0"],
+    "commitments.created_at_ms": ["created_at_ms INTEGER NOT NULL DEFAULT 0"],
+    "commitments.dedupe_key": ["dedupe_key TEXT NOT NULL DEFAULT ''"],
+    "commitments.due_timezone": ["due_timezone TEXT NOT NULL DEFAULT 'UTC'"],
+    "commitments.kind": ["kind TEXT NOT NULL DEFAULT 'followup'"],
+    "commitments.reason": ["reason TEXT NOT NULL DEFAULT ''"],
+    "commitments.sensitivity": ["sensitivity TEXT NOT NULL DEFAULT 'normal'"],
+    "commitments.source": ["source TEXT NOT NULL DEFAULT 'unknown'"],
+    "commitments.suggested_text": ["suggested_text TEXT NOT NULL DEFAULT ''"],
+    "cron_jobs.created_at_ms": ["created_at_ms INTEGER NOT NULL DEFAULT 0"],
+    "cron_jobs.enabled": ["enabled INTEGER NOT NULL DEFAULT 1"],
+    "cron_jobs.name": ["name TEXT NOT NULL DEFAULT ''"],
+    "cron_jobs.payload_kind": ["payload_kind TEXT NOT NULL DEFAULT 'message'"],
+    "cron_jobs.schedule_kind": ["schedule_kind TEXT NOT NULL DEFAULT 'manual'"],
+    "cron_jobs.session_target": ["session_target TEXT NOT NULL DEFAULT 'main'"],
+    "cron_jobs.wake_mode": ["wake_mode TEXT NOT NULL DEFAULT 'auto'"],
+    "current_conversation_bindings.conversation_kind": [
+      "conversation_kind TEXT NOT NULL DEFAULT 'channel'",
+    ],
+    "current_conversation_bindings.target_agent_id": [
+      "target_agent_id TEXT NOT NULL DEFAULT 'main'",
+    ],
+  },
+} satisfies SqliteSchemaCompatibility;
+
+/** Open shared SQLite database handle plus WAL maintenance lifecycle. */
+
+export function createOpenClawDatabaseVerificationError(
+  kind: "agent" | "state",
+  pathname: string,
+  storedError: string | null,
+): Error {
+  // Doctor's clearing hooks run after a full integrity assertion, so a still-
+  // corrupt file cannot be cleared directly: the file must be healthy first.
+  const error = new Error(
+    `OpenClaw ${kind} database ${pathname} is quarantined after integrity verification failed: ${storedError ?? "unknown integrity error"}. Restore the database from a backup or repair it, then run openclaw doctor --fix to clear the quarantine. See ${OPENCLAW_DATABASE_SCHEMA_DOCS_URL}.`,
+  );
+  error.name = "SqliteIntegrityError";
+  return error;
+}
+
+export function assertSupportedSchemaVersion(db: DatabaseSync, pathname: string): void {
+  const userVersion = readSqliteUserVersion(db);
+  if (userVersion > OPENCLAW_STATE_SCHEMA_VERSION) {
+    throw createNewerSqliteSchemaVersionError(
+      "OpenClaw state database",
+      pathname,
+      userVersion,
+      OPENCLAW_STATE_SCHEMA_VERSION,
+    );
+  }
+}
+/** Require the canonical shared-state owner and schema before offline file maintenance. */
+export function assertOpenClawStateDatabaseForMaintenance(
+  database: DatabaseSync,
+  options: { pathname: string },
+): void {
+  const userVersion = readSqliteUserVersion(database);
+  if (userVersion > OPENCLAW_STATE_SCHEMA_VERSION) {
+    throw createNewerSqliteSchemaVersionError(
+      "OpenClaw state database",
+      options.pathname,
+      userVersion,
+      OPENCLAW_STATE_SCHEMA_VERSION,
+    );
+  }
+  if (userVersion !== OPENCLAW_STATE_SCHEMA_VERSION) {
+    throw new Error(
+      `OpenClaw state database ${options.pathname} uses schema version ${userVersion}; run openclaw doctor --fix before compacting it.`,
+    );
+  }
+
+  const metadata = database
+    .prepare("SELECT role, schema_version FROM schema_meta WHERE meta_key = 'primary' LIMIT 1")
+    .get() as { role?: unknown; schema_version?: unknown } | undefined;
+  if (metadata?.role !== "global") {
+    const role = typeof metadata?.role === "string" ? metadata.role : "missing";
+    throw new Error(
+      `OpenClaw state database ${options.pathname} has schema role ${role}; expected global.`,
+    );
+  }
+  if (metadata.schema_version !== OPENCLAW_STATE_SCHEMA_VERSION) {
+    const schemaVersion =
+      typeof metadata.schema_version === "number" ? metadata.schema_version : "invalid";
+    throw new Error(
+      `OpenClaw state database ${options.pathname} metadata schema version ${schemaVersion} does not match ${OPENCLAW_STATE_SCHEMA_VERSION}; run openclaw doctor --fix before compacting it.`,
+    );
+  }
+  assertSqliteSchemaContains(
+    database,
+    options.pathname,
+    OPENCLAW_STATE_SCHEMA_SQL,
+    OPENCLAW_STATE_MAINTENANCE_SCHEMA_COMPATIBILITY,
+  );
+}
+
+export function resolveDatabasePath(options: OpenClawStateDatabaseOptions = {}): string {
+  return path.resolve(options.path ?? resolveOpenClawStateSqlitePath(options.env ?? process.env));
+}
diff --git a/src/state/openclaw-state-db-permissions.ts b/src/state/openclaw-state-db-permissions.ts
new file mode 100644
index 00000000000..86d85aa8fcd
--- /dev/null
+++ b/src/state/openclaw-state-db-permissions.ts
@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { createDedupeCache } from "../infra/dedupe.js";
+import { applyPrivateModeSync } from "../infra/private-mode.js";
+import { resolveSqliteDatabaseFilePaths } from "../infra/sqlite-files.js";
+import { createSubsystemLogger } from "../logging/subsystem.js";
+import {
+  resolveOpenClawStateSqliteDir,
+  resolveOpenClawStateSqlitePath,
+} from "./openclaw-state-db.paths.js";
+
+const OPENCLAW_STATE_DIR_MODE = 0o700;
+const OPENCLAW_STATE_FILE_MODE = 0o600;
+
+const stateDbLog = createSubsystemLogger("state/db");
+
+/** Targets already warned about, so chmod-less filesystems warn once per path. */
+const chmodWarnedTargets = createDedupeCache({
+  ttlMs: 0,
+  maxSize: 4096,
+});
+
+// Permission hardening is best-effort only on filesystems that cannot apply
+// it: the database stays usable without the chmod, and crashing at open would
+// take the gateway down on Azure Files/NFS/Docker volumes (#91919). Unexpected
+// chmod failures still throw so credentials-adjacent hardening stays loud.
+function bestEffortChmodSync(target: string, mode: number): void {
+  const result = applyPrivateModeSync(target, mode);
+  if (result.applied || chmodWarnedTargets.check(target)) {
+    return;
+  }
+  stateDbLog.warn(`skipped permission hardening for ${target}: ${String(result.error)}`);
+}
+
+export function ensureOpenClawStatePermissions(pathname: string, env: NodeJS.ProcessEnv): void {
+  const dir = path.dirname(pathname);
+  const defaultDir = resolveOpenClawStateSqliteDir(env);
+  const isDefaultStateDatabase =
+    path.resolve(pathname) === path.resolve(resolveOpenClawStateSqlitePath(env));
+  if (isDefaultStateDatabase && dir !== defaultDir) {
+    throw new Error(`OpenClaw state database path resolved outside its state dir: ${pathname}`);
+  }
+  const dirExisted = existsSync(dir);
+  mkdirSync(dir, { recursive: true, mode: OPENCLAW_STATE_DIR_MODE });
+  // Default state contains credentials-adjacent metadata; custom existing dirs keep caller modes.
+  if (isDefaultStateDatabase || !dirExisted) {
+    bestEffortChmodSync(dir, OPENCLAW_STATE_DIR_MODE);
+  }
+  for (const candidate of resolveSqliteDatabaseFilePaths(pathname)) {
+    if (existsSync(candidate)) {
+      bestEffortChmodSync(candidate, OPENCLAW_STATE_FILE_MODE);
+    }
+  }
+}
diff --git a/src/state/openclaw-state-db-schema-additive.ts b/src/state/openclaw-state-db-schema-additive.ts
new file mode 100644
index 00000000000..b7b80ecfb93
--- /dev/null
+++ b/src/state/openclaw-state-db-schema-additive.ts
@@ -0,0 +1,256 @@
+import type { DatabaseSync } from "node:sqlite";
+import {
+  backfillAcpReplayEstimatedBytes,
+  backfillCronJobsFromJobJson,
+  backfillCronRunLogEntryJson,
+  backfillDeliveryQueueEntriesFromEntryJson,
+  ensureOperatorApprovalResolutionRefs,
+  migrateLegacyCronDeliveryThreadIds,
+  repairLegacyTaskAgentAttribution,
+  repairLegacyTaskDeliveryStatuses,
+} from "./openclaw-state-db-legacy-backfills.js";
+import { ensureColumn } from "./openclaw-state-db-schema-helpers.js";
+
+export function ensureAdditiveStateColumns(db: DatabaseSync): void {
+  const addedDiagnosticEventSequence = ensureColumn(
+    db,
+    "diagnostic_events",
+    "sequence INTEGER NOT NULL DEFAULT 0",
+  );
+  if (addedDiagnosticEventSequence) {
+    // Preserve the legacy (created_at, rowid) order before the new sequence
+    // index becomes authoritative, including stable ties within each scope.
+    db.exec(`
+      WITH ranked AS (
+        SELECT
+          rowid AS event_rowid,
+          ROW_NUMBER() OVER (
+            PARTITION BY scope
+            ORDER BY created_at ASC, rowid ASC
+          ) AS sequence
+        FROM diagnostic_events
+      )
+      UPDATE diagnostic_events
+      SET sequence = (
+        SELECT ranked.sequence
+        FROM ranked
+        WHERE ranked.event_rowid = diagnostic_events.rowid
+      );
+    `);
+  }
+  db.exec("DROP INDEX IF EXISTS idx_diagnostic_events_scope_created;");
+  ensureColumn(db, "worktrees", "provisioned_paths_json TEXT");
+  ensureColumn(db, "node_host_config", "gateway_context_path TEXT");
+  ensureColumn(db, "node_host_config", "installed_apps_sharing INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "apns_registrations", "relay_origin TEXT");
+  ensureColumn(db, "device_pairing_pending", "refreshed_at_ms INTEGER");
+  ensureColumn(db, "device_pairing_pending", "browser_origin TEXT");
+  ensureColumn(db, "device_pairing_paired", "approved_via TEXT");
+  ensureColumn(db, "device_pairing_paired", "browser_origin TEXT");
+  ensureColumn(db, "device_pairing_paired", "operator_label TEXT");
+  ensureColumn(db, "device_pairing_paired", "node_surface_json TEXT");
+  ensureColumn(db, "device_pairing_paired", "pending_node_surface_json TEXT");
+  ensureColumn(db, "cron_run_logs", "status TEXT");
+  ensureColumn(db, "cron_run_logs", "error TEXT");
+  ensureColumn(db, "cron_run_logs", "summary TEXT");
+  ensureColumn(db, "cron_run_logs", "diagnostics_summary TEXT");
+  ensureColumn(db, "cron_run_logs", "delivery_status TEXT");
+  ensureColumn(db, "cron_run_logs", "delivery_error TEXT");
+  ensureColumn(db, "cron_run_logs", "delivered INTEGER");
+  ensureColumn(db, "cron_run_logs", "session_id TEXT");
+  ensureColumn(db, "cron_run_logs", "session_key TEXT");
+  ensureColumn(db, "cron_run_logs", "run_id TEXT");
+  ensureColumn(db, "cron_run_logs", "run_at_ms INTEGER");
+  ensureColumn(db, "cron_run_logs", "duration_ms INTEGER");
+  ensureColumn(db, "cron_run_logs", "next_run_at_ms INTEGER");
+  ensureColumn(db, "cron_run_logs", "model TEXT");
+  ensureColumn(db, "cron_run_logs", "provider TEXT");
+  ensureColumn(db, "cron_run_logs", "total_tokens INTEGER");
+  ensureColumn(db, "cron_run_logs", "entry_json TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, "cron_run_logs", "created_at INTEGER NOT NULL DEFAULT 0");
+  backfillCronRunLogEntryJson(db);
+  ensureColumn(db, "acp_replay_events", "estimated_bytes INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "acp_replay_sessions", "estimated_bytes INTEGER NOT NULL DEFAULT 0");
+  backfillAcpReplayEstimatedBytes(db);
+  ensureColumn(db, "cron_jobs", "description TEXT");
+  ensureColumn(db, "cron_jobs", "declaration_key TEXT");
+  ensureColumn(db, "cron_jobs", "display_name TEXT");
+  ensureColumn(db, "cron_jobs", "owner_agent_id TEXT");
+  ensureColumn(db, "cron_jobs", "owner_session_key TEXT");
+  ensureColumn(db, "cron_jobs", "name TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "cron_jobs", "enabled INTEGER NOT NULL DEFAULT 1");
+  ensureColumn(db, "cron_jobs", "delete_after_run INTEGER");
+  ensureColumn(db, "cron_jobs", "created_at_ms INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "cron_jobs", "agent_id TEXT");
+  ensureColumn(db, "cron_jobs", "session_key TEXT");
+  ensureColumn(db, "cron_jobs", "schedule_kind TEXT NOT NULL DEFAULT 'manual'");
+  ensureColumn(db, "cron_jobs", "schedule_expr TEXT");
+  ensureColumn(db, "cron_jobs", "schedule_tz TEXT");
+  ensureColumn(db, "cron_jobs", "every_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "anchor_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "at TEXT");
+  ensureColumn(db, "cron_jobs", "stagger_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "session_target TEXT NOT NULL DEFAULT 'main'");
+  ensureColumn(db, "cron_jobs", "wake_mode TEXT NOT NULL DEFAULT 'auto'");
+  ensureColumn(db, "cron_jobs", "trigger_script TEXT");
+  ensureColumn(db, "cron_jobs", "trigger_once INTEGER");
+  ensureColumn(db, "cron_jobs", "payload_kind TEXT NOT NULL DEFAULT 'message'");
+  ensureColumn(db, "cron_jobs", "payload_message TEXT");
+  ensureColumn(db, "cron_jobs", "payload_model TEXT");
+  ensureColumn(db, "cron_jobs", "payload_fallbacks_json TEXT");
+  ensureColumn(db, "cron_jobs", "payload_thinking TEXT");
+  ensureColumn(db, "cron_jobs", "payload_timeout_seconds INTEGER");
+  ensureColumn(db, "cron_jobs", "payload_allow_unsafe_external_content INTEGER");
+  ensureColumn(db, "cron_jobs", "payload_external_content_source_json TEXT");
+  ensureColumn(db, "cron_jobs", "payload_light_context INTEGER");
+  ensureColumn(db, "cron_jobs", "payload_tools_allow_json TEXT");
+  ensureColumn(db, "cron_jobs", "payload_tools_allow_is_default INTEGER");
+  ensureColumn(db, "cron_jobs", "delivery_mode TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_channel TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_to TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_thread_id TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_account_id TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_best_effort INTEGER");
+  ensureColumn(db, "cron_jobs", "delivery_completion_mode TEXT");
+  ensureColumn(db, "cron_jobs", "delivery_completion_to TEXT");
+  ensureColumn(db, "cron_jobs", "failure_delivery_mode TEXT");
+  ensureColumn(db, "cron_jobs", "failure_delivery_channel TEXT");
+  ensureColumn(db, "cron_jobs", "failure_delivery_to TEXT");
+  ensureColumn(db, "cron_jobs", "failure_delivery_account_id TEXT");
+  ensureColumn(db, "cron_jobs", "failure_alert_disabled INTEGER");
+  ensureColumn(db, "cron_jobs", "failure_alert_after INTEGER");
+  ensureColumn(db, "cron_jobs", "failure_alert_channel TEXT");
+  ensureColumn(db, "cron_jobs", "failure_alert_to TEXT");
+  ensureColumn(db, "cron_jobs", "failure_alert_cooldown_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "failure_alert_include_skipped INTEGER");
+  ensureColumn(db, "cron_jobs", "failure_alert_mode TEXT");
+  ensureColumn(db, "cron_jobs", "failure_alert_account_id TEXT");
+  ensureColumn(db, "cron_jobs", "next_run_at_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "running_at_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "last_run_at_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "last_run_status TEXT");
+  ensureColumn(db, "cron_jobs", "last_error TEXT");
+  ensureColumn(db, "cron_jobs", "last_duration_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "consecutive_errors INTEGER");
+  ensureColumn(db, "cron_jobs", "consecutive_skipped INTEGER");
+  ensureColumn(db, "cron_jobs", "schedule_error_count INTEGER");
+  ensureColumn(db, "cron_jobs", "last_delivery_status TEXT");
+  ensureColumn(db, "cron_jobs", "last_delivery_error TEXT");
+  ensureColumn(db, "cron_jobs", "last_delivered INTEGER");
+  ensureColumn(db, "cron_jobs", "last_failure_alert_at_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "state_json TEXT NOT NULL DEFAULT '{}'");
+  ensureColumn(db, "cron_jobs", "runtime_updated_at_ms INTEGER");
+  ensureColumn(db, "cron_jobs", "schedule_identity TEXT");
+  ensureColumn(db, "cron_jobs", "sort_order INTEGER NOT NULL DEFAULT 0");
+  backfillCronJobsFromJobJson(db);
+  const addedDeliveryThreadIdType = ensureColumn(db, "cron_jobs", "delivery_thread_id_type TEXT");
+  if (addedDeliveryThreadIdType) {
+    migrateLegacyCronDeliveryThreadIds(db);
+  }
+  ensureColumn(db, "sandbox_registry_entries", "session_key TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "backend_id TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "runtime_label TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "image TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "created_at_ms INTEGER");
+  ensureColumn(db, "sandbox_registry_entries", "last_used_at_ms INTEGER");
+  ensureColumn(db, "sandbox_registry_entries", "config_label_kind TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "config_hash TEXT");
+  ensureColumn(db, "sandbox_registry_entries", "cdp_port INTEGER");
+  ensureColumn(db, "sandbox_registry_entries", "no_vnc_port INTEGER");
+  ensureColumn(db, "delivery_queue_entries", "entry_kind TEXT");
+  ensureColumn(db, "delivery_queue_entries", "session_key TEXT");
+  ensureColumn(db, "delivery_queue_entries", "channel TEXT");
+  ensureColumn(db, "delivery_queue_entries", "target TEXT");
+  ensureColumn(db, "delivery_queue_entries", "account_id TEXT");
+  ensureColumn(db, "delivery_queue_entries", "retry_count INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "delivery_queue_entries", "last_attempt_at INTEGER");
+  ensureColumn(db, "delivery_queue_entries", "last_error TEXT");
+  ensureColumn(db, "delivery_queue_entries", "recovery_state TEXT");
+  ensureColumn(db, "delivery_queue_entries", "platform_send_started_at INTEGER");
+  backfillDeliveryQueueEntriesFromEntryJson(db);
+  ensureColumn(db, "commitments", "account_id TEXT");
+  ensureColumn(db, "commitments", "recipient_id TEXT");
+  ensureColumn(db, "commitments", "thread_id TEXT");
+  ensureColumn(db, "commitments", "sender_id TEXT");
+  ensureColumn(db, "commitments", "kind TEXT NOT NULL DEFAULT 'followup'");
+  ensureColumn(db, "commitments", "sensitivity TEXT NOT NULL DEFAULT 'normal'");
+  ensureColumn(db, "commitments", "source TEXT NOT NULL DEFAULT 'unknown'");
+  ensureColumn(db, "commitments", "reason TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "commitments", "suggested_text TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "commitments", "dedupe_key TEXT NOT NULL DEFAULT ''");
+  ensureColumn(db, "commitments", "confidence REAL NOT NULL DEFAULT 0");
+  ensureColumn(db, "commitments", "due_timezone TEXT NOT NULL DEFAULT 'UTC'");
+  ensureColumn(db, "commitments", "source_message_id TEXT");
+  ensureColumn(db, "commitments", "source_run_id TEXT");
+  ensureColumn(db, "commitments", "created_at_ms INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "commitments", "attempts INTEGER NOT NULL DEFAULT 0");
+  ensureColumn(db, "commitments", "last_attempt_at_ms INTEGER");
+  ensureColumn(db, "commitments", "sent_at_ms INTEGER");
+  ensureColumn(db, "commitments", "dismissed_at_ms INTEGER");
+  ensureColumn(db, "commitments", "snoozed_until_ms INTEGER");
+  ensureColumn(db, "commitments", "expired_at_ms INTEGER");
+  // The shipped JSON runtime predeclared this table but never populated it.
+  // Add required typed columns before Doctor or runtime can insert canonical rows.
+  ensureColumn(db, "managed_outgoing_image_records", "original_media_root TEXT NOT NULL");
+  ensureColumn(db, "managed_outgoing_image_records", "agent_id TEXT");
+  ensureColumn(
+    db,
+    "managed_outgoing_image_records",
+    "cleanup_pending INTEGER NOT NULL DEFAULT 0 CHECK (cleanup_pending IN (0, 1))",
+  );
+  ensureColumn(db, "current_conversation_bindings", "target_agent_id TEXT NOT NULL DEFAULT 'main'");
+  ensureColumn(db, "current_conversation_bindings", "target_session_id TEXT");
+  ensureColumn(
+    db,
+    "current_conversation_bindings",
+    "conversation_kind TEXT NOT NULL DEFAULT 'channel'",
+  );
+  ensureColumn(db, "device_bootstrap_tokens", "pending_profile_json TEXT");
+  ensureColumn(db, "gateway_restart_handoff", "restart_trace_started_at INTEGER");
+  ensureColumn(db, "gateway_restart_handoff", "restart_trace_last_at INTEGER");
+  ensureColumn(db, "gateway_restart_intent", "reason TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "delivery_channel TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "delivery_to TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "delivery_account_id TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "message TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "continuation_json TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "doctor_hint TEXT");
+  ensureColumn(db, "gateway_restart_sentinel", "stats_json TEXT");
+  ensureColumn(db, "gateway_boot_lifecycle", "startup_reason TEXT");
+  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_mode TEXT");
+  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_key_id TEXT");
+  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_signature_count INTEGER");
+  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_threshold INTEGER");
+  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_verified_at TEXT");
+  const addedTaskRequesterAgentId = ensureColumn(db, "task_runs", "requester_agent_id TEXT");
+  if (addedTaskRequesterAgentId) {
+    repairLegacyTaskAgentAttribution(db);
+  }
+  repairLegacyTaskDeliveryStatuses(db);
+  ensureColumn(db, "task_runs", "tool_use_count INTEGER");
+  ensureColumn(db, "task_runs", "last_tool_name TEXT");
+  ensureColumn(db, "task_runs", "detail_json TEXT");
+  ensureColumn(db, "subagent_runs", "task_name TEXT");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_status TEXT");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_attempt_count INTEGER");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_replay_count INTEGER");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_next_attempt_at INTEGER");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_batch_run_ids_json TEXT");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_last_error TEXT");
+  ensureColumn(db, "subagent_runs", "requester_settle_wake_retire_after INTEGER");
+  ensureColumn(db, "worker_environments", "bootstrap_bundle_hash TEXT");
+  ensureColumn(db, "worker_environments", "bootstrap_openclaw_version TEXT");
+  ensureColumn(db, "worker_environments", "bootstrap_protocol_features_json TEXT");
+  ensureColumn(
+    db,
+    "worker_environments",
+    "owner_epoch INTEGER NOT NULL DEFAULT 0 CHECK (owner_epoch >= 0)",
+  );
+  ensureColumn(db, "worker_environments", "ssh_host_key TEXT");
+  ensureColumn(
+    db,
+    "worker_environments",
+    "teardown_terminal_state TEXT CHECK (teardown_terminal_state IN ('destroyed', 'failed'))",
+  );
+  ensureOperatorApprovalResolutionRefs(db);
+}
diff --git a/src/state/openclaw-state-db-schema-repair.ts b/src/state/openclaw-state-db-schema-repair.ts
new file mode 100644
index 00000000000..305423873a0
--- /dev/null
+++ b/src/state/openclaw-state-db-schema-repair.ts
@@ -0,0 +1,153 @@
+import { existsSync } from "node:fs";
+import type { DatabaseSync } from "node:sqlite";
+import { requireNodeSqlite } from "../infra/node-sqlite.js";
+import { readSqliteUserVersion } from "../infra/sqlite-user-version.js";
+import {
+  canRepairLegacyAuditEventsSchema,
+  hasCanonicalAuditEventsSchema,
+} from "./openclaw-state-db-audit-migration.js";
+import {
+  OPENCLAW_STATE_SCHEMA_VERSION,
+  OPENCLAW_STATE_STRICT_SCHEMA_VERSION,
+  type OpenClawStateDatabaseOptions,
+  type OpenClawStateDatabaseSchemaMigration,
+} from "./openclaw-state-db-contract.js";
+import { resolveDatabasePath } from "./openclaw-state-db-maintenance.js";
+import * as operatorApprovalMigration from "./openclaw-state-db-operator-approval-migration.js";
+import {
+  tableExists,
+  tableHasColumn,
+  tablePrimaryKeyColumns,
+} from "./openclaw-state-db-schema-helpers.js";
+import * as sessionWatchMigration from "./openclaw-state-db-session-watch-migration.js";
+
+export function dropLegacyStateTables(db: DatabaseSync): void {
+  // Unreleased transient history; drop, do not migrate.
+  const transientHistoryTable = ["database", "verifications"].join("_");
+  db.exec(`DROP TABLE IF EXISTS ${transientHistoryTable};`);
+  // Retired node pairing tables never had a shipped writer.
+  db.exec("DROP TABLE IF EXISTS node_pairing_pending; DROP TABLE IF EXISTS node_pairing_paired;");
+}
+
+function hasCanonicalAgentDatabasesPrimaryKey(db: DatabaseSync): boolean {
+  if (!tableExists(db, "agent_databases")) {
+    return true;
+  }
+  const primaryKey = tablePrimaryKeyColumns(db, "agent_databases");
+  return primaryKey.length === 2 && primaryKey[0] === "agent_id" && primaryKey[1] === "path";
+}
+
+function canRepairAgentDatabasesPrimaryKey(db: DatabaseSync): boolean {
+  if (!tableExists(db, "agent_databases")) {
+    return false;
+  }
+  const requiredColumns = ["agent_id", "path", "schema_version", "last_seen_at", "size_bytes"];
+  return requiredColumns.every((column) => tableHasColumn(db, "agent_databases", column));
+}
+
+export function repairAgentDatabasesCompositePrimaryKey(db: DatabaseSync): boolean {
+  if (hasCanonicalAgentDatabasesPrimaryKey(db) || !canRepairAgentDatabasesPrimaryKey(db)) {
+    return false;
+  }
+  // Released DBs may have PRIMARY KEY(agent_id); current registration upserts by
+  // (agent_id,path) so explicit relocated agent DBs do not overwrite each other.
+  db.exec(`
+    DROP TABLE IF EXISTS agent_databases_migration_new;
+    CREATE TABLE agent_databases_migration_new (
+      agent_id TEXT NOT NULL,
+      path TEXT NOT NULL,
+      schema_version INTEGER NOT NULL,
+      last_seen_at INTEGER NOT NULL,
+      size_bytes INTEGER,
+      PRIMARY KEY (agent_id, path)
+    );
+    INSERT OR REPLACE INTO agent_databases_migration_new (
+      agent_id,
+      path,
+      schema_version,
+      last_seen_at,
+      size_bytes
+    )
+    SELECT
+      agent_id,
+      path,
+      schema_version,
+      last_seen_at,
+      size_bytes
+    FROM agent_databases
+    WHERE agent_id IS NOT NULL AND path IS NOT NULL;
+    DROP TABLE agent_databases;
+    ALTER TABLE agent_databases_migration_new RENAME TO agent_databases;
+  `);
+  return true;
+}
+
+export function markCurrentStateSchemaVersion(db: DatabaseSync): void {
+  // Pre-v2 databases can legitimately predate the audit table. Leave their
+  // version untouched so normal open can create the complete v2 schema first.
+  if (!tableExists(db, "audit_events")) {
+    return;
+  }
+  db.exec(`PRAGMA user_version = ${OPENCLAW_STATE_SCHEMA_VERSION};`);
+  if (
+    tableExists(db, "schema_meta") &&
+    ["meta_key", "schema_version", "updated_at"].every((column) =>
+      tableHasColumn(db, "schema_meta", column),
+    )
+  ) {
+    db.prepare(
+      "UPDATE schema_meta SET schema_version = ?, updated_at = ? WHERE meta_key = 'primary'",
+    ).run(OPENCLAW_STATE_SCHEMA_VERSION, Date.now());
+  }
+}
+
+export function assertCanonicalStateSchemaShape(db: DatabaseSync, pathname: string): void {
+  operatorApprovalMigration.assertCanonicalOperatorApprovalKinds(db, pathname);
+  if (!hasCanonicalAgentDatabasesPrimaryKey(db)) {
+    throw new Error(
+      `OpenClaw state database ${pathname} has a legacy agent database registry schema; run openclaw doctor --fix to migrate it.`,
+    );
+  }
+  if (!hasCanonicalAuditEventsSchema(db)) {
+    if (canRepairLegacyAuditEventsSchema(db)) {
+      throw new Error(
+        `OpenClaw state database ${pathname} has a legacy audit event schema; run openclaw doctor --fix to migrate it.`,
+      );
+    }
+    throw new Error(
+      `OpenClaw state database ${pathname} has a noncanonical audit event schema that cannot be repaired automatically; restore the canonical audit_events shape before retrying.`,
+    );
+  }
+}
+export function detectOpenClawStateDatabaseSchemaMigrations(
+  options: OpenClawStateDatabaseOptions = {},
+): OpenClawStateDatabaseSchemaMigration[] {
+  const pathname = resolveDatabasePath(options);
+  if (!existsSync(pathname)) {
+    return [];
+  }
+  const sqlite = requireNodeSqlite();
+  const db = new sqlite.DatabaseSync(pathname, { readOnly: true });
+  try {
+    const migrations: OpenClawStateDatabaseSchemaMigration[] = [];
+    const userVersion = readSqliteUserVersion(db);
+    if (!hasCanonicalAgentDatabasesPrimaryKey(db)) {
+      migrations.push({ kind: "agent-databases-composite-primary-key", path: pathname });
+    }
+    if (!hasCanonicalAuditEventsSchema(db)) {
+      migrations.push({ kind: "audit-events-v2", path: pathname });
+    }
+    if (tableExists(db, "audit_events") && userVersion < OPENCLAW_STATE_STRICT_SCHEMA_VERSION) {
+      migrations.push({ kind: "strict-tables-v3", path: pathname });
+    }
+    if (sessionWatchMigration.needsSessionWatchCursorProvenanceMigration(db, userVersion)) {
+      migrations.push({ kind: "session-watch-cursor-provenance-v4", path: pathname });
+    }
+    migrations.push(
+      ...operatorApprovalMigration.detectOperatorApprovalSchemaMigration(db, pathname),
+    );
+    return migrations;
+  } finally {
+    db.close();
+  }
+}
diff --git a/src/state/openclaw-state-db-startup-checkpoint.ts b/src/state/openclaw-state-db-startup-checkpoint.ts
new file mode 100644
index 00000000000..2e75ec2cee4
--- /dev/null
+++ b/src/state/openclaw-state-db-startup-checkpoint.ts
@@ -0,0 +1,80 @@
+import type { DatabaseSync } from "node:sqlite";
+import { requireNodeSqlite } from "../infra/node-sqlite.js";
+import { assertSqliteIntegrity } from "../infra/sqlite-integrity.js";
+import { runSqliteImmediateTransactionSync } from "../infra/sqlite-transaction.js";
+import {
+  OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
+  type OpenClawStateDatabaseOptions,
+} from "./openclaw-state-db-contract.js";
+import {
+  assertSupportedSchemaVersion,
+  resolveDatabasePath,
+} from "./openclaw-state-db-maintenance.js";
+import { ensureOpenClawStatePermissions } from "./openclaw-state-db-permissions.js";
+import { ensureColumn } from "./openclaw-state-db-schema-helpers.js";
+
+function ensureStartupMigrationCheckpointSchema(db: DatabaseSync, pathname: string): void {
+  runSqliteImmediateTransactionSync(
+    db,
+    () => {
+      assertSupportedSchemaVersion(db, pathname);
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS schema_meta (
+          meta_key TEXT NOT NULL PRIMARY KEY,
+          role TEXT NOT NULL,
+          schema_version INTEGER NOT NULL,
+          agent_id TEXT,
+          app_version TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS state_leases (
+          scope TEXT NOT NULL,
+          lease_key TEXT NOT NULL,
+          owner TEXT NOT NULL,
+          expires_at INTEGER,
+          heartbeat_at INTEGER,
+          payload_json TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL,
+          PRIMARY KEY (scope, lease_key)
+        );
+        CREATE INDEX IF NOT EXISTS idx_state_leases_expiry
+          ON state_leases(expires_at, scope, lease_key)
+          WHERE expires_at IS NOT NULL;
+        CREATE INDEX IF NOT EXISTS idx_state_leases_owner
+          ON state_leases(owner, updated_at DESC);
+      `);
+      ensureColumn(db, "schema_meta", "app_version TEXT");
+    },
+    {
+      busyTimeoutMs: OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
+      databaseLabel: pathname,
+      operationLabel: "state.schema.ensure-startup-checkpoint",
+    },
+  );
+}
+
+export function withOpenClawStateStartupMigrationCheckpointDatabase<T>(
+  callback: (db: DatabaseSync) => T,
+  options: OpenClawStateDatabaseOptions = {},
+): T {
+  const env = options.env ?? process.env;
+  const pathname = resolveDatabasePath(options);
+  ensureOpenClawStatePermissions(pathname, env);
+  const sqlite = requireNodeSqlite();
+  const db = new sqlite.DatabaseSync(pathname);
+  try {
+    assertSqliteIntegrity(db, pathname);
+    ensureStartupMigrationCheckpointSchema(db, pathname);
+    return callback(db);
+  } finally {
+    db.close();
+    ensureOpenClawStatePermissions(pathname, env);
+  }
+}
+
+// One-time seed for the ledger footprint aggregates (#100622): estimate rows
+// written before the estimated_bytes columns existed, then roll them up per
+// session. Zero is a safe "not seeded" sentinel because every real row costs
+// at least its 32-byte overhead.
diff --git a/src/state/openclaw-state-db.ts b/src/state/openclaw-state-db.ts
index f41892ac3db..015bf4819c4 100644
--- a/src/state/openclaw-state-db.ts
+++ b/src/state/openclaw-state-db.ts
@@ -1,17 +1,12 @@
 // OpenClaw state database manages shared persisted state and migrations.
-import { existsSync, mkdirSync } from "node:fs";
-import path from "node:path";
+import { existsSync } from "node:fs";
 import type { DatabaseSync } from "node:sqlite";
-import { buildApprovalResolutionRef } from "../infra/approval-resolution-ref.js";
-import { createDedupeCache } from "../infra/dedupe.js";
 import {
   clearNodeSqliteKyselyCacheForDatabase,
   executeSqliteQuerySync,
   getNodeSqliteKysely,
 } from "../infra/kysely-sync.js";
 import { requireNodeSqlite } from "../infra/node-sqlite.js";
-import { applyPrivateModeSync } from "../infra/private-mode.js";
-import { resolveSqliteDatabaseFilePaths } from "../infra/sqlite-files.js";
 import {
   repairCanonicalSqliteUniqueIndexes,
   type CanonicalSqliteUniqueIndex,
@@ -21,20 +16,13 @@ import {
   assertSqliteTableIntegrity,
   isTerminalSqliteIntegrityError,
 } from "../infra/sqlite-integrity.js";
-import {
-  assertSqliteSchemaContains,
-  type SqliteSchemaCompatibility,
-} from "../infra/sqlite-schema-contract.js";
 import { migrateSqliteSchemaToStrictInTransaction } from "../infra/sqlite-strict.js";
 import { createSqliteTerminalOpenLatch } from "../infra/sqlite-terminal-open-latch.js";
 import {
   runSqliteImmediateTransactionSync,
   type SqliteTransactionOptions,
 } from "../infra/sqlite-transaction.js";
-import {
-  createNewerSqliteSchemaVersionError,
-  readSqliteUserVersion,
-} from "../infra/sqlite-user-version.js";
+import { readSqliteUserVersion } from "../infra/sqlite-user-version.js";
 import {
   configureSqliteConnectionPragmas,
   configureSqlitePreSchemaPragmas,
@@ -47,21 +35,52 @@ import {
   clearOpenClawDatabaseQuarantine,
   readOpenClawDatabaseQuarantine,
 } from "./openclaw-quarantine-store.js";
+import { repairAuditEventsSchema } from "./openclaw-state-db-audit-migration.js";
+import {
+  OPENCLAW_DATABASE_SCHEMA_DOCS_URL,
+  OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
+  OPENCLAW_STATE_SCHEMA_VERSION,
+  OPENCLAW_STATE_STRICT_SCHEMA_VERSION,
+  type OpenClawStateDatabase,
+  type OpenClawStateDatabaseOptions,
+} from "./openclaw-state-db-contract.js";
+import {
+  assertSupportedSchemaVersion,
+  createOpenClawDatabaseVerificationError,
+  resolveDatabasePath,
+} from "./openclaw-state-db-maintenance.js";
 import * as operatorApprovalMigration from "./openclaw-state-db-operator-approval-migration.js";
+import { ensureOpenClawStatePermissions } from "./openclaw-state-db-permissions.js";
+import { ensureAdditiveStateColumns } from "./openclaw-state-db-schema-additive.js";
+import { tableExists } from "./openclaw-state-db-schema-helpers.js";
 import {
-  ensureColumn,
-  tableExists,
-  tableHasColumn,
-  tablePrimaryKeyColumns,
-} from "./openclaw-state-db-schema-helpers.js";
+  assertCanonicalStateSchemaShape,
+  dropLegacyStateTables,
+  markCurrentStateSchemaVersion,
+  repairAgentDatabasesCompositePrimaryKey,
+} from "./openclaw-state-db-schema-repair.js";
 import * as sessionWatchMigration from "./openclaw-state-db-session-watch-migration.js";
 import type { DB as OpenClawStateKyselyDatabase } from "./openclaw-state-db.generated.js";
-import {
-  resolveOpenClawStateSqliteDir,
-  resolveOpenClawStateSqlitePath,
-} from "./openclaw-state-db.paths.js";
 import { OPENCLAW_STATE_SCHEMA_SQL } from "./openclaw-state-schema.generated.js";
 
+export {
+  OPENCLAW_DATABASE_SCHEMA_DOCS_URL,
+  OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
+  OPENCLAW_STATE_SCHEMA_VERSION,
+};
+export type {
+  OpenClawStateDatabase,
+  OpenClawStateDatabaseOptions,
+  OpenClawStateDatabaseSchemaMigration,
+} from "./openclaw-state-db-contract.js";
+export {
+  assertOpenClawStateDatabaseForMaintenance,
+  createOpenClawDatabaseVerificationError,
+} from "./openclaw-state-db-maintenance.js";
+export { ensureOpenClawStatePermissions } from "./openclaw-state-db-permissions.js";
+export { detectOpenClawStateDatabaseSchemaMigrations } from "./openclaw-state-db-schema-repair.js";
+export { withOpenClawStateStartupMigrationCheckpointDatabase } from "./openclaw-state-db-startup-checkpoint.js";
+
 /**
  * Shared OpenClaw SQLite state database lifecycle and metadata writers.
  *
@@ -69,16 +88,6 @@ import { OPENCLAW_STATE_SCHEMA_SQL } from "./openclaw-state-schema.generated.js"
  * tables, private file permissions, cached handles, and audit rows for
  * migrations/backups that operate on local state.
  */
-// v4 replaces ambient session-watch sentinel rows with cursor provenance.
-export const OPENCLAW_STATE_SCHEMA_VERSION = 4;
-const OPENCLAW_STATE_STRICT_SCHEMA_VERSION = 3;
-/** Maximum time one synchronous SQLite call may wait for a lock. */
-export const OPENCLAW_SQLITE_BUSY_TIMEOUT_MS = 5_000;
-/** User-facing guide for schema refusals; lives here so error sites avoid import cycles. */
-export const OPENCLAW_DATABASE_SCHEMA_DOCS_URL =
-  "https://docs.openclaw.ai/reference/database-schemas";
-const OPENCLAW_STATE_DIR_MODE = 0o700;
-const OPENCLAW_STATE_FILE_MODE = 0o600;
 const OPENCLAW_STATE_CANONICAL_UNIQUE_INDEXES = [
   {
     name: "idx_operator_approvals_resolution_ref",
@@ -92,55 +101,7 @@ const OPENCLAW_STATE_CANONICAL_UNIQUE_INDEXES = [
     `,
   },
 ] as const satisfies readonly CanonicalSqliteUniqueIndex[];
-const OPENCLAW_STATE_MAINTENANCE_SCHEMA_COMPATIBILITY = {
-  allowedColumnDefinitions: {
-    "diagnostic_events.sequence": ["sequence INTEGER NOT NULL DEFAULT 0"],
-    "commitments.attempts": ["attempts INTEGER NOT NULL DEFAULT 0"],
-    "commitments.confidence": ["confidence REAL NOT NULL DEFAULT 0"],
-    "commitments.created_at_ms": ["created_at_ms INTEGER NOT NULL DEFAULT 0"],
-    "commitments.dedupe_key": ["dedupe_key TEXT NOT NULL DEFAULT ''"],
-    "commitments.due_timezone": ["due_timezone TEXT NOT NULL DEFAULT 'UTC'"],
-    "commitments.kind": ["kind TEXT NOT NULL DEFAULT 'followup'"],
-    "commitments.reason": ["reason TEXT NOT NULL DEFAULT ''"],
-    "commitments.sensitivity": ["sensitivity TEXT NOT NULL DEFAULT 'normal'"],
-    "commitments.source": ["source TEXT NOT NULL DEFAULT 'unknown'"],
-    "commitments.suggested_text": ["suggested_text TEXT NOT NULL DEFAULT ''"],
-    "cron_jobs.created_at_ms": ["created_at_ms INTEGER NOT NULL DEFAULT 0"],
-    "cron_jobs.enabled": ["enabled INTEGER NOT NULL DEFAULT 1"],
-    "cron_jobs.name": ["name TEXT NOT NULL DEFAULT ''"],
-    "cron_jobs.payload_kind": ["payload_kind TEXT NOT NULL DEFAULT 'message'"],
-    "cron_jobs.schedule_kind": ["schedule_kind TEXT NOT NULL DEFAULT 'manual'"],
-    "cron_jobs.session_target": ["session_target TEXT NOT NULL DEFAULT 'main'"],
-    "cron_jobs.wake_mode": ["wake_mode TEXT NOT NULL DEFAULT 'auto'"],
-    "current_conversation_bindings.conversation_kind": [
-      "conversation_kind TEXT NOT NULL DEFAULT 'channel'",
-    ],
-    "current_conversation_bindings.target_agent_id": [
-      "target_agent_id TEXT NOT NULL DEFAULT 'main'",
-    ],
-  },
-} satisfies SqliteSchemaCompatibility;
 
-/** Open shared SQLite database handle plus WAL maintenance lifecycle. */
-export type OpenClawStateDatabase = {
-  db: DatabaseSync;
-  path: string;
-  walMaintenance: SqliteWalMaintenance;
-};
-/** Options for resolving or overriding the shared state database path. */
-export type OpenClawStateDatabaseOptions = {
-  env?: NodeJS.ProcessEnv;
-  path?: string;
-};
-export type OpenClawStateDatabaseSchemaMigration = {
-  kind:
-    | "agent-databases-composite-primary-key"
-    | "audit-events-v2"
-    | "operator-approvals-system-agent"
-    | "session-watch-cursor-provenance-v4"
-    | "strict-tables-v3";
-  path: string;
-};
 const cachedDatabases = new Map<string, OpenClawStateDatabase>();
 const terminalOpenLatch = createSqliteTerminalOpenLatch({
   closeByPath: (pathname) => {
@@ -166,701 +127,10 @@ export function recordOpenClawStateDatabaseOpenFailure(pathname: string, error:
 export function clearOpenClawStateDatabaseOpenFailure(pathname: string): void {
   terminalOpenLatch.clear(pathname);
 }
-type OpenClawStateMetadataDatabase = Pick<OpenClawStateKyselyDatabase, "schema_meta">;
-
-/** Build the shared refusal used by state and agent database opens. */
-export function createOpenClawDatabaseVerificationError(
-  kind: "agent" | "state",
-  pathname: string,
-  storedError: string | null,
-): Error {
-  // Doctor's clearing hooks run after a full integrity assertion, so a still-
-  // corrupt file cannot be cleared directly: the file must be healthy first.
-  const error = new Error(
-    `OpenClaw ${kind} database ${pathname} is quarantined after integrity verification failed: ${storedError ?? "unknown integrity error"}. Restore the database from a backup or repair it, then run openclaw doctor --fix to clear the quarantine. See ${OPENCLAW_DATABASE_SCHEMA_DOCS_URL}.`,
-  );
-  error.name = "SqliteIntegrityError";
-  return error;
-}
-
-function assertSupportedSchemaVersion(db: DatabaseSync, pathname: string): void {
-  const userVersion = readSqliteUserVersion(db);
-  if (userVersion > OPENCLAW_STATE_SCHEMA_VERSION) {
-    throw createNewerSqliteSchemaVersionError(
-      "OpenClaw state database",
-      pathname,
-      userVersion,
-      OPENCLAW_STATE_SCHEMA_VERSION,
-    );
-  }
-}
-/** Require the canonical shared-state owner and schema before offline file maintenance. */
-export function assertOpenClawStateDatabaseForMaintenance(
-  database: DatabaseSync,
-  options: { pathname: string },
-): void {
-  const userVersion = readSqliteUserVersion(database);
-  if (userVersion > OPENCLAW_STATE_SCHEMA_VERSION) {
-    throw createNewerSqliteSchemaVersionError(
-      "OpenClaw state database",
-      options.pathname,
-      userVersion,
-      OPENCLAW_STATE_SCHEMA_VERSION,
-    );
-  }
-  if (userVersion !== OPENCLAW_STATE_SCHEMA_VERSION) {
-    throw new Error(
-      `OpenClaw state database ${options.pathname} uses schema version ${userVersion}; run openclaw doctor --fix before compacting it.`,
-    );
-  }
-
-  const metadata = database
-    .prepare("SELECT role, schema_version FROM schema_meta WHERE meta_key = 'primary' LIMIT 1")
-    .get() as { role?: unknown; schema_version?: unknown } | undefined;
-  if (metadata?.role !== "global") {
-    const role = typeof metadata?.role === "string" ? metadata.role : "missing";
-    throw new Error(
-      `OpenClaw state database ${options.pathname} has schema role ${role}; expected global.`,
-    );
-  }
-  if (metadata.schema_version !== OPENCLAW_STATE_SCHEMA_VERSION) {
-    const schemaVersion =
-      typeof metadata.schema_version === "number" ? metadata.schema_version : "invalid";
-    throw new Error(
-      `OpenClaw state database ${options.pathname} metadata schema version ${schemaVersion} does not match ${OPENCLAW_STATE_SCHEMA_VERSION}; run openclaw doctor --fix before compacting it.`,
-    );
-  }
-  assertSqliteSchemaContains(
-    database,
-    options.pathname,
-    OPENCLAW_STATE_SCHEMA_SQL,
-    OPENCLAW_STATE_MAINTENANCE_SCHEMA_COMPATIBILITY,
-  );
-}
 
+type OpenClawStateMetadataDatabase = Pick<OpenClawStateKyselyDatabase, "schema_meta">;
 const stateDbLog = createSubsystemLogger("state/db");
 
-/** Targets already warned about, so chmod-less filesystems warn once per path. */
-const chmodWarnedTargets = createDedupeCache({
-  ttlMs: 0,
-  maxSize: 4096,
-});
-
-// Permission hardening is best-effort only on filesystems that cannot apply
-// it: the database stays usable without the chmod, and crashing at open would
-// take the gateway down on Azure Files/NFS/Docker volumes (#91919). Unexpected
-// chmod failures still throw so credentials-adjacent hardening stays loud.
-function bestEffortChmodSync(target: string, mode: number): void {
-  const result = applyPrivateModeSync(target, mode);
-  if (result.applied || chmodWarnedTargets.check(target)) {
-    return;
-  }
-  stateDbLog.warn(`skipped permission hardening for ${target}: ${String(result.error)}`);
-}
-
-export function ensureOpenClawStatePermissions(pathname: string, env: NodeJS.ProcessEnv): void {
-  const dir = path.dirname(pathname);
-  const defaultDir = resolveOpenClawStateSqliteDir(env);
-  const isDefaultStateDatabase =
-    path.resolve(pathname) === path.resolve(resolveOpenClawStateSqlitePath(env));
-  if (isDefaultStateDatabase && dir !== defaultDir) {
-    throw new Error(`OpenClaw state database path resolved outside its state dir: ${pathname}`);
-  }
-  const dirExisted = existsSync(dir);
-  mkdirSync(dir, { recursive: true, mode: OPENCLAW_STATE_DIR_MODE });
-  // Default state contains credentials-adjacent metadata; custom existing dirs keep caller modes.
-  if (isDefaultStateDatabase || !dirExisted) {
-    bestEffortChmodSync(dir, OPENCLAW_STATE_DIR_MODE);
-  }
-  for (const candidate of resolveSqliteDatabaseFilePaths(pathname)) {
-    if (existsSync(candidate)) {
-      bestEffortChmodSync(candidate, OPENCLAW_STATE_FILE_MODE);
-    }
-  }
-}
-
-function ensureOperatorApprovalResolutionRefs(db: DatabaseSync): void {
-  if (!tableExists(db, "operator_approvals")) {
-    return;
-  }
-  runSqliteImmediateTransactionSync(db, () => {
-    ensureColumn(db, "operator_approvals", "resolution_ref TEXT");
-    const rows = db
-      .prepare("SELECT approval_id, kind, resolution_ref FROM operator_approvals")
-      .all() as Array<{
-      approval_id?: unknown;
-      kind?: unknown;
-      resolution_ref?: unknown;
-    }>;
-    const update = db.prepare(
-      "UPDATE operator_approvals SET resolution_ref = ? WHERE approval_id = ?",
-    );
-    for (const row of rows) {
-      if (
-        typeof row.approval_id !== "string" ||
-        !operatorApprovalMigration.isCanonicalOperatorApprovalKind(row.kind)
-      ) {
-        throw new Error("operator approval row cannot be assigned a transport reference");
-      }
-      const resolutionRef = buildApprovalResolutionRef({
-        approvalId: row.approval_id,
-        approvalKind: row.kind,
-      });
-      if (row.resolution_ref !== resolutionRef) {
-        update.run(resolutionRef, row.approval_id);
-      }
-    }
-    const namespaceConflict = db
-      .prepare(
-        `SELECT canonical.approval_id
-         FROM operator_approvals AS canonical
-         JOIN operator_approvals AS referenced
-           ON canonical.approval_id = referenced.resolution_ref
-         WHERE canonical.approval_id <> referenced.approval_id
-         LIMIT 1`,
-      )
-      .get();
-    if (namespaceConflict) {
-      throw new Error("operator approval ids conflict with durable transport references");
-    }
-    db.exec(`
-      CREATE UNIQUE INDEX IF NOT EXISTS idx_operator_approvals_resolution_ref
-        ON operator_approvals(resolution_ref);
-    `);
-  });
-}
-
-function repairLegacyTaskAgentAttribution(db: DatabaseSync): void {
-  if (!tableExists(db, "task_runs") || !tableHasColumn(db, "task_runs", "requester_agent_id")) {
-    return;
-  }
-  // Before requester_agent_id existed, scoped subagent/ACP rows stored the
-  // requester in agent_id. Repair only rows with recoverable requester
-  // provenance; global legacy rows must keep the existing fallback behavior.
-  db.exec(`
-    UPDATE task_runs
-    SET
-      requester_agent_id = CASE
-        WHEN owner_key GLOB 'agent:*:*' THEN substr(
-          owner_key,
-          7,
-          instr(substr(owner_key, 7), ':') - 1
-        )
-        WHEN requester_session_key GLOB 'agent:*:*' THEN substr(
-          requester_session_key,
-          7,
-          instr(substr(requester_session_key, 7), ':') - 1
-        )
-        WHEN agent_id <> substr(
-          child_session_key,
-          7,
-          instr(substr(child_session_key, 7), ':') - 1
-        ) THEN agent_id
-        ELSE NULL
-      END,
-      agent_id = substr(
-        child_session_key,
-        7,
-        instr(substr(child_session_key, 7), ':') - 1
-      )
-    WHERE requester_agent_id IS NULL
-      AND runtime IN ('subagent', 'acp')
-      AND child_session_key GLOB 'agent:*:*'
-      AND instr(substr(child_session_key, 7), ':') > 1
-      AND (
-        owner_key GLOB 'agent:*:*'
-        OR requester_session_key GLOB 'agent:*:*'
-        OR (
-          agent_id IS NOT NULL
-          AND agent_id <> substr(
-            child_session_key,
-            7,
-            instr(substr(child_session_key, 7), ':') - 1
-          )
-        )
-      );
-  `);
-}
-
-function repairLegacyTaskDeliveryStatuses(db: DatabaseSync): void {
-  if (!tableExists(db, "task_runs") || !tableHasColumn(db, "task_runs", "delivery_status")) {
-    return;
-  }
-  // Successful sidecar imports archive their source, so database open must
-  // also canonicalize rows already copied by released migrations.
-  db.exec(`
-    UPDATE task_runs
-    SET delivery_status = 'not_applicable'
-    WHERE delivery_status = 'not-requested';
-  `);
-}
-
-function dropLegacyStateTables(db: DatabaseSync): void {
-  // Unreleased transient history; drop, do not migrate.
-  const transientHistoryTable = ["database", "verifications"].join("_");
-  db.exec(`DROP TABLE IF EXISTS ${transientHistoryTable};`);
-  // Retired node pairing tables never had a shipped writer.
-  db.exec("DROP TABLE IF EXISTS node_pairing_pending; DROP TABLE IF EXISTS node_pairing_paired;");
-}
-
-function hasCanonicalAgentDatabasesPrimaryKey(db: DatabaseSync): boolean {
-  if (!tableExists(db, "agent_databases")) {
-    return true;
-  }
-  const primaryKey = tablePrimaryKeyColumns(db, "agent_databases");
-  return primaryKey.length === 2 && primaryKey[0] === "agent_id" && primaryKey[1] === "path";
-}
-
-function canRepairAgentDatabasesPrimaryKey(db: DatabaseSync): boolean {
-  if (!tableExists(db, "agent_databases")) {
-    return false;
-  }
-  const requiredColumns = ["agent_id", "path", "schema_version", "last_seen_at", "size_bytes"];
-  return requiredColumns.every((column) => tableHasColumn(db, "agent_databases", column));
-}
-
-function repairAgentDatabasesCompositePrimaryKey(db: DatabaseSync): boolean {
-  if (hasCanonicalAgentDatabasesPrimaryKey(db) || !canRepairAgentDatabasesPrimaryKey(db)) {
-    return false;
-  }
-  // Released DBs may have PRIMARY KEY(agent_id); current registration upserts by
-  // (agent_id,path) so explicit relocated agent DBs do not overwrite each other.
-  db.exec(`
-    DROP TABLE IF EXISTS agent_databases_migration_new;
-    CREATE TABLE agent_databases_migration_new (
-      agent_id TEXT NOT NULL,
-      path TEXT NOT NULL,
-      schema_version INTEGER NOT NULL,
-      last_seen_at INTEGER NOT NULL,
-      size_bytes INTEGER,
-      PRIMARY KEY (agent_id, path)
-    );
-    INSERT OR REPLACE INTO agent_databases_migration_new (
-      agent_id,
-      path,
-      schema_version,
-      last_seen_at,
-      size_bytes
-    )
-    SELECT
-      agent_id,
-      path,
-      schema_version,
-      last_seen_at,
-      size_bytes
-    FROM agent_databases
-    WHERE agent_id IS NOT NULL AND path IS NOT NULL;
-    DROP TABLE agent_databases;
-    ALTER TABLE agent_databases_migration_new RENAME TO agent_databases;
-  `);
-  return true;
-}
-
-const AUDIT_EVENT_STATE_SCHEMA_VERSION = 2;
-
-const AUDIT_EVENT_LEGACY_COLUMNS = [
-  "sequence",
-  "event_id",
-  "source_id",
-  "source_sequence",
-  "occurred_at",
-  "kind",
-  "action",
-  "status",
-  "error_code",
-  "actor_type",
-  "actor_id",
-  "agent_id",
-  "session_key",
-  "session_id",
-  "run_id",
-  "tool_call_id",
-  "tool_name",
-] as const;
-
-const AUDIT_EVENT_V2_COLUMNS = [
-  "sequence",
-  "event_id",
-  "source_id",
-  "schema_version",
-  "source_sequence",
-  "occurred_at",
-  "kind",
-  "action",
-  "status",
-  "error_code",
-  "actor_type",
-  "actor_id",
-  "agent_id",
-  "session_key",
-  "session_id",
-  "run_id",
-  "tool_call_id",
-  "tool_name",
-  "direction",
-  "channel",
-  "conversation_kind",
-  "message_outcome",
-  "reason_code",
-  "delivery_kind",
-  "failure_stage",
-  "duration_ms",
-  "result_count",
-  "account_ref",
-  "conversation_ref",
-  "message_ref",
-  "target_ref",
-] as const;
-
-type TableColumnInfo = {
-  name?: unknown;
-  notnull?: unknown;
-  pk?: unknown;
-};
-
-function tableColumnInfo(db: DatabaseSync, tableName: string): TableColumnInfo[] {
-  return db.prepare(`PRAGMA table_info(${tableName})`).all() as TableColumnInfo[];
-}
-
-function tableHasExactColumns(
-  db: DatabaseSync,
-  tableName: string,
-  expected: readonly string[],
-): boolean {
-  const names = tableColumnInfo(db, tableName).map((column) => column.name);
-  return names.length === expected.length && names.every((name, index) => name === expected[index]);
-}
-
-function tableHasRequiredColumns(
-  db: DatabaseSync,
-  tableName: string,
-  required: readonly string[],
-): boolean {
-  const columns = new Map(tableColumnInfo(db, tableName).map((column) => [column.name, column]));
-  return required.every((name) => Number(columns.get(name)?.notnull ?? 0) === 1);
-}
-
-function tableSql(db: DatabaseSync, tableName: string): string | undefined {
-  const row = db
-    .prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?")
-    .get(tableName) as { sql?: unknown } | undefined;
-  return typeof row?.sql === "string" ? row.sql : undefined;
-}
-
-function tableHasUniqueColumn(db: DatabaseSync, tableName: string, columnName: string): boolean {
-  const indexes = db.prepare(`PRAGMA index_list(${tableName})`).all() as Array<{
-    name?: unknown;
-    unique?: unknown;
-  }>;
-  return indexes.some((index) => {
-    if (Number(index.unique ?? 0) !== 1 || typeof index.name !== "string") {
-      return false;
-    }
-    const escaped = index.name.replaceAll("'", "''");
-    const columns = db.prepare(`PRAGMA index_info('${escaped}')`).all() as Array<{
-      name?: unknown;
-    }>;
-    return columns.length === 1 && columns[0]?.name === columnName;
-  });
-}
-
-function hasCanonicalAuditEventTable(
-  db: DatabaseSync,
-  expectedColumns: readonly string[],
-  requiredColumns: readonly string[],
-): boolean {
-  const sql = tableSql(db, "audit_events")?.toLowerCase();
-  return (
-    tableHasExactColumns(db, "audit_events", expectedColumns) &&
-    tablePrimaryKeyColumns(db, "audit_events").join(",") === "sequence" &&
-    tableHasRequiredColumns(db, "audit_events", requiredColumns) &&
-    typeof sql === "string" &&
-    /\bsequence\s+integer\s+primary\s+key\s+autoincrement\b/.test(sql) &&
-    tableHasUniqueColumn(db, "audit_events", "event_id") &&
-    tableHasUniqueColumn(db, "audit_events", "source_id")
-  );
-}
-
-function hasCanonicalAuditIdentityKeyTable(db: DatabaseSync): boolean {
-  if (!tableExists(db, "audit_identity_keys")) {
-    return false;
-  }
-  const sql = tableSql(db, "audit_identity_keys")?.toLowerCase();
-  return (
-    tableHasExactColumns(db, "audit_identity_keys", ["id", "key_id", "key", "created_at"]) &&
-    tablePrimaryKeyColumns(db, "audit_identity_keys").join(",") === "id" &&
-    tableHasRequiredColumns(db, "audit_identity_keys", ["id", "key_id", "key", "created_at"]) &&
-    typeof sql === "string" &&
-    /\bcheck\s*\(\s*id\s*=\s*1\s*\)/.test(sql)
-  );
-}
-
-function hasCanonicalAuditEventsSchema(db: DatabaseSync): boolean {
-  if (!tableExists(db, "audit_events")) {
-    return (
-      readSqliteUserVersion(db) < AUDIT_EVENT_STATE_SCHEMA_VERSION &&
-      !tableExists(db, "audit_identity_keys")
-    );
-  }
-  return (
-    hasCanonicalAuditEventTable(db, AUDIT_EVENT_V2_COLUMNS, [
-      "event_id",
-      "source_id",
-      "schema_version",
-      "source_sequence",
-      "occurred_at",
-      "kind",
-      "action",
-      "status",
-      "actor_type",
-      "actor_id",
-    ]) && hasCanonicalAuditIdentityKeyTable(db)
-  );
-}
-
-function canRepairLegacyAuditEventsSchema(db: DatabaseSync): boolean {
-  // Our own transactional repair cannot leave audit_events_migration_new
-  // behind, so an existing one is foreign data; fail closed rather than let
-  // repair silently drop it.
-  if (
-    !tableExists(db, "audit_events") ||
-    tableExists(db, "audit_events_migration_new") ||
-    tableHasColumn(db, "audit_events", "schema_version")
-  ) {
-    return false;
-  }
-  const identityTableIsSafe =
-    !tableExists(db, "audit_identity_keys") || hasCanonicalAuditIdentityKeyTable(db);
-  return (
-    identityTableIsSafe &&
-    hasCanonicalAuditEventTable(db, AUDIT_EVENT_LEGACY_COLUMNS, [
-      "event_id",
-      "source_id",
-      "source_sequence",
-      "occurred_at",
-      "kind",
-      "action",
-      "status",
-      "actor_type",
-      "actor_id",
-      "agent_id",
-      "run_id",
-    ])
-  );
-}
-
-function readAuditEventSequenceHighWater(db: DatabaseSync): number | undefined {
-  if (!tableExists(db, "sqlite_sequence")) {
-    return undefined;
-  }
-  const row = db
-    .prepare("SELECT CAST(seq AS TEXT) AS seq FROM sqlite_sequence WHERE name = 'audit_events'")
-    .get() as { seq?: unknown } | undefined;
-  if (row === undefined) {
-    return undefined;
-  }
-  if (typeof row.seq !== "string" || !/^\d+$/.test(row.seq)) {
-    throw new Error("audit event sequence high-water mark is invalid");
-  }
-  const sequence = BigInt(row.seq);
-  if (sequence > BigInt(Number.MAX_SAFE_INTEGER)) {
-    throw new Error("audit event sequence high-water mark exceeds the supported integer range");
-  }
-  return Number(sequence);
-}
-
-function restoreAuditEventSequenceHighWater(db: DatabaseSync, sequence: number | undefined): void {
-  if (sequence === undefined) {
-    return;
-  }
-  db.prepare("DELETE FROM sqlite_sequence WHERE name = 'audit_events'").run();
-  db.prepare("INSERT INTO sqlite_sequence (name, seq) VALUES ('audit_events', ?)").run(sequence);
-}
-
-function repairAuditEventsSchema(db: DatabaseSync): boolean {
-  if (hasCanonicalAuditEventsSchema(db) || !canRepairLegacyAuditEventsSchema(db)) {
-    return false;
-  }
-  const sequenceHighWater = readAuditEventSequenceHighWater(db);
-  // This is the only shipped legacy shape. The surrounding doctor transaction
-  // rolls back the table swap and sequence restore together on any bad row.
-  // canRepairLegacyAuditEventsSchema refuses foreign audit_events_migration_new
-  // tables, so this CREATE never clobbers existing data.
-  db.exec(`
-    CREATE TABLE audit_events_migration_new (
-      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
-      event_id TEXT NOT NULL UNIQUE,
-      source_id TEXT NOT NULL UNIQUE,
-      schema_version INTEGER NOT NULL DEFAULT 1,
-      source_sequence INTEGER NOT NULL,
-      occurred_at INTEGER NOT NULL,
-      kind TEXT NOT NULL,
-      action TEXT NOT NULL,
-      status TEXT NOT NULL,
-      error_code TEXT,
-      actor_type TEXT NOT NULL,
-      actor_id TEXT NOT NULL,
-      agent_id TEXT,
-      session_key TEXT,
-      session_id TEXT,
-      run_id TEXT,
-      tool_call_id TEXT,
-      tool_name TEXT,
-      direction TEXT,
-      channel TEXT,
-      conversation_kind TEXT,
-      message_outcome TEXT,
-      reason_code TEXT,
-      delivery_kind TEXT,
-      failure_stage TEXT,
-      duration_ms INTEGER,
-      result_count INTEGER,
-      account_ref TEXT,
-      conversation_ref TEXT,
-      message_ref TEXT,
-      target_ref TEXT
-    );
-    INSERT INTO audit_events_migration_new (
-      sequence,
-      event_id,
-      source_id,
-      schema_version,
-      source_sequence,
-      occurred_at,
-      kind,
-      action,
-      status,
-      error_code,
-      actor_type,
-      actor_id,
-      agent_id,
-      session_key,
-      session_id,
-      run_id,
-      tool_call_id,
-      tool_name
-    )
-    SELECT
-      sequence,
-      event_id,
-      source_id,
-      1,
-      source_sequence,
-      occurred_at,
-      kind,
-      action,
-      status,
-      error_code,
-      actor_type,
-      actor_id,
-      agent_id,
-      session_key,
-      session_id,
-      run_id,
-      tool_call_id,
-      tool_name
-    FROM audit_events;
-    DROP TABLE audit_events;
-    ALTER TABLE audit_events_migration_new RENAME TO audit_events;
-    CREATE INDEX idx_audit_events_time
-      ON audit_events(occurred_at DESC, sequence DESC);
-    CREATE INDEX idx_audit_events_agent_sequence
-      ON audit_events(agent_id, sequence DESC);
-    CREATE INDEX idx_audit_events_session_sequence
-      ON audit_events(session_key, sequence DESC);
-    CREATE INDEX idx_audit_events_run_sequence
-      ON audit_events(run_id, sequence DESC);
-    CREATE INDEX idx_audit_events_kind_sequence
-      ON audit_events(kind, sequence DESC);
-    CREATE INDEX idx_audit_events_status_sequence
-      ON audit_events(status, sequence DESC);
-    CREATE INDEX idx_audit_events_channel_sequence
-      ON audit_events(channel, sequence DESC);
-    CREATE INDEX idx_audit_events_direction_sequence
-      ON audit_events(direction, sequence DESC);
-    CREATE TABLE IF NOT EXISTS audit_identity_keys (
-      id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
-      key_id TEXT NOT NULL,
-      key BLOB NOT NULL,
-      created_at INTEGER NOT NULL
-    );
-  `);
-  // AUTOINCREMENT is part of the stable cursor contract. Rebuilding an empty
-  // or sparsely retained table must not reuse a sequence already handed out.
-  restoreAuditEventSequenceHighWater(db, sequenceHighWater);
-  return true;
-}
-
-function markCurrentStateSchemaVersion(db: DatabaseSync): void {
-  // Pre-v2 databases can legitimately predate the audit table. Leave their
-  // version untouched so normal open can create the complete v2 schema first.
-  if (!tableExists(db, "audit_events")) {
-    return;
-  }
-  db.exec(`PRAGMA user_version = ${OPENCLAW_STATE_SCHEMA_VERSION};`);
-  if (
-    tableExists(db, "schema_meta") &&
-    ["meta_key", "schema_version", "updated_at"].every((column) =>
-      tableHasColumn(db, "schema_meta", column),
-    )
-  ) {
-    db.prepare(
-      "UPDATE schema_meta SET schema_version = ?, updated_at = ? WHERE meta_key = 'primary'",
-    ).run(OPENCLAW_STATE_SCHEMA_VERSION, Date.now());
-  }
-}
-
-function assertCanonicalStateSchemaShape(db: DatabaseSync, pathname: string): void {
-  operatorApprovalMigration.assertCanonicalOperatorApprovalKinds(db, pathname);
-  if (!hasCanonicalAgentDatabasesPrimaryKey(db)) {
-    throw new Error(
-      `OpenClaw state database ${pathname} has a legacy agent database registry schema; run openclaw doctor --fix to migrate it.`,
-    );
-  }
-  if (!hasCanonicalAuditEventsSchema(db)) {
-    if (canRepairLegacyAuditEventsSchema(db)) {
-      throw new Error(
-        `OpenClaw state database ${pathname} has a legacy audit event schema; run openclaw doctor --fix to migrate it.`,
-      );
-    }
-    throw new Error(
-      `OpenClaw state database ${pathname} has a noncanonical audit event schema that cannot be repaired automatically; restore the canonical audit_events shape before retrying.`,
-    );
-  }
-}
-export function detectOpenClawStateDatabaseSchemaMigrations(
-  options: OpenClawStateDatabaseOptions = {},
-): OpenClawStateDatabaseSchemaMigration[] {
-  const pathname = resolveDatabasePath(options);
-  if (!existsSync(pathname)) {
-    return [];
-  }
-  const sqlite = requireNodeSqlite();
-  const db = new sqlite.DatabaseSync(pathname, { readOnly: true });
-  try {
-    const migrations: OpenClawStateDatabaseSchemaMigration[] = [];
-    const userVersion = readSqliteUserVersion(db);
-    if (!hasCanonicalAgentDatabasesPrimaryKey(db)) {
-      migrations.push({ kind: "agent-databases-composite-primary-key", path: pathname });
-    }
-    if (!hasCanonicalAuditEventsSchema(db)) {
-      migrations.push({ kind: "audit-events-v2", path: pathname });
-    }
-    if (tableExists(db, "audit_events") && userVersion < OPENCLAW_STATE_STRICT_SCHEMA_VERSION) {
-      migrations.push({ kind: "strict-tables-v3", path: pathname });
-    }
-    if (sessionWatchMigration.needsSessionWatchCursorProvenanceMigration(db, userVersion)) {
-      migrations.push({ kind: "session-watch-cursor-provenance-v4", path: pathname });
-    }
-    migrations.push(
-      ...operatorApprovalMigration.detectOperatorApprovalSchemaMigration(db, pathname),
-    );
-    return migrations;
-  } finally {
-    db.close();
-  }
-}
-
 export function repairOpenClawStateDatabaseSchema(options: OpenClawStateDatabaseOptions = {}): {
   changes: string[];
   warnings: string[];
@@ -954,742 +224,6 @@ export function repairOpenClawStateDatabaseSchema(options: OpenClawStateDatabase
   }
 }
 
-function ensureStartupMigrationCheckpointSchema(db: DatabaseSync, pathname: string): void {
-  runSqliteImmediateTransactionSync(
-    db,
-    () => {
-      assertSupportedSchemaVersion(db, pathname);
-      db.exec(`
-        CREATE TABLE IF NOT EXISTS schema_meta (
-          meta_key TEXT NOT NULL PRIMARY KEY,
-          role TEXT NOT NULL,
-          schema_version INTEGER NOT NULL,
-          agent_id TEXT,
-          app_version TEXT,
-          created_at INTEGER NOT NULL,
-          updated_at INTEGER NOT NULL
-        );
-        CREATE TABLE IF NOT EXISTS state_leases (
-          scope TEXT NOT NULL,
-          lease_key TEXT NOT NULL,
-          owner TEXT NOT NULL,
-          expires_at INTEGER,
-          heartbeat_at INTEGER,
-          payload_json TEXT,
-          created_at INTEGER NOT NULL,
-          updated_at INTEGER NOT NULL,
-          PRIMARY KEY (scope, lease_key)
-        );
-        CREATE INDEX IF NOT EXISTS idx_state_leases_expiry
-          ON state_leases(expires_at, scope, lease_key)
-          WHERE expires_at IS NOT NULL;
-        CREATE INDEX IF NOT EXISTS idx_state_leases_owner
-          ON state_leases(owner, updated_at DESC);
-      `);
-      ensureColumn(db, "schema_meta", "app_version TEXT");
-    },
-    {
-      busyTimeoutMs: OPENCLAW_SQLITE_BUSY_TIMEOUT_MS,
-      databaseLabel: pathname,
-      operationLabel: "state.schema.ensure-startup-checkpoint",
-    },
-  );
-}
-
-export function withOpenClawStateStartupMigrationCheckpointDatabase<T>(
-  callback: (db: DatabaseSync) => T,
-  options: OpenClawStateDatabaseOptions = {},
-): T {
-  const env = options.env ?? process.env;
-  const pathname = resolveDatabasePath(options);
-  ensureOpenClawStatePermissions(pathname, env);
-  const sqlite = requireNodeSqlite();
-  const db = new sqlite.DatabaseSync(pathname);
-  try {
-    assertSqliteIntegrity(db, pathname);
-    ensureStartupMigrationCheckpointSchema(db, pathname);
-    return callback(db);
-  } finally {
-    db.close();
-    ensureOpenClawStatePermissions(pathname, env);
-  }
-}
-
-// One-time seed for the ledger footprint aggregates (#100622): estimate rows
-// written before the estimated_bytes columns existed, then roll them up per
-// session. Zero is a safe "not seeded" sentinel because every real row costs
-// at least its 32-byte overhead.
-function backfillAcpReplayEstimatedBytes(db: DatabaseSync): void {
-  if (
-    !tableExists(db, "acp_replay_events") ||
-    !tableHasColumn(db, "acp_replay_events", "estimated_bytes")
-  ) {
-    return;
-  }
-  const pendingEvent = db
-    .prepare("SELECT 1 FROM acp_replay_events WHERE estimated_bytes = 0 LIMIT 1")
-    .get();
-  const pendingSession = db
-    .prepare("SELECT 1 FROM acp_replay_sessions WHERE estimated_bytes = 0 LIMIT 1")
-    .get();
-  if (!pendingEvent && !pendingSession) {
-    return;
-  }
-  db.exec(`
-    UPDATE acp_replay_events
-       SET estimated_bytes = length(session_id) + length(session_key) + length(update_json)
-             + COALESCE(length(run_id), 0) + 32
-     WHERE estimated_bytes = 0;
-    UPDATE acp_replay_sessions
-       SET estimated_bytes = length(session_id) + length(session_key) + length(cwd) + 32
-             + COALESCE((SELECT SUM(e.estimated_bytes) FROM acp_replay_events e
-                          WHERE e.session_id = acp_replay_sessions.session_id), 0)
-     WHERE estimated_bytes = 0;
-  `);
-}
-
-function backfillCronRunLogEntryJson(db: DatabaseSync): void {
-  if (!tableExists(db, "cron_run_logs") || !tableHasColumn(db, "cron_run_logs", "entry_json")) {
-    return;
-  }
-  const rows = db
-    .prepare(
-      `SELECT store_key, job_id, seq, ts
-         FROM cron_run_logs
-        WHERE entry_json = '{}'`,
-    )
-    .all() as Array<{
-    store_key: string;
-    job_id: string;
-    seq: number | bigint;
-    ts: number | bigint;
-  }>;
-  if (rows.length === 0) {
-    return;
-  }
-  const update = db.prepare(
-    `UPDATE cron_run_logs
-        SET entry_json = ?
-      WHERE store_key = ? AND job_id = ? AND seq = ?`,
-  );
-  for (const row of rows) {
-    update.run(
-      JSON.stringify({ ts: Number(row.ts), jobId: row.job_id, action: "finished" }),
-      row.store_key,
-      row.job_id,
-      row.seq,
-    );
-  }
-}
-
-function parseJsonRecord(value: string): Record<string, unknown> | null {
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function textField(record: Record<string, unknown>, key: string): string | null {
-  const value = record[key];
-  return typeof value === "string" && value.trim() ? value : null;
-}
-
-function numberField(record: Record<string, unknown>, key: string): number | null {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function recordField(record: Record<string, unknown>, key: string): Record<string, unknown> | null {
-  const value = record[key];
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-function jsonField(value: unknown): string | null {
-  return value === undefined ? null : JSON.stringify(value);
-}
-
-function cronSessionTargetField(record: Record<string, unknown>): string | null {
-  const value = textField(record, "sessionTarget");
-  if (!value) {
-    return null;
-  }
-  return value === "main" ||
-    value === "isolated" ||
-    value === "current" ||
-    value.startsWith("session:")
-    ? value
-    : null;
-}
-
-function cronWakeModeField(record: Record<string, unknown>): string | null {
-  const value = textField(record, "wakeMode");
-  return value === "now" || value === "next-heartbeat" ? value : null;
-}
-
-function booleanField(record: Record<string, unknown>, key: string): number | null {
-  const value = record[key];
-  return typeof value === "boolean" ? (value ? 1 : 0) : null;
-}
-
-function failureDestinationField(
-  record: Record<string, unknown> | null,
-  key: "accountId" | "channel" | "mode" | "to",
-): string | null {
-  if (!record || !Object.hasOwn(record, key)) {
-    return null;
-  }
-  const value = record[key];
-  return typeof value === "string" && value.trim() ? value : "";
-}
-
-function migrateLegacyCronDeliveryThreadIds(db: DatabaseSync): void {
-  const rows = db
-    .prepare(
-      `SELECT store_key, job_id, job_json, delivery_thread_id
-         FROM cron_jobs
-        WHERE delivery_thread_id_type IS NULL`,
-    )
-    .all() as Array<{
-    store_key: string;
-    job_id: string;
-    job_json: string;
-    delivery_thread_id: string | null;
-  }>;
-  const update = db.prepare(
-    `UPDATE cron_jobs
-        SET delivery_thread_id = ?, delivery_thread_id_type = ?
-      WHERE store_key = ? AND job_id = ? AND delivery_thread_id_type IS NULL`,
-  );
-  for (const row of rows) {
-    const job = parseJsonRecord(row.job_json);
-    const delivery = job ? recordField(job, "delivery") : null;
-    const typed = delivery?.threadId;
-    if (row.delivery_thread_id === null) {
-      // The first normalized cron migration could not project numeric thread IDs.
-      // Recover only that known lost shape while this type column is first added.
-      if (typeof typed === "number" && Number.isFinite(typed)) {
-        update.run(String(typed), "number", row.store_key, row.job_id);
-      }
-      continue;
-    }
-    const type =
-      typeof typed === "number" &&
-      Number.isFinite(typed) &&
-      String(typed) === row.delivery_thread_id
-        ? "number"
-        : "string";
-    update.run(row.delivery_thread_id, type, row.store_key, row.job_id);
-  }
-}
-
-function backfillCronJobsFromJobJson(db: DatabaseSync): void {
-  if (
-    !tableExists(db, "cron_jobs") ||
-    !tableHasColumn(db, "cron_jobs", "job_json") ||
-    !tableHasColumn(db, "cron_jobs", "schedule_kind") ||
-    !tableHasColumn(db, "cron_jobs", "payload_kind")
-  ) {
-    return;
-  }
-  const rows = db
-    .prepare(
-      `SELECT store_key, job_id, job_json, updated_at
-         FROM cron_jobs
-        WHERE schedule_kind = 'manual'
-           OR payload_kind = 'message'
-           OR name = ''`,
-    )
-    .all() as Array<{
-    store_key: string;
-    job_id: string;
-    job_json: string;
-    updated_at: number | bigint;
-  }>;
-  if (rows.length === 0) {
-    return;
-  }
-  const update = db.prepare(
-    `UPDATE cron_jobs
-        SET name = ?,
-            enabled = ?,
-            delete_after_run = ?,
-            created_at_ms = ?,
-            agent_id = ?,
-            session_key = ?,
-            schedule_kind = ?,
-            schedule_expr = ?,
-            schedule_tz = ?,
-            every_ms = ?,
-            anchor_ms = ?,
-            at = ?,
-            stagger_ms = ?,
-            session_target = ?,
-            wake_mode = ?,
-            payload_kind = ?,
-            payload_message = ?,
-            payload_model = ?,
-            payload_fallbacks_json = ?,
-            payload_thinking = ?,
-            payload_timeout_seconds = ?,
-            payload_allow_unsafe_external_content = ?,
-            payload_external_content_source_json = ?,
-            payload_light_context = ?,
-            payload_tools_allow_json = ?,
-            delivery_mode = ?,
-            delivery_channel = ?,
-            delivery_to = ?,
-            delivery_thread_id = ?,
-            delivery_account_id = ?,
-            delivery_best_effort = ?,
-            delivery_completion_mode = ?,
-            delivery_completion_to = ?,
-            failure_delivery_mode = ?,
-            failure_delivery_channel = ?,
-            failure_delivery_to = ?,
-            failure_delivery_account_id = ?,
-            failure_alert_disabled = ?,
-            failure_alert_after = ?,
-            failure_alert_channel = ?,
-            failure_alert_to = ?,
-            failure_alert_cooldown_ms = ?,
-            failure_alert_include_skipped = ?,
-            failure_alert_mode = ?,
-            failure_alert_account_id = ?,
-            runtime_updated_at_ms = ?
-      WHERE store_key = ?
-        AND job_id = ?`,
-  );
-  for (const row of rows) {
-    const job = parseJsonRecord(row.job_json);
-    if (!job) {
-      continue;
-    }
-    // Legacy cron rows kept the contract in job_json; columns are a queryable projection of it.
-    const schedule = recordField(job, "schedule");
-    const payload = recordField(job, "payload");
-    const scheduleKind = textField(schedule ?? {}, "kind");
-    const payloadKind = textField(payload ?? {}, "kind");
-    const isAt = scheduleKind === "at" && textField(schedule ?? {}, "at");
-    const isEvery = scheduleKind === "every" && numberField(schedule ?? {}, "everyMs") != null;
-    const isCron = scheduleKind === "cron" && textField(schedule ?? {}, "expr");
-    const isSystemEvent = payloadKind === "systemEvent" && textField(payload ?? {}, "text");
-    const isAgentTurn = payloadKind === "agentTurn" && textField(payload ?? {}, "message");
-    if (
-      !schedule ||
-      !payload ||
-      (!isAt && !isEvery && !isCron) ||
-      (!isSystemEvent && !isAgentTurn)
-    ) {
-      continue;
-    }
-    const fallbackTime = Number(row.updated_at) || 0;
-    const delivery = recordField(job, "delivery");
-    const completionDestination = delivery ? recordField(delivery, "completionDestination") : null;
-    const failureDestination = delivery ? recordField(delivery, "failureDestination") : null;
-    const failureAlertValue = job.failureAlert;
-    const failureAlert =
-      failureAlertValue &&
-      typeof failureAlertValue === "object" &&
-      !Array.isArray(failureAlertValue)
-        ? (failureAlertValue as Record<string, unknown>)
-        : null;
-    update.run(
-      textField(job, "name") ?? row.job_id,
-      job.enabled === false ? 0 : 1,
-      booleanField(job, "deleteAfterRun"),
-      numberField(job, "createdAtMs") ?? fallbackTime,
-      textField(job, "agentId"),
-      textField(job, "sessionKey"),
-      scheduleKind,
-      isCron ? textField(schedule, "expr") : null,
-      isCron ? textField(schedule, "tz") : null,
-      isEvery ? numberField(schedule, "everyMs") : null,
-      isEvery ? numberField(schedule, "anchorMs") : null,
-      isAt ? textField(schedule, "at") : null,
-      isCron ? numberField(schedule, "staggerMs") : null,
-      cronSessionTargetField(job) ?? (payloadKind === "agentTurn" ? "isolated" : "main"),
-      cronWakeModeField(job) ?? "now",
-      payloadKind,
-      isSystemEvent ? textField(payload, "text") : textField(payload, "message"),
-      isAgentTurn ? textField(payload, "model") : null,
-      isAgentTurn ? jsonField(payload.fallbacks) : null,
-      isAgentTurn ? textField(payload, "thinking") : null,
-      isAgentTurn ? numberField(payload, "timeoutSeconds") : null,
-      isAgentTurn && typeof payload.allowUnsafeExternalContent === "boolean"
-        ? payload.allowUnsafeExternalContent
-          ? 1
-          : 0
-        : null,
-      isAgentTurn ? jsonField(payload.externalContentSource) : null,
-      isAgentTurn && typeof payload.lightContext === "boolean"
-        ? payload.lightContext
-          ? 1
-          : 0
-        : null,
-      isAgentTurn ? jsonField(payload.toolsAllow) : null,
-      delivery ? textField(delivery, "mode") : null,
-      delivery ? textField(delivery, "channel") : null,
-      delivery ? textField(delivery, "to") : null,
-      delivery ? textField(delivery, "threadId") : null,
-      delivery ? textField(delivery, "accountId") : null,
-      delivery && typeof delivery.bestEffort === "boolean" ? (delivery.bestEffort ? 1 : 0) : null,
-      completionDestination ? textField(completionDestination, "mode") : null,
-      completionDestination ? textField(completionDestination, "to") : null,
-      failureDestinationField(failureDestination, "mode"),
-      failureDestinationField(failureDestination, "channel"),
-      failureDestinationField(failureDestination, "to"),
-      failureDestinationField(failureDestination, "accountId"),
-      failureAlertValue === false ? 1 : failureAlert ? 0 : null,
-      failureAlert ? numberField(failureAlert, "after") : null,
-      failureAlert ? textField(failureAlert, "channel") : null,
-      failureAlert ? textField(failureAlert, "to") : null,
-      failureAlert ? numberField(failureAlert, "cooldownMs") : null,
-      failureAlert && typeof failureAlert.includeSkipped === "boolean"
-        ? failureAlert.includeSkipped
-          ? 1
-          : 0
-        : null,
-      failureAlert ? textField(failureAlert, "mode") : null,
-      failureAlert ? textField(failureAlert, "accountId") : null,
-      numberField(job, "updatedAtMs") ?? fallbackTime,
-      row.store_key,
-      row.job_id,
-    );
-  }
-}
-
-function metadataStringField(record: Record<string, unknown>, key: string): string | null {
-  return textField(record, key);
-}
-
-function backfillDeliveryQueueEntriesFromEntryJson(db: DatabaseSync): void {
-  if (
-    !tableExists(db, "delivery_queue_entries") ||
-    !tableHasColumn(db, "delivery_queue_entries", "entry_json") ||
-    !tableHasColumn(db, "delivery_queue_entries", "retry_count")
-  ) {
-    return;
-  }
-  const rows = db
-    .prepare(
-      `SELECT queue_name, id, entry_json
-         FROM delivery_queue_entries
-        WHERE status <> 'completed'
-          AND (retry_count = 0
-            OR last_attempt_at IS NULL
-            OR last_error IS NULL
-            OR recovery_state IS NULL
-            OR platform_send_started_at IS NULL
-            OR entry_kind IS NULL
-            OR session_key IS NULL
-            OR channel IS NULL
-            OR target IS NULL
-            OR account_id IS NULL)`,
-    )
-    .all() as Array<{ queue_name: string; id: string; entry_json: string }>;
-  if (rows.length === 0) {
-    return;
-  }
-  const update = db.prepare(
-    `UPDATE delivery_queue_entries
-        SET entry_kind = COALESCE(?, entry_kind),
-            session_key = COALESCE(?, session_key),
-            channel = COALESCE(?, channel),
-            target = COALESCE(?, target),
-            account_id = COALESCE(?, account_id),
-            retry_count = ?,
-            last_attempt_at = COALESCE(?, last_attempt_at),
-            last_error = COALESCE(?, last_error),
-            recovery_state = COALESCE(?, recovery_state),
-            platform_send_started_at = COALESCE(?, platform_send_started_at)
-      WHERE queue_name = ?
-        AND id = ?`,
-  );
-  for (const row of rows) {
-    const entry = parseJsonRecord(row.entry_json);
-    if (!entry) {
-      continue;
-    }
-    // Queue metadata is denormalized for recovery queries but entry_json remains source of truth.
-    const session = recordField(entry, "session");
-    const route = recordField(entry, "route");
-    const deliveryContext = recordField(entry, "deliveryContext");
-    update.run(
-      metadataStringField(entry, "kind"),
-      metadataStringField(entry, "sessionKey") ??
-        (session ? metadataStringField(session, "key") : null),
-      metadataStringField(entry, "channel") ??
-        (route ? metadataStringField(route, "channel") : null) ??
-        (deliveryContext ? metadataStringField(deliveryContext, "channel") : null),
-      metadataStringField(entry, "to") ??
-        (route ? metadataStringField(route, "to") : null) ??
-        (deliveryContext ? metadataStringField(deliveryContext, "to") : null),
-      metadataStringField(entry, "accountId") ??
-        (route ? metadataStringField(route, "accountId") : null) ??
-        (deliveryContext ? metadataStringField(deliveryContext, "accountId") : null),
-      numberField(entry, "retryCount") ?? 0,
-      numberField(entry, "lastAttemptAt"),
-      metadataStringField(entry, "lastError"),
-      metadataStringField(entry, "recoveryState"),
-      numberField(entry, "platformSendStartedAt"),
-      row.queue_name,
-      row.id,
-    );
-  }
-}
-
-// The caller owns the state.schema.ensure transaction so every probe, DDL
-// change, and backfill observes one authoritative schema across processes.
-function ensureAdditiveStateColumns(db: DatabaseSync): void {
-  const addedDiagnosticEventSequence = ensureColumn(
-    db,
-    "diagnostic_events",
-    "sequence INTEGER NOT NULL DEFAULT 0",
-  );
-  if (addedDiagnosticEventSequence) {
-    // Preserve the legacy (created_at, rowid) order before the new sequence
-    // index becomes authoritative, including stable ties within each scope.
-    db.exec(`
-      WITH ranked AS (
-        SELECT
-          rowid AS event_rowid,
-          ROW_NUMBER() OVER (
-            PARTITION BY scope
-            ORDER BY created_at ASC, rowid ASC
-          ) AS sequence
-        FROM diagnostic_events
-      )
-      UPDATE diagnostic_events
-      SET sequence = (
-        SELECT ranked.sequence
-        FROM ranked
-        WHERE ranked.event_rowid = diagnostic_events.rowid
-      );
-    `);
-  }
-  db.exec("DROP INDEX IF EXISTS idx_diagnostic_events_scope_created;");
-  ensureColumn(db, "worktrees", "provisioned_paths_json TEXT");
-  ensureColumn(db, "node_host_config", "gateway_context_path TEXT");
-  ensureColumn(db, "node_host_config", "installed_apps_sharing INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "apns_registrations", "relay_origin TEXT");
-  ensureColumn(db, "device_pairing_pending", "refreshed_at_ms INTEGER");
-  ensureColumn(db, "device_pairing_pending", "browser_origin TEXT");
-  ensureColumn(db, "device_pairing_paired", "approved_via TEXT");
-  ensureColumn(db, "device_pairing_paired", "browser_origin TEXT");
-  ensureColumn(db, "device_pairing_paired", "operator_label TEXT");
-  ensureColumn(db, "device_pairing_paired", "node_surface_json TEXT");
-  ensureColumn(db, "device_pairing_paired", "pending_node_surface_json TEXT");
-  ensureColumn(db, "cron_run_logs", "status TEXT");
-  ensureColumn(db, "cron_run_logs", "error TEXT");
-  ensureColumn(db, "cron_run_logs", "summary TEXT");
-  ensureColumn(db, "cron_run_logs", "diagnostics_summary TEXT");
-  ensureColumn(db, "cron_run_logs", "delivery_status TEXT");
-  ensureColumn(db, "cron_run_logs", "delivery_error TEXT");
-  ensureColumn(db, "cron_run_logs", "delivered INTEGER");
-  ensureColumn(db, "cron_run_logs", "session_id TEXT");
-  ensureColumn(db, "cron_run_logs", "session_key TEXT");
-  ensureColumn(db, "cron_run_logs", "run_id TEXT");
-  ensureColumn(db, "cron_run_logs", "run_at_ms INTEGER");
-  ensureColumn(db, "cron_run_logs", "duration_ms INTEGER");
-  ensureColumn(db, "cron_run_logs", "next_run_at_ms INTEGER");
-  ensureColumn(db, "cron_run_logs", "model TEXT");
-  ensureColumn(db, "cron_run_logs", "provider TEXT");
-  ensureColumn(db, "cron_run_logs", "total_tokens INTEGER");
-  ensureColumn(db, "cron_run_logs", "entry_json TEXT NOT NULL DEFAULT '{}'");
-  ensureColumn(db, "cron_run_logs", "created_at INTEGER NOT NULL DEFAULT 0");
-  backfillCronRunLogEntryJson(db);
-  ensureColumn(db, "acp_replay_events", "estimated_bytes INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "acp_replay_sessions", "estimated_bytes INTEGER NOT NULL DEFAULT 0");
-  backfillAcpReplayEstimatedBytes(db);
-  ensureColumn(db, "cron_jobs", "description TEXT");
-  ensureColumn(db, "cron_jobs", "declaration_key TEXT");
-  ensureColumn(db, "cron_jobs", "display_name TEXT");
-  ensureColumn(db, "cron_jobs", "owner_agent_id TEXT");
-  ensureColumn(db, "cron_jobs", "owner_session_key TEXT");
-  ensureColumn(db, "cron_jobs", "name TEXT NOT NULL DEFAULT ''");
-  ensureColumn(db, "cron_jobs", "enabled INTEGER NOT NULL DEFAULT 1");
-  ensureColumn(db, "cron_jobs", "delete_after_run INTEGER");
-  ensureColumn(db, "cron_jobs", "created_at_ms INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "cron_jobs", "agent_id TEXT");
-  ensureColumn(db, "cron_jobs", "session_key TEXT");
-  ensureColumn(db, "cron_jobs", "schedule_kind TEXT NOT NULL DEFAULT 'manual'");
-  ensureColumn(db, "cron_jobs", "schedule_expr TEXT");
-  ensureColumn(db, "cron_jobs", "schedule_tz TEXT");
-  ensureColumn(db, "cron_jobs", "every_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "anchor_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "at TEXT");
-  ensureColumn(db, "cron_jobs", "stagger_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "session_target TEXT NOT NULL DEFAULT 'main'");
-  ensureColumn(db, "cron_jobs", "wake_mode TEXT NOT NULL DEFAULT 'auto'");
-  ensureColumn(db, "cron_jobs", "trigger_script TEXT");
-  ensureColumn(db, "cron_jobs", "trigger_once INTEGER");
-  ensureColumn(db, "cron_jobs", "payload_kind TEXT NOT NULL DEFAULT 'message'");
-  ensureColumn(db, "cron_jobs", "payload_message TEXT");
-  ensureColumn(db, "cron_jobs", "payload_model TEXT");
-  ensureColumn(db, "cron_jobs", "payload_fallbacks_json TEXT");
-  ensureColumn(db, "cron_jobs", "payload_thinking TEXT");
-  ensureColumn(db, "cron_jobs", "payload_timeout_seconds INTEGER");
-  ensureColumn(db, "cron_jobs", "payload_allow_unsafe_external_content INTEGER");
-  ensureColumn(db, "cron_jobs", "payload_external_content_source_json TEXT");
-  ensureColumn(db, "cron_jobs", "payload_light_context INTEGER");
-  ensureColumn(db, "cron_jobs", "payload_tools_allow_json TEXT");
-  ensureColumn(db, "cron_jobs", "payload_tools_allow_is_default INTEGER");
-  ensureColumn(db, "cron_jobs", "delivery_mode TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_channel TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_to TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_thread_id TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_account_id TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_best_effort INTEGER");
-  ensureColumn(db, "cron_jobs", "delivery_completion_mode TEXT");
-  ensureColumn(db, "cron_jobs", "delivery_completion_to TEXT");
-  ensureColumn(db, "cron_jobs", "failure_delivery_mode TEXT");
-  ensureColumn(db, "cron_jobs", "failure_delivery_channel TEXT");
-  ensureColumn(db, "cron_jobs", "failure_delivery_to TEXT");
-  ensureColumn(db, "cron_jobs", "failure_delivery_account_id TEXT");
-  ensureColumn(db, "cron_jobs", "failure_alert_disabled INTEGER");
-  ensureColumn(db, "cron_jobs", "failure_alert_after INTEGER");
-  ensureColumn(db, "cron_jobs", "failure_alert_channel TEXT");
-  ensureColumn(db, "cron_jobs", "failure_alert_to TEXT");
-  ensureColumn(db, "cron_jobs", "failure_alert_cooldown_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "failure_alert_include_skipped INTEGER");
-  ensureColumn(db, "cron_jobs", "failure_alert_mode TEXT");
-  ensureColumn(db, "cron_jobs", "failure_alert_account_id TEXT");
-  ensureColumn(db, "cron_jobs", "next_run_at_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "running_at_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "last_run_at_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "last_run_status TEXT");
-  ensureColumn(db, "cron_jobs", "last_error TEXT");
-  ensureColumn(db, "cron_jobs", "last_duration_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "consecutive_errors INTEGER");
-  ensureColumn(db, "cron_jobs", "consecutive_skipped INTEGER");
-  ensureColumn(db, "cron_jobs", "schedule_error_count INTEGER");
-  ensureColumn(db, "cron_jobs", "last_delivery_status TEXT");
-  ensureColumn(db, "cron_jobs", "last_delivery_error TEXT");
-  ensureColumn(db, "cron_jobs", "last_delivered INTEGER");
-  ensureColumn(db, "cron_jobs", "last_failure_alert_at_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "state_json TEXT NOT NULL DEFAULT '{}'");
-  ensureColumn(db, "cron_jobs", "runtime_updated_at_ms INTEGER");
-  ensureColumn(db, "cron_jobs", "schedule_identity TEXT");
-  ensureColumn(db, "cron_jobs", "sort_order INTEGER NOT NULL DEFAULT 0");
-  backfillCronJobsFromJobJson(db);
-  const addedDeliveryThreadIdType = ensureColumn(db, "cron_jobs", "delivery_thread_id_type TEXT");
-  if (addedDeliveryThreadIdType) {
-    migrateLegacyCronDeliveryThreadIds(db);
-  }
-  ensureColumn(db, "sandbox_registry_entries", "session_key TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "backend_id TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "runtime_label TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "image TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "created_at_ms INTEGER");
-  ensureColumn(db, "sandbox_registry_entries", "last_used_at_ms INTEGER");
-  ensureColumn(db, "sandbox_registry_entries", "config_label_kind TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "config_hash TEXT");
-  ensureColumn(db, "sandbox_registry_entries", "cdp_port INTEGER");
-  ensureColumn(db, "sandbox_registry_entries", "no_vnc_port INTEGER");
-  ensureColumn(db, "delivery_queue_entries", "entry_kind TEXT");
-  ensureColumn(db, "delivery_queue_entries", "session_key TEXT");
-  ensureColumn(db, "delivery_queue_entries", "channel TEXT");
-  ensureColumn(db, "delivery_queue_entries", "target TEXT");
-  ensureColumn(db, "delivery_queue_entries", "account_id TEXT");
-  ensureColumn(db, "delivery_queue_entries", "retry_count INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "delivery_queue_entries", "last_attempt_at INTEGER");
-  ensureColumn(db, "delivery_queue_entries", "last_error TEXT");
-  ensureColumn(db, "delivery_queue_entries", "recovery_state TEXT");
-  ensureColumn(db, "delivery_queue_entries", "platform_send_started_at INTEGER");
-  backfillDeliveryQueueEntriesFromEntryJson(db);
-  ensureColumn(db, "commitments", "account_id TEXT");
-  ensureColumn(db, "commitments", "recipient_id TEXT");
-  ensureColumn(db, "commitments", "thread_id TEXT");
-  ensureColumn(db, "commitments", "sender_id TEXT");
-  ensureColumn(db, "commitments", "kind TEXT NOT NULL DEFAULT 'followup'");
-  ensureColumn(db, "commitments", "sensitivity TEXT NOT NULL DEFAULT 'normal'");
-  ensureColumn(db, "commitments", "source TEXT NOT NULL DEFAULT 'unknown'");
-  ensureColumn(db, "commitments", "reason TEXT NOT NULL DEFAULT ''");
-  ensureColumn(db, "commitments", "suggested_text TEXT NOT NULL DEFAULT ''");
-  ensureColumn(db, "commitments", "dedupe_key TEXT NOT NULL DEFAULT ''");
-  ensureColumn(db, "commitments", "confidence REAL NOT NULL DEFAULT 0");
-  ensureColumn(db, "commitments", "due_timezone TEXT NOT NULL DEFAULT 'UTC'");
-  ensureColumn(db, "commitments", "source_message_id TEXT");
-  ensureColumn(db, "commitments", "source_run_id TEXT");
-  ensureColumn(db, "commitments", "created_at_ms INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "commitments", "attempts INTEGER NOT NULL DEFAULT 0");
-  ensureColumn(db, "commitments", "last_attempt_at_ms INTEGER");
-  ensureColumn(db, "commitments", "sent_at_ms INTEGER");
-  ensureColumn(db, "commitments", "dismissed_at_ms INTEGER");
-  ensureColumn(db, "commitments", "snoozed_until_ms INTEGER");
-  ensureColumn(db, "commitments", "expired_at_ms INTEGER");
-  // The shipped JSON runtime predeclared this table but never populated it.
-  // Add required typed columns before Doctor or runtime can insert canonical rows.
-  ensureColumn(db, "managed_outgoing_image_records", "original_media_root TEXT NOT NULL");
-  ensureColumn(db, "managed_outgoing_image_records", "agent_id TEXT");
-  ensureColumn(
-    db,
-    "managed_outgoing_image_records",
-    "cleanup_pending INTEGER NOT NULL DEFAULT 0 CHECK (cleanup_pending IN (0, 1))",
-  );
-  ensureColumn(db, "current_conversation_bindings", "target_agent_id TEXT NOT NULL DEFAULT 'main'");
-  ensureColumn(db, "current_conversation_bindings", "target_session_id TEXT");
-  ensureColumn(
-    db,
-    "current_conversation_bindings",
-    "conversation_kind TEXT NOT NULL DEFAULT 'channel'",
-  );
-  ensureColumn(db, "device_bootstrap_tokens", "pending_profile_json TEXT");
-  ensureColumn(db, "gateway_restart_handoff", "restart_trace_started_at INTEGER");
-  ensureColumn(db, "gateway_restart_handoff", "restart_trace_last_at INTEGER");
-  ensureColumn(db, "gateway_restart_intent", "reason TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "delivery_channel TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "delivery_to TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "delivery_account_id TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "message TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "continuation_json TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "doctor_hint TEXT");
-  ensureColumn(db, "gateway_restart_sentinel", "stats_json TEXT");
-  ensureColumn(db, "gateway_boot_lifecycle", "startup_reason TEXT");
-  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_mode TEXT");
-  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_key_id TEXT");
-  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_signature_count INTEGER");
-  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_threshold INTEGER");
-  ensureColumn(db, "official_external_plugin_catalog_snapshots", "trust_verified_at TEXT");
-  const addedTaskRequesterAgentId = ensureColumn(db, "task_runs", "requester_agent_id TEXT");
-  if (addedTaskRequesterAgentId) {
-    repairLegacyTaskAgentAttribution(db);
-  }
-  repairLegacyTaskDeliveryStatuses(db);
-  ensureColumn(db, "task_runs", "tool_use_count INTEGER");
-  ensureColumn(db, "task_runs", "last_tool_name TEXT");
-  ensureColumn(db, "task_runs", "detail_json TEXT");
-  ensureColumn(db, "subagent_runs", "task_name TEXT");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_status TEXT");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_attempt_count INTEGER");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_replay_count INTEGER");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_next_attempt_at INTEGER");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_batch_run_ids_json TEXT");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_last_error TEXT");
-  ensureColumn(db, "subagent_runs", "requester_settle_wake_retire_after INTEGER");
-  ensureColumn(db, "worker_environments", "bootstrap_bundle_hash TEXT");
-  ensureColumn(db, "worker_environments", "bootstrap_openclaw_version TEXT");
-  ensureColumn(db, "worker_environments", "bootstrap_protocol_features_json TEXT");
-  ensureColumn(
-    db,
-    "worker_environments",
-    "owner_epoch INTEGER NOT NULL DEFAULT 0 CHECK (owner_epoch >= 0)",
-  );
-  ensureColumn(db, "worker_environments", "ssh_host_key TEXT");
-  ensureColumn(
-    db,
-    "worker_environments",
-    "teardown_terminal_state TEXT CHECK (teardown_terminal_state IN ('destroyed', 'failed'))",
-  );
-  ensureOperatorApprovalResolutionRefs(db);
-}
-
 function ensureSchema(db: DatabaseSync, pathname: string): void {
   const now = Date.now();
   const kysely = getNodeSqliteKysely<OpenClawStateMetadataDatabase>(db);
@@ -1749,10 +283,6 @@ function ensureSchema(db: DatabaseSync, pathname: string): void {
   }
 }
 
-function resolveDatabasePath(options: OpenClawStateDatabaseOptions = {}): string {
-  return path.resolve(options.path ?? resolveOpenClawStateSqlitePath(options.env ?? process.env));
-}
-
 function assertStateDatabaseIntegrityBeforeMutation(
   database: DatabaseSync,
   pathname: string,
@@ -1782,6 +312,7 @@ function assertStateDatabaseIntegrityBeforeMutation(
 }
 
 /** Open or return a cached shared state database after schema and migration checks. */
+
 export function openOpenClawStateDatabase(
   options: OpenClawStateDatabaseOptions = {},
 ): OpenClawStateDatabase {
@@ -1907,4 +438,3 @@ export function closeOpenClawStateDatabaseForTest(): void {
   closeOpenClawStateDatabase();
   terminalOpenLatch.clearAll();
 }
-/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */

From 40793e6f8b5d9362e9b94d9e18cd95581c6bfc18 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 13:54:56 +0100
Subject: [PATCH 63/76] fix: bound pasted input and provider response bodies
 (#110627)

* refactor(runtime): centralize bounded I/O handling

* fix(runtime): finalize bounded I/O contracts

* chore(security): drop stale audit import

* docs(changelog): credit bounded I/O fixes

Co-authored-by: Pick-cat <huang.ting3@xydigit.com>

* fix(agents): keep provider HTTP options private

* fix(ai): traverse OpenAI schema maps by value

* fix(runtime): preserve absolute download deadlines

* ci(ui): stabilize compressed CSS budget

* fix(ai): traverse legacy schema applicators

---------

Co-authored-by: Pick-cat <huang.ting3@xydigit.com>
---
 CHANGELOG.md                                  |   1 +
 .../.generated/plugin-sdk-api-baseline.sha256 |   8 +-
 .../video-generation-provider.test.ts         | 124 ++++++++-
 .../byteplus/video-generation-provider.ts     |  70 +++--
 extensions/matrix/src/cli.ts                  |  19 +-
 .../minimax/music-generation-provider.test.ts |  27 +-
 .../minimax/music-generation-provider.ts      |  92 ++-----
 .../minimax/provider-http.test-helpers.ts     |  44 ++-
 .../minimax/video-generation-provider.ts      |  61 ++++-
 .../openai/video-generation-provider.ts       |  32 ++-
 .../runway/video-generation-provider.ts       |  73 +++--
 .../synology-chat/src/client.loopback.test.ts |  48 ++--
 .../together/video-generation-provider.ts     |  15 +-
 extensions/vydra/shared.test.ts               |  29 +-
 extensions/vydra/shared.ts                    | 137 ++++------
 .../xai/video-generation-provider.test.ts     |   3 +-
 extensions/xai/video-generation-transport.ts  |  17 +-
 packages/ai/src/internal/openai.ts            |   1 +
 .../providers/openai-tool-schema-compat.ts    | 245 +++++++++++++++++
 .../src/providers/openai-tool-schema.test.ts  |  49 ++++
 .../ai/src/providers/openai-tool-schema.ts    |  71 +----
 .../src/read-byte-stream-with-limit.test.ts   |   5 +-
 .../src/read-byte-stream-with-limit.ts        |   9 +-
 scripts/check-control-ui-performance.mjs      |   6 +-
 src/agents/provider-http-errors.test.ts       |  50 ++++
 src/agents/provider-http-errors.ts            |  96 +++++--
 src/cli/config-cli.ts                         |  22 +-
 src/cli/exec-approvals-cli.ts                 |  17 +-
 src/commands/models/auth.ts                   |  17 +-
 src/infra/http-body.response.test.ts          |  43 +++
 src/infra/http-body.ts                        |  14 +-
 src/media-understanding/shared.test.ts        |  83 +++++-
 src/media-understanding/shared.ts             | 123 +++++++--
 src/music-generation/provider-assets.ts       |  21 +-
 src/plugin-sdk/provider-tools.test.ts         |  43 +++
 src/plugin-sdk/provider-tools.ts              | 255 +-----------------
 .../test-helpers/provider-http-mocks.ts       |  44 ++-
 test/scripts/control-ui-performance.test.ts   |  43 +++
 38 files changed, 1289 insertions(+), 768 deletions(-)
 create mode 100644 packages/ai/src/providers/openai-tool-schema-compat.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75763220837..14ce3db2188 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -42,6 +42,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- **Bounded input and provider responses:** cap pasted auth/config input and enforce wall-clock deadlines across generated-media downloads, polling JSON, and failed response details so oversized or slow-drip streams cannot exceed resource budgets (thanks @Pick-cat).
 - **Cloud worker derived workspace caches:** exclude Python caches, dependency trees, and macOS metadata symmetrically from outbound sync and inbound reconciliation so local cache rewrites cannot fence later cloud results or worker reclaim.
 - **Codex model status diagnostics:** report a configured Codex route as unavailable when its harness plugin is disabled, missing, or quarantined, while preserving the separate credential result and making `models status --check` fail instead of silently treating fallback execution as healthy. Thanks @shakkernerd.
 - **Gateway control-plane rate limiting:** use per-method buckets with a 30-per-minute budget so interactive admin writes remain responsive while retaining runaway-loop protection.
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 7b67958017e..9648715b86e 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -215,7 +215,7 @@ b32f041136217c510e559e5fcf7ed4361cf51ebfad0fa15799d69fe539780feb  module/provide
 ee5184ab251bcbe49a4cb9c845eee31975733bce1dc2300854cff14e99cf6db7  module/provider-catalog-shared
 ca5d408937bc0ff92021673320aeba6ae6fce705711b251f15797887b8f34d3a  module/provider-entry
 52085bfaa917f4fd262508a93af923e5e834901b5f0f017c93b02a0798073344  module/provider-env-vars
-404840e551472a1debea4e7ff26c6df99e219bfcfdaf7491553eed0e843f77bf  module/provider-http
+3b311719eae8dbb061ac2e79f0a58f8540f7a416ec281f3ee0c1cc3cfa6b401f  module/provider-http
 47564e55d5ae9174fc402d6a1ef7120a799a92bb3625106327b642d4d9eb3bd9  module/provider-model-shared
 966830793fccc5e5a7e6ae2f7df84f5f39120ac9a6af8c10be1e070eaf257f32  module/provider-model-types
 f1452aec01b1bc1d8764b666131b6237bce5b78477ce1137d622c4aa0b691a8e  module/provider-oauth-runtime
@@ -225,7 +225,7 @@ c543747f32aebde42508e31606db325739f0c54fcc7cf683f68ac941c835f737  module/provide
 413af0d4597c1bab45e2f1a260b520445a25b9d11abd46a98fdfb74c60ddd601  module/provider-stream
 ea8bd63655e983dacfd306fe77d0793097166228a2dabd9b7fc8e33252eb359f  module/provider-stream-family
 cdcc81cbd0aff7e341cd7edeec77b02b55d0d27af03278d13ef07487aa8eeae7  module/provider-stream-shared
-4a30f74ae2706ec08d26ed37c86c3fb07ca03bba9ae3bff3a1e4375f8cfa0fbb  module/provider-tools
+5a907292055c941ec7420163ea50e8bc90ead816b3c5867d94a23024d3b579e8  module/provider-tools
 8236935f56423a26aeb7219173c0c8c8c7aacb4a13d0d851f05bdf2d35790cd4  module/provider-transport-runtime
 009a594b19aa9f0d0c0c28f54968f807cad4b3ee40ec13c685367116d63aafdc  module/provider-usage
 b6c43bdb895139e6bbdb30f861b7e0e66bd2e8960e4129cc2bdb562c575c5f2f  module/provider-web-fetch
@@ -284,8 +284,8 @@ cd431f6ba8327b81438b7a63b1963120f200f5abd145fb6aa7c5c561339cb0b1  module/setup-t
 f2095165f836537aa6c145aecfff32543c9cc7b3935d33d107869b5f975475ee  module/simple-completion-runtime
 18e384ec43d9eaee52c8e286e127bda2048370e2337964a754d94b236724ca9e  module/skill-commands-runtime
 7eaea43619ee15e8b0d2d17c81c63b057576b251fecebcb5034d4e06e5940aea  module/skills-runtime
-91e261cfc2a847bb6adc7147027b2f7a83acd6207b51b225b4452742104312da  module/speech
-08d11b92b5947cf43636fa58c0b1505d1f656106d22653f6b0fd14020ca839f2  module/speech-core
+6639d26ccc022ee5c55e23aa52071e30dbbddb17e7c4ecf62b152358380e087f  module/speech
+5c228af0457bf14b2833c2d0994c98212f6a7451abec7d5fe5cad0632115bb84  module/speech-core
 ae469f32799380e6b045abaefefee6eb3f00d714ffbf36b6eeef5025dc529472  module/speech-settings
 ba7bd1528069e8d1dc6a6fc3626aebb0cd8f8d3f7715dba0916d315ea3787b2a  module/sqlite-runtime
 e1379adab6398cdeda7671a4e6cc268508d21270815b53fef793249698a8d601  module/ssrf-dispatcher
diff --git a/extensions/byteplus/video-generation-provider.test.ts b/extensions/byteplus/video-generation-provider.test.ts
index bf8ae396c70..cb98e9d96d2 100644
--- a/extensions/byteplus/video-generation-provider.test.ts
+++ b/extensions/byteplus/video-generation-provider.test.ts
@@ -19,36 +19,87 @@ vi.mock("openclaw/plugin-sdk/provider-auth-runtime", () => ({
 
 vi.mock("openclaw/plugin-sdk/provider-http", async (importActual) => {
   const actual = await importActual<typeof import("openclaw/plugin-sdk/provider-http")>();
-  const resolveTimeoutMs = (timeoutMs: unknown): number =>
-    typeof timeoutMs === "function" ? (timeoutMs() as number) : ((timeoutMs as number) ?? 60_000);
   return {
     // REAL byte-bounded JSON reader under test — not stubbed.
     readProviderJsonResponse: actual.readProviderJsonResponse,
     postJsonRequest: postJsonRequestMock,
-    fetchProviderOperationResponse: async (params: {
+    pollProviderOperationJson: async (params: {
       url: string;
-      init?: RequestInit;
-      timeoutMs?: unknown;
-      fetchFn: typeof fetch;
-    }) => fetchWithTimeoutMock(params.url, params.init ?? {}, resolveTimeoutMs(params.timeoutMs)),
+      headers: Headers;
+      defaultTimeoutMs: number;
+      maxAttempts: number;
+      requestFailedMessage: string;
+      timeoutMessage: string;
+      isComplete: (payload: unknown) => boolean;
+      getFailureMessage?: (payload: unknown) => string | undefined;
+    }) => {
+      for (let attempt = 0; attempt < params.maxAttempts; attempt += 1) {
+        const response = await fetchWithTimeoutMock(
+          params.url,
+          { method: "GET", headers: params.headers },
+          params.defaultTimeoutMs,
+        );
+        const payload = await actual.readProviderJsonResponse(
+          response,
+          params.requestFailedMessage,
+        );
+        if (params.isComplete(payload)) {
+          return payload;
+        }
+        const failureMessage = params.getFailureMessage?.(payload);
+        if (failureMessage) {
+          throw new Error(failureMessage);
+        }
+      }
+      throw new Error(params.timeoutMessage);
+    },
     fetchProviderDownloadResponse: async (params: {
       url: string;
       init?: RequestInit;
-      timeoutMs?: unknown;
+      deadline: { deadlineAtMs?: number; timeoutMs?: number };
       fetchFn: typeof fetch;
-    }) => fetchWithTimeoutMock(params.url, params.init ?? {}, resolveTimeoutMs(params.timeoutMs)),
+    }) =>
+      fetchWithTimeoutMock(
+        params.url,
+        params.init ?? {},
+        params.deadline.deadlineAtMs === undefined
+          ? (params.deadline.timeoutMs ?? 60_000)
+          : Math.max(1, params.deadline.deadlineAtMs - Date.now()),
+      ),
     assertOkOrThrowHttpError: async () => {},
     createProviderOperationDeadline: ({
       label,
       timeoutMs,
     }: {
       label: string;
-      timeoutMs?: number;
-    }) => ({ label, timeoutMs }),
+      timeoutMs?: number | (() => number);
+    }) => {
+      const resolvedTimeoutMs = typeof timeoutMs === "function" ? timeoutMs() : timeoutMs;
+      return {
+        label,
+        timeoutMs: resolvedTimeoutMs,
+        deadlineAtMs:
+          typeof resolvedTimeoutMs === "number" ? Date.now() + resolvedTimeoutMs : undefined,
+      };
+    },
     createProviderOperationTimeoutResolver:
-      ({ defaultTimeoutMs }: { defaultTimeoutMs: number }) =>
-      () =>
+      ({
+        deadline,
         defaultTimeoutMs,
+      }: {
+        deadline: { deadlineAtMs?: number; label: string; timeoutMs?: number };
+        defaultTimeoutMs: number;
+      }) =>
+      () => {
+        if (typeof deadline.deadlineAtMs !== "number") {
+          return defaultTimeoutMs;
+        }
+        const remainingMs = deadline.deadlineAtMs - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error(`${deadline.label} timed out after ${deadline.timeoutMs}ms`);
+        }
+        return Math.min(defaultTimeoutMs, remainingMs);
+      },
     resolveProviderOperationTimeoutMs: ({ defaultTimeoutMs }: { defaultTimeoutMs: number }) =>
       defaultTimeoutMs,
     resolveProviderHttpRequestConfig: (params: {
@@ -62,7 +113,6 @@ vi.mock("openclaw/plugin-sdk/provider-http", async (importActual) => {
       headers: new Headers(params.defaultHeaders),
       dispatcherPolicy: undefined,
     }),
-    waitProviderOperationPollInterval: async () => {},
   };
 });
 
@@ -76,6 +126,7 @@ afterEach(() => {
   postJsonRequestMock.mockReset();
   fetchWithTimeoutMock.mockReset();
   resolveApiKeyForProviderMock.mockClear();
+  vi.useRealTimers();
 });
 
 function mockSuccessfulBytePlusTask(params?: { model?: string }) {
@@ -246,6 +297,51 @@ describe("byteplus video generation provider", () => {
     ).rejects.toThrow("BytePlus generated video download exceeds 1 bytes");
   });
 
+  it("shares one wall-clock deadline across download headers and body", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    postJsonRequestMock.mockResolvedValue({
+      response: streamedJsonResponse({ id: "task_slow_download" }),
+      release: vi.fn(async () => {}),
+    });
+    fetchWithTimeoutMock
+      .mockResolvedValueOnce(
+        streamedJsonResponse({
+          id: "task_slow_download",
+          status: "succeeded",
+          content: { video_url: "https://example.com/slow.mp4" },
+        }),
+      )
+      .mockImplementationOnce(async () => {
+        vi.setSystemTime(1_090);
+        return new Response(
+          new ReadableStream<Uint8Array>({
+            async pull(controller) {
+              controller.enqueue(new Uint8Array([1]));
+              await new Promise<void>((resolve) => {
+                setTimeout(resolve, 20);
+              });
+            },
+          }),
+          { headers: { "content-type": "video/mp4" } },
+        );
+      });
+
+    const result = buildBytePlusVideoGenerationProvider().generateVideo({
+      provider: "byteplus",
+      model: "seedance-1-0-pro-250528",
+      prompt: "slow download",
+      timeoutMs: 100,
+      cfg: {},
+    });
+    const assertion = expect(result).rejects.toThrow(
+      "BytePlus generated video download timed out after 100ms",
+    );
+
+    await vi.advanceTimersByTimeAsync(11);
+    await assertion;
+  });
+
   it("keeps the unified model for image requests and lowercases resolution", async () => {
     mockSuccessfulBytePlusTask({ model: "seedance-1-0-pro-250528" });
 
diff --git a/extensions/byteplus/video-generation-provider.ts b/extensions/byteplus/video-generation-provider.ts
index 0f417f0f568..0d5bbd48220 100644
--- a/extensions/byteplus/video-generation-provider.ts
+++ b/extensions/byteplus/video-generation-provider.ts
@@ -10,12 +10,11 @@ import {
   createProviderOperationDeadline,
   createProviderOperationTimeoutResolver,
   fetchProviderDownloadResponse,
-  fetchProviderOperationResponse,
+  pollProviderOperationJson,
   postJsonRequest,
   readProviderJsonResponse,
   resolveProviderOperationTimeoutMs,
   resolveProviderHttpRequestConfig,
-  waitProviderOperationPollInterval,
   type ProviderOperationTimeoutMs,
 } from "openclaw/plugin-sdk/provider-http";
 import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
@@ -163,40 +162,24 @@ async function pollBytePlusTask(params: {
     timeoutMs: params.timeoutMs,
     label: `BytePlus video generation task ${params.taskId}`,
   });
-  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
-    const response = await fetchProviderOperationResponse({
-      stage: "poll",
-      url: `${params.baseUrl}/contents/generations/tasks/${params.taskId}`,
-      init: {
-        method: "GET",
-        headers: params.headers,
-      },
-      timeoutMs: createProviderOperationTimeoutResolver({
-        deadline,
-        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
-      }),
-      fetchFn: params.fetchFn,
-      provider: "byteplus",
-      requestFailedMessage: "BytePlus video status request failed",
-    });
-    const payload = await readBytePlusJsonResponse<BytePlusTaskResponse>(
-      response,
-      "BytePlus video status request failed",
-    );
-    switch (readBytePlusTaskStatus(payload)) {
-      case "succeeded":
-        return payload;
-      case "failed":
-      case "cancelled":
-        throw new Error(
-          readBytePlusErrorMessage(payload.error) || "BytePlus video generation failed",
-        );
-      default:
-        await waitProviderOperationPollInterval({ deadline, pollIntervalMs: POLL_INTERVAL_MS });
-        break;
-    }
-  }
-  throw new Error(`BytePlus video generation task ${params.taskId} did not finish in time`);
+  return await pollProviderOperationJson<BytePlusTaskResponse>({
+    url: `${params.baseUrl}/contents/generations/tasks/${params.taskId}`,
+    headers: params.headers,
+    deadline,
+    defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+    fetchFn: params.fetchFn,
+    maxAttempts: MAX_POLL_ATTEMPTS,
+    pollIntervalMs: POLL_INTERVAL_MS,
+    requestFailedMessage: "BytePlus video status request failed",
+    timeoutMessage: `BytePlus video generation task ${params.taskId} did not finish in time`,
+    isComplete: (payload) => readBytePlusTaskStatus(payload) === "succeeded",
+    getFailureMessage: (payload) => {
+      const status = readBytePlusTaskStatus(payload);
+      return status === "failed" || status === "cancelled"
+        ? readBytePlusErrorMessage(payload.error) || "BytePlus video generation failed"
+        : undefined;
+    },
+  });
 }
 
 async function downloadBytePlusVideo(params: {
@@ -205,16 +188,29 @@ async function downloadBytePlusVideo(params: {
   fetchFn: typeof fetch;
   maxBytes: number;
 }): Promise<GeneratedVideoAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "BytePlus generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const response = await fetchProviderDownloadResponse({
     url: params.url,
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    deadline,
     fetchFn: params.fetchFn,
     provider: "byteplus",
     requestFailedMessage: "BytePlus generated video download failed",
   });
   const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
   const buffer = await readResponseWithLimit(response, params.maxBytes, {
+    timeoutMs,
+    onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+      new Error(
+        `BytePlus generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+      ),
     onOverflow: ({ maxBytes }) =>
       new Error(`BytePlus generated video download exceeds ${maxBytes} bytes`),
   });
diff --git a/extensions/matrix/src/cli.ts b/extensions/matrix/src/cli.ts
index 6a6f5a09e77..56357364703 100644
--- a/extensions/matrix/src/cli.ts
+++ b/extensions/matrix/src/cli.ts
@@ -3,6 +3,7 @@ import type { Command } from "commander";
 import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
 import { createLazyRuntimeModule } from "openclaw/plugin-sdk/lazy-runtime";
 import { parseStrictInteger, timestampMsToIsoString } from "openclaw/plugin-sdk/number-runtime";
+import { readByteStreamWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
 import type { ChannelSetupInput } from "openclaw/plugin-sdk/setup";
 import { resolveMatrixAccount, resolveMatrixAccountConfig } from "./matrix/accounts.js";
 import { listMatrixOwnDevices, pruneMatrixStaleGatewayDevices } from "./matrix/actions/devices.js";
@@ -68,19 +69,11 @@ function markCliFailure(): void {
 }
 
 async function readMatrixCliRecoveryKeyFromStdin(): Promise<string> {
-  const chunks: Buffer[] = [];
-  let totalBytes = 0;
-  for await (const chunk of process.stdin) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
-    totalBytes += buffer.byteLength;
-    if (totalBytes > MATRIX_CLI_RECOVERY_KEY_STDIN_MAX_BYTES) {
-      throw new Error(
-        `Matrix recovery key stdin exceeds ${MATRIX_CLI_RECOVERY_KEY_STDIN_MAX_BYTES} bytes.`,
-      );
-    }
-    chunks.push(buffer);
-  }
-  const recoveryKey = Buffer.concat(chunks, totalBytes).toString("utf8").trim();
+  const bytes = await readByteStreamWithLimit(process.stdin, {
+    maxBytes: MATRIX_CLI_RECOVERY_KEY_STDIN_MAX_BYTES,
+    onOverflow: ({ maxBytes }) => new Error(`Matrix recovery key stdin exceeds ${maxBytes} bytes.`),
+  });
+  const recoveryKey = bytes.toString("utf8").trim();
   if (!recoveryKey) {
     throw new Error("Matrix recovery key was requested from stdin, but stdin was empty.");
   }
diff --git a/extensions/minimax/music-generation-provider.test.ts b/extensions/minimax/music-generation-provider.test.ts
index 910fc1e01f1..b2790d8a8c1 100644
--- a/extensions/minimax/music-generation-provider.test.ts
+++ b/extensions/minimax/music-generation-provider.test.ts
@@ -68,6 +68,19 @@ function expectMinimaxGuardedFetchCall(index: number, url: string) {
   };
 }
 
+function expectDownloadFetchTimeout(url: string, totalTimeoutMs: number): void {
+  const call = fetchWithTimeoutMock.mock.calls[0];
+  if (!call) {
+    throw new Error("expected generated music download");
+  }
+  const [actualUrl, init, timeoutMs, fetchFn] = call;
+  expect(actualUrl).toBe(url);
+  expect(init).toEqual({ method: "GET" });
+  expect(timeoutMs).toBeGreaterThan(totalTimeoutMs - 1_000);
+  expect(timeoutMs).toBeLessThanOrEqual(totalTimeoutMs);
+  expect(fetchFn).toBe(fetch);
+}
+
 function expectAllowPrivateNetworkPolicy(options: Record<string, unknown> | undefined): void {
   expect(options).toEqual({
     ssrfPolicy: { allowPrivateNetwork: true },
@@ -269,12 +282,7 @@ describe("minimax music generation provider", () => {
       lyrics: "our city wakes",
     });
 
-    expect(fetchWithTimeoutMock).toHaveBeenCalledWith(
-      "https://example.com/url-audio.mp3",
-      { method: "GET" },
-      120000,
-      fetch,
-    );
+    expectDownloadFetchTimeout("https://example.com/url-audio.mp3", 120_000);
     expect(result.tracks[0]?.buffer.byteLength).toBeGreaterThan(0);
     expect(result.lyrics).toEqual(["our city wakes"]);
     expect(result.metadata?.taskId).toBe("task-url");
@@ -326,12 +334,7 @@ describe("minimax music generation provider", () => {
     });
 
     expect(mockCallArg(postJsonRequestMock).timeoutMs).toBe(600000);
-    expect(fetchWithTimeoutMock).toHaveBeenCalledWith(
-      "https://example.com/long-timeout.mp3",
-      { method: "GET" },
-      600000,
-      fetch,
-    );
+    expectDownloadFetchTimeout("https://example.com/long-timeout.mp3", 600_000);
   });
 
   it("applies explicit caller timeouts while reading streaming response bodies", async () => {
diff --git a/extensions/minimax/music-generation-provider.ts b/extensions/minimax/music-generation-provider.ts
index eee8710e854..70e3b440976 100644
--- a/extensions/minimax/music-generation-provider.ts
+++ b/extensions/minimax/music-generation-provider.ts
@@ -10,6 +10,7 @@ import { resolveApiKeyForProvider } from "openclaw/plugin-sdk/provider-auth-runt
 import {
   assertOkOrThrowHttpError,
   createProviderOperationDeadline,
+  createProviderOperationTimeoutResolver,
   executeProviderOperationWithRetry,
   fetchWithTimeoutGuarded,
   postJsonRequest,
@@ -141,6 +142,14 @@ async function downloadTrackFromUrl(params: {
   maxBytes: number;
   policy: MinimaxRequestPolicy;
 }): Promise<GeneratedMusicAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "MiniMax generated music download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const result = await executeProviderOperationWithRetry({
     provider: "minimax",
     stage: "download",
@@ -148,7 +157,7 @@ async function downloadTrackFromUrl(params: {
       const guardedResult = await fetchWithTimeoutGuarded(
         params.url,
         { method: "GET" },
-        params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        timeoutMs(),
         params.fetchFn,
         resolveMinimaxGuardedRequestOptions(params.policy),
       );
@@ -170,6 +179,11 @@ async function downloadTrackFromUrl(params: {
     const ext = extensionForMime(mimeType)?.replace(/^\./u, "") || "mp3";
     return {
       buffer: await readResponseWithLimit(result.response, params.maxBytes, {
+        timeoutMs,
+        onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+          new Error(
+            `MiniMax generated music download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+          ),
         onOverflow: ({ maxBytes }) =>
           new Error(`MiniMax generated music download exceeds ${maxBytes} bytes`),
       }),
@@ -181,12 +195,6 @@ async function downloadTrackFromUrl(params: {
   }
 }
 
-function createMinimaxMusicTimeoutError(deadline: ProviderOperationDeadline): Error {
-  const timeoutLabel =
-    typeof deadline.timeoutMs === "number" ? ` after ${deadline.timeoutMs}ms` : "";
-  return new Error(`${deadline.label} timed out${timeoutLabel}`);
-}
-
 function resolveBodyReadTimeoutMs(deadline: ProviderOperationDeadline): number {
   return resolveProviderOperationTimeoutMs({
     deadline,
@@ -198,6 +206,12 @@ function createGeneratedMusicTooLargeError(maxBytes: number): Error {
   return new Error(`MiniMax generated music download exceeds ${maxBytes} bytes`);
 }
 
+function createMinimaxMusicTimeoutError(deadline: ProviderOperationDeadline): Error {
+  const timeoutLabel =
+    typeof deadline.timeoutMs === "number" ? ` after ${deadline.timeoutMs}ms` : "";
+  return new Error(`${deadline.label} timed out${timeoutLabel}`);
+}
+
 function resolveStreamEnvelopeMaxBytes(maxBytes: number): number {
   return Math.max(
     STREAM_ENVELOPE_OVERHEAD_BYTES,
@@ -210,65 +224,11 @@ async function readResponseBufferWithDeadline(
   deadline: ProviderOperationDeadline,
   maxBytes: number,
 ): Promise<Buffer> {
-  const body = response.body;
-  if (!body) {
-    return Buffer.alloc(0);
-  }
-
-  const reader = body.getReader();
-  const chunks: Uint8Array[] = [];
-  let totalBytes = 0;
-  try {
-    while (true) {
-      let timeoutId: ReturnType<typeof setTimeout> | undefined;
-      try {
-        const timeoutMs = resolveBodyReadTimeoutMs(deadline);
-        const timeoutPromise = new Promise<never>((_, reject) => {
-          timeoutId = setTimeout(() => reject(createMinimaxMusicTimeoutError(deadline)), timeoutMs);
-        });
-        const result = await Promise.race([reader.read(), timeoutPromise]);
-        if (result.done) {
-          break;
-        }
-        if (!result.value || result.value.length === 0) {
-          continue;
-        }
-        const nextTotalBytes = totalBytes + result.value.byteLength;
-        if (nextTotalBytes > maxBytes) {
-          const error = createGeneratedMusicTooLargeError(maxBytes);
-          try {
-            await reader.cancel(error);
-          } catch {
-            // Preserve the size-limit failure that caused cancellation.
-          }
-          throw error;
-        }
-        chunks.push(result.value);
-        totalBytes = nextTotalBytes;
-      } catch (error) {
-        try {
-          await reader.cancel(error);
-        } catch {
-          // Preserve the timeout or stream read failure that caused cancellation.
-        }
-        throw error;
-      } finally {
-        if (timeoutId) {
-          clearTimeout(timeoutId);
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-
-  const buffer = Buffer.allocUnsafe(totalBytes);
-  let offset = 0;
-  for (const chunk of chunks) {
-    buffer.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return buffer;
+  return await readResponseWithLimit(response, maxBytes, {
+    timeoutMs: () => resolveBodyReadTimeoutMs(deadline),
+    onTimeout: () => createMinimaxMusicTimeoutError(deadline),
+    onOverflow: ({ maxBytes: limit }) => createGeneratedMusicTooLargeError(limit),
+  });
 }
 
 async function readStreamingTrack(
diff --git a/extensions/minimax/provider-http.test-helpers.ts b/extensions/minimax/provider-http.test-helpers.ts
index 78bb4ba0ae9..48ca377603a 100644
--- a/extensions/minimax/provider-http.test-helpers.ts
+++ b/extensions/minimax/provider-http.test-helpers.ts
@@ -91,6 +91,15 @@ function resolveMockProviderTimeoutMs(
   return typeof timeoutMs === "function" ? timeoutMs() : (timeoutMs ?? 60_000);
 }
 
+function resolveMockProviderDownloadTimeoutMs(params: FetchProviderDownloadResponseParams) {
+  if (!params.deadline) {
+    return resolveMockProviderTimeoutMs(params.timeoutMs);
+  }
+  return params.deadline.deadlineAtMs === undefined
+    ? (params.deadline.timeoutMs ?? 60_000)
+    : Math.max(1, params.deadline.deadlineAtMs - Date.now());
+}
+
 minimaxProviderHttpMocks.fetchProviderOperationResponseMock.mockImplementation(
   async (params: FetchProviderOperationResponseParams) => {
     const response = await minimaxProviderHttpMocks.fetchWithTimeoutMock(
@@ -114,7 +123,7 @@ minimaxProviderHttpMocks.fetchProviderDownloadResponseMock.mockImplementation(
     const response = await minimaxProviderHttpMocks.fetchWithTimeoutMock(
       params.url,
       params.init ?? {},
-      resolveMockProviderTimeoutMs(params.timeoutMs),
+      resolveMockProviderDownloadTimeoutMs(params),
       params.fetchFn,
     );
     await minimaxProviderHttpMocks.assertOkOrThrowHttpErrorMock(
@@ -156,15 +165,34 @@ vi.mock("openclaw/plugin-sdk/provider-http", async (importActual) => {
       timeoutMs,
     }: {
       label: string;
-      timeoutMs?: number;
-    }) => ({
-      label,
-      timeoutMs,
-    }),
+      timeoutMs?: number | (() => number);
+    }) => {
+      const resolvedTimeoutMs = typeof timeoutMs === "function" ? timeoutMs() : timeoutMs;
+      return {
+        label,
+        timeoutMs: resolvedTimeoutMs,
+        deadlineAtMs:
+          typeof resolvedTimeoutMs === "number" ? Date.now() + resolvedTimeoutMs : undefined,
+      };
+    },
     createProviderOperationTimeoutResolver:
-      ({ defaultTimeoutMs }: { defaultTimeoutMs: number }) =>
-      () =>
+      ({
+        deadline,
         defaultTimeoutMs,
+      }: {
+        deadline: { deadlineAtMs?: number; label: string; timeoutMs?: number };
+        defaultTimeoutMs: number;
+      }) =>
+      () => {
+        if (typeof deadline.deadlineAtMs !== "number") {
+          return defaultTimeoutMs;
+        }
+        const remainingMs = deadline.deadlineAtMs - Date.now();
+        if (remainingMs <= 0) {
+          throw new Error(`${deadline.label} timed out after ${deadline.timeoutMs}ms`);
+        }
+        return Math.min(defaultTimeoutMs, remainingMs);
+      },
     executeProviderOperationWithRetry:
       minimaxProviderHttpMocks.executeProviderOperationWithRetryMock,
     fetchProviderDownloadResponse: minimaxProviderHttpMocks.fetchProviderDownloadResponseMock,
diff --git a/extensions/minimax/video-generation-provider.ts b/extensions/minimax/video-generation-provider.ts
index b84e1841b60..cc0f707e63b 100644
--- a/extensions/minimax/video-generation-provider.ts
+++ b/extensions/minimax/video-generation-provider.ts
@@ -248,6 +248,10 @@ async function pollMinimaxVideo(params: {
     timeoutMs: params.timeoutMs,
     label: `MiniMax video generation task ${params.taskId}`,
   });
+  const resolveTimeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+  });
   for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
     const url = new URL(`${params.baseUrl}/v1/query/video_generation`);
     url.searchParams.set("task_id", params.taskId);
@@ -258,10 +262,7 @@ async function pollMinimaxVideo(params: {
         method: "GET",
         headers: params.headers,
       },
-      timeoutMs: createProviderOperationTimeoutResolver({
-        deadline,
-        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
-      }),
+      timeoutMs: resolveTimeoutMs,
       fetchFn: params.fetchFn,
       requestFailedMessage: "MiniMax video status request failed",
       policy: params.policy,
@@ -271,6 +272,11 @@ async function pollMinimaxVideo(params: {
       payload = await readProviderJsonResponse<MinimaxQueryResponse>(
         response,
         "MiniMax video generation failed",
+        {
+          timeoutMs: resolveTimeoutMs,
+          onTimeout: ({ timeoutMs }) =>
+            new Error(`MiniMax video generation timed out after ${timeoutMs}ms`),
+        },
       );
     } finally {
       await release();
@@ -299,11 +305,19 @@ async function downloadVideoFromUrl(params: {
   maxBytes: number;
   policy: MinimaxRequestPolicy;
 }): Promise<GeneratedVideoAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "MiniMax generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const { response, release } = await fetchMinimaxResponse({
     stage: "download",
     url: params.url,
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    timeoutMs,
     fetchFn: params.fetchFn,
     requestFailedMessage: "MiniMax generated video download failed",
     policy: params.policy,
@@ -311,6 +325,11 @@ async function downloadVideoFromUrl(params: {
   try {
     const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
     const buffer = await readResponseWithLimit(response, params.maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `MiniMax generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes }) =>
         new Error(`MiniMax generated video download exceeds ${maxBytes} bytes`),
     });
@@ -335,6 +354,14 @@ async function downloadVideoFromFileId(params: {
 }): Promise<GeneratedVideoAsset> {
   const url = new URL(`${params.baseUrl}/v1/files/retrieve`);
   url.searchParams.set("file_id", params.fileId);
+  const metadataDeadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "MiniMax generated video metadata",
+  });
+  const metadataTimeoutMs = createProviderOperationTimeoutResolver({
+    deadline: metadataDeadline,
+    defaultTimeoutMs: metadataDeadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const { response: metadataResponse, release: releaseMetadata } = await fetchMinimaxResponse({
     stage: "download",
     url: url.toString(),
@@ -342,7 +369,7 @@ async function downloadVideoFromFileId(params: {
       method: "GET",
       headers: params.headers,
     },
-    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    timeoutMs: metadataTimeoutMs,
     fetchFn: params.fetchFn,
     requestFailedMessage: "MiniMax generated video metadata request failed",
     policy: params.policy,
@@ -352,6 +379,13 @@ async function downloadVideoFromFileId(params: {
     metadata = await readProviderJsonResponse<MinimaxFileRetrieveResponse>(
       metadataResponse,
       "MiniMax generated video metadata",
+      {
+        timeoutMs: metadataTimeoutMs,
+        onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+          new Error(
+            `MiniMax generated video metadata timed out after ${metadataDeadline.timeoutMs ?? bodyTimeoutMs}ms`,
+          ),
+      },
     );
   } finally {
     await releaseMetadata();
@@ -361,11 +395,19 @@ async function downloadVideoFromFileId(params: {
   if (!downloadUrl) {
     throw new Error("MiniMax generated video metadata missing download_url");
   }
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "MiniMax generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const { response, release } = await fetchMinimaxResponse({
     stage: "download",
     url: downloadUrl,
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    timeoutMs,
     fetchFn: params.fetchFn,
     requestFailedMessage: "MiniMax generated video download failed",
     policy: params.policy,
@@ -373,6 +415,11 @@ async function downloadVideoFromFileId(params: {
   try {
     const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
     const buffer = await readResponseWithLimit(response, params.maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `MiniMax generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes }) =>
         new Error(`MiniMax generated video download exceeds ${maxBytes} bytes`),
     });
diff --git a/extensions/openai/video-generation-provider.ts b/extensions/openai/video-generation-provider.ts
index e4e6fdfa46f..a93d42a57e1 100644
--- a/extensions/openai/video-generation-provider.ts
+++ b/extensions/openai/video-generation-provider.ts
@@ -183,26 +183,23 @@ async function pollOpenAIVideo(
   });
 }
 
-function resolveOpenAIVideoDownloadTimeoutMs(timeoutMs: ProviderOperationTimeoutMs | undefined) {
-  const resolved = typeof timeoutMs === "function" ? timeoutMs() : timeoutMs;
-  return typeof resolved === "number" && Number.isFinite(resolved) && resolved > 0
-    ? resolved
-    : DEFAULT_TIMEOUT_MS;
-}
-
 async function fetchOpenAIVideoDownload(
   params: {
     url: string;
     init: RequestInit;
-    timeoutMs?: ProviderOperationTimeoutMs;
+    deadline: ReturnType<typeof createProviderOperationDeadline>;
     fetchFn: typeof fetch;
   } & OpenAIVideoRequestPolicy,
 ) {
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline: params.deadline,
+    defaultTimeoutMs: params.deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   if (!params.allowPrivateNetwork && !params.dispatcherPolicy) {
     const response = await fetchProviderDownloadResponse({
       url: params.url,
       init: params.init,
-      timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      deadline: params.deadline,
       fetchFn: params.fetchFn,
       provider: "openai",
       requestFailedMessage: "OpenAI video download failed",
@@ -220,7 +217,7 @@ async function fetchOpenAIVideoDownload(
       const result = await fetchWithTimeoutGuarded(
         params.url,
         params.init,
-        resolveOpenAIVideoDownloadTimeoutMs(params.timeoutMs),
+        timeoutMs(),
         params.fetchFn,
         {
           ...(params.allowPrivateNetwork ? { ssrfPolicy: { allowPrivateNetwork: true } } : {}),
@@ -251,6 +248,14 @@ async function downloadOpenAIVideo(
 ): Promise<GeneratedVideoAsset> {
   const url = new URL(`${params.baseUrl}/videos/${params.videoId}/content`);
   url.searchParams.set("variant", "video");
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "OpenAI generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const { response, release } = await fetchOpenAIVideoDownload({
     url: url.toString(),
     init: {
@@ -260,7 +265,7 @@ async function downloadOpenAIVideo(
         Accept: "application/binary",
       }),
     },
-    timeoutMs: params.timeoutMs,
+    deadline,
     fetchFn: params.fetchFn,
     allowPrivateNetwork: params.allowPrivateNetwork,
     dispatcherPolicy: params.dispatcherPolicy,
@@ -268,6 +273,11 @@ async function downloadOpenAIVideo(
   try {
     const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
     const buffer = await readResponseWithLimit(response, params.maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `OpenAI generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes }) =>
         new Error(`OpenAI generated video download exceeds ${maxBytes} bytes`),
     });
diff --git a/extensions/runway/video-generation-provider.ts b/extensions/runway/video-generation-provider.ts
index 8b82a9111c5..5d7f1b55d60 100644
--- a/extensions/runway/video-generation-provider.ts
+++ b/extensions/runway/video-generation-provider.ts
@@ -7,12 +7,11 @@ import {
   createProviderOperationDeadline,
   createProviderOperationTimeoutResolver,
   fetchProviderDownloadResponse,
-  fetchProviderOperationResponse,
+  pollProviderOperationJson,
   postJsonRequest,
   readProviderJsonResponse,
   resolveProviderOperationTimeoutMs,
   resolveProviderHttpRequestConfig,
-  waitProviderOperationPollInterval,
   type ProviderOperationTimeoutMs,
 } from "openclaw/plugin-sdk/provider-http";
 import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
@@ -279,42 +278,25 @@ async function pollRunwayTask(params: {
     timeoutMs: params.timeoutMs,
     label: `Runway video generation task ${params.taskId}`,
   });
-  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
-    const response = await fetchProviderOperationResponse({
-      stage: "poll",
-      url: `${params.baseUrl}/v1/tasks/${params.taskId}`,
-      init: {
-        method: "GET",
-        headers: params.headers,
-      },
-      timeoutMs: createProviderOperationTimeoutResolver({
-        deadline,
-        defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
-      }),
-      fetchFn: params.fetchFn,
-      provider: "runway",
-      requestFailedMessage: "Runway video status request failed",
-    });
-    const payload = await readRunwayJsonResponse<RunwayTaskDetailResponse>(
-      response,
-      "Runway video status request failed",
-    );
-    const status = readRunwayTaskStatus(payload);
-    switch (status) {
-      case "SUCCEEDED":
-        return payload;
-      case "FAILED":
-      case "CANCELLED":
-        throw new Error(
-          readRunwayFailureMessage(payload.failure) ||
-            `Runway video generation ${normalizeLowercaseStringOrEmpty(status)}`,
-        );
-      default:
-        await waitProviderOperationPollInterval({ deadline, pollIntervalMs: POLL_INTERVAL_MS });
-        break;
-    }
-  }
-  throw new Error(`Runway video generation task ${params.taskId} did not finish in time`);
+  return await pollProviderOperationJson<RunwayTaskDetailResponse>({
+    url: `${params.baseUrl}/v1/tasks/${params.taskId}`,
+    headers: params.headers,
+    deadline,
+    defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+    fetchFn: params.fetchFn,
+    maxAttempts: MAX_POLL_ATTEMPTS,
+    pollIntervalMs: POLL_INTERVAL_MS,
+    requestFailedMessage: "Runway video status request failed",
+    timeoutMessage: `Runway video generation task ${params.taskId} did not finish in time`,
+    isComplete: (payload) => readRunwayTaskStatus(payload) === "SUCCEEDED",
+    getFailureMessage: (payload) => {
+      const status = readRunwayTaskStatus(payload);
+      return status === "FAILED" || status === "CANCELLED"
+        ? readRunwayFailureMessage(payload.failure) ||
+            `Runway video generation ${normalizeLowercaseStringOrEmpty(status)}`
+        : undefined;
+    },
+  });
 }
 
 async function downloadRunwayVideos(params: {
@@ -325,16 +307,29 @@ async function downloadRunwayVideos(params: {
 }): Promise<GeneratedVideoAsset[]> {
   const videos: GeneratedVideoAsset[] = [];
   for (const [index, url] of params.urls.entries()) {
+    const deadline = createProviderOperationDeadline({
+      timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      label: "Runway generated video download",
+    });
+    const timeoutMs = createProviderOperationTimeoutResolver({
+      deadline,
+      defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    });
     const response = await fetchProviderDownloadResponse({
       url,
       init: { method: "GET" },
-      timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      deadline,
       fetchFn: params.fetchFn,
       provider: "runway",
       requestFailedMessage: "Runway generated video download failed",
     });
     const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
     const buffer = await readResponseWithLimit(response, params.maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `Runway generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes }) =>
         new Error(`Runway generated video download exceeds ${maxBytes} bytes`),
     });
diff --git a/extensions/synology-chat/src/client.loopback.test.ts b/extensions/synology-chat/src/client.loopback.test.ts
index 6449cb6cc4f..6004cbd86bb 100644
--- a/extensions/synology-chat/src/client.loopback.test.ts
+++ b/extensions/synology-chat/src/client.loopback.test.ts
@@ -8,6 +8,18 @@ const USER_LIST_RESPONSE_MAX_BYTES = 1 * 1024 * 1024;
 describe("Synology Chat user_list loopback", () => {
   let server: http.Server | undefined;
 
+  async function listenLoopback(handler: http.RequestListener): Promise<number> {
+    server = http.createServer(handler);
+    server.on("clientError", (_err, socket) => socket.destroy());
+    server.listen(0, "127.0.0.1");
+    await once(server, "listening");
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("expected loopback server address");
+    }
+    return address.port;
+  }
+
   afterEach(async () => {
     vi.restoreAllMocks();
     if (server) {
@@ -21,7 +33,7 @@ describe("Synology Chat user_list loopback", () => {
 
   it("aborts a streamed overflow and returns the stale cached identity", async () => {
     let requestCount = 0;
-    server = http.createServer((_req, res) => {
+    const port = await listenLoopback((_req, res) => {
       requestCount += 1;
       res.on("error", () => {});
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -37,16 +49,8 @@ describe("Synology Chat user_list loopback", () => {
       res.write(Buffer.alloc(USER_LIST_RESPONSE_MAX_BYTES, 0x78));
       res.end(Buffer.from("x"));
     });
-    server.on("clientError", (_err, socket) => socket.destroy());
-    server.listen(0, "127.0.0.1");
-    await once(server, "listening");
-
-    const address = server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("expected loopback server address");
-    }
     const incomingUrl =
-      `http://127.0.0.1:${address.port}/webapi/entry.cgi?` +
+      `http://127.0.0.1:${port}/webapi/entry.cgi?` +
       "api=SYNO.Chat.External&method=chatbot&version=2";
     const now = vi.spyOn(Date, "now");
     now.mockReturnValue(1_700_000_000_000);
@@ -76,7 +80,7 @@ describe("Synology Chat user_list loopback", () => {
 
   it("bounds a dripping user_list body with a wall-clock deadline", async () => {
     let requestCount = 0;
-    server = http.createServer((_req, res) => {
+    const port = await listenLoopback((_req, res) => {
       requestCount += 1;
       res.on("error", () => {});
       res.writeHead(200, {
@@ -102,16 +106,8 @@ describe("Synology Chat user_list loopback", () => {
       res.on("close", () => clearInterval(dripTimer));
       res.write("x");
     });
-    server.on("clientError", (_err, socket) => socket.destroy());
-    server.listen(0, "127.0.0.1");
-    await once(server, "listening");
-
-    const address = server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("expected loopback server address");
-    }
     const incomingUrl =
-      `http://127.0.0.1:${address.port}/webapi/entry.cgi?` +
+      `http://127.0.0.1:${port}/webapi/entry.cgi?` +
       "api=SYNO.Chat.External&method=chatbot&version=2";
     const now = vi.spyOn(Date, "now");
     now.mockReturnValue(1_700_000_100_000);
@@ -152,7 +148,7 @@ describe("Synology Chat user_list loopback", () => {
 
   it("bounds a dripping chatbot response with a wall-clock deadline", async () => {
     let requestCount = 0;
-    server = http.createServer((_req, res) => {
+    const port = await listenLoopback((_req, res) => {
       requestCount += 1;
       res.on("error", () => {});
       res.writeHead(200, {
@@ -167,15 +163,7 @@ describe("Synology Chat user_list loopback", () => {
       res.on("close", () => clearInterval(dripTimer));
       res.write("x");
     });
-    server.on("clientError", (_err, socket) => socket.destroy());
-    server.listen(0, "127.0.0.1");
-    await once(server, "listening");
-
-    const address = server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("expected loopback server address");
-    }
-    const incomingUrl = `http://127.0.0.1:${address.port}/webapi/entry.cgi`;
+    const incomingUrl = `http://127.0.0.1:${port}/webapi/entry.cgi`;
     const timeoutMs = 250;
     const nativeSetTimeout = globalThis.setTimeout;
     const timeoutSpy = vi.spyOn(globalThis, "setTimeout");
diff --git a/extensions/together/video-generation-provider.ts b/extensions/together/video-generation-provider.ts
index 97a2334282d..594c569a54d 100644
--- a/extensions/together/video-generation-provider.ts
+++ b/extensions/together/video-generation-provider.ts
@@ -153,16 +153,29 @@ async function downloadTogetherVideo(params: {
   fetchFn: typeof fetch;
   maxBytes: number;
 }): Promise<GeneratedVideoAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    label: "Together generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
   const response = await fetchProviderDownloadResponse({
     url: params.url,
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    deadline,
     fetchFn: params.fetchFn,
     provider: "together",
     requestFailedMessage: "Together generated video download failed",
   });
   const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
   const buffer = await readResponseWithLimit(response, params.maxBytes, {
+    timeoutMs,
+    onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+      new Error(
+        `Together generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+      ),
     onOverflow: ({ maxBytes }) =>
       new Error(`Together generated video download exceeds ${maxBytes} bytes`),
   });
diff --git a/extensions/vydra/shared.test.ts b/extensions/vydra/shared.test.ts
index 02000c03921..035f51b6e7a 100644
--- a/extensions/vydra/shared.test.ts
+++ b/extensions/vydra/shared.test.ts
@@ -172,31 +172,12 @@ describe("downloadVydraAsset", () => {
 
   it("does not bound a dripping body when only chunk idle timeout is used", async () => {
     // Negative control: chunkTimeoutMs resets on every drip, so idle alone never fires.
-    server = http.createServer((_req, res) => {
-      res.on("error", () => {});
-      res.writeHead(200, {
-        "Content-Type": "image/png",
-        "Transfer-Encoding": "chunked",
-      });
-      const drip = () => {
-        if (res.writableEnded || res.destroyed) {
-          return;
-        }
-        res.write(Buffer.from([0x00]));
-        const timer = setTimeout(drip, 20);
-        dripTimers.add(timer);
-      };
-      drip();
+    const port = await listenDripServer({
+      statusCode: 200,
+      contentType: "image/png",
+      chunk: Buffer.from([0x00]),
     });
-    server.listen(0, "127.0.0.1");
-    await once(server, "listening");
-
-    const address = server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("expected loopback server address");
-    }
-
-    const response = await fetch(`http://127.0.0.1:${address.port}/`);
+    const response = await fetch(`http://127.0.0.1:${port}/`);
     let settled = false;
     void readResponseWithLimit(response, 1024 * 1024, {
       chunkTimeoutMs: 100,
diff --git a/extensions/vydra/shared.ts b/extensions/vydra/shared.ts
index 33b87fb9bee..0c1474c5e6e 100644
--- a/extensions/vydra/shared.ts
+++ b/extensions/vydra/shared.ts
@@ -4,20 +4,15 @@ import { extensionForMime } from "openclaw/plugin-sdk/media-mime";
 import { resolveApiKeyForProvider } from "openclaw/plugin-sdk/provider-auth-runtime";
 import {
   assertOkOrThrowHttpError,
-  createProviderHttpError,
   createProviderOperationDeadline,
+  createProviderOperationTimeoutResolver,
   fetchWithTimeout,
-  readProviderJsonResponse,
-  resolveProviderOperationTimeoutMs,
+  pollProviderOperationJson,
   resolveProviderHttpRequestConfig,
-  waitProviderOperationPollInterval,
   type ProviderOperationDeadline,
   type ProviderOperationTimeoutMs,
 } from "openclaw/plugin-sdk/provider-http";
-import {
-  readResponseTextPrefix,
-  readResponseWithLimit,
-} from "openclaw/plugin-sdk/response-limit-runtime";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -38,8 +33,6 @@ type VydraAuthStore = Parameters<typeof resolveApiKeyForProvider>[0]["store"];
 
 type VydraMediaKind = "audio" | "image" | "video";
 
-class VydraDownloadBodyTimeoutError extends Error {}
-
 type VydraJobPayload = {
   id?: string;
   jobId?: string;
@@ -222,6 +215,12 @@ function resolveVydraHttpTimeoutMs(timeoutMs: ProviderOperationTimeoutMs | undef
   return resolved;
 }
 
+function createVydraTimeoutError(deadline: ProviderOperationDeadline): Error {
+  const timeoutLabel =
+    typeof deadline.timeoutMs === "number" ? ` after ${deadline.timeoutMs}ms` : "";
+  return new Error(`${deadline.label} timed out${timeoutLabel}`);
+}
+
 export function resolveVydraGeneratedMediaMaxBytes(params: {
   cfg: { agents?: { defaults?: { mediaMaxMb?: number } } };
   kind: VydraMediaKind;
@@ -239,25 +238,6 @@ export function resolveVydraGeneratedMediaMaxBytes(params: {
   return DEFAULT_GENERATED_VIDEO_MAX_BYTES;
 }
 
-function resolveVydraDownloadBodyTimeout(params: {
-  kind: VydraMediaKind;
-  timeoutMs: number;
-  deadlineMs: number;
-}) {
-  return {
-    chunkTimeoutMs: params.timeoutMs,
-    timeoutMs: Math.max(1, params.deadlineMs - Date.now()),
-    onIdleTimeout: ({ chunkTimeoutMs }: { chunkTimeoutMs: number }) =>
-      new VydraDownloadBodyTimeoutError(
-        `Vydra ${params.kind} download stalled after ${chunkTimeoutMs}ms`,
-      ),
-    onTimeout: () =>
-      new VydraDownloadBodyTimeoutError(
-        `Vydra ${params.kind} download timed out after ${params.timeoutMs}ms`,
-      ),
-  };
-}
-
 export async function downloadVydraAsset(params: {
   url: string;
   kind: VydraMediaKind;
@@ -266,47 +246,30 @@ export async function downloadVydraAsset(params: {
   maxBytes: number;
 }): Promise<{ buffer: Buffer; mimeType: string; fileName: string }> {
   const timeoutMs = resolveVydraHttpTimeoutMs(params.timeoutMs);
-  // fetchWithTimeout clears its abort after headers land. Keep one wall-clock deadline across
-  // non-2xx error-detail and successful-body reads so a slow drip cannot reset chunk idle forever.
-  const deadlineMs = Date.now() + timeoutMs;
-  const response = await fetchWithTimeout(params.url, { method: "GET" }, timeoutMs, params.fetchFn);
-  if (!response.ok) {
-    // Shared assertOkOrThrowHttpError reads error detail without a wall-clock bound; a dripping
-    // non-2xx body would hang before the success-path reader runs.
-    let errorBody: string | null = null;
-    try {
-      errorBody =
-        (
-          await readResponseTextPrefix(
-            response,
-            16 * 1024,
-            resolveVydraDownloadBodyTimeout({ kind: params.kind, timeoutMs, deadlineMs }),
-          )
-        ).text || null;
-    } catch (error) {
-      if (error instanceof VydraDownloadBodyTimeoutError) {
-        throw error;
-      }
-      // The shared formatter historically ignored unreadable error bodies. Preserve the known
-      // HTTP status and request id even when the provider closes a failed response mid-stream.
-    }
-    // Re-run the bounded body through the shared formatter so provider error metadata and
-    // sensitive-text redaction remain identical to the previous assertOkOrThrowHttpError path.
-    throw await createProviderHttpError(
-      new Response(errorBody, {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-      }),
-      `Vydra ${params.kind} download failed`,
-      { statusPrefix: "HTTP " },
-    );
-  }
+  const deadline = createProviderOperationDeadline({
+    timeoutMs,
+    label: `Vydra ${params.kind} download`,
+  });
+  const resolveTimeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: timeoutMs,
+  });
+  const response = await fetchWithTimeout(
+    params.url,
+    { method: "GET" },
+    resolveTimeoutMs(),
+    params.fetchFn,
+  );
+  await assertOkOrThrowHttpError(response, `Vydra ${params.kind} download failed`, {
+    bodyTimeoutMs: resolveTimeoutMs,
+    onBodyTimeout: () => createVydraTimeoutError(deadline),
+  });
   const mimeType =
     response.headers.get("content-type")?.trim() ||
     (params.kind === "image" ? "image/png" : params.kind === "audio" ? "audio/mpeg" : "video/mp4");
   const buffer = await readResponseWithLimit(response, params.maxBytes, {
-    ...resolveVydraDownloadBodyTimeout({ kind: params.kind, timeoutMs, deadlineMs }),
+    timeoutMs: resolveTimeoutMs,
+    onTimeout: () => createVydraTimeoutError(deadline),
     onOverflow: ({ maxBytes }) =>
       new Error(`Vydra ${params.kind} download exceeds ${maxBytes} bytes`),
   });
@@ -334,28 +297,26 @@ async function waitForVydraJob(params: {
       timeoutMs: params.timeoutMs,
       label: `Vydra job ${params.jobId}`,
     });
-  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt += 1) {
-    const response = await fetchWithTimeout(
-      `${params.baseUrl}/jobs/${params.jobId}`,
-      {
-        method: "GET",
-        headers: params.headers,
-      },
-      resolveProviderOperationTimeoutMs({ deadline, defaultTimeoutMs: DEFAULT_HTTP_TIMEOUT_MS }),
-      params.fetchFn,
-    );
-    await assertOkOrThrowHttpError(response, "Vydra job status request failed");
-    const payload = await readProviderJsonResponse<unknown>(response, "Vydra job status");
-    const status = resolveVydraResponseStatus(payload);
-    if (status === "completed" || extractVydraResultUrls(payload, params.kind).length > 0) {
-      return payload;
-    }
-    if (status === "failed" || status === "error" || status === "cancelled") {
-      throw new Error(resolveVydraErrorMessage(payload) ?? `Vydra job ${params.jobId} failed`);
-    }
-    await waitProviderOperationPollInterval({ deadline, pollIntervalMs: POLL_INTERVAL_MS });
-  }
-  throw new Error(`Vydra job ${params.jobId} did not finish in time`);
+  return await pollProviderOperationJson<unknown>({
+    url: `${params.baseUrl}/jobs/${params.jobId}`,
+    headers: params.headers,
+    deadline,
+    defaultTimeoutMs: DEFAULT_HTTP_TIMEOUT_MS,
+    fetchFn: params.fetchFn,
+    maxAttempts: MAX_POLL_ATTEMPTS,
+    pollIntervalMs: POLL_INTERVAL_MS,
+    requestFailedMessage: "Vydra job status request failed",
+    timeoutMessage: `Vydra job ${params.jobId} did not finish in time`,
+    isComplete: (payload) =>
+      resolveVydraResponseStatus(payload) === "completed" ||
+      extractVydraResultUrls(payload, params.kind).length > 0,
+    getFailureMessage: (payload) => {
+      const status = resolveVydraResponseStatus(payload);
+      return status === "failed" || status === "error" || status === "cancelled"
+        ? (resolveVydraErrorMessage(payload) ?? `Vydra job ${params.jobId} failed`)
+        : undefined;
+    },
+  });
 }
 
 export async function resolveCompletedVydraPayload(params: {
diff --git a/extensions/xai/video-generation-provider.test.ts b/extensions/xai/video-generation-provider.test.ts
index 1c79d356633..a328bb234d6 100644
--- a/extensions/xai/video-generation-provider.test.ts
+++ b/extensions/xai/video-generation-provider.test.ts
@@ -359,7 +359,8 @@ describe("xai video generation provider", () => {
     expect(pollRequest.url).toBe("https://api.x.ai/v1/videos/req_123");
     expect(pollRequest.init?.method).toBe("GET");
     expect(provider.defaultTimeoutMs).toBe(600_000);
-    expect(pollRequest.timeoutMs).toBe(600_000);
+    expect(pollRequest.timeoutMs).toBeGreaterThan(599_000);
+    expect(pollRequest.timeoutMs).toBeLessThanOrEqual(600_000);
     expect(result.videos[0]?.mimeType).toBe("video/webm");
     expect(result.videos[0]?.fileName).toBe("video-1.webm");
     expect(result.metadata?.requestId).toBe("req_123");
diff --git a/extensions/xai/video-generation-transport.ts b/extensions/xai/video-generation-transport.ts
index 0ff08f42a46..d5065fbe957 100644
--- a/extensions/xai/video-generation-transport.ts
+++ b/extensions/xai/video-generation-transport.ts
@@ -1,6 +1,8 @@
 import { extensionForMime } from "openclaw/plugin-sdk/media-mime";
 import {
   assertOkOrThrowHttpError,
+  createProviderOperationDeadline,
+  createProviderOperationTimeoutResolver,
   executeProviderOperationWithRetry,
   fetchWithTimeoutGuarded,
   type ProviderOperationTimeoutMs,
@@ -71,13 +73,21 @@ export async function downloadXaiVideo(
     maxBytes: number;
   } & XaiVideoRequestPolicy,
 ): Promise<GeneratedVideoAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs ?? params.defaultTimeoutMs,
+    label: "xAI generated video download",
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: deadline.timeoutMs ?? params.defaultTimeoutMs,
+  });
   const { response, release } = await fetchXaiVideoResponse({
     url: params.url,
     stage: "download",
     requestFailedMessage: "xAI generated video download failed",
     auditContext: "xai-video-download",
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs,
+    timeoutMs,
     defaultTimeoutMs: params.defaultTimeoutMs,
     allowPrivateNetwork: params.allowPrivateNetwork,
     dispatcherPolicy: params.dispatcherPolicy,
@@ -86,6 +96,11 @@ export async function downloadXaiVideo(
   try {
     const mimeType = normalizeOptionalString(response.headers.get("content-type")) ?? "video/mp4";
     const buffer = await readResponseWithLimit(response, params.maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `xAI generated video download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes }) =>
         new Error(`xAI generated video download exceeds ${maxBytes} bytes`),
     });
diff --git a/packages/ai/src/internal/openai.ts b/packages/ai/src/internal/openai.ts
index 3461d7df5c1..7b58db5ca9c 100644
--- a/packages/ai/src/internal/openai.ts
+++ b/packages/ai/src/internal/openai.ts
@@ -10,6 +10,7 @@ export * from "../providers/openai-responses-stream-compat.js";
 export * from "../providers/openai-responses-tool-call-tracker.js";
 export * from "../providers/openai-stop-reason.js";
 export * from "../providers/openai-tool-projection.js";
+export * from "../providers/openai-tool-schema-compat.js";
 export * from "../providers/openai-tool-schema.js";
 export * from "../providers/schema-keyword-strip.js";
 export * from "../providers/tool-schema-json-projection.js";
diff --git a/packages/ai/src/providers/openai-tool-schema-compat.ts b/packages/ai/src/providers/openai-tool-schema-compat.ts
new file mode 100644
index 00000000000..d8868e0128c
--- /dev/null
+++ b/packages/ai/src/providers/openai-tool-schema-compat.ts
@@ -0,0 +1,245 @@
+import type { TSchema } from "typebox";
+
+type NormalizeOpenAIStrictCompatOptions = {
+  promoteEmptyObject: boolean;
+};
+
+const OPENAI_STRICT_COMPAT_SCHEMA_MAP_KEYS = new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  // Draft-07 dependencies mix schema values with property-name arrays. The
+  // recursive helpers leave scalar array entries untouched.
+  "dependencies",
+  "patternProperties",
+  "properties",
+]);
+
+// Annotation-only keywords whose null values can be dropped without changing
+// what the schema accepts; null constraint keywords must stay so projection
+// quarantines the tool instead of widening it.
+const OPENAI_NULLABLE_ANNOTATION_KEYS = new Set([
+  "default",
+  "description",
+  "examples",
+  "format",
+  "title",
+]);
+
+const OPENAI_STRICT_COMPAT_SCHEMA_NESTED_KEYS = new Set([
+  "additionalItems",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "oneOf",
+  "prefixItems",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+]);
+
+function normalizeOpenAIStrictCompatSchemaMap(schema: unknown): unknown {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return schema;
+  }
+
+  let changed = false;
+  const normalized: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
+    const next = normalizeOpenAIStrictCompatSchemaRecursive(value, {
+      promoteEmptyObject: false,
+    });
+    normalized[key] = next;
+    changed ||= next !== value;
+  }
+  return changed ? normalized : schema;
+}
+
+function normalizeOpenAIStrictCompatSchemaRecursive(
+  schema: unknown,
+  options: NormalizeOpenAIStrictCompatOptions,
+): unknown {
+  if (Array.isArray(schema)) {
+    let changed = false;
+    const normalized = schema.map((entry) => {
+      const next = normalizeOpenAIStrictCompatSchemaRecursive(entry, {
+        promoteEmptyObject: false,
+      });
+      changed ||= next !== entry;
+      return next;
+    });
+    return changed ? normalized : schema;
+  }
+  if (!schema || typeof schema !== "object") {
+    return schema;
+  }
+
+  const record = schema as Record<string, unknown>;
+  let changed = false;
+  let hadNullType = false;
+  const normalized: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    // Repair only null-valued entries that carry no constraint semantics.
+    // Null constraints stay invalid so projection quarantines the tool.
+    if (value === null && OPENAI_NULLABLE_ANNOTATION_KEYS.has(key)) {
+      changed = true;
+      continue;
+    }
+    if (value === null && key === "type") {
+      hadNullType = true;
+      changed = true;
+      continue;
+    }
+    const next = OPENAI_STRICT_COMPAT_SCHEMA_MAP_KEYS.has(key)
+      ? normalizeOpenAIStrictCompatSchemaMap(value)
+      : OPENAI_STRICT_COMPAT_SCHEMA_NESTED_KEYS.has(key)
+        ? normalizeOpenAIStrictCompatSchemaRecursive(value, {
+            promoteEmptyObject: false,
+          })
+        : value;
+    normalized[key] = next;
+    changed ||= next !== value;
+  }
+
+  if (Object.keys(normalized).length === 0) {
+    if (!options.promoteEmptyObject) {
+      return schema;
+    }
+    return {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    };
+  }
+
+  const hasObjectShapeHints =
+    (normalized.properties &&
+      typeof normalized.properties === "object" &&
+      !Array.isArray(normalized.properties)) ||
+    Array.isArray(normalized.required);
+  const hasArrayShapeHints = "items" in normalized;
+  if (!("type" in normalized) && hasObjectShapeHints !== hasArrayShapeHints) {
+    normalized.type = hasObjectShapeHints ? "object" : "array";
+    changed = true;
+  } else if (hadNullType && !("type" in normalized)) {
+    // Without an unambiguous shape, retain the invalid type so projection
+    // rejects the tool instead of widening it to an unconstrained schema.
+    normalized.type = null;
+  }
+  if (normalized.type === "object" && !("properties" in normalized)) {
+    normalized.properties = {};
+    changed = true;
+  }
+
+  const hasEmptyProperties =
+    normalized.properties &&
+    typeof normalized.properties === "object" &&
+    !Array.isArray(normalized.properties) &&
+    Object.keys(normalized.properties as Record<string, unknown>).length === 0;
+
+  if (normalized.type === "object" && !Array.isArray(normalized.required) && hasEmptyProperties) {
+    normalized.required = [];
+    changed = true;
+  }
+  if (
+    normalized.type === "object" &&
+    hasEmptyProperties &&
+    !("additionalProperties" in normalized)
+  ) {
+    normalized.additionalProperties = false;
+    changed = true;
+  }
+
+  return changed ? normalized : schema;
+}
+
+/** Repairs recoverable OpenAI tool-schema shapes before canonical normalization. */
+export function normalizeOpenAIStrictCompatSchema(schema: unknown): TSchema {
+  return normalizeOpenAIStrictCompatSchemaRecursive(schema, {
+    promoteEmptyObject: true,
+  }) as TSchema;
+}
+
+/** Finds schema paths that violate OpenAI strict tool-schema requirements. */
+export function findOpenAIStrictSchemaViolations(
+  schema: unknown,
+  path: string,
+  options?: { requireObjectRoot?: boolean },
+): string[] {
+  if (Array.isArray(schema)) {
+    if (options?.requireObjectRoot) {
+      return [`${path}.type`];
+    }
+    return schema.flatMap((item, index) =>
+      findOpenAIStrictSchemaViolations(item, `${path}[${index}]`),
+    );
+  }
+  if (!schema || typeof schema !== "object") {
+    return options?.requireObjectRoot ? [`${path}.type`] : [];
+  }
+
+  const record = schema as Record<string, unknown>;
+  const violations: string[] = [];
+  for (const key of ["anyOf", "oneOf", "allOf"] as const) {
+    if (key in record) {
+      violations.push(`${path}.${key}`);
+    }
+  }
+  if (Array.isArray(record.type)) {
+    violations.push(`${path}.type`);
+  }
+
+  const properties =
+    record.properties && typeof record.properties === "object" && !Array.isArray(record.properties)
+      ? (record.properties as Record<string, unknown>)
+      : undefined;
+
+  if (record.type === "object") {
+    if (record.additionalProperties !== false) {
+      violations.push(`${path}.additionalProperties`);
+    }
+    const required = Array.isArray(record.required)
+      ? record.required.filter((entry): entry is string => typeof entry === "string")
+      : undefined;
+    if (!required) {
+      violations.push(`${path}.required`);
+    } else if (properties) {
+      const requiredSet = new Set(required);
+      for (const key of Object.keys(properties)) {
+        if (!requiredSet.has(key)) {
+          violations.push(`${path}.required.${key}`);
+        }
+      }
+    }
+  }
+
+  // Schema maps contain user-chosen names. Walk their values as schemas, but
+  // never interpret map keys such as `$defs.anyOf` as schema keywords.
+  for (const key of OPENAI_STRICT_COMPAT_SCHEMA_MAP_KEYS) {
+    const schemaMap = record[key];
+    if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
+      continue;
+    }
+    for (const [entryKey, value] of Object.entries(schemaMap as Record<string, unknown>)) {
+      violations.push(...findOpenAIStrictSchemaViolations(value, `${path}.${key}.${entryKey}`));
+    }
+  }
+  // Only recurse through JSON Schema applicators. Annotation payloads such as
+  // examples/default may contain arbitrary objects that are not schemas.
+  for (const key of OPENAI_STRICT_COMPAT_SCHEMA_NESTED_KEYS) {
+    const value = record[key];
+    if (value && typeof value === "object") {
+      violations.push(...findOpenAIStrictSchemaViolations(value, `${path}.${key}`));
+    }
+  }
+
+  return violations;
+}
diff --git a/packages/ai/src/providers/openai-tool-schema.test.ts b/packages/ai/src/providers/openai-tool-schema.test.ts
index fa0e32a53bc..305bef130bb 100644
--- a/packages/ai/src/providers/openai-tool-schema.test.ts
+++ b/packages/ai/src/providers/openai-tool-schema.test.ts
@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it } from "vitest";
 import { projectOpenAITools } from "./openai-tool-projection.js";
 import {
   clearOpenAIToolSchemaCacheForTest,
+  findOpenAIStrictSchemaViolations,
   findOpenAIStrictToolProjectionDiagnostics,
   isStrictOpenAIJsonSchemaCompatible,
   normalizeOpenAIStrictToolParameters,
@@ -63,6 +64,54 @@ describe("OpenAI strict tool schema normalization", () => {
     ).toBe(false);
   });
 
+  it("walks named schema maps without treating definition names as keywords", () => {
+    const schema = {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+      $defs: {
+        anyOf: { type: "string" },
+      },
+      examples: [{ anyOf: [{ type: "string" }] }],
+    };
+
+    expect(
+      findOpenAIStrictSchemaViolations(schema, "parameters", { requireObjectRoot: true }),
+    ).toEqual([]);
+  });
+
+  it("walks legacy and content schema applicators", () => {
+    const nestedObject = {
+      type: "object",
+      properties: { value: { type: "string" } },
+    };
+    const schema = {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+      dependencies: {
+        mode: ["payload"],
+        payload: nestedObject,
+      },
+      additionalItems: nestedObject,
+      contentSchema: nestedObject,
+    };
+
+    expect(
+      findOpenAIStrictSchemaViolations(schema, "parameters", { requireObjectRoot: true }),
+    ).toEqual([
+      "parameters.dependencies.payload.additionalProperties",
+      "parameters.dependencies.payload.required",
+      "parameters.additionalItems.additionalProperties",
+      "parameters.additionalItems.required",
+      "parameters.contentSchema.additionalProperties",
+      "parameters.contentSchema.required",
+    ]);
+    expect(isStrictOpenAIJsonSchemaCompatible(schema)).toBe(false);
+  });
+
   it("normalizes truly empty MCP tool schema {} for strict mode", () => {
     const schema = {};
     const normalized = normalizeStrictOpenAIJsonSchema(schema) as Record<string, unknown>;
diff --git a/packages/ai/src/providers/openai-tool-schema.ts b/packages/ai/src/providers/openai-tool-schema.ts
index e9679186d54..8ce3fa8d00d 100644
--- a/packages/ai/src/providers/openai-tool-schema.ts
+++ b/packages/ai/src/providers/openai-tool-schema.ts
@@ -9,6 +9,9 @@ import {
   type ToolSchemaModelCompat,
 } from "./agent-tools-parameter-schema.js";
 import type { OpenAIToolProjection } from "./openai-tool-projection.js";
+import { findOpenAIStrictSchemaViolations } from "./openai-tool-schema-compat.js";
+
+export { findOpenAIStrictSchemaViolations } from "./openai-tool-schema-compat.js";
 
 /**
  * OpenAI strict-tool-schema normalization and diagnostics.
@@ -188,7 +191,7 @@ export function findOpenAIStrictToolProjectionDiagnostics(
       violations: [...diagnostic.violations],
     })),
     ...projection.tools.flatMap((tool) => {
-      const violations = findStrictOpenAIJsonSchemaViolations(
+      const violations = findOpenAIStrictSchemaViolations(
         normalizeStrictOpenAIJsonSchema(tool.parameters),
         `${tool.name}.parameters`,
       );
@@ -246,72 +249,6 @@ function isStrictOpenAIJsonSchemaCompatibleRecursive(schema: unknown): boolean {
   });
 }
 
-function findStrictOpenAIJsonSchemaViolations(schema: unknown, path: string): string[] {
-  if (Array.isArray(schema)) {
-    return schema.flatMap((entry, index) =>
-      findStrictOpenAIJsonSchemaViolations(entry, `${path}[${index}]`),
-    );
-  }
-  if (!schema || typeof schema !== "object") {
-    return [];
-  }
-
-  const record = schema as Record<string, unknown>;
-  const violations: string[] = [];
-  for (const key of ["anyOf", "oneOf", "allOf"] as const) {
-    if (key in record) {
-      violations.push(`${path}.${key}`);
-    }
-  }
-  if (Array.isArray(record.type)) {
-    violations.push(`${path}.type`);
-  }
-  if (record.type === "object") {
-    if (record.additionalProperties !== false) {
-      violations.push(`${path}.additionalProperties`);
-    }
-    const properties =
-      record.properties &&
-      typeof record.properties === "object" &&
-      !Array.isArray(record.properties)
-        ? (record.properties as Record<string, unknown>)
-        : {};
-    const required = Array.isArray(record.required)
-      ? record.required.filter((entry): entry is string => typeof entry === "string")
-      : undefined;
-    if (!required) {
-      violations.push(`${path}.required`);
-    } else {
-      const requiredSet = new Set(required);
-      for (const key of Object.keys(properties)) {
-        if (!requiredSet.has(key)) {
-          violations.push(`${path}.required.${key}`);
-        }
-      }
-    }
-  }
-
-  if (
-    record.properties &&
-    typeof record.properties === "object" &&
-    !Array.isArray(record.properties)
-  ) {
-    for (const [key, value] of Object.entries(record.properties)) {
-      violations.push(...findStrictOpenAIJsonSchemaViolations(value, `${path}.properties.${key}`));
-    }
-  }
-  for (const [key, value] of Object.entries(record)) {
-    if (key === "properties") {
-      continue;
-    }
-    if (value && typeof value === "object") {
-      violations.push(...findStrictOpenAIJsonSchemaViolations(value, `${path}.${key}`));
-    }
-  }
-
-  return violations;
-}
-
 /** Resolves strict mode for the projected tools that will be emitted in the request payload. */
 export function resolveOpenAIProjectedToolsStrictToolFlag(
   projection: OpenAIToolProjection,
diff --git a/packages/media-core/src/read-byte-stream-with-limit.test.ts b/packages/media-core/src/read-byte-stream-with-limit.test.ts
index 464f827a1ca..c9b27b9c359 100644
--- a/packages/media-core/src/read-byte-stream-with-limit.test.ts
+++ b/packages/media-core/src/read-byte-stream-with-limit.test.ts
@@ -15,6 +15,8 @@ describe("readByteStreamWithLimit", () => {
   it("throws and destroys node streams after overflow", async () => {
     const stream = Readable.from([Buffer.alloc(4), Buffer.alloc(4)]);
     const destroySpy = vi.spyOn(stream, "destroy");
+    const errorSpy = vi.fn();
+    stream.on("error", errorSpy);
 
     await expect(
       readByteStreamWithLimit(stream, {
@@ -22,6 +24,7 @@ describe("readByteStreamWithLimit", () => {
         onOverflow: ({ size, maxBytes }) => new Error(`too large ${size}/${maxBytes}`),
       }),
     ).rejects.toThrow("too large 8/7");
-    expect(destroySpy).toHaveBeenCalled();
+    expect(destroySpy).toHaveBeenCalledWith();
+    expect(errorSpy).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/media-core/src/read-byte-stream-with-limit.ts b/packages/media-core/src/read-byte-stream-with-limit.ts
index 16d683e2771..97ac5621ad0 100644
--- a/packages/media-core/src/read-byte-stream-with-limit.ts
+++ b/packages/media-core/src/read-byte-stream-with-limit.ts
@@ -28,20 +28,23 @@ function normalizeByteChunk(chunk: unknown): Buffer {
 
 function destroyReadableOnOverflow(stream: unknown, err: Error): void {
   const readable = stream as {
-    destroy?: (error?: Error) => unknown;
+    destroy?: () => unknown;
     cancel?: (reason?: unknown) => unknown;
   };
   // Stop upstream producers immediately after overflow; otherwise large media
   // streams can continue buffering after the caller has already failed.
   if (typeof readable.destroy === "function") {
     try {
-      readable.destroy(err);
+      // The helper already throws the overflow error to its caller. Passing the
+      // same error to destroy() also emits it on Node streams, which can become
+      // an unrelated uncaught exception after the awaited rejection settles.
+      readable.destroy();
     } catch {}
     return;
   }
   if (typeof readable.cancel === "function") {
     try {
-      void readable.cancel(err);
+      void Promise.resolve(readable.cancel(err)).catch(() => undefined);
     } catch {}
   }
 }
diff --git a/scripts/check-control-ui-performance.mjs b/scripts/check-control-ui-performance.mjs
index 1d3819eb96c..2bc5c605b5c 100644
--- a/scripts/check-control-ui-performance.mjs
+++ b/scripts/check-control-ui-performance.mjs
@@ -156,7 +156,11 @@ function formatViolation(violation) {
     violation.unit === "bytes"
       ? formatControlUiPerformanceBytes(violation.limit)
       : String(violation.limit);
-  return `${violation.metric}: ${actual} exceeds ${limit}`;
+  const exactBytes =
+    violation.unit === "bytes" && actual === limit
+      ? ` (${violation.actual} B vs ${violation.limit} B)`
+      : "";
+  return `${violation.metric}: ${actual} exceeds ${limit}${exactBytes}`;
 }
 
 export function formatControlUiPerformanceReport(
diff --git a/src/agents/provider-http-errors.test.ts b/src/agents/provider-http-errors.test.ts
index 6cb79f45680..276c69084d4 100644
--- a/src/agents/provider-http-errors.test.ts
+++ b/src/agents/provider-http-errors.test.ts
@@ -176,6 +176,56 @@ describe("provider error utils", () => {
     } satisfies Partial<ProviderHttpError>);
   });
 
+  it("propagates a bounded error-body timeout instead of hanging normalization", async () => {
+    vi.useFakeTimers();
+    try {
+      const cancel = vi.fn();
+      const response = new Response(
+        new ReadableStream<Uint8Array>({
+          pull() {
+            return new Promise<void>(() => {});
+          },
+          cancel,
+        }),
+        { status: 503 },
+      );
+      const assertion = expect(
+        assertOkOrThrowHttpError(response, "Provider API error", {
+          bodyTimeoutMs: () => 50,
+          onBodyTimeout: ({ timeoutMs }) => new Error(`provider body timed out ${timeoutMs}`),
+        }),
+      ).rejects.toThrow("provider body timed out 50");
+
+      await vi.advanceTimersByTimeAsync(50);
+      await assertion;
+      expect(cancel).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("propagates an already-expired lazy error-body deadline", async () => {
+    const cancel = vi.fn();
+    const response = new Response(
+      new ReadableStream<Uint8Array>({
+        pull() {
+          return new Promise<void>(() => {});
+        },
+        cancel,
+      }),
+      { status: 503 },
+    );
+
+    await expect(
+      assertOkOrThrowHttpError(response, "Provider API error", {
+        bodyTimeoutMs: () => {
+          throw new Error("provider deadline already expired");
+        },
+      }),
+    ).rejects.toThrow("provider deadline already expired");
+    expect(cancel).toHaveBeenCalledTimes(1);
+  });
+
   it("releases provider error body reader locks after bounded reads complete", async () => {
     const releaseLock = vi.fn();
     const cancel = vi.fn(async () => undefined);
diff --git a/src/agents/provider-http-errors.ts b/src/agents/provider-http-errors.ts
index 0fa813d519d..16a35424430 100644
--- a/src/agents/provider-http-errors.ts
+++ b/src/agents/provider-http-errors.ts
@@ -7,7 +7,11 @@
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 export { asFiniteNumber } from "../../packages/normalization-core/src/number-coercion.js";
 import { normalizeOptionalString as trimToUndefined } from "../../packages/normalization-core/src/string-coerce.js";
-import { readResponseTextPrefix, readResponseWithLimit } from "../infra/http-body.js";
+import {
+  readResponseTextPrefix,
+  readResponseWithLimit,
+  type ReadResponseTextPrefixOptions,
+} from "../infra/http-body.js";
 import { redactSensitiveText } from "../logging/redact.js";
 export { asBoolean } from "../utils/boolean.js";
 export { normalizeOptionalString as trimToUndefined } from "../../packages/normalization-core/src/string-coerce.js";
@@ -17,6 +21,30 @@ const PROVIDER_BINARY_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
 const PROVIDER_JSON_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
 const PROVIDER_TEXT_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
 
+/** Shared timeout and byte-limit options for provider response consumption. */
+type ProviderResponseReadOptions = ReadResponseTextPrefixOptions & {
+  maxBytes?: number;
+};
+
+/** Options for bounded provider error-body normalization. */
+type ProviderHttpErrorOptions = {
+  statusPrefix?: string;
+  bodyTimeoutMs?: ReadResponseTextPrefixOptions["timeoutMs"];
+  onBodyTimeout?: NonNullable<ReadResponseTextPrefixOptions["onTimeout"]>;
+};
+
+class ProviderErrorBodyTimeout extends Error {
+  readonly timeoutError: unknown;
+
+  constructor(timeoutError: unknown) {
+    super(timeoutError instanceof Error ? timeoutError.message : String(timeoutError), {
+      cause: timeoutError,
+    });
+    this.name = "ProviderErrorBodyTimeout";
+    this.timeoutError = timeoutError;
+  }
+}
+
 /** Returns a plain object view for provider JSON payloads when one exists. */
 export function asObject(value: unknown): Record<string, unknown> | undefined {
   return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -38,21 +66,23 @@ function redactProviderErrorBody(body: string): string {
 export async function readResponseTextLimited(
   response: Response,
   limitBytes = 16 * 1024,
+  options?: ReadResponseTextPrefixOptions,
 ): Promise<string> {
   if (limitBytes <= 0) {
     return "";
   }
-  return (await readResponseTextPrefix(response, limitBytes)).text;
+  return (await readResponseTextPrefix(response, limitBytes, options)).text;
 }
 
 /** Reads a successful provider text response under a byte cap. */
 export async function readProviderTextResponse(
   response: Response,
   label: string,
-  opts?: { maxBytes?: number },
+  opts?: ProviderResponseReadOptions,
 ): Promise<string> {
   const maxBytes = opts?.maxBytes ?? PROVIDER_TEXT_RESPONSE_MAX_BYTES;
   const bytes = await readResponseWithLimit(response, maxBytes, {
+    ...opts,
     onOverflow: ({ maxBytes: maxBytesLocal }) =>
       new Error(`${label}: text response exceeds ${maxBytesLocal} bytes`),
   });
@@ -131,8 +161,35 @@ type ProviderHttpErrorInfo = {
 };
 
 /** Extracts normalized provider error metadata while keeping the raw body bounded and redacted. */
-async function extractProviderErrorInfo(response: Response): Promise<ProviderHttpErrorInfo> {
-  const rawBody = trimToUndefined(await readResponseTextLimited(response).catch(() => ""));
+async function extractProviderErrorInfo(
+  response: Response,
+  options?: ProviderHttpErrorOptions,
+): Promise<ProviderHttpErrorInfo> {
+  const bodyTimeoutMs = options?.bodyTimeoutMs;
+  const rawBody = trimToUndefined(
+    await readResponseTextLimited(response, 16 * 1024, {
+      timeoutMs:
+        typeof bodyTimeoutMs === "function"
+          ? () => {
+              try {
+                return bodyTimeoutMs();
+              } catch (error) {
+                throw new ProviderErrorBodyTimeout(error);
+              }
+            }
+          : bodyTimeoutMs,
+      onTimeout: (params) =>
+        new ProviderErrorBodyTimeout(
+          options?.onBodyTimeout?.(params) ??
+            new Error(`Provider error body timed out after ${params.timeoutMs}ms`),
+        ),
+    }).catch((error: unknown) => {
+      if (error instanceof ProviderErrorBodyTimeout) {
+        throw error.timeoutError;
+      }
+      return "";
+    }),
+  );
   const requestId = extractProviderRequestId(response);
   if (!rawBody) {
     return requestId ? { requestId } : {};
@@ -221,9 +278,9 @@ export function formatProviderHttpErrorMessage(params: {
 export async function createProviderHttpError(
   response: Response,
   label: string,
-  options?: { statusPrefix?: string },
+  options?: ProviderHttpErrorOptions,
 ): Promise<Error> {
-  const info = await extractProviderErrorInfo(response);
+  const info = await extractProviderErrorInfo(response, options);
   return new ProviderHttpError(
     formatProviderHttpErrorMessage({
       label,
@@ -246,19 +303,24 @@ export async function createProviderHttpError(
 export async function assertOkOrThrowProviderError(
   response: Response,
   label: string,
+  options?: Omit<ProviderHttpErrorOptions, "statusPrefix">,
 ): Promise<void> {
   if (response.ok) {
     return;
   }
-  throw await createProviderHttpError(response, label);
+  throw await createProviderHttpError(response, label, options);
 }
 
 /** Throws a normalized generic HTTP error when a fetch response is not OK. */
-export async function assertOkOrThrowHttpError(response: Response, label: string): Promise<void> {
+export async function assertOkOrThrowHttpError(
+  response: Response,
+  label: string,
+  options?: Omit<ProviderHttpErrorOptions, "statusPrefix">,
+): Promise<void> {
   if (response.ok) {
     return;
   }
-  throw await createProviderHttpError(response, label, { statusPrefix: "HTTP " });
+  throw await createProviderHttpError(response, label, { ...options, statusPrefix: "HTTP " });
 }
 
 /**
@@ -270,10 +332,11 @@ export async function assertOkOrThrowHttpError(response: Response, label: string
 export async function readProviderJsonResponse<T>(
   response: Response,
   label: string,
-  opts?: { maxBytes?: number },
+  opts?: ProviderResponseReadOptions,
 ): Promise<T> {
   const maxBytes = opts?.maxBytes ?? PROVIDER_JSON_RESPONSE_MAX_BYTES;
   const bytes = await readResponseWithLimit(response, maxBytes, {
+    ...opts,
     onOverflow: ({ maxBytes: maxBytesLocal }) =>
       new Error(`${label}: JSON response exceeds ${maxBytesLocal} bytes`),
   });
@@ -288,8 +351,9 @@ export async function readProviderJsonResponse<T>(
 export async function readProviderJsonObjectResponse(
   response: Response,
   label: string,
+  opts?: ProviderResponseReadOptions,
 ): Promise<Record<string, unknown>> {
-  const payload = await readProviderJsonResponse<unknown>(response, label);
+  const payload = await readProviderJsonResponse<unknown>(response, label, opts);
   const object = asObject(payload);
   if (!object) {
     throw new Error(`${label}: malformed JSON response`);
@@ -302,8 +366,9 @@ export async function readProviderJsonArrayFieldResponse(
   response: Response,
   label: string,
   field: string,
+  opts?: ProviderResponseReadOptions,
 ): Promise<unknown[]> {
-  const payload = await readProviderJsonObjectResponse(response, label);
+  const payload = await readProviderJsonObjectResponse(response, label, opts);
   const value = payload[field];
   if (!Array.isArray(value)) {
     throw new Error(`${label}: malformed JSON response`);
@@ -340,13 +405,12 @@ export async function readProviderBinaryResponse(
   response: Response,
   label: string,
   kind = "binary",
-  opts?: {
-    maxBytes?: number;
-  },
+  opts?: ProviderResponseReadOptions,
 ): Promise<Uint8Array> {
   assertProviderBinaryResponseContent(response, label, kind);
   const maxBytes = opts?.maxBytes ?? PROVIDER_BINARY_RESPONSE_MAX_BYTES;
   const bytes = await readResponseWithLimit(response, maxBytes, {
+    ...opts,
     onOverflow: ({ maxBytes: maxBytesLocal }) =>
       new Error(`${label}: ${kind} response exceeds ${maxBytesLocal} bytes`),
   });
diff --git a/src/cli/config-cli.ts b/src/cli/config-cli.ts
index fda6841cc3b..4f45d0f2a7c 100644
--- a/src/cli/config-cli.ts
+++ b/src/cli/config-cli.ts
@@ -1,5 +1,6 @@
 // Config CLI command implementation for get/set/unset/patch/validate and secret refs.
 import fs from "node:fs";
+import { readByteStreamWithLimit } from "@openclaw/media-core/read-byte-stream-with-limit";
 import { expectDefined } from "@openclaw/normalization-core";
 import { isRecord as isPlainRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -1478,25 +1479,20 @@ function configPatchModeError(message: string): Error {
 }
 
 async function readStdinText(): Promise<string> {
-  const chunks: string[] = [];
-  let bytes = 0;
   if (process.stdin.isTTY) {
     throw configPatchModeError(
       "--stdin refuses to read from an interactive terminal; pipe input or use --file <path>.",
     );
   }
   process.stdin.setEncoding("utf8");
-  for await (const chunk of process.stdin) {
-    const text = String(chunk);
-    bytes += Buffer.byteLength(text, "utf8");
-    if (bytes > CONFIG_PATCH_STDIN_MAX_BYTES) {
-      throw configPatchModeError(
-        `--stdin input exceeds ${CONFIG_PATCH_STDIN_MAX_BYTES} bytes; use --file <path> for larger patches.`,
-      );
-    }
-    chunks.push(text);
-  }
-  return chunks.join("");
+  const bytes = await readByteStreamWithLimit(process.stdin, {
+    maxBytes: CONFIG_PATCH_STDIN_MAX_BYTES,
+    onOverflow: ({ maxBytes }) =>
+      configPatchModeError(
+        `--stdin input exceeds ${maxBytes} bytes; use --file <path> for larger patches.`,
+      ),
+  });
+  return bytes.toString("utf8");
 }
 
 async function readConfigPatchInput(opts: ConfigPatchOptions): Promise<unknown> {
diff --git a/src/cli/exec-approvals-cli.ts b/src/cli/exec-approvals-cli.ts
index b6586dfd380..2f4c72f17d3 100644
--- a/src/cli/exec-approvals-cli.ts
+++ b/src/cli/exec-approvals-cli.ts
@@ -1,5 +1,6 @@
 // CLI for reading and mutating exec approval allowlists locally, via gateway, or via node.
 import fs from "node:fs/promises";
+import { readByteStreamWithLimit } from "@openclaw/media-core/read-byte-stream-with-limit";
 import { expectDefined } from "@openclaw/normalization-core";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
@@ -91,17 +92,11 @@ async function readStdin(
   stream: NodeJS.ReadableStream = process.stdin,
   maxBytes = EXEC_APPROVALS_STDIN_MAX_BYTES,
 ): Promise<string> {
-  const chunks: Buffer[] = [];
-  let total = 0;
-  for await (const chunk of stream) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    total += buffer.byteLength;
-    if (total > maxBytes) {
-      throw new Error(`Exec approvals stdin exceeds ${maxBytes} bytes.`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks, total).toString("utf8");
+  const bytes = await readByteStreamWithLimit(stream, {
+    maxBytes,
+    onOverflow: ({ maxBytes: limit }) => new Error(`Exec approvals stdin exceeds ${limit} bytes.`),
+  });
+  return bytes.toString("utf8");
 }
 
 async function resolveTargetNodeId(opts: ExecApprovalsCliOpts): Promise<string | null> {
diff --git a/src/commands/models/auth.ts b/src/commands/models/auth.ts
index 5e66f8d61b9..5f9c10558c3 100644
--- a/src/commands/models/auth.ts
+++ b/src/commands/models/auth.ts
@@ -7,6 +7,7 @@ import {
   select as clackSelect,
   text as clackText,
 } from "@clack/prompts";
+import { readByteStreamWithLimit } from "@openclaw/media-core/read-byte-stream-with-limit";
 import { expectDefined } from "@openclaw/normalization-core";
 import { resolveExpiresAtMsFromDurationMs } from "@openclaw/normalization-core/number-coercion";
 import {
@@ -133,17 +134,11 @@ const select = async <T>(params: Parameters<typeof clackSelect<T>>[0]) =>
 const MODELS_AUTH_STDIN_MAX_BYTES = 1024 * 1024;
 
 async function readPipedStdin(): Promise<string> {
-  const chunks: Buffer[] = [];
-  let totalBytes = 0;
-  for await (const chunk of process.stdin) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
-    totalBytes += buffer.byteLength;
-    if (totalBytes > MODELS_AUTH_STDIN_MAX_BYTES) {
-      throw new Error(`Piped auth input exceeds ${MODELS_AUTH_STDIN_MAX_BYTES} bytes.`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks, totalBytes).toString("utf8");
+  const bytes = await readByteStreamWithLimit(process.stdin, {
+    maxBytes: MODELS_AUTH_STDIN_MAX_BYTES,
+    onOverflow: ({ maxBytes }) => new Error(`Piped auth input exceeds ${maxBytes} bytes.`),
+  });
+  return bytes.toString("utf8");
 }
 
 async function readPastedSecret(params: {
diff --git a/src/infra/http-body.response.test.ts b/src/infra/http-body.response.test.ts
index c3a9ffe76dd..c0b154d4c6b 100644
--- a/src/infra/http-body.response.test.ts
+++ b/src/infra/http-body.response.test.ts
@@ -265,6 +265,49 @@ describe("readResponseWithLimit", () => {
     }
   });
 
+  it("resolves a lazy overall timeout immediately before reading", async () => {
+    vi.useFakeTimers();
+    try {
+      const cancel = vi.fn();
+      const timeoutMs = vi.fn(() => 75);
+      const response = new Response(makeTricklingStream(40, cancel));
+      const assertion = expect(
+        readResponseWithLimit(response, 1024, {
+          timeoutMs,
+          onTimeout: ({ timeoutMs: resolved }) => new Error(`lazy overall ${resolved}`),
+        }),
+      ).rejects.toThrow("lazy overall 75");
+
+      expect(timeoutMs).toHaveBeenCalledTimes(1);
+      await vi.advanceTimersByTimeAsync(80);
+      await assertion;
+      expect(cancel).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("cancels the body when a lazy timeout resolver reports an expired deadline", async () => {
+    const cancel = vi.fn();
+    const response = new Response(
+      new ReadableStream<Uint8Array>({
+        pull() {
+          return new Promise<void>(() => {});
+        },
+        cancel,
+      }),
+    );
+
+    await expect(
+      readResponseWithLimit(response, 1024, {
+        timeoutMs: () => {
+          throw new Error("deadline expired");
+        },
+      }),
+    ).rejects.toThrow("deadline expired");
+    expect(cancel).toHaveBeenCalledWith(expect.objectContaining({ message: "deadline expired" }));
+  });
+
   it("cancels a getReader-less body when its overall timeout expires", async () => {
     vi.useFakeTimers();
     try {
diff --git a/src/infra/http-body.ts b/src/infra/http-body.ts
index caf05dc6eed..6c11ba20502 100644
--- a/src/infra/http-body.ts
+++ b/src/infra/http-body.ts
@@ -140,7 +140,8 @@ type ReadResponsePrefixResult = {
 export type ReadResponseTextPrefixOptions = {
   chunkTimeoutMs?: number;
   onIdleTimeout?: (params: { chunkTimeoutMs: number }) => Error;
-  timeoutMs?: number;
+  /** Static timeout or lazy resolver evaluated immediately before body consumption. */
+  timeoutMs?: number | (() => number);
   onTimeout?: (params: { timeoutMs: number }) => Error;
 };
 
@@ -215,10 +216,17 @@ async function readResponsePrefix(
   options?: ReadResponsePrefixOptions,
 ): Promise<ReadResponsePrefixResult> {
   validateMaxBytes(maxBytes);
+  let timeoutMs: number | undefined;
+  try {
+    timeoutMs = typeof options?.timeoutMs === "function" ? options.timeoutMs() : options?.timeoutMs;
+  } catch (error) {
+    await response.body?.cancel(error).catch(() => undefined);
+    throw error;
+  }
   const body = response.body;
   if (!body || typeof body.getReader !== "function") {
     return await withResponseBodyTimeout({
-      timeoutMs: options?.timeoutMs,
+      timeoutMs,
       onTimeout: options?.onTimeout,
       cancel: async (error) => await body?.cancel(error),
       read: async () => {
@@ -237,7 +245,7 @@ async function readResponsePrefix(
 
   const reader = body.getReader();
   return await withResponseBodyTimeout({
-    timeoutMs: options?.timeoutMs,
+    timeoutMs,
     onTimeout: options?.onTimeout,
     cancel: async (error) => await reader.cancel(error),
     read: async () => await readResponsePrefixFromReader(reader, maxBytes, options),
diff --git a/src/media-understanding/shared.test.ts b/src/media-understanding/shared.test.ts
index bd7d1839d3e..7a932912dc7 100644
--- a/src/media-understanding/shared.test.ts
+++ b/src/media-understanding/shared.test.ts
@@ -34,7 +34,6 @@ vi.mock("../infra/net/proxy-env.js", async () => {
 
 import {
   createProviderOperationDeadline,
-  createProviderOperationTimeoutResolver,
   fetchProviderDownloadResponse,
   fetchWithTimeoutGuarded,
   pollProviderOperationJson,
@@ -69,6 +68,21 @@ function getFirstGuardedFetchCall() {
   return request as Record<string, unknown>;
 }
 
+function createTricklingResponse(status = 200): Response {
+  const chunk = new TextEncoder().encode("{");
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        controller.enqueue(chunk);
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 20);
+        });
+      },
+    }),
+    { status, headers: { "content-type": "application/json" } },
+  );
+}
+
 describe("provider operation deadlines", () => {
   it("keeps default per-call timeouts when no operation timeout is configured", () => {
     const deadline = createProviderOperationDeadline({
@@ -126,6 +140,22 @@ describe("provider operation deadlines", () => {
     expect(resolveProviderOperationTimeoutMs({ deadline, defaultTimeoutMs: 60_000 })).toBe(1_750);
   });
 
+  it("resolves a lazy total timeout once when the deadline starts", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const resolveTimeoutMs = vi.fn(() => 5_000);
+
+    const deadline = createProviderOperationDeadline({
+      label: "generated media download",
+      timeoutMs: resolveTimeoutMs,
+    });
+    vi.setSystemTime(4_250);
+
+    expect(resolveTimeoutMs).toHaveBeenCalledTimes(1);
+    expect(resolveProviderOperationTimeoutMs({ deadline, defaultTimeoutMs: 60_000 })).toBe(1_750);
+    expect(resolveTimeoutMs).toHaveBeenCalledTimes(1);
+  });
+
   it("throws once the operation deadline has expired", () => {
     vi.useFakeTimers();
     vi.setSystemTime(1_000);
@@ -211,6 +241,34 @@ describe("provider operation deadlines", () => {
     expect(fetchFn).toHaveBeenCalledTimes(2);
   });
 
+  it("bounds a trickling poll response body with the operation deadline", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const fetchFn = vi.fn<typeof fetch>().mockResolvedValue(createTricklingResponse());
+    const result = pollProviderOperationJson<{ status?: string }>({
+      url: "https://api.example.com/v1/videos/task-1",
+      headers: new Headers(),
+      deadline: createProviderOperationDeadline({
+        label: "video generation task task-1",
+        timeoutMs: 100,
+      }),
+      defaultTimeoutMs: 5_000,
+      fetchFn,
+      maxAttempts: 3,
+      pollIntervalMs: 1_000,
+      requestFailedMessage: "status failed",
+      timeoutMessage: "task timed out",
+      isComplete: (payload) => payload.status === "completed",
+    });
+    const assertion = expect(result).rejects.toThrow(
+      "video generation task task-1 timed out after 100ms",
+    );
+
+    await vi.advanceTimersByTimeAsync(110);
+    await assertion;
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
   it("passes guarded request policy through provider status polling", async () => {
     const release = vi.fn(async () => {});
     fetchWithSsrFGuardMock.mockResolvedValueOnce({
@@ -432,6 +490,7 @@ describe("provider operation deadlines", () => {
     const response = await fetchProviderDownloadResponse({
       url: "https://cdn.example.com/video.mp4",
       init: { method: "GET" },
+      // Keep the shipped timeoutMs call shape working for external plugins.
       timeoutMs: 5_000,
       fetchFn,
       provider: "test-video",
@@ -444,6 +503,26 @@ describe("provider operation deadlines", () => {
     expect(sleep).toHaveBeenCalledWith(0, undefined);
   });
 
+  it("bounds a trickling generated-asset error body", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const fetchFn = vi.fn<typeof fetch>().mockResolvedValue(createTricklingResponse(503));
+    const result = fetchProviderDownloadResponse({
+      url: "https://cdn.example.com/video.mp4",
+      init: { method: "GET" },
+      deadline: createProviderOperationDeadline({ label: "download failed", timeoutMs: 100 }),
+      fetchFn,
+      provider: "test-video",
+      requestFailedMessage: "download failed",
+      retry: { attempts: 1 },
+    });
+    const assertion = expect(result).rejects.toThrow("download failed timed out after 100ms");
+
+    await vi.advanceTimersByTimeAsync(110);
+    await assertion;
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
   it("recomputes remaining download timeout before retry attempts", async () => {
     vi.useFakeTimers();
     vi.setSystemTime(1_000);
@@ -461,7 +540,7 @@ describe("provider operation deadlines", () => {
       fetchProviderDownloadResponse({
         url: "https://cdn.example.com/video.mp4",
         init: { method: "GET" },
-        timeoutMs: createProviderOperationTimeoutResolver({ deadline, defaultTimeoutMs: 5_000 }),
+        deadline,
         fetchFn,
         provider: "test-video",
         requestFailedMessage: "download failed",
diff --git a/src/media-understanding/shared.ts b/src/media-understanding/shared.ts
index c260cdc62f2..a4d3ed07893 100644
--- a/src/media-understanding/shared.ts
+++ b/src/media-understanding/shared.ts
@@ -108,25 +108,22 @@ type GuardedProviderRequestParams = {
   mode?: GuardedFetchMode;
 };
 
-/** Creates a timer-safe absolute operation deadline from an optional total timeout. */
+/** Creates a timer-safe absolute deadline, resolving a lazy total timeout exactly once. */
 export function createProviderOperationDeadline(params: {
-  timeoutMs?: number;
+  timeoutMs?: ProviderOperationTimeoutMs;
   label: string;
 }): ProviderOperationDeadline {
-  if (
-    typeof params.timeoutMs !== "number" ||
-    !Number.isFinite(params.timeoutMs) ||
-    params.timeoutMs <= 0
-  ) {
+  const timeoutMs = typeof params.timeoutMs === "function" ? params.timeoutMs() : params.timeoutMs;
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
     return { label: params.label };
   }
-  const timeoutMs = resolveTimerTimeoutMs(params.timeoutMs, 1);
+  const resolvedTimeoutMs = resolveTimerTimeoutMs(timeoutMs, 1);
   const deadlineAtMs =
-    resolveExpiresAtMsFromDurationMs(timeoutMs) ?? resolveDateTimestampMs(Date.now());
+    resolveExpiresAtMsFromDurationMs(resolvedTimeoutMs) ?? resolveDateTimestampMs(Date.now());
   return {
     deadlineAtMs,
     label: params.label,
-    timeoutMs,
+    timeoutMs: resolvedTimeoutMs,
   };
 }
 
@@ -142,11 +139,42 @@ export function resolveProviderOperationTimeoutMs(params: {
   }
   const remainingMs = deadlineAtMs - Date.now();
   if (remainingMs <= 0) {
-    throw new Error(`${params.deadline.label} timed out after ${params.deadline.timeoutMs}ms`);
+    throw createProviderOperationTimeoutError(params.deadline);
   }
   return Math.max(1, Math.min(defaultTimeoutMs, remainingMs));
 }
 
+/** Builds the canonical error for an exhausted provider operation deadline. */
+function createProviderOperationTimeoutError(deadline: ProviderOperationDeadline): Error {
+  const timeoutLabel =
+    typeof deadline.timeoutMs === "number" ? ` after ${deadline.timeoutMs}ms` : "";
+  return new Error(`${deadline.label} timed out${timeoutLabel}`);
+}
+
+/** Resolves a static or lazy request timeout with a validated fallback. */
+function resolveProviderRequestTimeoutMs(params: {
+  timeoutMs?: ProviderOperationTimeoutMs;
+  defaultTimeoutMs: number;
+}): number {
+  const resolved = typeof params.timeoutMs === "function" ? params.timeoutMs() : params.timeoutMs;
+  const fallback = resolveTimerTimeoutMs(params.defaultTimeoutMs, DEFAULT_GUARDED_HTTP_TIMEOUT_MS);
+  if (typeof resolved !== "number" || !Number.isFinite(resolved) || resolved <= 0) {
+    return fallback;
+  }
+  return resolveTimerTimeoutMs(resolved, fallback);
+}
+
+/** Returns lazy body-read options tied to the same absolute provider operation deadline. */
+function createProviderOperationBodyReadOptions(params: {
+  deadline: ProviderOperationDeadline;
+  defaultTimeoutMs: number;
+}) {
+  return {
+    timeoutMs: createProviderOperationTimeoutResolver(params),
+    onTimeout: () => createProviderOperationTimeoutError(params.deadline),
+  };
+}
+
 /** Returns a lazy timeout resolver for code paths that retry or poll multiple HTTP calls. */
 export function createProviderOperationTimeoutResolver(params: {
   deadline: ProviderOperationDeadline;
@@ -170,7 +198,7 @@ export async function waitProviderOperationPollInterval(params: {
   }
   const remainingMs = deadlineAtMs - Date.now();
   if (remainingMs <= 0) {
-    throw new Error(`${params.deadline.label} timed out after ${params.deadline.timeoutMs}ms`);
+    throw createProviderOperationTimeoutError(params.deadline);
   }
   await new Promise((resolve) => {
     setTimeout(resolve, Math.min(pollIntervalMs, remainingMs));
@@ -192,6 +220,10 @@ export async function pollProviderOperationJson<TPayload>(
     getFailureMessage?: (payload: TPayload) => string | undefined;
   } & GuardedProviderRequestParams,
 ): Promise<TPayload> {
+  const bodyReadOptions = createProviderOperationBodyReadOptions({
+    deadline: params.deadline,
+    defaultTimeoutMs: params.defaultTimeoutMs,
+  });
   for (let attempt = 0; attempt < params.maxAttempts; attempt += 1) {
     const init = {
       method: "GET",
@@ -217,6 +249,7 @@ export async function pollProviderOperationJson<TPayload>(
             return (await readProviderJsonObjectResponse(
               result.response,
               params.requestFailedMessage,
+              bodyReadOptions,
             )) as TPayload;
           } finally {
             await result.release();
@@ -232,6 +265,7 @@ export async function pollProviderOperationJson<TPayload>(
             requestFailedMessage: params.requestFailedMessage,
           }),
           params.requestFailedMessage,
+          bodyReadOptions,
         )) as TPayload);
     if (params.isComplete(payload)) {
       return payload;
@@ -263,34 +297,65 @@ export async function fetchProviderOperationResponse(params: {
     stage: params.stage,
     retry: params.retry,
     operation: async () => {
+      const timeoutMs = resolveProviderRequestTimeoutMs({
+        timeoutMs: params.timeoutMs,
+        defaultTimeoutMs: DEFAULT_GUARDED_HTTP_TIMEOUT_MS,
+      });
+      const requestDeadline = createProviderOperationDeadline({
+        timeoutMs,
+        label: params.requestFailedMessage ?? `${params.provider ?? "provider"} ${params.stage}`,
+      });
       const response = await fetchWithTimeout(
         params.url,
         params.init ?? {},
-        resolveProviderOperationRequestTimeoutMs(params.timeoutMs),
+        timeoutMs,
         params.fetchFn,
       );
       if (params.requestFailedMessage) {
-        await assertOkOrThrowHttpError(response, params.requestFailedMessage);
+        await assertOkOrThrowHttpError(response, params.requestFailedMessage, {
+          bodyTimeoutMs: createProviderOperationTimeoutResolver({
+            deadline: requestDeadline,
+            defaultTimeoutMs: timeoutMs,
+          }),
+          onBodyTimeout: () => createProviderOperationTimeoutError(requestDeadline),
+        });
       }
       return response;
     },
   });
 }
 
+/**
+ * Fetches generated-asset response headers and bounded error details under an absolute deadline.
+ * Successful-body readers must reuse the same deadline so header time cannot reset the budget.
+ */
 export async function fetchProviderDownloadResponse(params: {
   url: string;
   init?: RequestInit;
+  deadline?: ProviderOperationDeadline;
+  /** @deprecated Pass `deadline` so successful-body reads can reuse the same total budget. */
   timeoutMs?: ProviderOperationTimeoutMs;
   fetchFn: typeof fetch;
   provider?: string;
   requestFailedMessage: string;
   retry?: TransientProviderRetryConfig;
 }): Promise<Response> {
+  // timeoutMs is a shipped Plugin SDK contract. Normalize it at this boundary;
+  // new callers pass the deadline through to their successful-body reader.
+  const deadline =
+    params.deadline ??
+    createProviderOperationDeadline({
+      timeoutMs: params.timeoutMs,
+      label: params.requestFailedMessage,
+    });
   return await fetchProviderOperationResponse({
     stage: "download",
     url: params.url,
     init: params.init,
-    timeoutMs: params.timeoutMs,
+    timeoutMs: createProviderOperationTimeoutResolver({
+      deadline,
+      defaultTimeoutMs: deadline.timeoutMs ?? DEFAULT_GUARDED_HTTP_TIMEOUT_MS,
+    }),
     fetchFn: params.fetchFn,
     provider: params.provider,
     requestFailedMessage: params.requestFailedMessage,
@@ -298,16 +363,6 @@ export async function fetchProviderDownloadResponse(params: {
   });
 }
 
-function resolveProviderOperationRequestTimeoutMs(
-  timeoutMs: ProviderOperationTimeoutMs | undefined,
-): number {
-  const resolved = typeof timeoutMs === "function" ? timeoutMs() : timeoutMs;
-  if (typeof resolved !== "number" || !Number.isFinite(resolved) || resolved <= 0) {
-    return DEFAULT_GUARDED_HTTP_TIMEOUT_MS;
-  }
-  return resolved;
-}
-
 function resolveGuardedHttpTimeoutMs(timeoutMs: number | undefined): number {
   if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
     return DEFAULT_GUARDED_HTTP_TIMEOUT_MS;
@@ -549,16 +604,30 @@ async function fetchGuardedProviderOperationResponse(params: {
     stage: params.stage,
     retry: params.retry,
     operation: async () => {
+      const timeoutMs = resolveProviderRequestTimeoutMs({
+        timeoutMs: params.timeoutMs,
+        defaultTimeoutMs: DEFAULT_GUARDED_HTTP_TIMEOUT_MS,
+      });
+      const requestDeadline = createProviderOperationDeadline({
+        timeoutMs,
+        label: params.requestFailedMessage ?? `${params.provider ?? "provider"} ${params.stage}`,
+      });
       const result = await fetchWithTimeoutGuarded(
         params.url,
         params.init,
-        resolveProviderOperationRequestTimeoutMs(params.timeoutMs),
+        timeoutMs,
         params.fetchFn,
         params.guardedOptions,
       );
       try {
         if (params.requestFailedMessage) {
-          await assertOkOrThrowHttpError(result.response, params.requestFailedMessage);
+          await assertOkOrThrowHttpError(result.response, params.requestFailedMessage, {
+            bodyTimeoutMs: createProviderOperationTimeoutResolver({
+              deadline: requestDeadline,
+              defaultTimeoutMs: timeoutMs,
+            }),
+            onBodyTimeout: () => createProviderOperationTimeoutError(requestDeadline),
+          });
         }
         return result;
       } catch (error) {
diff --git a/src/music-generation/provider-assets.ts b/src/music-generation/provider-assets.ts
index 30fe2c39adc..3a104883d37 100644
--- a/src/music-generation/provider-assets.ts
+++ b/src/music-generation/provider-assets.ts
@@ -4,7 +4,11 @@ import { extensionForMime } from "@openclaw/media-core/mime";
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { readResponseWithLimit } from "../infra/http-body.js";
-import { fetchProviderDownloadResponse } from "../media-understanding/shared.js";
+import {
+  createProviderOperationDeadline,
+  createProviderOperationTimeoutResolver,
+  fetchProviderDownloadResponse,
+} from "../media-understanding/shared.js";
 import type { GeneratedMusicAsset } from "./types.js";
 
 /**
@@ -98,10 +102,18 @@ export async function downloadGeneratedMusicAsset(params: {
   index?: number;
   maxBytes?: number;
 }): Promise<GeneratedMusicAsset> {
+  const deadline = createProviderOperationDeadline({
+    timeoutMs: params.timeoutMs,
+    label: `${params.provider} generated music download`,
+  });
+  const timeoutMs = createProviderOperationTimeoutResolver({
+    deadline,
+    defaultTimeoutMs: params.timeoutMs,
+  });
   const response = await fetchProviderDownloadResponse({
     url: params.candidate.url,
     init: { method: "GET" },
-    timeoutMs: params.timeoutMs,
+    deadline,
     fetchFn: params.fetchFn,
     provider: params.provider,
     requestFailedMessage: params.requestFailedMessage,
@@ -114,6 +126,11 @@ export async function downloadGeneratedMusicAsset(params: {
   const maxBytes = params.maxBytes ?? maxBytesForKind("audio");
   return {
     buffer: await readResponseWithLimit(response, maxBytes, {
+      timeoutMs,
+      onTimeout: ({ timeoutMs: bodyTimeoutMs }) =>
+        new Error(
+          `${params.provider} generated music download timed out after ${deadline.timeoutMs ?? bodyTimeoutMs}ms`,
+        ),
       onOverflow: ({ maxBytes: maxBytesLocal }) =>
         new Error(`${params.provider} generated music download exceeds ${maxBytesLocal} bytes`),
     }),
diff --git a/src/plugin-sdk/provider-tools.test.ts b/src/plugin-sdk/provider-tools.test.ts
index 18311eccc98..a0054b18927 100644
--- a/src/plugin-sdk/provider-tools.test.ts
+++ b/src/plugin-sdk/provider-tools.test.ts
@@ -437,6 +437,49 @@ describe("buildProviderToolCompatFamilyHooks", () => {
     }
   });
 
+  it("repairs legacy and content schema applicators without changing property dependencies", () => {
+    expect(
+      normalizeOpenAIParameters({
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+        dependencies: {
+          mode: ["payload"],
+          payload: { type: "object" },
+        },
+        additionalItems: { type: "object" },
+        contentSchema: { type: "object" },
+      }),
+    ).toEqual({
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+      dependencies: {
+        mode: ["payload"],
+        payload: {
+          type: "object",
+          properties: {},
+          required: [],
+          additionalProperties: false,
+        },
+      },
+      additionalItems: {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+      contentSchema: {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+      },
+    });
+  });
+
   it("does not tighten or warn for permissive object schemas that use strict:false", () => {
     const hooks = buildProviderToolCompatFamilyHooks("openai");
     const permissiveParameters = {
diff --git a/src/plugin-sdk/provider-tools.ts b/src/plugin-sdk/provider-tools.ts
index 2cc937d61d2..ce58dad6857 100644
--- a/src/plugin-sdk/provider-tools.ts
+++ b/src/plugin-sdk/provider-tools.ts
@@ -1,6 +1,8 @@
 import {
   cleanSchemaForGemini,
+  findOpenAIStrictSchemaViolations,
   GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS,
+  normalizeOpenAIStrictCompatSchema,
   stripUnsupportedSchemaKeywords,
 } from "@openclaw/ai/internal/openai";
 // Provider tool helpers expose shared tool-call payload contracts for provider plugins.
@@ -11,7 +13,12 @@ import type {
   ProviderToolSchemaDiagnostic,
 } from "./plugin-entry.js";
 
-export { cleanSchemaForGemini, GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS, stripUnsupportedSchemaKeywords };
+export {
+  cleanSchemaForGemini,
+  findOpenAIStrictSchemaViolations,
+  GEMINI_UNSUPPORTED_SCHEMA_KEYWORDS,
+  stripUnsupportedSchemaKeywords,
+};
 
 /**
  * Finds unsupported JSON-schema keywords and reports their nested schema paths.
@@ -126,12 +133,6 @@ export function normalizeOpenAIToolSchemas(
   });
 }
 
-function normalizeOpenAIStrictCompatSchema(schema: unknown): TSchema {
-  return normalizeOpenAIStrictCompatSchemaRecursive(schema, {
-    promoteEmptyObject: true,
-  }) as TSchema;
-}
-
 function shouldApplyOpenAIToolCompat(ctx: ProviderNormalizeToolSchemasContext): boolean {
   const provider = (ctx.model?.provider ?? ctx.provider ?? "").trim().toLowerCase();
   const api = (ctx.model?.api ?? ctx.modelApi ?? "").trim().toLowerCase();
@@ -161,246 +162,6 @@ function isOpenAICodexBaseUrl(baseUrl: string): boolean {
   return /^https:\/\/chatgpt\.com\/backend-api(?:\/|$)/i.test(baseUrl);
 }
 
-type NormalizeOpenAIStrictCompatOptions = {
-  promoteEmptyObject: boolean;
-};
-
-const OPENAI_STRICT_COMPAT_SCHEMA_MAP_KEYS = new Set([
-  "$defs",
-  "definitions",
-  "dependentSchemas",
-  "patternProperties",
-  "properties",
-]);
-
-// Annotation-only keywords whose null values can be dropped without changing
-// what the schema accepts; null constraint keywords must stay so projection
-// quarantines the tool instead of widening it.
-const OPENAI_NULLABLE_ANNOTATION_KEYS = new Set([
-  "default",
-  "description",
-  "examples",
-  "format",
-  "title",
-]);
-
-const OPENAI_STRICT_COMPAT_SCHEMA_NESTED_KEYS = new Set([
-  "additionalProperties",
-  "allOf",
-  "anyOf",
-  "contains",
-  "else",
-  "if",
-  "items",
-  "not",
-  "oneOf",
-  "prefixItems",
-  "propertyNames",
-  "then",
-  "unevaluatedItems",
-  "unevaluatedProperties",
-]);
-
-function normalizeOpenAIStrictCompatSchemaMap(schema: unknown): unknown {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-    return schema;
-  }
-
-  let changed = false;
-  const normalized: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
-    const next = normalizeOpenAIStrictCompatSchemaRecursive(value, {
-      promoteEmptyObject: false,
-    });
-    normalized[key] = next;
-    changed ||= next !== value;
-  }
-  return changed ? normalized : schema;
-}
-
-function normalizeOpenAIStrictCompatSchemaRecursive(
-  schema: unknown,
-  options: NormalizeOpenAIStrictCompatOptions,
-): unknown {
-  if (Array.isArray(schema)) {
-    let changed = false;
-    const normalized = schema.map((entry) => {
-      const next = normalizeOpenAIStrictCompatSchemaRecursive(entry, {
-        promoteEmptyObject: false,
-      });
-      changed ||= next !== entry;
-      return next;
-    });
-    return changed ? normalized : schema;
-  }
-  if (!schema || typeof schema !== "object") {
-    return schema;
-  }
-
-  const record = schema as Record<string, unknown>;
-  let changed = false;
-  let hadNullType = false;
-  const normalized: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(record)) {
-    // Repair only null-valued entries that carry no constraint semantics:
-    // annotation keywords, and `type: null` when the shape inference below can
-    // supply the real type. Null constraint keywords (additionalProperties,
-    // required, enum, ...) stay put so projection quarantines instead of
-    // silently accepting arguments the plugin never declared.
-    if (value === null && OPENAI_NULLABLE_ANNOTATION_KEYS.has(key)) {
-      changed = true;
-      continue;
-    }
-    if (value === null && key === "type") {
-      hadNullType = true;
-      changed = true;
-      continue;
-    }
-    const next = OPENAI_STRICT_COMPAT_SCHEMA_MAP_KEYS.has(key)
-      ? normalizeOpenAIStrictCompatSchemaMap(value)
-      : OPENAI_STRICT_COMPAT_SCHEMA_NESTED_KEYS.has(key)
-        ? normalizeOpenAIStrictCompatSchemaRecursive(value, {
-            promoteEmptyObject: false,
-          })
-        : value;
-    normalized[key] = next;
-    changed ||= next !== value;
-  }
-
-  if (Object.keys(normalized).length === 0) {
-    if (!options.promoteEmptyObject) {
-      return schema;
-    }
-    return {
-      type: "object",
-      properties: {},
-      required: [],
-      additionalProperties: false,
-    };
-  }
-
-  const hasObjectShapeHints =
-    (normalized.properties &&
-      typeof normalized.properties === "object" &&
-      !Array.isArray(normalized.properties)) ||
-    Array.isArray(normalized.required);
-  const hasArrayShapeHints = "items" in normalized;
-  if (!("type" in normalized) && hasObjectShapeHints !== hasArrayShapeHints) {
-    normalized.type = hasObjectShapeHints ? "object" : "array";
-    changed = true;
-  } else if (hadNullType && !("type" in normalized)) {
-    // Inference failed (no hints, or ambiguous object+array hints): restore the
-    // invalid `type: null` so downstream projection quarantines the tool
-    // instead of shipping an unconstrained schema.
-    normalized.type = null;
-  }
-  if (normalized.type === "object" && !("properties" in normalized)) {
-    normalized.properties = {};
-    changed = true;
-  }
-
-  const hasEmptyProperties =
-    normalized.properties &&
-    typeof normalized.properties === "object" &&
-    !Array.isArray(normalized.properties) &&
-    Object.keys(normalized.properties as Record<string, unknown>).length === 0;
-
-  if (normalized.type === "object" && !Array.isArray(normalized.required) && hasEmptyProperties) {
-    normalized.required = [];
-    changed = true;
-  }
-
-  if (
-    normalized.type === "object" &&
-    hasEmptyProperties &&
-    !("additionalProperties" in normalized)
-  ) {
-    normalized.additionalProperties = false;
-    changed = true;
-  }
-
-  return changed ? normalized : schema;
-}
-
-/**
- * Finds schema paths that violate OpenAI strict tool-schema requirements.
- */
-export function findOpenAIStrictSchemaViolations(
-  /** JSON schema node to inspect recursively. */
-  schema: unknown,
-  /** Dot/bracket path prefix used in returned diagnostics. */
-  path: string,
-  /** Strictness controls for the current schema position. */
-  options?: { requireObjectRoot?: boolean },
-): string[] {
-  if (Array.isArray(schema)) {
-    if (options?.requireObjectRoot) {
-      return [`${path}.type`];
-    }
-    return schema.flatMap((item, index) =>
-      findOpenAIStrictSchemaViolations(item, `${path}[${index}]`),
-    );
-  }
-  if (!schema || typeof schema !== "object") {
-    if (options?.requireObjectRoot) {
-      return [`${path}.type`];
-    }
-    return [];
-  }
-
-  const record = schema as Record<string, unknown>;
-  const violations: string[] = [];
-  for (const key of ["anyOf", "oneOf", "allOf"] as const) {
-    if (Array.isArray(record[key])) {
-      violations.push(`${path}.${key}`);
-    }
-  }
-  if (Array.isArray(record.type)) {
-    violations.push(`${path}.type`);
-  }
-
-  const properties =
-    record.properties && typeof record.properties === "object" && !Array.isArray(record.properties)
-      ? (record.properties as Record<string, unknown>)
-      : undefined;
-
-  if (record.type === "object") {
-    if (record.additionalProperties !== false) {
-      violations.push(`${path}.additionalProperties`);
-    }
-    const required = Array.isArray(record.required)
-      ? record.required.filter((entry): entry is string => typeof entry === "string")
-      : undefined;
-    if (!required) {
-      violations.push(`${path}.required`);
-    } else if (properties) {
-      const requiredSet = new Set(required);
-      for (const key of Object.keys(properties)) {
-        if (!requiredSet.has(key)) {
-          violations.push(`${path}.required.${key}`);
-        }
-      }
-    }
-  }
-
-  if (properties) {
-    for (const [key, value] of Object.entries(properties)) {
-      violations.push(...findOpenAIStrictSchemaViolations(value, `${path}.properties.${key}`));
-    }
-  }
-
-  for (const [key, value] of Object.entries(record)) {
-    if (key === "properties") {
-      continue;
-    }
-    if (value && typeof value === "object") {
-      violations.push(...findOpenAIStrictSchemaViolations(value, `${path}.${key}`));
-    }
-  }
-
-  return violations;
-}
-
 /**
  * Reports OpenAI strict-schema diagnostics for transports that enforce them before dispatch.
  */
diff --git a/src/plugin-sdk/test-helpers/provider-http-mocks.ts b/src/plugin-sdk/test-helpers/provider-http-mocks.ts
index c1df54b5a2a..d86fae65268 100644
--- a/src/plugin-sdk/test-helpers/provider-http-mocks.ts
+++ b/src/plugin-sdk/test-helpers/provider-http-mocks.ts
@@ -213,6 +213,15 @@ function resolveMockProviderTimeoutMs(
   return typeof timeoutMs === "function" ? timeoutMs() : (timeoutMs ?? 60_000);
 }
 
+function resolveMockProviderDownloadTimeoutMs(params: FetchProviderDownloadResponseParams) {
+  if (!params.deadline) {
+    return resolveMockProviderTimeoutMs(params.timeoutMs);
+  }
+  return params.deadline.deadlineAtMs === undefined
+    ? (params.deadline.timeoutMs ?? 60_000)
+    : Math.max(1, params.deadline.deadlineAtMs - Date.now());
+}
+
 providerHttpMocks.fetchProviderOperationResponseMock.mockImplementation(
   async (params: FetchProviderOperationResponseParams) => {
     const response = await providerHttpMocks.fetchWithTimeoutMock(
@@ -233,7 +242,7 @@ providerHttpMocks.fetchProviderDownloadResponseMock.mockImplementation(
     const response = await providerHttpMocks.fetchWithTimeoutMock(
       params.url,
       params.init ?? {},
-      resolveMockProviderTimeoutMs(params.timeoutMs),
+      resolveMockProviderDownloadTimeoutMs(params),
       params.fetchFn,
     );
     await providerHttpMocks.assertOkOrThrowHttpErrorMock(response, params.requestFailedMessage);
@@ -280,15 +289,34 @@ vi.mock("openclaw/plugin-sdk/provider-http", () => ({
     timeoutMs,
   }: {
     label: string;
-    timeoutMs?: number;
-  }) => ({
-    label,
-    timeoutMs,
-  }),
+    timeoutMs?: number | (() => number);
+  }) => {
+    const resolvedTimeoutMs = typeof timeoutMs === "function" ? timeoutMs() : timeoutMs;
+    return {
+      label,
+      timeoutMs: resolvedTimeoutMs,
+      deadlineAtMs:
+        typeof resolvedTimeoutMs === "number" ? Date.now() + resolvedTimeoutMs : undefined,
+    };
+  },
   createProviderOperationTimeoutResolver:
-    ({ defaultTimeoutMs }: { defaultTimeoutMs: number }) =>
-    () =>
+    ({
+      deadline,
       defaultTimeoutMs,
+    }: {
+      deadline: { deadlineAtMs?: number; label: string; timeoutMs?: number };
+      defaultTimeoutMs: number;
+    }) =>
+    () => {
+      if (typeof deadline.deadlineAtMs !== "number") {
+        return defaultTimeoutMs;
+      }
+      const remainingMs = deadline.deadlineAtMs - Date.now();
+      if (remainingMs <= 0) {
+        throw new Error(`${deadline.label} timed out after ${deadline.timeoutMs}ms`);
+      }
+      return Math.min(defaultTimeoutMs, remainingMs);
+    },
   executeProviderOperationWithRetry: providerHttpMocks.executeProviderOperationWithRetryMock,
   fetchProviderDownloadResponse: providerHttpMocks.fetchProviderDownloadResponseMock,
   fetchProviderOperationResponse: providerHttpMocks.fetchProviderOperationResponseMock,
diff --git a/test/scripts/control-ui-performance.test.ts b/test/scripts/control-ui-performance.test.ts
index 463ac622d0a..cc52fdcc8c6 100644
--- a/test/scripts/control-ui-performance.test.ts
+++ b/test/scripts/control-ui-performance.test.ts
@@ -102,6 +102,49 @@ describe("Control UI performance budgets", () => {
     );
   });
 
+  it("includes exact bytes when rounded violation values collide", () => {
+    const metrics = {
+      schemaVersion: 1 as const,
+      startup: {
+        js: { requests: 1, rawBytes: 100, gzipBytes: 43_009, brotliBytes: 30 },
+        css: { requests: 1, rawBytes: 50, gzipBytes: 15, brotliBytes: 12 },
+        assets: [],
+      },
+      total: {
+        js: { requests: 1, rawBytes: 100, gzipBytes: 43_009, brotliBytes: 30 },
+        css: { requests: 1, rawBytes: 50, gzipBytes: 15, brotliBytes: 12 },
+      },
+      largest: {
+        js: {
+          file: "assets/index-a.js",
+          type: "js",
+          rawBytes: 100,
+          gzipBytes: 43_009,
+          brotliBytes: 30,
+        },
+        css: {
+          file: "assets/index-c.css",
+          type: "css",
+          rawBytes: 50,
+          gzipBytes: 15,
+          brotliBytes: 12,
+        },
+      },
+    } satisfies ReturnType<typeof collectControlUiPerformanceMetrics>;
+    const budgets = {
+      startupJsRequests: 1,
+      startupCssRequests: 1,
+      startupJsGzipBytes: 43_008,
+      startupCssGzipBytes: 20,
+      largestJsGzipBytes: 43_008,
+      largestCssGzipBytes: 20,
+    };
+
+    expect(formatControlUiPerformanceReport(metrics, budgets)).toContain(
+      "startup JS gzip: 42.0 KiB exceeds 42.0 KiB (43009 B vs 43008 B)",
+    );
+  });
+
   it("fails when a compressed sidecar is missing", () => {
     const { distDir } = createDistFixture();
     fs.writeFileSync(

From 881b0a619f56dcb64c7b173eeeaf68b7bbb27052 Mon Sep 17 00:00:00 2001
From: cxbAsDev <chen.xianbiao@xydigit.com>
Date: Sat, 18 Jul 2026 21:05:51 +0800
Subject: [PATCH 64/76] fix(doctor): bound AGENTS.md and root-memory file reads
 (#101448)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix(doctor): bound AGENTS.md and root-memory file reads

* chore(doctor): retrigger CI after QA smoke flake

* fix(doctor): validate root-memory inputs before archiving

* fix(doctor): distinguish oversized root-memory reads from other read failures

* fix(doctor): preserve legacy memory on bounded-read races

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

* fix(doctor): preserve archives on restoration failure

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

* fix(doctor): keep independent archive on migration races

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

* fix(doctor): preserve symlinked workspace guidance

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

* fix(doctor): report atomic archive failures

Co-authored-by: 陈宪彪0668000387 <chen.xianbiao@xydigit.com>

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
---
 src/commands/doctor-workspace.test.ts | 249 ++++++++++++++++++++++++++
 src/commands/doctor-workspace.ts      | 166 +++++++++++++++--
 2 files changed, 396 insertions(+), 19 deletions(-)

diff --git a/src/commands/doctor-workspace.test.ts b/src/commands/doctor-workspace.test.ts
index 0297272b926..ca1bc28b7ca 100644
--- a/src/commands/doctor-workspace.test.ts
+++ b/src/commands/doctor-workspace.test.ts
@@ -90,6 +90,77 @@ describe("root memory repair", () => {
     await expect(fs.access(migration.archivedLegacyPath)).resolves.toBeUndefined();
   });
 
+  it("reads legacy content after moving it into the archive", async () => {
+    const canonicalPath = path.join(tmpDir, "MEMORY.md");
+    const legacyPath = path.join(tmpDir, "memory.md");
+    await fs.writeFile(canonicalPath, "# Canonical\n", "utf8");
+    await fs.writeFile(legacyPath, "# Legacy\n", "utf8");
+
+    const rename = vi.spyOn(fs, "rename");
+    rename.mockImplementationOnce(async (sourcePath, targetPath) => {
+      await fs.appendFile(sourcePath, "# Added before archive\n", "utf8");
+      rename.mockRestore();
+      await fs.rename(sourcePath, targetPath);
+    });
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+    expect(migration.changed).toBe(true);
+    const canonical = await fs.readFile(canonicalPath, "utf8");
+    expect(canonical).toContain("# Legacy");
+    expect(canonical).toContain("# Added before archive");
+  });
+
+  it("preserves the archive when the archived file grows past the read limit", async () => {
+    const canonicalPath = path.join(tmpDir, "MEMORY.md");
+    const legacyPath = path.join(tmpDir, "memory.md");
+    await fs.writeFile(canonicalPath, "# Canonical\n", "utf8");
+    await fs.writeFile(legacyPath, "# Legacy\n", "utf8");
+
+    const rename = vi.spyOn(fs, "rename");
+    rename.mockImplementationOnce(async (sourcePath, targetPath) => {
+      await fs.appendFile(sourcePath, Buffer.alloc(9 * 1024 * 1024));
+      rename.mockRestore();
+      await fs.rename(sourcePath, targetPath);
+    });
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+
+    expect(migration.changed).toBe(true);
+    expect(migration.removedLegacy).toBe(true);
+    expect(migration.readLimitExceeded).toBe(true);
+    await expectPathMissing(legacyPath);
+    if (!migration.archivedLegacyPath) {
+      throw new Error("expected preserved archive path");
+    }
+    await expect(fs.access(migration.archivedLegacyPath)).resolves.toBeUndefined();
+  });
+
+  it("preserves a concurrent legacy replacement beside the archive", async () => {
+    const canonicalPath = path.join(tmpDir, "MEMORY.md");
+    const legacyPath = path.join(tmpDir, "memory.md");
+    await fs.writeFile(canonicalPath, "# Canonical\n", "utf8");
+    await fs.writeFile(legacyPath, "# Legacy\n", "utf8");
+
+    const rename = vi.spyOn(fs, "rename");
+    rename.mockImplementationOnce(async (sourcePath, targetPath) => {
+      await fs.appendFile(sourcePath, Buffer.alloc(9 * 1024 * 1024));
+      rename.mockRestore();
+      await fs.rename(sourcePath, targetPath);
+      await fs.writeFile(sourcePath, "# Concurrent replacement\n", "utf8");
+    });
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+
+    expect(migration.changed).toBe(true);
+    expect(migration.removedLegacy).toBe(true);
+    expect(migration.readLimitExceeded).toBe(true);
+    if (!migration.archivedLegacyPath) {
+      throw new Error("expected preserved archive path");
+    }
+    await expect(fs.readFile(legacyPath, "utf8")).resolves.toBe("# Concurrent replacement\n");
+    await expect(fs.access(migration.archivedLegacyPath)).resolves.toBeUndefined();
+  });
+
   it("warns and repairs split-brain root memory through workspace doctor helpers", async () => {
     await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Canonical\n", "utf8");
     await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n", "utf8");
@@ -132,4 +203,182 @@ describe("root memory repair", () => {
     expect(repairLines).toContain(`- removed legacy file: ${path.join(tmpDir, "memory.md")}`);
     expect(repairNote?.[1]).toBe("Doctor changes");
   });
+
+  it("treats an oversized AGENTS.md as missing memory guidance", async () => {
+    await fs.writeFile(path.join(tmpDir, "AGENTS.md"), "x".repeat(2 * 1024 * 1024), "utf8");
+
+    await expect(shouldSuggestMemorySystem(tmpDir)).resolves.toBe(true);
+  });
+
+  it("follows a symlinked AGENTS.md while keeping its target bounded", async () => {
+    const agentsTarget = path.join(tmpDir, "agents-target.md");
+    const agentsPath = path.join(tmpDir, "AGENTS.md");
+    await fs.writeFile(agentsTarget, "Use MEMORY.md for durable memory.\n", "utf8");
+    await fs.symlink(agentsTarget, agentsPath);
+
+    await expect(shouldSuggestMemorySystem(tmpDir)).resolves.toBe(false);
+
+    await fs.writeFile(agentsTarget, "MEMORY.md\n".repeat(200_000), "utf8");
+    await expect(shouldSuggestMemorySystem(tmpDir)).resolves.toBe(true);
+  });
+
+  it("does not archive or remove an oversized legacy memory file", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Canonical\n", "utf8");
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n".repeat(1_000_000), "utf8");
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+    expect(migration.changed).toBe(false);
+    expect(migration.removedLegacy).toBe(false);
+    expect(migration.mergedLegacy).toBe(false);
+    expect(migration.readLimitExceeded).toBe(true);
+    await expect(fs.readFile(path.join(tmpDir, "memory.md"), "utf8")).resolves.toContain(
+      "# Legacy",
+    );
+  });
+
+  it("does not archive or remove a valid legacy memory file when canonical is oversized", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Canonical\n".repeat(1_000_000), "utf8");
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n", "utf8");
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+    expect(migration.changed).toBe(false);
+    expect(migration.removedLegacy).toBe(false);
+    expect(migration.mergedLegacy).toBe(false);
+    expect(migration.readLimitExceeded).toBe(true);
+    await expect(fs.readFile(path.join(tmpDir, "memory.md"), "utf8")).resolves.toContain(
+      "# Legacy",
+    );
+  });
+
+  it("does not archive or remove a legacy memory file when canonical cannot be read", async () => {
+    const targetFile = path.join(tmpDir, "canonical-target.md");
+    await fs.writeFile(targetFile, "# Canonical\n", "utf8");
+    await fs.symlink(targetFile, path.join(tmpDir, "MEMORY.md"));
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n", "utf8");
+
+    const migration = await migrateLegacyRootMemoryFile(tmpDir);
+    expect(migration.changed).toBe(false);
+    expect(migration.removedLegacy).toBe(false);
+    expect(migration.mergedLegacy).toBe(false);
+    expect(migration.readError).toBe(true);
+    expect(migration.readLimitExceeded).toBe(false);
+    await expect(fs.readFile(path.join(tmpDir, "memory.md"), "utf8")).resolves.toContain(
+      "# Legacy",
+    );
+  });
+
+  it("reports a skipped repair when a root memory file cannot be read", async () => {
+    const targetFile = path.join(tmpDir, "canonical-target.md");
+    await fs.writeFile(targetFile, "# Canonical\n", "utf8");
+    await fs.symlink(targetFile, path.join(tmpDir, "MEMORY.md"));
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n", "utf8");
+    const cfg = { agents: { defaults: { workspace: tmpDir } } } as OpenClawConfig;
+    const prompter = {
+      confirmRuntimeRepair: vi.fn(async () => true),
+    } as unknown as DoctorPrompter;
+
+    await maybeRepairWorkspaceMemoryHealth({ cfg, prompter });
+
+    expect(note).toHaveBeenCalledTimes(1);
+    const repairNote = firstNoteCall();
+    const repairMessage = String(repairNote?.[0] ?? "");
+    const repairLines = repairMessage.split("\n");
+    expect(repairLines[0]).toBe("Workspace memory root repair skipped (a file could not be read):");
+    expect(repairLines).toContain(`- canonical: ${path.join(tmpDir, "MEMORY.md")}`);
+    expect(repairLines).toContain(`- legacy: ${path.join(tmpDir, "memory.md")}`);
+    expect(repairNote?.[1]).toBe("Doctor changes");
+  });
+
+  it("reports a skipped repair when a root memory file is oversized", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Canonical\n", "utf8");
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n".repeat(1_000_000), "utf8");
+    const cfg = { agents: { defaults: { workspace: tmpDir } } } as OpenClawConfig;
+    const prompter = {
+      confirmRuntimeRepair: vi.fn(async () => true),
+    } as unknown as DoctorPrompter;
+
+    await maybeRepairWorkspaceMemoryHealth({ cfg, prompter });
+
+    expect(note).toHaveBeenCalledTimes(1);
+    const repairNote = firstNoteCall();
+    const repairMessage = String(repairNote?.[0] ?? "");
+    const repairLines = repairMessage.split("\n");
+    expect(repairLines[0]).toBe(
+      "Workspace memory root repair skipped (a file exceeded the safe read limit):",
+    );
+    expect(repairLines).toContain(`- canonical: ${path.join(tmpDir, "MEMORY.md")}`);
+    expect(repairLines).toContain(`- legacy: ${path.join(tmpDir, "memory.md")}`);
+    expect(repairNote?.[1]).toBe("Doctor changes");
+  });
+
+  it("skips without mutation when legacy memory cannot be archived atomically", async () => {
+    const canonicalPath = path.join(tmpDir, "MEMORY.md");
+    const legacyPath = path.join(tmpDir, "memory.md");
+    await fs.writeFile(canonicalPath, "# Canonical\n", "utf8");
+    await fs.writeFile(legacyPath, "# Legacy\n", "utf8");
+    const rename = vi
+      .spyOn(fs, "rename")
+      .mockRejectedValueOnce(Object.assign(new Error("cross-device rename"), { code: "EXDEV" }));
+
+    try {
+      const migration = await migrateLegacyRootMemoryFile(tmpDir);
+
+      expect(migration.changed).toBe(false);
+      expect(migration.removedLegacy).toBe(false);
+      expect(migration.mergedLegacy).toBe(false);
+      expect(migration.archiveError).toBe(true);
+      await expect(fs.readFile(canonicalPath, "utf8")).resolves.toBe("# Canonical\n");
+      await expect(fs.readFile(legacyPath, "utf8")).resolves.toBe("# Legacy\n");
+    } finally {
+      rename.mockRestore();
+    }
+  });
+
+  it("reports when legacy memory cannot be archived atomically", async () => {
+    await fs.writeFile(path.join(tmpDir, "MEMORY.md"), "# Canonical\n", "utf8");
+    await fs.writeFile(path.join(tmpDir, "memory.md"), "# Legacy\n", "utf8");
+    const cfg = { agents: { defaults: { workspace: tmpDir } } } as OpenClawConfig;
+    const prompter = {
+      confirmRuntimeRepair: vi.fn(async () => true),
+    } as unknown as DoctorPrompter;
+    const rename = vi
+      .spyOn(fs, "rename")
+      .mockRejectedValueOnce(Object.assign(new Error("cross-device rename"), { code: "EXDEV" }));
+
+    try {
+      await maybeRepairWorkspaceMemoryHealth({ cfg, prompter });
+    } finally {
+      rename.mockRestore();
+    }
+
+    const repairNote = firstNoteCall();
+    const repairLines = String(repairNote?.[0] ?? "").split("\n");
+    expect(repairLines[0]).toBe(
+      "Workspace memory root repair skipped (legacy memory could not be archived atomically):",
+    );
+    expect(repairLines).toContain(`- canonical: ${path.join(tmpDir, "MEMORY.md")}`);
+    expect(repairLines).toContain(`- legacy: ${path.join(tmpDir, "memory.md")}`);
+    expect(repairNote?.[1]).toBe("Doctor changes");
+  });
+
+  it("reports a preserved archive when a failed repair cannot restore legacy", async () => {
+    const canonicalPath = path.join(tmpDir, "MEMORY.md");
+    const legacyPath = path.join(tmpDir, "memory.md");
+    await fs.writeFile(canonicalPath, "# Canonical\n", "utf8");
+    await fs.writeFile(legacyPath, "# Legacy\n", "utf8");
+    const cfg = { agents: { defaults: { workspace: tmpDir } } } as OpenClawConfig;
+    const prompter = {
+      confirmRuntimeRepair: vi.fn(async () => true),
+    } as unknown as DoctorPrompter;
+    const rename = vi.spyOn(fs, "rename");
+    rename.mockImplementationOnce(async (sourcePath, targetPath) => {
+      await fs.appendFile(sourcePath, Buffer.alloc(9 * 1024 * 1024));
+      rename.mockRestore();
+      await fs.rename(sourcePath, targetPath);
+    });
+    await maybeRepairWorkspaceMemoryHealth({ cfg, prompter });
+
+    const repairLines = String(firstNoteCall()?.[0] ?? "").split("\n");
+    expect(repairLines).toContainEqual(expect.stringContaining("- preserved archive: "));
+  });
 });
diff --git a/src/commands/doctor-workspace.ts b/src/commands/doctor-workspace.ts
index eb1bf67b5ca..87e56f134f9 100644
--- a/src/commands/doctor-workspace.ts
+++ b/src/commands/doctor-workspace.ts
@@ -6,6 +6,7 @@ import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent
 import { DEFAULT_AGENTS_FILENAME } from "../agents/workspace.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { formatErrorMessage } from "../infra/errors.js";
+import { readRegularFile } from "../infra/regular-file.js";
 import {
   CANONICAL_ROOT_MEMORY_FILENAME,
   LEGACY_ROOT_MEMORY_FILENAME,
@@ -16,6 +17,13 @@ import {
 import { shortenHomePath } from "../utils.js";
 import type { DoctorPrompter } from "./doctor-prompter.js";
 
+// AGENTS.md is only scanned for a memory-system reference; a small cap prevents
+// a huge file from being buffered just for one regex check.
+const AGENTS_MD_MAX_BYTES = 1024 * 1024;
+// Root memory files are markdown journals; 8 MiB is generous while preventing
+// a runaway file from OOMing the migration path.
+const ROOT_MEMORY_FILE_MAX_BYTES = 8 * 1024 * 1024;
+
 export const MEMORY_SYSTEM_PROMPT = [
   "Memory system not found in workspace.",
   "Paste this into your agent:",
@@ -41,8 +49,18 @@ export async function shouldSuggestMemorySystem(workspaceDir: string): Promise<b
 
   const agentsPath = path.join(workspaceDir, DEFAULT_AGENTS_FILENAME);
   try {
-    const content = await fs.promises.readFile(agentsPath, "utf-8");
-    if (new RegExp(`\\b${CANONICAL_ROOT_MEMORY_FILENAME.replace(".", "\\.")}\\b`).test(content)) {
+    // Workspace instruction files may intentionally be symlinked. Resolve the
+    // final target first, then keep the descriptor-backed read bounded.
+    const resolvedAgentsPath = await fs.promises.realpath(agentsPath);
+    const { buffer } = await readRegularFile({
+      filePath: resolvedAgentsPath,
+      maxBytes: AGENTS_MD_MAX_BYTES,
+    });
+    if (
+      new RegExp(`\\b${CANONICAL_ROOT_MEMORY_FILENAME.replace(".", "\\.")}\\b`).test(
+        buffer.toString("utf-8"),
+      )
+    ) {
       return false;
     }
   } catch {
@@ -147,6 +165,12 @@ export type RootMemoryMigrationResult = {
   mergedLegacy: boolean;
   archivedLegacyPath?: string;
   copiedBytes?: number;
+  /** True when the repair was skipped because a file exceeded the safe read limit. */
+  readLimitExceeded?: boolean;
+  /** True when the repair was skipped because a file could not be read. */
+  readError?: boolean;
+  /** True when the legacy file could not be archived atomically. */
+  archiveError?: boolean;
 };
 
 async function moveLegacyRootMemoryFileToArchive(params: {
@@ -161,15 +185,9 @@ async function moveLegacyRootMemoryFileToArchive(params: {
   );
   await fs.promises.mkdir(archiveDir, { recursive: true });
   const archivePath = path.join(archiveDir, LEGACY_ROOT_MEMORY_FILENAME);
-  try {
-    await fs.promises.rename(params.legacyPath, archivePath);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException | undefined)?.code !== "EXDEV") {
-      throw err;
-    }
-    await fs.promises.copyFile(params.legacyPath, archivePath);
-    await fs.promises.unlink(params.legacyPath);
-  }
+  // Source and repair archive live under one workspace. If a mounted file makes
+  // this cross-device, fail before mutation instead of copying an unbounded file.
+  await fs.promises.rename(params.legacyPath, archivePath);
   return archivePath;
 }
 
@@ -203,14 +221,81 @@ export async function migrateLegacyRootMemoryFile(
       mergedLegacy: false,
     };
   }
-  const archivedLegacyPath = await moveLegacyRootMemoryFileToArchive({
-    workspaceDir: detection.workspaceDir,
-    legacyPath: detection.legacyPath,
-  });
-  const [canonicalText, legacyText] = await Promise.all([
-    fs.promises.readFile(detection.canonicalPath, "utf-8"),
-    fs.promises.readFile(archivedLegacyPath, "utf-8"),
-  ]);
+  const skippedForReadFailure = (err: unknown): RootMemoryMigrationResult => {
+    const isTooLarge =
+      typeof err === "object" &&
+      err !== null &&
+      "message" in err &&
+      typeof (err as Error).message === "string" &&
+      (err as Error).message.startsWith("File exceeds");
+    return {
+      changed: false,
+      canonicalPath: detection.canonicalPath,
+      legacyPath: detection.legacyPath,
+      removedLegacy: false,
+      mergedLegacy: false,
+      readLimitExceeded: isTooLarge,
+      readError: !isTooLarge,
+    };
+  };
+  try {
+    // Reject oversized, unreadable, symlinked, or non-regular inputs before the
+    // archive rename. The archived snapshot is read again after the atomic move.
+    await Promise.all([
+      readRegularFile({
+        filePath: detection.canonicalPath,
+        maxBytes: ROOT_MEMORY_FILE_MAX_BYTES,
+      }),
+      readRegularFile({
+        filePath: detection.legacyPath,
+        maxBytes: ROOT_MEMORY_FILE_MAX_BYTES,
+      }),
+    ]);
+  } catch (err) {
+    return skippedForReadFailure(err);
+  }
+  let archivedLegacyPath: string;
+  try {
+    archivedLegacyPath = await moveLegacyRootMemoryFileToArchive({
+      workspaceDir: detection.workspaceDir,
+      legacyPath: detection.legacyPath,
+    });
+  } catch {
+    return {
+      changed: false,
+      canonicalPath: detection.canonicalPath,
+      legacyPath: detection.legacyPath,
+      removedLegacy: false,
+      mergedLegacy: false,
+      archiveError: true,
+    };
+  }
+  let canonicalText: string;
+  let legacyText: string;
+  try {
+    [canonicalText, legacyText] = await Promise.all([
+      readRegularFile({
+        filePath: detection.canonicalPath,
+        maxBytes: ROOT_MEMORY_FILE_MAX_BYTES,
+      }).then(({ buffer }) => buffer.toString("utf-8")),
+      readRegularFile({
+        filePath: archivedLegacyPath,
+        maxBytes: ROOT_MEMORY_FILE_MAX_BYTES,
+      }).then(({ buffer }) => buffer.toString("utf-8")),
+    ]);
+  } catch (err) {
+    const skipped = skippedForReadFailure(err);
+    // The archive is the independent recovery copy. Do not link or copy it
+    // back into the live path: linking lets later in-place writes corrupt the
+    // archive, while copying a concurrently growing file would reintroduce an
+    // unbounded read. A concurrent replacement at legacyPath stays untouched.
+    return {
+      ...skipped,
+      changed: true,
+      removedLegacy: true,
+      archivedLegacyPath,
+    };
+  }
   if (canonicalText !== legacyText) {
     const merged = `${canonicalText.trimEnd()}\n${buildMergedLegacyRootMemorySection({
       legacyText,
@@ -265,6 +350,49 @@ export async function maybeRepairWorkspaceMemoryHealth(params: {
       return;
     }
     const migration = await migrateLegacyRootMemoryFile(configuredWorkspaceDir);
+    if (migration.readLimitExceeded) {
+      note(
+        [
+          "Workspace memory root repair skipped (a file exceeded the safe read limit):",
+          `- canonical: ${migration.canonicalPath}`,
+          `- legacy: ${migration.legacyPath}`,
+          migration.archivedLegacyPath
+            ? `- preserved archive: ${migration.archivedLegacyPath}`
+            : null,
+        ]
+          .filter((line): line is string => Boolean(line))
+          .join("\n"),
+        "Doctor changes",
+      );
+      return;
+    }
+    if (migration.readError) {
+      note(
+        [
+          "Workspace memory root repair skipped (a file could not be read):",
+          `- canonical: ${migration.canonicalPath}`,
+          `- legacy: ${migration.legacyPath}`,
+          migration.archivedLegacyPath
+            ? `- preserved archive: ${migration.archivedLegacyPath}`
+            : null,
+        ]
+          .filter((line): line is string => Boolean(line))
+          .join("\n"),
+        "Doctor changes",
+      );
+      return;
+    }
+    if (migration.archiveError) {
+      note(
+        [
+          "Workspace memory root repair skipped (legacy memory could not be archived atomically):",
+          `- canonical: ${migration.canonicalPath}`,
+          `- legacy: ${migration.legacyPath}`,
+        ].join("\n"),
+        "Doctor changes",
+      );
+      return;
+    }
     if (!migration.changed) {
       return;
     }

From 1cddec35f4b70612d373902243b59795efc9fdf5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 14:09:42 +0100
Subject: [PATCH 65/76] feat(clients): session groups, batch actions,
 inspector, and worktree-aware creation for native chat (#110347)

* feat(clients): gateway session groups, batch operations, session inspector, and new-session options

* chore(i18n): translate session management strings and regenerate catalogs

* chore(i18n): complete translation artifacts for session management strings

* fix(clients): fail closed when a transport cannot honor agent or base-ref session options

* fix(clients): authoritative agent identity for new-session parents and revision-keyed sidebar group refresh

* fix(clients): refetch session groups on remote catalog events and correct Swedish repository-root translation

* fix(clients): resilient new-session popover, revision-keyed group manager, and popover string translations

* fix(clients): scope reset fallback to plain new-session requests and revision-key the inspector groups

* fix(clients): reject empty agent catalogs and refresh sessions on remote group events

* refactor(clients): drop unused agents fetch wrapper and runtime memberwise init flagged by periphery

* chore(i18n): realign locale artifacts after rebase onto model-controls main

* chore(clients): split session creation into the session-actions extension and realign i18n after ask-user main rebase

* chore(i18n): resync derived artifacts after question-card main rebase
---
 .../apple-translation-contradictions.json     |  567 +-
 apps/.i18n/native-source.json                 | 1088 ++-
 apps/.i18n/native/ar.json                     |  397 +-
 apps/.i18n/native/de.json                     |  397 +-
 apps/.i18n/native/es.json                     |  397 +-
 apps/.i18n/native/fa.json                     |  397 +-
 apps/.i18n/native/fr.json                     |  397 +-
 apps/.i18n/native/hi.json                     |  397 +-
 apps/.i18n/native/id.json                     |  397 +-
 apps/.i18n/native/it.json                     |  397 +-
 apps/.i18n/native/ja-JP.json                  |  397 +-
 apps/.i18n/native/ko.json                     |  397 +-
 apps/.i18n/native/nl.json                     |  397 +-
 apps/.i18n/native/pl.json                     |  397 +-
 apps/.i18n/native/pt-BR.json                  |  397 +-
 apps/.i18n/native/ru.json                     |  397 +-
 apps/.i18n/native/sv.json                     |  397 +-
 apps/.i18n/native/th.json                     |  397 +-
 apps/.i18n/native/tr.json                     |  397 +-
 apps/.i18n/native/uk.json                     |  397 +-
 apps/.i18n/native/vi.json                     |  397 +-
 apps/.i18n/native/zh-CN.json                  |  397 +-
 apps/.i18n/native/zh-TW.json                  |  397 +-
 .../app/src/main/res/values-es/strings.xml    |    4 +-
 .../app/src/main/res/values-fr/strings.xml    |    2 +-
 .../app/src/main/res/values-hi/strings.xml    |    2 +-
 .../app/src/main/res/values-it/strings.xml    |    2 +-
 .../app/src/main/res/values-th/strings.xml    |    2 +-
 .../app/src/main/res/values-tr/strings.xml    |    2 +-
 .../app/src/main/res/values-uk/strings.xml    |    2 +-
 .../src/main/res/values-zh-rCN/strings.xml    |    2 +-
 .../src/main/res/values-zh-rTW/strings.xml    |    2 +-
 apps/ios/Resources/Localizable.xcstrings      | 6192 ++++++++++++++++-
 ...cGatewayChatTransport+SessionActions.swift |  113 +-
 .../Sources/OpenClaw/WebChatSwiftUI.swift     |   62 +-
 .../OpenClawChatUI/ChatGatewayRequest.swift   |   37 +-
 .../ChatSessionManagementViews.swift          |  637 ++
 .../OpenClawChatUI/ChatSessionSidebar.swift   |  105 +-
 .../ChatSessionSidebarModel.swift             |   23 +-
 .../Sources/OpenClawChatUI/ChatSessions.swift |   82 +-
 .../Sources/OpenClawChatUI/ChatSheets.swift   |  312 +-
 .../OpenClawChatUI/ChatTransport.swift        |  221 +-
 .../ChatViewModel+SessionActions.swift        |  286 +-
 .../ChatViewModel+TransportEvents.swift       |   10 +
 .../OpenClawChatUI/ChatViewModel.swift        |   58 +-
 .../OpenClawChatUI/ChatWindowShell.swift      |   12 +
 .../ChatGatewayRequestTests.swift             |   21 +-
 .../ChatSessionSidebarModelTests.swift        |   86 +
 .../ChatViewModelSessionActionTests.swift     |  280 +
 .../OpenClawKitTests/ChatViewModelTests.swift |   34 +
 docs/platforms/mac/webchat.md                 |    5 +-
 51 files changed, 17537 insertions(+), 1051 deletions(-)
 create mode 100644 apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift

diff --git a/apps/.i18n/apple-translation-contradictions.json b/apps/.i18n/apple-translation-contradictions.json
index 1cd929526d4..c2ed401a116 100644
--- a/apps/.i18n/apple-translation-contradictions.json
+++ b/apps/.i18n/apple-translation-contradictions.json
@@ -744,6 +744,62 @@
         "Arkivera"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Archived",
+      "translations": [
+        "مؤرشف",
+        "مؤرشفة"
+      ]
+    },
+    {
+      "locale": "es",
+      "source": "Archived",
+      "translations": [
+        "Archivada",
+        "Archivadas"
+      ]
+    },
+    {
+      "locale": "fr",
+      "source": "Archived",
+      "translations": [
+        "Archivé",
+        "Archivée"
+      ]
+    },
+    {
+      "locale": "it",
+      "source": "Archived",
+      "translations": [
+        "Archiviata",
+        "Archiviato"
+      ]
+    },
+    {
+      "locale": "pl",
+      "source": "Archived",
+      "translations": [
+        "Zarchiwizowana",
+        "Zarchiwizowane"
+      ]
+    },
+    {
+      "locale": "th",
+      "source": "Archived",
+      "translations": [
+        "เก็บถาวรแล้ว",
+        "เก็บเข้าคลังแล้ว"
+      ]
+    },
+    {
+      "locale": "tr",
+      "source": "Archived",
+      "translations": [
+        "Arşivlendi",
+        "Arşivlenmiş"
+      ]
+    },
     {
       "locale": "fr",
       "source": "Asking OpenClaw",
@@ -1955,6 +2011,38 @@
         "हटाएँ"
       ]
     },
+    {
+      "locale": "nl",
+      "source": "Delete",
+      "translations": [
+        "Verwijder",
+        "Verwijderen"
+      ]
+    },
+    {
+      "locale": "sv",
+      "source": "Delete",
+      "translations": [
+        "Radera",
+        "Ta bort"
+      ]
+    },
+    {
+      "locale": "sv",
+      "source": "Delete Group",
+      "translations": [
+        "Radera grupp",
+        "Ta bort grupp"
+      ]
+    },
+    {
+      "locale": "zh-CN",
+      "source": "Delete Group",
+      "translations": [
+        "删除分组",
+        "删除群组"
+      ]
+    },
     {
       "locale": "fa",
       "source": "Delete Session",
@@ -1979,6 +2067,22 @@
         "Удалить сессию"
       ]
     },
+    {
+      "locale": "fr",
+      "source": "Delete “%@”?",
+      "translations": [
+        "Supprimer « %@ » ?",
+        "Supprimer « %@ » ?"
+      ]
+    },
+    {
+      "locale": "sv",
+      "source": "Delete “%@”?",
+      "translations": [
+        "Radera ”%@”?",
+        "Ta bort ”%@”?"
+      ]
+    },
     {
       "locale": "it",
       "source": "Deny",
@@ -2427,6 +2531,14 @@
         "Listo"
       ]
     },
+    {
+      "locale": "hi",
+      "source": "Done",
+      "translations": [
+        "पूर्ण",
+        "हो गया"
+      ]
+    },
     {
       "locale": "it",
       "source": "Done",
@@ -3511,12 +3623,53 @@
         "Gateway設定"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Get Info…",
+      "translations": [
+        "إحضار المعلومات…",
+        "الحصول على معلومات…"
+      ]
+    },
+    {
+      "locale": "hi",
+      "source": "Get Info…",
+      "translations": [
+        "जानकारी पाएँ…",
+        "जानकारी प्राप्त करें…"
+      ]
+    },
+    {
+      "locale": "pl",
+      "source": "Get Info…",
+      "translations": [
+        "Informacje…",
+        "Pokaż informacje…"
+      ]
+    },
+    {
+      "locale": "pt-BR",
+      "source": "Get Info…",
+      "translations": [
+        "Obter Informações…",
+        "Obter informações…"
+      ]
+    },
+    {
+      "locale": "uk",
+      "source": "Get Info…",
+      "translations": [
+        "Отримати інформацію…",
+        "Переглянути інформацію…"
+      ]
+    },
     {
       "locale": "zh-CN",
       "source": "Group name",
       "translations": [
         "分组名称",
-        "组名称"
+        "组名称",
+        "群组名称"
       ]
     },
     {
@@ -4742,6 +4895,14 @@
         "ขาดหาย: %@"
       ]
     },
+    {
+      "locale": "ru",
+      "source": "Name",
+      "translations": [
+        "Имя",
+        "Название"
+      ]
+    },
     {
       "locale": "ar",
       "source": "Needs attention",
@@ -6276,14 +6437,31 @@
         "Vastzetten"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Pinned",
+      "translations": [
+        "مثبّت",
+        "مثبّتة"
+      ]
+    },
     {
       "locale": "es",
       "source": "Pinned",
       "translations": [
+        "Fijada",
         "Fijadas",
         "Fijado"
       ]
     },
+    {
+      "locale": "fr",
+      "source": "Pinned",
+      "translations": [
+        "Épinglé",
+        "Épinglée"
+      ]
+    },
     {
       "locale": "it",
       "source": "Pinned",
@@ -6293,6 +6471,14 @@
         "In evidenza"
       ]
     },
+    {
+      "locale": "pl",
+      "source": "Pinned",
+      "translations": [
+        "Przypięta",
+        "Przypięte"
+      ]
+    },
     {
       "locale": "pt-BR",
       "source": "Pinned",
@@ -6381,6 +6567,30 @@
         "Port"
       ]
     },
+    {
+      "locale": "ko",
+      "source": "Provider",
+      "translations": [
+        "제공업체",
+        "제공자"
+      ]
+    },
+    {
+      "locale": "ru",
+      "source": "Provider",
+      "translations": [
+        "Поставщик",
+        "Провайдер"
+      ]
+    },
+    {
+      "locale": "zh-CN",
+      "source": "Provider",
+      "translations": [
+        "提供商",
+        "提供方"
+      ]
+    },
     {
       "locale": "ja-JP",
       "source": "QR Scanner Unavailable",
@@ -6750,6 +6960,150 @@
         "دامنهٔ راه دور"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "أزل المرفقات أو انتظر حتى يكتمل التسليم قبل بدء محادثة جديدة.",
+        "أزِل المرفقات أو انتظر اكتمال التسليم قبل بدء محادثة جديدة."
+      ]
+    },
+    {
+      "locale": "de",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Entferne Anhänge oder warte, bis die Zustellung abgeschlossen ist, bevor du einen neuen Chat startest.",
+        "Entfernen Sie Anhänge oder warten Sie auf die Zustellung, bevor Sie einen neuen Chat starten."
+      ]
+    },
+    {
+      "locale": "es",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Elimina los adjuntos o espera a que se complete la entrega antes de iniciar un nuevo chat.",
+        "Elimina los archivos adjuntos o espera a que se complete la entrega antes de iniciar un nuevo chat."
+      ]
+    },
+    {
+      "locale": "fa",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "پیش از شروع گفتگوی جدید، پیوست‌ها را حذف کنید یا منتظر تکمیل ارسال بمانید.",
+        "پیش از شروع گفت‌وگوی جدید، پیوست‌ها را حذف کنید یا منتظر بمانید تا ارسال آن‌ها تکمیل شود."
+      ]
+    },
+    {
+      "locale": "fr",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Supprimez les pièces jointes ou attendez la fin de leur envoi avant de démarrer une nouvelle discussion.",
+        "Supprimez les pièces jointes ou attendez la livraison avant de démarrer une nouvelle conversation."
+      ]
+    },
+    {
+      "locale": "hi",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "नई चैट शुरू करने से पहले अटैचमेंट हटाएँ या डिलीवरी पूरी होने की प्रतीक्षा करें।",
+        "नई चैट शुरू करने से पहले अटैचमेंट हटाएं या डिलीवरी पूरी होने की प्रतीक्षा करें।"
+      ]
+    },
+    {
+      "locale": "id",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Hapus lampiran atau tunggu hingga pengiriman selesai sebelum memulai obrolan baru.",
+        "Hapus lampiran atau tunggu pengiriman selesai sebelum memulai obrolan baru."
+      ]
+    },
+    {
+      "locale": "ja-JP",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "新しいチャットを開始する前に、添付ファイルを削除するか、配信が完了するまでお待ちください。",
+        "新しいチャットを開始する前に、添付ファイルを削除するか送信が完了するのを待ってください。"
+      ]
+    },
+    {
+      "locale": "nl",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Verwijder bijlagen of wacht tot de bezorging is afgerond voordat je een nieuwe chat start.",
+        "Verwijder bijlagen of wacht tot de bezorging is voltooid voordat je een nieuwe chat start."
+      ]
+    },
+    {
+      "locale": "pt-BR",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Remova os anexos ou aguarde a conclusão da entrega antes de iniciar uma nova conversa.",
+        "Remova os anexos ou aguarde a entrega ser concluída antes de iniciar uma nova conversa."
+      ]
+    },
+    {
+      "locale": "ru",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Удалите вложения или дождитесь доставки, прежде чем начинать новый чат.",
+        "Удалите вложения или дождитесь завершения доставки, прежде чем начинать новый чат."
+      ]
+    },
+    {
+      "locale": "sv",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Ta bort bilagor eller vänta på att leveransen slutförs innan du startar en ny chatt.",
+        "Ta bort bilagor eller vänta tills leveransen är klar innan du startar en ny chatt."
+      ]
+    },
+    {
+      "locale": "th",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "นำไฟล์แนบออกหรือรอให้การส่งเสร็จสิ้นก่อนเริ่มแชตใหม่",
+        "ลบไฟล์แนบหรือรอให้การส่งเสร็จสิ้นก่อนเริ่มแชทใหม่"
+      ]
+    },
+    {
+      "locale": "uk",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Видаліть вкладення або дочекайтеся завершення доставки, перш ніж починати новий чат.",
+        "Видаліть вкладення або зачекайте на завершення доставлення, перш ніж починати новий чат."
+      ]
+    },
+    {
+      "locale": "vi",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "Gỡ tệp đính kèm hoặc chờ gửi xong trước khi bắt đầu cuộc trò chuyện mới.",
+        "Xóa tệp đính kèm hoặc chờ quá trình gửi hoàn tất trước khi bắt đầu cuộc trò chuyện mới."
+      ]
+    },
+    {
+      "locale": "zh-CN",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "请移除附件或等待发送完成后再开始新聊天。",
+        "请移除附件或等待发送完成后，再开始新聊天。"
+      ]
+    },
+    {
+      "locale": "zh-TW",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translations": [
+        "請先移除附件或等待傳送完成，再開始新的聊天。",
+        "請移除附件，或等待傳送問題解決後再開始新的聊天。"
+      ]
+    },
+    {
+      "locale": "ar",
+      "source": "Rename",
+      "translations": [
+        "إعادة التسمية",
+        "إعادة تسمية"
+      ]
+    },
     {
       "locale": "es",
       "source": "Rename",
@@ -6763,7 +7117,8 @@
       "source": "Rename",
       "translations": [
         "Ganti Nama",
-        "Ubah Nama"
+        "Ubah Nama",
+        "Ubah nama"
       ]
     },
     {
@@ -6782,6 +7137,30 @@
         "Hernoemen"
       ]
     },
+    {
+      "locale": "es",
+      "source": "Rename Group",
+      "translations": [
+        "Cambiar nombre del grupo",
+        "Renombrar grupo"
+      ]
+    },
+    {
+      "locale": "id",
+      "source": "Rename Group",
+      "translations": [
+        "Ganti Nama Grup",
+        "Ubah Nama Grup"
+      ]
+    },
+    {
+      "locale": "nl",
+      "source": "Rename Group",
+      "translations": [
+        "Groep hernoemen",
+        "Groepsnaam wijzigen"
+      ]
+    },
     {
       "locale": "es",
       "source": "Rename Session",
@@ -6847,6 +7226,14 @@
         "Перейменувати сесію"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Rename…",
+      "translations": [
+        "إعادة التسمية…",
+        "إعادة تسمية…"
+      ]
+    },
     {
       "locale": "es",
       "source": "Rename…",
@@ -7040,7 +7427,8 @@
       "translations": [
         "Ponów",
         "Ponów próbę",
-        "Retry"
+        "Retry",
+        "Spróbuj ponownie"
       ]
     },
     {
@@ -7116,12 +7504,133 @@
         "重試"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Run",
+      "translations": [
+        "التشغيل",
+        "تشغيل"
+      ]
+    },
+    {
+      "locale": "de",
+      "source": "Run",
+      "translations": [
+        "Ausführen",
+        "Ausführung"
+      ]
+    },
+    {
+      "locale": "es",
+      "source": "Run",
+      "translations": [
+        "Ejecución",
+        "Ejecutar"
+      ]
+    },
+    {
+      "locale": "fr",
+      "source": "Run",
+      "translations": [
+        "Exécuter",
+        "Exécution"
+      ]
+    },
     {
       "locale": "hi",
       "source": "Run",
       "translations": [
         "चलाएँ",
-        "चलाएं"
+        "चलाएं",
+        "रन"
+      ]
+    },
+    {
+      "locale": "id",
+      "source": "Run",
+      "translations": [
+        "Jalankan",
+        "Proses"
+      ]
+    },
+    {
+      "locale": "it",
+      "source": "Run",
+      "translations": [
+        "Esecuzione",
+        "Esegui"
+      ]
+    },
+    {
+      "locale": "nl",
+      "source": "Run",
+      "translations": [
+        "Uitvoeren",
+        "Uitvoering"
+      ]
+    },
+    {
+      "locale": "pl",
+      "source": "Run",
+      "translations": [
+        "Uruchom",
+        "Uruchomienie"
+      ]
+    },
+    {
+      "locale": "pt-BR",
+      "source": "Run",
+      "translations": [
+        "Executar",
+        "Execução"
+      ]
+    },
+    {
+      "locale": "ru",
+      "source": "Run",
+      "translations": [
+        "Запуск",
+        "Запустить"
+      ]
+    },
+    {
+      "locale": "sv",
+      "source": "Run",
+      "translations": [
+        "Kör",
+        "Körning"
+      ]
+    },
+    {
+      "locale": "th",
+      "source": "Run",
+      "translations": [
+        "การทำงาน",
+        "เรียกใช้"
+      ]
+    },
+    {
+      "locale": "tr",
+      "source": "Run",
+      "translations": [
+        "Çalıştır",
+        "Çalıştırma"
+      ]
+    },
+    {
+      "locale": "uk",
+      "source": "Run",
+      "translations": [
+        "Запуск",
+        "Запустити"
+      ]
+    },
+    {
+      "locale": "vi",
+      "source": "Run",
+      "translations": [
+        "Chạy",
+        "Lần chạy"
       ]
     },
     {
@@ -7154,6 +7663,7 @@
       "source": "Running",
       "translations": [
         "Actief",
+        "In uitvoering",
         "Wordt uitgevoerd"
       ]
     },
@@ -7161,6 +7671,7 @@
       "locale": "pl",
       "source": "Running",
       "translations": [
+        "Uruchomiona",
         "Uruchomione",
         "Uruchomiono",
         "W toku"
@@ -7182,6 +7693,54 @@
         "运行中"
       ]
     },
+    {
+      "locale": "ar",
+      "source": "Runtime",
+      "translations": [
+        "بيئة التشغيل",
+        "وقت التشغيل"
+      ]
+    },
+    {
+      "locale": "es",
+      "source": "Runtime",
+      "translations": [
+        "Entorno de ejecución",
+        "Runtime"
+      ]
+    },
+    {
+      "locale": "fa",
+      "source": "Runtime",
+      "translations": [
+        "زمان اجرا",
+        "محیط اجرا"
+      ]
+    },
+    {
+      "locale": "pt-BR",
+      "source": "Runtime",
+      "translations": [
+        "Ambiente de execução",
+        "Tempo de execução"
+      ]
+    },
+    {
+      "locale": "tr",
+      "source": "Runtime",
+      "translations": [
+        "Çalışma Zamanı",
+        "Çalışma zamanı"
+      ]
+    },
+    {
+      "locale": "vi",
+      "source": "Runtime",
+      "translations": [
+        "Môi trường chạy",
+        "Thời gian chạy"
+      ]
+    },
     {
       "locale": "de",
       "source": "Same Machine (Dev)",
diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json
index 90e2d6f7697..f453d3de337 100644
--- a/apps/.i18n/native-source.json
+++ b/apps/.i18n/native-source.json
@@ -35995,7 +35995,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 758,
+      "line": 816,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Talk mode off",
       "surface": "apple",
@@ -36003,7 +36003,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 759,
+      "line": 817,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Talk mode paused",
       "surface": "apple",
@@ -36011,7 +36011,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 761,
+      "line": 819,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Talk mode ready",
       "surface": "apple",
@@ -36019,7 +36019,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 762,
+      "line": 820,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Listening",
       "surface": "apple",
@@ -36027,7 +36027,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 763,
+      "line": 821,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Thinking",
       "surface": "apple",
@@ -36035,7 +36035,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 764,
+      "line": 822,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Speaking",
       "surface": "apple",
@@ -36043,7 +36043,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 768,
+      "line": 826,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "What would you like to work on?",
       "surface": "apple",
@@ -36051,7 +36051,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 772,
+      "line": 830,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Check OpenClaw status",
       "surface": "apple",
@@ -36059,7 +36059,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 773,
+      "line": 831,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Summarize the current OpenClaw status and tell me what needs attention.",
       "surface": "apple",
@@ -36067,7 +36067,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 776,
+      "line": 834,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "What can you do?",
       "surface": "apple",
@@ -36075,7 +36075,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 777,
+      "line": 835,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Show me what you can help with on this Mac right now.",
       "surface": "apple",
@@ -36083,7 +36083,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 780,
+      "line": 838,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Catch me up",
       "surface": "apple",
@@ -36091,7 +36091,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 781,
+      "line": 839,
       "path": "apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift",
       "source": "Summarize what happened in my sessions since yesterday.",
       "surface": "apple",
@@ -36819,279 +36819,751 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 33,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Search sessions",
+      "line": 30,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "This session cannot be archived while it is active or running.",
       "surface": "apple",
-      "id": "native.apple.8ec708a3605a2cc3"
+      "id": "native.apple.b1cdcb906a43d5d6"
     },
     {
       "kind": "ui-localized-call",
-      "line": 38,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "No Sessions",
+      "line": 32,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "The main session cannot be deleted.",
       "surface": "apple",
-      "id": "native.apple.23b069b4e7f97039"
+      "id": "native.apple.5817e3f3dab1ee19"
     },
     {
       "kind": "ui-localized-call",
-      "line": 39,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "No Results",
-      "surface": "apple",
-      "id": "native.apple.2d4ee298bdd1c05d"
-    },
-    {
-      "kind": "ui-call",
-      "line": 49,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "New Session",
+      "line": 34,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
       "surface": "apple",
-      "id": "native.apple.0058923f2ce8a3ec"
+      "id": "native.apple.a6b8df3f18171c91"
     },
     {
       "kind": "ui-localized-call",
-      "line": 51,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "New session",
+      "line": 141,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Running",
       "surface": "apple",
-      "id": "native.apple.66ba42960eb4135b"
+      "id": "native.apple.476b3862e0449857"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 61,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Rename Session",
+      "kind": "ui-call",
+      "line": 171,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Identity",
       "surface": "apple",
-      "id": "native.apple.36753ef2f1ed4264"
+      "id": "native.apple.83b41e41f428cffb"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 64,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Session name",
+      "kind": "ui-call",
+      "line": 172,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Name",
       "surface": "apple",
-      "id": "native.apple.c9de0a1510ef475f"
+      "id": "native.apple.ba6710da42846eed"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 65,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Rename",
+      "kind": "ui-call",
+      "line": 174,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Key",
       "surface": "apple",
-      "id": "native.apple.6ec5a13c0e6c20d9"
+      "id": "native.apple.bdb1928f7e63c4c6"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 71,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Cancel",
+      "kind": "ui-modifier",
+      "line": 181,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Copy session key",
       "surface": "apple",
-      "id": "native.apple.4c76665d89af4bec"
+      "id": "native.apple.7259d51423f8def0"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 76,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Delete Session",
+      "kind": "ui-call",
+      "line": 183,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Kind",
       "surface": "apple",
-      "id": "native.apple.afb4e6c99c63a28d"
+      "id": "native.apple.1494b638984ddca3"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 83,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "The session and its transcript are removed from the gateway.",
+      "kind": "ui-call",
+      "line": 187,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Organization",
       "surface": "apple",
-      "id": "native.apple.3d4ef32e42f136a4"
+      "id": "native.apple.49cd6c21bdd0d8da"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 105,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Delete “%@”?",
+      "kind": "ui-call",
+      "line": 188,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Group",
       "surface": "apple",
-      "id": "native.apple.90bcad5f067b4be1"
+      "id": "native.apple.83e2ae5c4c7dbb94"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 153,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Session running",
+      "kind": "ui-call",
+      "line": 189,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "None",
       "surface": "apple",
-      "id": "native.apple.9a7dca238fba628d"
+      "id": "native.apple.1ba465bfa16ed23b"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 158,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Session failed",
+      "kind": "ui-call",
+      "line": 199,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Pinned",
       "surface": "apple",
-      "id": "native.apple.fcfbfe5e97a95e9c"
+      "id": "native.apple.2c7c9e5dc8ad574e"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 167,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Unread",
+      "kind": "ui-call",
+      "line": 201,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Archived",
       "surface": "apple",
-      "id": "native.apple.ac85292b16a7465f"
+      "id": "native.apple.b0d3e265af9f562a"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 177,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Rename…",
+      "kind": "ui-call",
+      "line": 208,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Run",
       "surface": "apple",
-      "id": "native.apple.a174cb1027a9b881"
+      "id": "native.apple.de94ca2cf7d4d766"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 183,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Pin",
+      "kind": "ui-call",
+      "line": 209,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Status",
       "surface": "apple",
-      "id": "native.apple.134d6bf84d58fb38"
+      "id": "native.apple.f7a51dca3268b26c"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 183,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Unpin",
+      "kind": "ui-call",
+      "line": 210,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Model",
       "surface": "apple",
-      "id": "native.apple.e7815cc4ba359513"
+      "id": "native.apple.12678de5fa43321d"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 189,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Fork",
+      "kind": "ui-call",
+      "line": 211,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Provider",
       "surface": "apple",
-      "id": "native.apple.83f9f2db7eef6a19"
+      "id": "native.apple.8ec6bd6001df285d"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 195,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Mark Read",
+      "kind": "ui-call",
+      "line": 212,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Runtime",
       "surface": "apple",
-      "id": "native.apple.235614194dc19df2"
+      "id": "native.apple.f43534cf1ee73605"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 195,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Mark Unread",
+      "kind": "ui-call",
+      "line": 214,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Run duration",
       "surface": "apple",
-      "id": "native.apple.bc71f0d20b7f72a0"
+      "id": "native.apple.f0775e602bbe75ed"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 206,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Archive",
+      "kind": "ui-call",
+      "line": 221,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Worktree",
       "surface": "apple",
-      "id": "native.apple.c9e118f6aae18d97"
+      "id": "native.apple.ecde91d89eab026b"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 206,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Restore",
+      "kind": "ui-call",
+      "line": 222,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "ID",
       "surface": "apple",
-      "id": "native.apple.10365a351a1b58b3"
+      "id": "native.apple.1ef1698bb3ff7166"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 215,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Copy Session Key",
+      "kind": "ui-call",
+      "line": 223,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Branch",
       "surface": "apple",
-      "id": "native.apple.660f63319b89bd8e"
+      "id": "native.apple.69bc49f9663fa205"
     },
     {
-      "kind": "ui-localized-call",
+      "kind": "ui-call",
       "line": 224,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Delete Session…",
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Repository root",
       "surface": "apple",
-      "id": "native.apple.4aeb7c14c26dabac"
+      "id": "native.apple.aa430e81e52e2354"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 254,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Gateway connected",
+      "kind": "ui-call",
+      "line": 228,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Activity",
       "surface": "apple",
-      "id": "native.apple.6a3425ea2811ff88"
+      "id": "native.apple.6e851b012a982d38"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 255,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
-      "source": "Connecting…",
+      "kind": "ui-call",
+      "line": 229,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Updated",
       "surface": "apple",
-      "id": "native.apple.e3958d1053259f1d"
+      "id": "native.apple.bf87c6fd92c9315a"
     },
     {
-      "kind": "ui-named-argument",
-      "line": 67,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift",
-      "source": "Pinned",
+      "kind": "ui-call",
+      "line": 230,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Last activity",
       "surface": "apple",
-      "id": "native.apple.63320b6d5138c0db"
+      "id": "native.apple.dcb1734cba578b79"
     },
     {
-      "kind": "conditional-branch",
-      "line": 16,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Active",
+      "kind": "ui-call",
+      "line": 231,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Last interaction",
       "surface": "apple",
-      "id": "native.apple.0d9f7c1e0e65a820"
+      "id": "native.apple.58ca290e3f032865"
     },
     {
-      "kind": "conditional-branch",
-      "line": 17,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Archived",
+      "kind": "ui-call",
+      "line": 232,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Run started",
       "surface": "apple",
-      "id": "native.apple.3c71a4c13836cc75"
+      "id": "native.apple.7020bd521499f3b8"
     },
     {
       "kind": "ui-call",
-      "line": 65,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Scope",
+      "line": 233,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Run ended",
       "surface": "apple",
-      "id": "native.apple.0489ad746c8d35c2"
+      "id": "native.apple.abb2b24d6378b605"
     },
     {
-      "kind": "ui-named-argument",
-      "line": 77,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Search sessions",
+      "kind": "ui-modifier",
+      "line": 244,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Session Info",
       "surface": "apple",
-      "id": "native.apple.2c37581c7b88f741"
+      "id": "native.apple.cd7c3095a22f80a9"
     },
     {
-      "kind": "ui-modifier",
-      "line": 78,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Sessions",
+      "kind": "ui-call",
+      "line": 359,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Groups",
       "surface": "apple",
-      "id": "native.apple.43be8a2336e42faf"
+      "id": "native.apple.e308b012d84b3b3e"
     },
     {
-      "kind": "ui-modifier",
-      "line": 103,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Rename Session",
+      "kind": "ui-call",
+      "line": 366,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Rename…",
+      "surface": "apple",
+      "id": "native.apple.6438f66cfcaefaf7"
+    },
+    {
+      "kind": "ui-call",
+      "line": 370,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Delete…",
+      "surface": "apple",
+      "id": "native.apple.58b0f1df4985b0d1"
+    },
+    {
+      "kind": "ui-call",
+      "line": 383,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "No groups",
+      "surface": "apple",
+      "id": "native.apple.bc70cc0f0b882179"
+    },
+    {
+      "kind": "ui-call",
+      "line": 388,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Create Group",
+      "surface": "apple",
+      "id": "native.apple.cb3e1fa7783a35d2"
+    },
+    {
+      "kind": "ui-call",
+      "line": 392,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Add Group",
+      "surface": "apple",
+      "id": "native.apple.4ac72aeb70f107d8"
+    },
+    {
+      "kind": "ui-modifier",
+      "line": 412,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Session Groups",
+      "surface": "apple",
+      "id": "native.apple.23d628606fe0734f"
+    },
+    {
+      "kind": "ui-call",
+      "line": 415,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Done",
+      "surface": "apple",
+      "id": "native.apple.7777b2d2ec43ed59"
+    },
+    {
+      "kind": "ui-modifier",
+      "line": 423,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Rename Group",
+      "surface": "apple",
+      "id": "native.apple.0b0149661cacfe36"
+    },
+    {
+      "kind": "ui-call",
+      "line": 428,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Group name",
+      "surface": "apple",
+      "id": "native.apple.8cbd863aa4d0524f"
+    },
+    {
+      "kind": "ui-call",
+      "line": 430,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Rename",
+      "surface": "apple",
+      "id": "native.apple.6021088d5ed9c301"
+    },
+    {
+      "kind": "ui-call",
+      "line": 437,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Cancel",
+      "surface": "apple",
+      "id": "native.apple.e697417338a47751"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 440,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Delete “%@”?",
+      "surface": "apple",
+      "id": "native.apple.cc89328a14af7a23"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 441,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Delete group?",
+      "surface": "apple",
+      "id": "native.apple.4c09741db2e6c624"
+    },
+    {
+      "kind": "ui-call",
+      "line": 446,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Delete Group",
+      "surface": "apple",
+      "id": "native.apple.ddb1bbbd3c1a9c5e"
+    },
+    {
+      "kind": "ui-call",
+      "line": 453,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Sessions in this group become ungrouped.",
+      "surface": "apple",
+      "id": "native.apple.b049c8a4d2805e08"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 515,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "surface": "apple",
+      "id": "native.apple.5aa6082d78027c5f"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 555,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "No agents are available on this gateway.",
+      "surface": "apple",
+      "id": "native.apple.bb4b44183929c881"
+    },
+    {
+      "kind": "ui-call",
+      "line": 570,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "New Session Options",
+      "surface": "apple",
+      "id": "native.apple.6c89f35d53506406"
+    },
+    {
+      "kind": "ui-call",
+      "line": 572,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Agent",
+      "surface": "apple",
+      "id": "native.apple.5b0cde807ccb4241"
+    },
+    {
+      "kind": "ui-call",
+      "line": 580,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Create in a worktree",
+      "surface": "apple",
+      "id": "native.apple.124a640f9620d9cd"
+    },
+    {
+      "kind": "ui-call",
+      "line": 584,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Base ref (optional)",
+      "surface": "apple",
+      "id": "native.apple.632ce245d5575fea"
+    },
+    {
+      "kind": "ui-call",
+      "line": 594,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Retry",
+      "surface": "apple",
+      "id": "native.apple.fd81909fc9719a59"
+    },
+    {
+      "kind": "ui-call",
+      "line": 600,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "Create",
+      "surface": "apple",
+      "id": "native.apple.a085278be62286b2"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 618,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift",
+      "source": "The session could not be created.",
+      "surface": "apple",
+      "id": "native.apple.795ba37f6782cf28"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 64,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Search sessions",
+      "surface": "apple",
+      "id": "native.apple.8ec708a3605a2cc3"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 69,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "No Sessions",
+      "surface": "apple",
+      "id": "native.apple.23b069b4e7f97039"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 70,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "No Results",
+      "surface": "apple",
+      "id": "native.apple.2d4ee298bdd1c05d"
+    },
+    {
+      "kind": "ui-call",
+      "line": 81,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "New Session",
+      "surface": "apple",
+      "id": "native.apple.0058923f2ce8a3ec"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 83,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "New session",
+      "surface": "apple",
+      "id": "native.apple.66ba42960eb4135b"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 89,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "New session options",
+      "surface": "apple",
+      "id": "native.apple.2ef0e34db02ad255"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 117,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Rename Session",
+      "surface": "apple",
+      "id": "native.apple.36753ef2f1ed4264"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 120,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Session name",
+      "surface": "apple",
+      "id": "native.apple.c9de0a1510ef475f"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 121,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Rename",
+      "surface": "apple",
+      "id": "native.apple.6ec5a13c0e6c20d9"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 127,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Cancel",
+      "surface": "apple",
+      "id": "native.apple.4c76665d89af4bec"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 132,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Delete Session",
+      "surface": "apple",
+      "id": "native.apple.afb4e6c99c63a28d"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 139,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "The session and its transcript are removed from the gateway.",
+      "surface": "apple",
+      "id": "native.apple.3d4ef32e42f136a4"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 167,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Delete “%@”?",
+      "surface": "apple",
+      "id": "native.apple.90bcad5f067b4be1"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 215,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Session running",
+      "surface": "apple",
+      "id": "native.apple.9a7dca238fba628d"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 220,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Session failed",
+      "surface": "apple",
+      "id": "native.apple.fcfbfe5e97a95e9c"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 229,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Unread",
+      "surface": "apple",
+      "id": "native.apple.ac85292b16a7465f"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 238,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Get Info…",
+      "surface": "apple",
+      "id": "native.apple.f57a4b9c14d31867"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 245,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Rename…",
+      "surface": "apple",
+      "id": "native.apple.a174cb1027a9b881"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 251,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Pin",
+      "surface": "apple",
+      "id": "native.apple.134d6bf84d58fb38"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 251,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Unpin",
+      "surface": "apple",
+      "id": "native.apple.e7815cc4ba359513"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 257,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Fork",
+      "surface": "apple",
+      "id": "native.apple.83f9f2db7eef6a19"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 263,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Mark Read",
+      "surface": "apple",
+      "id": "native.apple.235614194dc19df2"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 263,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Mark Unread",
+      "surface": "apple",
+      "id": "native.apple.bc71f0d20b7f72a0"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 274,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Archive",
+      "surface": "apple",
+      "id": "native.apple.c9e118f6aae18d97"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 274,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Restore",
+      "surface": "apple",
+      "id": "native.apple.10365a351a1b58b3"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 283,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Copy Session Key",
+      "surface": "apple",
+      "id": "native.apple.660f63319b89bd8e"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 292,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Delete Session…",
+      "surface": "apple",
+      "id": "native.apple.4aeb7c14c26dabac"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 334,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Gateway connected",
+      "surface": "apple",
+      "id": "native.apple.6a3425ea2811ff88"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 335,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Connecting…",
+      "surface": "apple",
+      "id": "native.apple.e3958d1053259f1d"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 346,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift",
+      "source": "Retry session groups",
+      "surface": "apple",
+      "id": "native.apple.79f708b3bc1d3a6c"
+    },
+    {
+      "kind": "ui-named-argument",
+      "line": 76,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift",
+      "source": "Pinned",
+      "surface": "apple",
+      "id": "native.apple.63320b6d5138c0db"
+    },
+    {
+      "kind": "conditional-branch",
+      "line": 16,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Active",
+      "surface": "apple",
+      "id": "native.apple.0d9f7c1e0e65a820"
+    },
+    {
+      "kind": "conditional-branch",
+      "line": 17,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Archived",
+      "surface": "apple",
+      "id": "native.apple.3c71a4c13836cc75"
+    },
+    {
+      "kind": "ui-call",
+      "line": 76,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Scope",
+      "surface": "apple",
+      "id": "native.apple.0489ad746c8d35c2"
+    },
+    {
+      "kind": "ui-named-argument",
+      "line": 88,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Search sessions",
+      "surface": "apple",
+      "id": "native.apple.2c37581c7b88f741"
+    },
+    {
+      "kind": "ui-modifier",
+      "line": 89,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Sessions",
+      "surface": "apple",
+      "id": "native.apple.43be8a2336e42faf"
+    },
+    {
+      "kind": "ui-modifier",
+      "line": 146,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Rename Session",
       "surface": "apple",
       "id": "native.apple.0b379cdfcbd3247f"
     },
     {
       "kind": "ui-call",
-      "line": 109,
+      "line": 152,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
       "source": "Session name",
       "surface": "apple",
@@ -37099,79 +37571,111 @@
     },
     {
       "kind": "ui-call",
-      "line": 124,
+      "line": 167,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
       "source": "Cancel",
       "surface": "apple",
       "id": "native.apple.833fe2915430c89d"
     },
     {
-      "kind": "conditional-branch",
-      "line": 153,
+      "kind": "ui-modifier",
+      "line": 178,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "No archived sessions",
+      "source": "Delete selected sessions?",
       "surface": "apple",
-      "id": "native.apple.b67eaecec1b423ac"
+      "id": "native.apple.751e0f6b81cd374a"
     },
     {
-      "kind": "conditional-branch",
-      "line": 153,
+      "kind": "ui-call",
+      "line": 183,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "No sessions found",
+      "source": "Delete Sessions",
       "surface": "apple",
-      "id": "native.apple.b2435a79abf0c794"
+      "id": "native.apple.aa679276581b0058"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 162,
+      "kind": "ui-call",
+      "line": 187,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Restore",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
       "surface": "apple",
-      "id": "native.apple.f0e9d8f69c1d9190"
+      "id": "native.apple.f837129cbee23297"
     },
     {
-      "kind": "ui-localized-call",
-      "line": 163,
+      "kind": "ui-call",
+      "line": 216,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Archive",
+      "source": "Groups",
       "surface": "apple",
-      "id": "native.apple.666ba6eb696e649f"
+      "id": "native.apple.bf09df5e38a7a950"
     },
     {
       "kind": "ui-modifier",
-      "line": 197,
+      "line": 222,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Pinned",
+      "source": "Manage session groups",
       "surface": "apple",
-      "id": "native.apple.05cb1fecc5844b69"
+      "id": "native.apple.64013cfee5e25305"
     },
     {
-      "kind": "ui-call",
-      "line": 235,
+      "kind": "conditional-branch",
+      "line": 226,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Rename",
+      "source": "Done",
       "surface": "apple",
-      "id": "native.apple.080fce25e4a9bb61"
+      "id": "native.apple.185f4688f98e244e"
     },
     {
       "kind": "conditional-branch",
-      "line": 243,
+      "line": 226,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Pin",
+      "source": "Select",
       "surface": "apple",
-      "id": "native.apple.d148288258094aa6"
+      "id": "native.apple.58133fc5791847e6"
     },
     {
       "kind": "conditional-branch",
-      "line": 243,
+      "line": 241,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
-      "source": "Unpin",
+      "source": "No archived sessions",
       "surface": "apple",
-      "id": "native.apple.3c62aaf44e6ab4d4"
+      "id": "native.apple.b67eaecec1b423ac"
+    },
+    {
+      "kind": "conditional-branch",
+      "line": 241,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "No sessions found",
+      "surface": "apple",
+      "id": "native.apple.b2435a79abf0c794"
     },
     {
       "kind": "ui-localized-call",
-      "line": 264,
+      "line": 260,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Restore",
+      "surface": "apple",
+      "id": "native.apple.f0e9d8f69c1d9190"
+    },
+    {
+      "kind": "ui-call",
+      "line": 310,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Get Info…",
+      "surface": "apple",
+      "id": "native.apple.158cfa096c57bcb9"
+    },
+    {
+      "kind": "ui-call",
+      "line": 317,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Rename",
+      "surface": "apple",
+      "id": "native.apple.080fce25e4a9bb61"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 346,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
       "source": "Fork",
       "surface": "apple",
@@ -37179,7 +37683,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 273,
+      "line": 355,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
       "source": "Mark Read",
       "surface": "apple",
@@ -37187,12 +37691,52 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 274,
+      "line": 356,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
       "source": "Mark Unread",
       "surface": "apple",
       "id": "native.apple.4f259c4409cfcc75"
     },
+    {
+      "kind": "ui-modifier",
+      "line": 387,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Pinned",
+      "surface": "apple",
+      "id": "native.apple.05cb1fecc5844b69"
+    },
+    {
+      "kind": "ui-call",
+      "line": 394,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Pin",
+      "surface": "apple",
+      "id": "native.apple.d148288258094aa6"
+    },
+    {
+      "kind": "ui-call",
+      "line": 395,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Unpin",
+      "surface": "apple",
+      "id": "native.apple.3c62aaf44e6ab4d4"
+    },
+    {
+      "kind": "ui-call",
+      "line": 396,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Archive",
+      "surface": "apple",
+      "id": "native.apple.666ba6eb696e649f"
+    },
+    {
+      "kind": "ui-call",
+      "line": 398,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift",
+      "source": "Delete",
+      "surface": "apple",
+      "id": "native.apple.b09b91392835fe58"
+    },
     {
       "kind": "ui-localized-call",
       "line": 49,
@@ -37443,23 +37987,39 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 1150,
-      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "line": 84,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "surface": "apple",
-      "id": "native.apple.710c7bd117a7cc12"
+      "id": "native.apple.787047d0da6b8b9f"
+    },
+    {
+      "kind": "ui-localized-call",
+      "line": 229,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift",
+      "source": "Gateway changed before the session operation started.",
+      "surface": "apple",
+      "id": "native.apple.980f552bb0f96c0f"
     },
     {
       "kind": "ui-localized-call",
-      "line": 1208,
+      "line": 773,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "surface": "apple",
       "id": "native.apple.d93e6fe16ec1b0e5"
     },
+    {
+      "kind": "ui-localized-call",
+      "line": 1156,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "surface": "apple",
+      "id": "native.apple.710c7bd117a7cc12"
+    },
     {
       "kind": "ui-modifier",
-      "line": 77,
+      "line": 78,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Clear this session's history?",
       "surface": "apple",
@@ -37467,7 +38027,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 83,
+      "line": 84,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Clear History",
       "surface": "apple",
@@ -37475,7 +38035,7 @@
     },
     {
       "kind": "ui-localized-call-multiline",
-      "line": 88,
+      "line": 89,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "This resets the conversation for %@. The session key stays the same.",
       "surface": "apple",
@@ -37483,7 +38043,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 94,
+      "line": 95,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Rename Session",
       "surface": "apple",
@@ -37491,7 +38051,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 95,
+      "line": 96,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Session name",
       "surface": "apple",
@@ -37499,7 +38059,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 96,
+      "line": 97,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Rename",
       "surface": "apple",
@@ -37507,7 +38067,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 101,
+      "line": 102,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Cancel",
       "surface": "apple",
@@ -37515,7 +38075,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 142,
+      "line": 143,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Export Transcript",
       "surface": "apple",
@@ -37523,7 +38083,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 151,
+      "line": 152,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Sessions",
       "surface": "apple",
@@ -37531,7 +38091,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 239,
+      "line": 240,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "%@ (override)",
       "surface": "apple",
@@ -37539,7 +38099,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 245,
+      "line": 246,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Thinking",
       "surface": "apple",
@@ -37547,7 +38107,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 249,
+      "line": 250,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Thinking level",
       "surface": "apple",
@@ -37555,7 +38115,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 262,
+      "line": 263,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Full",
       "surface": "apple",
@@ -37563,7 +38123,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 268,
+      "line": 269,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Verbosity",
       "surface": "apple",
@@ -37571,7 +38131,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 277,
+      "line": 278,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Default (inherited)",
       "surface": "apple",
@@ -37579,7 +38139,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 279,
+      "line": 280,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "On",
       "surface": "apple",
@@ -37587,7 +38147,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 280,
+      "line": 281,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Off",
       "surface": "apple",
@@ -37595,7 +38155,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 282,
+      "line": 283,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Fast",
       "surface": "apple",
@@ -37603,7 +38163,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 285,
+      "line": 286,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Fast responses",
       "surface": "apple",
@@ -37611,7 +38171,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 299,
+      "line": 300,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Pinned",
       "surface": "apple",
@@ -37619,7 +38179,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 302,
+      "line": 303,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Recent",
       "surface": "apple",
@@ -37627,7 +38187,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 319,
+      "line": 320,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Model",
       "surface": "apple",
@@ -37635,7 +38195,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 333,
+      "line": 334,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Default",
       "surface": "apple",
@@ -37643,7 +38203,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 347,
+      "line": 348,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "New Session",
       "surface": "apple",
@@ -37653,13 +38213,21 @@
       "kind": "ui-call",
       "line": 355,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
+      "source": "New Session Options…",
+      "surface": "apple",
+      "id": "native.apple.a7119fbf9d25df5e"
+    },
+    {
+      "kind": "ui-call",
+      "line": 362,
+      "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Refresh",
       "surface": "apple",
       "id": "native.apple.5361129a24118af6"
     },
     {
       "kind": "ui-call",
-      "line": 362,
+      "line": 369,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Sessions…",
       "surface": "apple",
@@ -37667,7 +38235,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 374,
+      "line": 381,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Rename Session…",
       "surface": "apple",
@@ -37675,7 +38243,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 382,
+      "line": 389,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Fork Session",
       "surface": "apple",
@@ -37683,7 +38251,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 393,
+      "line": 400,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Unpin",
       "surface": "apple",
@@ -37691,7 +38259,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 394,
+      "line": 401,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Pin",
       "surface": "apple",
@@ -37699,7 +38267,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 405,
+      "line": 412,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Mark Read",
       "surface": "apple",
@@ -37707,7 +38275,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 406,
+      "line": 413,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Mark Unread",
       "surface": "apple",
@@ -37715,7 +38283,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 422,
+      "line": 429,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Restore",
       "surface": "apple",
@@ -37723,7 +38291,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 423,
+      "line": 430,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Archive",
       "surface": "apple",
@@ -37731,7 +38299,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 435,
+      "line": 442,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Copy Session Key",
       "surface": "apple",
@@ -37739,7 +38307,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 441,
+      "line": 448,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Export Transcript…",
       "surface": "apple",
@@ -37747,7 +38315,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 453,
+      "line": 460,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Show Reasoning",
       "surface": "apple",
@@ -37755,7 +38323,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 465,
+      "line": 472,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Show Tool Activity",
       "surface": "apple",
@@ -37763,7 +38331,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 482,
+      "line": 489,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Clear History…",
       "surface": "apple",
@@ -37771,7 +38339,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 485,
+      "line": 492,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Session",
       "surface": "apple",
@@ -37779,7 +38347,7 @@
     },
     {
       "kind": "ui-modifier",
-      "line": 488,
+      "line": 500,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Session actions",
       "surface": "apple",
@@ -37787,7 +38355,7 @@
     },
     {
       "kind": "ui-localized-call",
-      "line": 522,
+      "line": 534,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Session cost %@",
       "surface": "apple",
@@ -37795,7 +38363,7 @@
     },
     {
       "kind": "ui-call",
-      "line": 528,
+      "line": 540,
       "path": "apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift",
       "source": "Compact Session",
       "surface": "apple",
diff --git a/apps/.i18n/native/ar.json b/apps/.i18n/native/ar.json
index bdc68a35d7e..21db4ef335c 100644
--- a/apps/.i18n/native/ar.json
+++ b/apps/.i18n/native/ar.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "المستخدم"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "لا يمكن أرشفة هذه الجلسة أثناء نشاطها أو تشغيلها."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "لا يمكن حذف الجلسة الرئيسية."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "أزل المرفقات أو انتظر تسليمها قبل أرشفة هذه الجلسة أو حذفها."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "قيد التشغيل"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "الهوية"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "الاسم"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "المفتاح"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "نسخ مفتاح الجلسة"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "النوع"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "المؤسسة"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "المجموعة"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "لا شيء"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "مثبّتة"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "مؤرشفة"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "التشغيل"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "الحالة"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "النموذج"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "المزوّد"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "بيئة التشغيل"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "مدة التشغيل"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "شجرة العمل"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "المعرّف"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "الفرع"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "جذر المستودع"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "النشاط"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "تم التحديث"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "آخر نشاط"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "آخر تفاعل"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "بدأ التشغيل"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "انتهى التشغيل"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "معلومات الجلسة"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "المجموعات"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "إعادة التسمية…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "حذف…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "لا توجد مجموعات"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "إنشاء مجموعة"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "إضافة مجموعة"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "مجموعات الجلسة"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "تم"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "إعادة تسمية المجموعة"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "اسم المجموعة"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "إعادة التسمية"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "إلغاء"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "حذف «%@»؟"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "حذف المجموعة؟"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "حذف المجموعة"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "ستصبح الجلسات في هذه المجموعة غير مصنّفة ضمن مجموعة."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "تغيّر Gateway. أغلق المجموعات وأعد فتحها للمتابعة."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "لا توجد وكلاء متاحة على هذا Gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "خيارات الجلسة الجديدة"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "الوكيل"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "إنشاء في شجرة عمل"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "المرجع الأساسي (اختياري)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "إعادة المحاولة"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "إنشاء"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "تعذّر إنشاء الجلسة."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "جلسة جديدة"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "خيارات الجلسة الجديدة"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "غير مقروء"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "الحصول على معلومات…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "جارٍ الاتصال…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "إعادة محاولة تحميل مجموعات الجلسات"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "إلغاء"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "حذف الجلسات المحددة؟"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "حذف الجلسات"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "ستُزال كل جلسة محددة ونصها من Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "المجموعات"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "إدارة مجموعات الجلسات"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "تم"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "تحديد"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "استعادة"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "أرشفة"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "مثبّت"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "إحضار المعلومات…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "إعادة تسمية"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "تثبيت"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "إلغاء التثبيت"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "وضع علامة كغير مقروء"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "مثبّت"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "تثبيت"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "إلغاء التثبيت"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "أرشفة"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "حذف"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "تمت الإضافة إلى قائمة الانتظار بعد تغيير المسار"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "أزِل المرفقات أو انتظر اكتمال التسليم قبل تبديل المحادثات."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "أزل المرفقات أو انتظر حتى يكتمل التسليم قبل بدء محادثة جديدة."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "تغيّر Gateway قبل بدء عملية الجلسة."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "أزِل المرفقات أو انتظر اكتمال التسليم قبل بدء محادثة جديدة."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "أزِل المرفقات أو انتظر اكتمال التسليم قبل تبديل المحادثات."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "جلسة جديدة"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "خيارات جلسة جديدة…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/de.json b/apps/.i18n/native/de.json
index 8c510faeef4..69777918739 100644
--- a/apps/.i18n/native/de.json
+++ b/apps/.i18n/native/de.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Benutzer"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Diese Sitzung kann nicht archiviert werden, solange sie aktiv ist oder ausgeführt wird."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Die Hauptsitzung kann nicht gelöscht werden."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Entfernen Sie Anhänge oder warten Sie auf deren Zustellung, bevor Sie diese Sitzung archivieren oder löschen."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Wird ausgeführt"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identität"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Name"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Schlüssel"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Sitzungsschlüssel kopieren"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Art"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organisation"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Gruppe"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Keine"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Angeheftet"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Archiviert"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Ausführung"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modell"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Anbieter"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Laufzeit"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Ausführungsdauer"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Arbeitsbaum"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branch"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Repository-Stammverzeichnis"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Aktivität"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Aktualisiert"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Letzte Aktivität"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Letzte Interaktion"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Ausführung gestartet"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Ausführung beendet"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Sitzungsinformationen"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Gruppen"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Umbenennen…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Löschen…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Keine Gruppen"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Gruppe erstellen"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Gruppe hinzufügen"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Sitzungsgruppen"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Fertig"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Gruppe umbenennen"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Gruppenname"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Umbenennen"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Abbrechen"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "„%@“ löschen?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Gruppe löschen?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Gruppe löschen"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Sitzungen in dieser Gruppe werden aus der Gruppe entfernt."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway wurde geändert. Schließen und öffnen Sie „Gruppen“ erneut, um fortzufahren."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Auf diesem Gateway sind keine Agenten verfügbar."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Optionen für neue Sitzungen"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agent"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "In einem Worktree erstellen"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Basis-Ref (optional)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Erneut versuchen"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Erstellen"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Die Sitzung konnte nicht erstellt werden."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Neue Sitzung"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Optionen für neue Sitzungen"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Ungelesen"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Informationen…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Verbindung wird hergestellt…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Sitzungsgruppen erneut laden"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Abbrechen"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Ausgewählte Sitzungen löschen?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Sitzungen löschen"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Alle ausgewählten Sitzungen und ihre Transkripte werden aus dem Gateway entfernt."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Gruppen"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Sitzungsgruppen verwalten"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Fertig"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Auswählen"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Wiederherstellen"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archivieren"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Angeheftet"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Informationen…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Umbenennen"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Anheften"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Lösen"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Als ungelesen markieren"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Angeheftet"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Anheften"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Lösen"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archivieren"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Löschen"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "nach Routenänderung in Warteschlange"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Entfernen Sie Anhänge oder warten Sie auf die Zustellung, bevor Sie den Chat wechseln."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Entferne Anhänge oder warte, bis die Zustellung abgeschlossen ist, bevor du einen neuen Chat startest."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Das Gateway wurde geändert, bevor der Sitzungsvorgang gestartet wurde."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Entfernen Sie Anhänge oder warten Sie auf die Zustellung, bevor Sie einen neuen Chat starten."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Entfernen Sie Anhänge oder warten Sie auf die Zustellung, bevor Sie den Chat wechseln."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Neue Sitzung"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Optionen für neue Sitzung…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/es.json b/apps/.i18n/native/es.json
index e07df840c5e..b0e650c3a3a 100644
--- a/apps/.i18n/native/es.json
+++ b/apps/.i18n/native/es.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Usuario"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Esta sesión no se puede archivar mientras esté activa o en ejecución."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "La sesión principal no se puede eliminar."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Elimina los archivos adjuntos o espera a que se entreguen antes de archivar o eliminar esta sesión."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "En ejecución"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identidad"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nombre"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Clave"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Copiar clave de sesión"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Tipo"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organización"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grupo"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Ninguno"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Fijada"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Archivada"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Ejecución"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Estado"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modelo"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Proveedor"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Entorno de ejecución"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Duración de la ejecución"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Árbol de trabajo"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Rama"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Raíz del repositorio"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Actividad"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Actualizado"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Última actividad"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Última interacción"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Ejecución iniciada"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Ejecución finalizada"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Información de la sesión"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Grupos"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Cambiar nombre…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Eliminar…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "No hay grupos"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Crear grupo"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Añadir grupo"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Grupos de sesiones"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Listo"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Cambiar nombre del grupo"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nombre del grupo"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Renombrar"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Cancelar"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "¿Eliminar “%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "¿Eliminar el grupo?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Eliminar grupo"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Las sesiones de este grupo quedarán sin agrupar."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "El Gateway ha cambiado. Cierra y vuelve a abrir Grupos para continuar."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "No hay agentes disponibles en este Gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opciones de nueva sesión"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agente"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Crear en un worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Referencia base (opcional)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Reintentar"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Crear"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "No se pudo crear la sesión."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nueva sesión"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opciones de nueva sesión"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "No leído"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Obtener información…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Conectando…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Reintentar grupos de sesiones"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Cancelar"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "¿Eliminar las sesiones seleccionadas?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Eliminar sesiones"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Cada sesión seleccionada y su transcripción se eliminarán del Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Grupos"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Gestionar grupos de sesiones"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Listo"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Seleccionar"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Restaurar"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archivar"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Fijadas"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Obtener información…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Cambiar nombre"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Fijar"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Dejar de fijar"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Marcar como no leído"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Fijadas"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Fijar"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Dejar de fijar"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archivar"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Eliminar"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "en cola tras cambio de ruta"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Elimina los adjuntos o espera a que se complete la entrega antes de cambiar de chat."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Elimina los archivos adjuntos o espera a que se complete la entrega antes de iniciar un nuevo chat."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "El Gateway cambió antes de que se iniciara la operación de sesión."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Elimina los adjuntos o espera a que se complete la entrega antes de iniciar un nuevo chat."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Elimina los adjuntos o espera a que se complete la entrega antes de cambiar de chat."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nueva sesión"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opciones de nueva sesión…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/fa.json b/apps/.i18n/native/fa.json
index 6f19b11908e..1c727271c60 100644
--- a/apps/.i18n/native/fa.json
+++ b/apps/.i18n/native/fa.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "کاربر"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "این نشست تا زمانی که فعال یا در حال اجرا است، قابل بایگانی نیست."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "نشست اصلی قابل حذف نیست."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "پیش از بایگانی یا حذف این نشست، پیوست‌ها را حذف کنید یا منتظر تحویل آن‌ها بمانید."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "در حال اجرا"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "هویت"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "نام"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "کلید"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "کپی کلید نشست"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "نوع"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "سازمان"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "گروه"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "هیچ‌کدام"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "سنجاق‌شده"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "بایگانی‌شده"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "اجرا"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "وضعیت"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "مدل"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "ارائه‌دهنده"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "محیط اجرا"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "مدت اجرا"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "درخت کاری"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "شناسه"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "شاخه"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "ریشهٔ مخزن"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "فعالیت"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "به‌روزرسانی‌شده"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "آخرین فعالیت"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "آخرین تعامل"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "اجرا آغاز شد"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "اجرا پایان یافت"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "اطلاعات نشست"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "گروه‌ها"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "تغییر نام…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "حذف…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "هیچ گروهی وجود ندارد"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "ایجاد گروه"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "افزودن گروه"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "گروه‌های نشست"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "انجام شد"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "تغییر نام گروه"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "نام گروه"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "تغییر نام"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "لغو"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "«%@» حذف شود؟"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "گروه حذف شود؟"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "حذف گروه"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "نشست‌های این گروه از گروه خارج می‌شوند."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway تغییر کرد. برای ادامه، Groups را ببندید و دوباره باز کنید."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "هیچ عاملی در این Gateway در دسترس نیست."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "گزینه‌های نشست جدید"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "عامل"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "ایجاد در یک worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "ارجاع پایه (اختیاری)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "تلاش مجدد"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "ایجاد"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "جلسه ایجاد نشد."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "نشست جدید"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "گزینه‌های نشست جدید"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "خوانده‌نشده"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "دریافت اطلاعات…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "در حال اتصال…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "تلاش مجدد برای گروه‌های نشست"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "لغو"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "نشست‌های انتخاب‌شده حذف شوند؟"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "حذف نشست‌ها"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "هر نشست انتخاب‌شده و رونوشت آن از Gateway حذف خواهد شد."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "گروه‌ها"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "مدیریت گروه‌های نشست"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "انجام شد"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "انتخاب"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "بازیابی"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "بایگانی"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "سنجاق‌شده"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "دریافت اطلاعات…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "تغییر نام"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "سنجاق کردن"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "برداشتن سنجاق"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "علامت‌گذاری به‌عنوان خوانده‌نشده"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "سنجاق‌شده"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "سنجاق کردن"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "برداشتن سنجاق"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "بایگانی"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "حذف"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "پس از تغییر مسیر در صف قرار گرفت"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "پیش از تغییر گفتگو، پیوست‌ها را حذف کنید یا منتظر تکمیل ارسال بمانید."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "پیش از شروع گفت‌وگوی جدید، پیوست‌ها را حذف کنید یا منتظر بمانید تا ارسال آن‌ها تکمیل شود."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway پیش از شروع عملیات نشست تغییر کرد."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "پیش از شروع گفتگوی جدید، پیوست‌ها را حذف کنید یا منتظر تکمیل ارسال بمانید."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "پیش از تغییر گفتگو، پیوست‌ها را حذف کنید یا منتظر تکمیل ارسال بمانید."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "نشست جدید"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "گزینه‌های نشست جدید…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/fr.json b/apps/.i18n/native/fr.json
index 7c3ceb43676..cc0beb4258e 100644
--- a/apps/.i18n/native/fr.json
+++ b/apps/.i18n/native/fr.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Utilisateur"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Cette session ne peut pas être archivée tant qu’elle est active ou en cours d’exécution."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "La session principale ne peut pas être supprimée."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Supprimez les pièces jointes ou attendez leur envoi avant d’archiver ou de supprimer cette session."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "En cours d’exécution"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identité"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nom"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Clé"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Copier la clé de session"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Type"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organisation"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Groupe"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Aucun"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Épinglée"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Archivée"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Exécution"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "État"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modèle"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Fournisseur"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Environnement d’exécution"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Durée d’exécution"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Arbre de travail"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branche"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Racine du dépôt"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Activité"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Mis à jour"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Dernière activité"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Dernière interaction"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Début de l’exécution"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Fin de l’exécution"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Informations sur la session"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Groupes"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Renommer…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Supprimer…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Aucun groupe"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Créer un groupe"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Ajouter un groupe"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Groupes de sessions"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Terminé"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Renommer le groupe"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nom du groupe"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Renommer"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Annuler"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Supprimer « %@ » ?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Supprimer le groupe ?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Supprimer le groupe"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Les sessions de ce groupe ne seront plus regroupées."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Le Gateway a changé. Fermez et rouvrez Groupes pour continuer."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Aucun agent n’est disponible sur ce Gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Options de la nouvelle session"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agent"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Créer dans un worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Référence de base (facultatif)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Réessayer"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Créer"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "La session n’a pas pu être créée."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nouvelle session"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Options de la nouvelle session"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Non lu"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Lire les informations…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Connexion…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Réessayer de charger les groupes de sessions"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Annuler"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Supprimer les sessions sélectionnées ?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Supprimer les sessions"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Chaque session sélectionnée et sa transcription seront supprimées du Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Groupes"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Gérer les groupes de sessions"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Terminé"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Sélectionner"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Restaurer"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archiver"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Épinglé"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Lire les informations…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Renommer"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Épingler"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Désépingler"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Marquer comme non lu"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Épinglé"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Épingler"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Désépingler"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archiver"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Supprimer"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "mis en file d’attente après le changement d’itinéraire"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Supprimez les pièces jointes ou attendez la livraison avant de changer de conversation."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Supprimez les pièces jointes ou attendez la fin de leur envoi avant de démarrer une nouvelle discussion."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Le Gateway a changé avant le début de l’opération sur la session."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Supprimez les pièces jointes ou attendez la livraison avant de démarrer une nouvelle conversation."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Supprimez les pièces jointes ou attendez la livraison avant de changer de conversation."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nouvelle session"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Options de la nouvelle session…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/hi.json b/apps/.i18n/native/hi.json
index 4903d9928f0..279802847fe 100644
--- a/apps/.i18n/native/hi.json
+++ b/apps/.i18n/native/hi.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "उपयोगकर्ता"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "यह सत्र सक्रिय या चल रहा होने के दौरान संग्रहीत नहीं किया जा सकता।"
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "मुख्य सत्र को हटाया नहीं जा सकता।"
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "इस सत्र को संग्रहीत करने या हटाने से पहले अटैचमेंट हटाएँ या डिलीवरी की प्रतीक्षा करें।"
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "चल रहा है"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "पहचान"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "नाम"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "कुंजी"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "सत्र कुंजी कॉपी करें"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "प्रकार"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "संगठन"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "समूह"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "कोई नहीं"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "पिन किया गया"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "संग्रहीत"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "रन"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "स्थिति"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "मॉडल"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "प्रदाता"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "रनटाइम"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "रन की अवधि"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "वर्कट्री"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "ब्रांच"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "रिपॉज़िटरी रूट"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "गतिविधि"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "अपडेट किया गया"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "पिछली गतिविधि"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "पिछला इंटरैक्शन"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "रन शुरू हुआ"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "रन समाप्त हुआ"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "सेशन की जानकारी"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "समूह"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "नाम बदलें…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "हटाएँ…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "कोई समूह नहीं"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "समूह बनाएँ"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "समूह जोड़ें"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "सेशन समूह"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "पूर्ण"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "समूह का नाम बदलें"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "समूह का नाम"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "नाम बदलें"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "रद्द करें"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "“%@” को हटाएँ?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "समूह हटाएँ?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "समूह हटाएँ"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "इस समूह के सत्र असमूहीकृत हो जाएँगे।"
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway बदल गया है। जारी रखने के लिए Groups को बंद करके फिर से खोलें।"
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "इस Gateway पर कोई एजेंट उपलब्ध नहीं है।"
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "नए सत्र के विकल्प"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "एजेंट"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "वर्कट्री में बनाएँ"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "बेस रेफ़रेंस (वैकल्पिक)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "पुनः प्रयास करें"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "बनाएँ"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "सत्र बनाया नहीं जा सका।"
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "नया सत्र"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "नए सत्र के विकल्प"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "अपठित"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "जानकारी पाएँ…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "कनेक्ट हो रहा है…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "सत्र समूहों के लिए फिर से प्रयास करें"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "रद्द करें"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "चुने गए सत्र हटाएँ?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "सत्र हटाएँ"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "हर चुना गया सत्र और उसकी प्रतिलिपि Gateway से हटा दी जाएगी।"
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "समूह"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "सत्र समूह प्रबंधित करें"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "पूर्ण"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "चुनें"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "पुनर्स्थापित करें"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "संग्रहित करें"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "पिन किया गया"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "जानकारी प्राप्त करें…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "नाम बदलें"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "पिन करें"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "अनपिन करें"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "अपठित चिह्नित करें"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "पिन किया गया"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "पिन करें"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "अनपिन करें"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "संग्रहित करें"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "हटाएँ"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "रूट बदलने के बाद कतार में रखा गया"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "चैट बदलने से पहले अटैचमेंट हटाएं या डिलीवरी पूरी होने की प्रतीक्षा करें।"
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "नई चैट शुरू करने से पहले अटैचमेंट हटाएँ या डिलीवरी पूरी होने की प्रतीक्षा करें।"
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "सत्र संचालन शुरू होने से पहले Gateway बदल गया।"
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "नई चैट शुरू करने से पहले अटैचमेंट हटाएं या डिलीवरी पूरी होने की प्रतीक्षा करें।"
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "चैट बदलने से पहले अटैचमेंट हटाएं या डिलीवरी पूरी होने की प्रतीक्षा करें।"
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "नया सेशन"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "नए सत्र के विकल्प…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/id.json b/apps/.i18n/native/id.json
index c5f7ceeecfd..dc50df90b73 100644
--- a/apps/.i18n/native/id.json
+++ b/apps/.i18n/native/id.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Pengguna"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Sesi ini tidak dapat diarsipkan saat masih aktif atau berjalan."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Sesi utama tidak dapat dihapus."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Hapus lampiran atau tunggu hingga pengiriman selesai sebelum mengarsipkan atau menghapus sesi ini."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Berjalan"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identitas"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nama"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Kunci"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Salin kunci sesi"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Jenis"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organisasi"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grup"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Tidak ada"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Disematkan"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Diarsipkan"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Proses"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Model"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Penyedia"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Runtime"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Durasi proses"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branch"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Root repositori"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Aktivitas"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Diperbarui"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Aktivitas terakhir"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Interaksi terakhir"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Proses dimulai"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Proses berakhir"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Info Sesi"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Grup"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Ubah nama…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Hapus…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Tidak ada grup"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Buat Grup"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Tambahkan Grup"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Grup Sesi"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Selesai"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Ubah Nama Grup"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nama grup"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Ubah nama"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Batal"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Hapus “%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Hapus grup?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Hapus Grup"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Sesi dalam grup ini tidak akan lagi dikelompokkan."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway berubah. Tutup dan buka kembali Grup untuk melanjutkan."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Tidak ada agen yang tersedia di gateway ini."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opsi Sesi Baru"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agen"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Buat di worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Ref dasar (opsional)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Coba lagi"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Buat"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Sesi tidak dapat dibuat."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Sesi baru"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opsi sesi baru"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Belum dibaca"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Dapatkan Info…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Menghubungkan…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Coba lagi grup sesi"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Batal"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Hapus sesi yang dipilih?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Hapus Sesi"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Setiap sesi yang dipilih beserta transkripnya akan dihapus dari Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Grup"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Kelola grup sesi"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Selesai"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Pilih"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Pulihkan"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Arsipkan"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Disematkan"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Dapatkan Info…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Ganti Nama"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Sematkan"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Lepas Sematan"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Tandai Belum Dibaca"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Disematkan"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Sematkan"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Lepas Sematan"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Arsipkan"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Hapus"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "diantrekan setelah perubahan rute"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Hapus lampiran atau tunggu pengiriman selesai sebelum beralih obrolan."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Hapus lampiran atau tunggu hingga pengiriman selesai sebelum memulai obrolan baru."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway berubah sebelum operasi sesi dimulai."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Hapus lampiran atau tunggu pengiriman selesai sebelum memulai obrolan baru."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Hapus lampiran atau tunggu pengiriman selesai sebelum beralih obrolan."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Sesi Baru"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opsi Sesi Baru…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/it.json b/apps/.i18n/native/it.json
index fd91454d974..148c5f65924 100644
--- a/apps/.i18n/native/it.json
+++ b/apps/.i18n/native/it.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Utente"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Questa sessione non può essere archiviata mentre è attiva o in esecuzione."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "La sessione principale non può essere eliminata."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Rimuovi gli allegati o attendi la consegna prima di archiviare o eliminare questa sessione."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "In esecuzione"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identità"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nome"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Chiave"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Copia chiave della sessione"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Tipo"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organizzazione"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Gruppo"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Nessuno"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "In evidenza"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Archiviata"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Esecuzione"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Stato"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modello"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Provider"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Runtime"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Durata dell'esecuzione"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branch"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Radice del repository"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Attività"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Aggiornato"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Ultima attività"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Ultima interazione"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Esecuzione avviata"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Esecuzione terminata"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Informazioni sulla sessione"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Gruppi"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Rinomina…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Elimina…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Nessun gruppo"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Crea gruppo"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Aggiungi gruppo"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Gruppi della sessione"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Fine"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Rinomina gruppo"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nome del gruppo"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Rinomina"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Annulla"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Eliminare “%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Eliminare il gruppo?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Elimina gruppo"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Le sessioni in questo gruppo non saranno più raggruppate."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Il Gateway è cambiato. Chiudi e riapri Gruppi per continuare."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Nessun agente è disponibile su questo gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opzioni nuova sessione"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agente"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Crea in un worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Riferimento di base (facoltativo)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Riprova"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Crea"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Non è stato possibile creare la sessione."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nuova sessione"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opzioni nuova sessione"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Da leggere"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Ottieni informazioni…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Connessione…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Riprova gruppi di sessioni"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Annulla"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Eliminare le sessioni selezionate?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Elimina sessioni"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Ogni sessione selezionata e la relativa trascrizione verranno rimosse dal Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Gruppi"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Gestisci gruppi di sessioni"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Fine"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Seleziona"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Ripristina"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archivia"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Fissato"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Ottieni informazioni…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Rinomina"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Fissa"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Rimuovi"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Segna come non letta"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Fissato"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Fissa"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Rimuovi"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archivia"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Elimina"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "in coda dopo la modifica del percorso"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Rimuovi gli allegati o attendi il completamento della consegna prima di cambiare chat."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Rimuovi gli allegati o attendi il completamento della consegna prima di iniziare una nuova chat."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Il Gateway è cambiato prima dell'inizio dell'operazione sulla sessione."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Rimuovi gli allegati o attendi il completamento della consegna prima di iniziare una nuova chat."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Rimuovi gli allegati o attendi il completamento della consegna prima di cambiare chat."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nuova sessione"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opzioni nuova sessione…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/ja-JP.json b/apps/.i18n/native/ja-JP.json
index 6bcaa809dce..db0959fca2f 100644
--- a/apps/.i18n/native/ja-JP.json
+++ b/apps/.i18n/native/ja-JP.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "ユーザー"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "このセッションは、アクティブまたは実行中のためアーカイブできません。"
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "メインセッションは削除できません。"
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "このセッションをアーカイブまたは削除する前に、添付ファイルを削除するか、配信が完了するまでお待ちください。"
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "実行中"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "名前"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "キー"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "セッションキーをコピー"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "種類"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "組織"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "グループ"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "なし"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "ピン留め済み"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "アーカイブ済み"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "実行"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "ステータス"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "モデル"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "プロバイダー"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "ランタイム"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "実行時間"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "ワークツリー"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "ブランチ"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "リポジトリのルート"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "アクティビティ"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "更新日時"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "最終アクティビティ"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "最終操作"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "実行開始"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "実行終了"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "セッション情報"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "グループ"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "名前を変更…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "削除…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "グループなし"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "グループを作成"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "グループを追加"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "セッショングループ"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "完了"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "グループ名を変更"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "グループ名"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "名前を変更"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "キャンセル"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "「%@」を削除しますか？"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "グループを削除しますか？"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "グループを削除"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "このグループ内のセッションはグループ化されていない状態になります。"
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gatewayが変更されました。続行するには「グループ」を閉じて再度開いてください。"
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "このGatewayでは利用可能なエージェントがありません。"
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "新規セッションのオプション"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "エージェント"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "ワークツリーに作成"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "ベース参照（任意）"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "再試行"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "作成"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "セッションを作成できませんでした。"
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "新規セッション"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "新規セッションのオプション"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "未読"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "情報を見る…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "接続中…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "セッショングループを再試行"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "キャンセル"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "選択したセッションを削除しますか？"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "セッションを削除"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "選択した各セッションとそのトランスクリプトがGatewayから削除されます。"
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "グループ"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "セッショングループを管理"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "完了"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "選択"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "復元"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "アーカイブ"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "ピン留め済み"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "情報を見る…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "名前を変更"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "ピン留め"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "ピン留めを解除"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "未読にする"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "ピン留め済み"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "ピン留め"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "ピン留めを解除"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "アーカイブ"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "削除"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "経路変更後にキューに追加済み"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "チャットを切り替える前に、添付ファイルを削除するか送信が完了するのを待ってください。"
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "新しいチャットを開始する前に、添付ファイルを削除するか、配信が完了するまでお待ちください。"
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "セッション操作を開始する前にGatewayが変更されました。"
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "新しいチャットを開始する前に、添付ファイルを削除するか送信が完了するのを待ってください。"
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "チャットを切り替える前に、添付ファイルを削除するか送信が完了するのを待ってください。"
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "新規セッション"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "新規セッションのオプション…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/ko.json b/apps/.i18n/native/ko.json
index b3b25c582ba..31709b79b83 100644
--- a/apps/.i18n/native/ko.json
+++ b/apps/.i18n/native/ko.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "사용자"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "이 세션은 활성 상태이거나 실행 중인 동안 보관할 수 없습니다."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "기본 세션은 삭제할 수 없습니다."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "이 세션을 보관하거나 삭제하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "실행 중"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "이름"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "키"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "세션 키 복사"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "종류"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "조직"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "그룹"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "없음"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "고정됨"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "보관됨"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "실행"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "상태"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "모델"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "제공업체"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "런타임"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "실행 시간"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "브랜치"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "저장소 루트"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "활동"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "업데이트됨"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "최근 활동"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "최근 상호작용"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "실행 시작"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "실행 종료"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "세션 정보"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "그룹"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "이름 변경…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "삭제…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "그룹 없음"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "그룹 생성"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "그룹 추가"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "세션 그룹"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "완료"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "그룹 이름 변경"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "그룹 이름"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "이름 변경"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "취소"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "“%@”을(를) 삭제하시겠습니까?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "그룹을 삭제하시겠습니까?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "그룹 삭제"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "이 그룹의 세션은 그룹에서 해제됩니다."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway가 변경되었습니다. 계속하려면 그룹을 닫았다가 다시 여세요."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "이 Gateway에서 사용할 수 있는 에이전트가 없습니다."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "새 세션 옵션"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "에이전트"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "워크트리에 생성"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "기준 참조(선택 사항)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "다시 시도"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "생성"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "세션을 생성할 수 없습니다."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "새 세션"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "새 세션 옵션"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "읽지 않음"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "정보 가져오기…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "연결 중…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "세션 그룹 다시 시도"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "취소"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "선택한 세션을 삭제하시겠습니까?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "세션 삭제"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "선택한 각 세션과 해당 기록이 Gateway에서 삭제됩니다."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "그룹"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "세션 그룹 관리"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "완료"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "선택"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "복원"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "보관"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "고정됨"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "정보 가져오기…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "이름 바꾸기"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "고정"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "고정 해제"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "읽지 않음으로 표시"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "고정됨"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "고정"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "고정 해제"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "보관"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "삭제"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "경로 변경 후 대기열에 추가됨"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "채팅을 전환하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "새 채팅을 시작하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "세션 작업이 시작되기 전에 Gateway가 변경되었습니다."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "새 채팅을 시작하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "채팅을 전환하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "새 세션"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "새 세션 옵션…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/nl.json b/apps/.i18n/native/nl.json
index c04764803fc..48457f1af24 100644
--- a/apps/.i18n/native/nl.json
+++ b/apps/.i18n/native/nl.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Gebruiker"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Deze sessie kan niet worden gearchiveerd terwijl deze actief of in uitvoering is."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "De hoofdsessie kan niet worden verwijderd."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Verwijder bijlagen of wacht op de bezorging voordat u deze sessie archiveert of verwijdert."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "In uitvoering"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identiteit"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Naam"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Sleutel"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Sessiesleutel kopiëren"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Type"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organisatie"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Groep"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Geen"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Vastgezet"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Gearchiveerd"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Uitvoering"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Model"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Provider"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Runtime"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Uitvoeringsduur"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branch"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Repositoryhoofdmap"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Activiteit"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Bijgewerkt"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Laatste activiteit"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Laatste interactie"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Uitvoering gestart"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Uitvoering beëindigd"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Sessie-informatie"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Groepen"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Naam wijzigen…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Verwijderen…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Geen groepen"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Groep aanmaken"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Groep toevoegen"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Sessiegroepen"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Gereed"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Groepsnaam wijzigen"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Groepsnaam"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Hernoemen"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Annuleren"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "‘%@’ verwijderen?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Groep verwijderen?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Groep verwijderen"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Sessies in deze groep worden uit de groep gehaald."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway gewijzigd. Sluit Groepen en open het opnieuw om door te gaan."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Er zijn geen agents beschikbaar op deze gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opties voor nieuwe sessie"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agent"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Aanmaken in een worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Basisreferentie (optioneel)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Opnieuw proberen"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Aanmaken"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "De sessie kon niet worden aangemaakt."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nieuwe sessie"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opties voor nieuwe sessie"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Ongelezen"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Toon info…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Verbinden…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Sessiegroepen opnieuw proberen"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Annuleren"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Geselecteerde sessies verwijderen?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Sessies verwijderen"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Elke geselecteerde sessie en het bijbehorende transcript worden van de Gateway verwijderd."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Groepen"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Sessiegroepen beheren"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Gereed"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Selecteer"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Herstel"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archiveren"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Vastgezet"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Toon info…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Hernoemen"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Vastzetten"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Losmaken"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Markeer als ongelezen"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Vastgezet"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Vastzetten"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Losmaken"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archiveren"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Verwijder"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "in wachtrij na routewijziging"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Verwijder bijlagen of wacht tot de bezorging is voltooid voordat je van chat wisselt."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Verwijder bijlagen of wacht tot de bezorging is afgerond voordat je een nieuwe chat start."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "De Gateway is gewijzigd voordat de sessiebewerking is gestart."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Verwijder bijlagen of wacht tot de bezorging is voltooid voordat je een nieuwe chat start."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Verwijder bijlagen of wacht tot de bezorging is voltooid voordat je van chat wisselt."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nieuwe sessie"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opties voor nieuwe sessie…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/pl.json b/apps/.i18n/native/pl.json
index 1c571e23d63..61a96c82dbe 100644
--- a/apps/.i18n/native/pl.json
+++ b/apps/.i18n/native/pl.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Użytkownik"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Nie można zarchiwizować tej sesji, gdy jest aktywna lub uruchomiona."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Nie można usunąć sesji głównej."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Usuń załączniki lub poczekaj na ich dostarczenie przed zarchiwizowaniem albo usunięciem tej sesji."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Uruchomiona"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Tożsamość"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nazwa"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Klucz"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Kopiuj klucz sesji"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Rodzaj"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organizacja"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grupa"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Brak"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Przypięta"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Zarchiwizowana"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Uruchomienie"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Model"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Dostawca"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Środowisko uruchomieniowe"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Czas trwania uruchomienia"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Drzewo robocze"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Gałąź"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Katalog główny repozytorium"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Aktywność"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Zaktualizowano"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Ostatnia aktywność"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Ostatnia interakcja"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Rozpoczęcie uruchomienia"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Zakończenie uruchomienia"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Informacje o sesji"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Grupy"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Zmień nazwę…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Usuń…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Brak grup"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Utwórz grupę"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Dodaj grupę"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Grupy sesji"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Gotowe"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Zmień nazwę grupy"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nazwa grupy"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Zmień nazwę"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Anuluj"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Usunąć „%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Usunąć grupę?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Usuń grupę"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Sesje w tej grupie przestaną być przypisane do grupy."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway został zmieniony. Zamknij i ponownie otwórz Grupy, aby kontynuować."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Na tym gatewayu nie są dostępni żadni agenci."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opcje nowej sesji"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agent"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Utwórz w drzewie roboczym"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Referencja bazowa (opcjonalnie)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Spróbuj ponownie"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Utwórz"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Nie udało się utworzyć sesji."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nowa sesja"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opcje nowej sesji"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Nieprzeczytane"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Informacje…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Łączenie…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Ponów próbę wczytania grup sesji"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Anuluj"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Usunąć wybrane sesje?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Usuń sesje"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Każda wybrana sesja i jej transkrypcja zostaną usunięte z Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Grupy"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Zarządzaj grupami sesji"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Gotowe"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Wybierz"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Przywróć"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Archiwizuj"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Przypięte"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Pokaż informacje…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Zmień nazwę"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Przypnij"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Odepnij"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Oznacz jako nieprzeczytane"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Przypięte"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Przypnij"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Odepnij"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Archiwizuj"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Usuń"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "dodano do kolejki po zmianie trasy"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Usuń załączniki lub poczekaj na zakończenie dostarczania przed przełączeniem czatów."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Usuń załączniki lub poczekaj na zakończenie dostarczania przed rozpoczęciem nowego czatu."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway zmienił się przed rozpoczęciem operacji na sesji."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Usuń załączniki lub poczekaj na zakończenie dostarczania przed rozpoczęciem nowego czatu."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Usuń załączniki lub poczekaj na zakończenie dostarczania przed przełączeniem czatów."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nowa sesja"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opcje nowej sesji…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/pt-BR.json b/apps/.i18n/native/pt-BR.json
index ce4630b53e5..df9a4950d27 100644
--- a/apps/.i18n/native/pt-BR.json
+++ b/apps/.i18n/native/pt-BR.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Usuário"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Esta sessão não pode ser arquivada enquanto estiver ativa ou em execução."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "A sessão principal não pode ser excluída."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Remova os anexos ou aguarde a entrega antes de arquivar ou excluir esta sessão."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Em execução"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identidade"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Nome"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Chave"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Copiar chave da sessão"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Tipo"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organização"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grupo"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Nenhum"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Fixada"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Arquivada"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Execução"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modelo"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Provedor"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Ambiente de execução"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Duração da execução"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Árvore de trabalho"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Branch"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Raiz do repositório"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Atividade"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Atualizado"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Última atividade"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Última interação"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Execução iniciada"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Execução encerrada"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Informações da sessão"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Grupos"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Renomear…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Excluir…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Nenhum grupo"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Criar grupo"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Adicionar grupo"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Grupos da sessão"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Concluído"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Renomear grupo"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Nome do grupo"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Renomear"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Cancelar"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Excluir “%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Excluir grupo?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Excluir grupo"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "As sessões deste grupo ficarão sem grupo."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "O Gateway foi alterado. Feche e reabra Grupos para continuar."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Nenhum agente está disponível neste gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Opções da nova sessão"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agente"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Criar em uma worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Referência base (opcional)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Tentar novamente"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Criar"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Não foi possível criar a sessão."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Nova sessão"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Opções da nova sessão"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Não lida"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Obter informações…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Conectando…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Tentar carregar os grupos de sessões novamente"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Cancelar"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Excluir as sessões selecionadas?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Excluir sessões"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Cada sessão selecionada e sua transcrição serão removidas do gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Grupos"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Gerenciar grupos de sessões"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Concluído"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Selecionar"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Restaurar"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Arquivar"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Fixada"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Obter Informações…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Renomear"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Fixar"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Desafixar"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Marcar como não lida"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Fixada"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Fixar"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Desafixar"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Arquivar"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Excluir"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "na fila após alteração de rota"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Remova os anexos ou aguarde a entrega ser concluída antes de trocar de conversa."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Remova os anexos ou aguarde a conclusão da entrega antes de iniciar uma nova conversa."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "O Gateway foi alterado antes do início da operação da sessão."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Remova os anexos ou aguarde a entrega ser concluída antes de iniciar uma nova conversa."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Remova os anexos ou aguarde a entrega ser concluída antes de trocar de conversa."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Nova sessão"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Opções de Nova Sessão…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/ru.json b/apps/.i18n/native/ru.json
index 5090db37b6f..4a22497f8e0 100644
--- a/apps/.i18n/native/ru.json
+++ b/apps/.i18n/native/ru.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Пользователь"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Этот сеанс нельзя архивировать, пока он активен или выполняется."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Основной сеанс нельзя удалить."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Удалите вложения или дождитесь доставки, прежде чем архивировать или удалять этот сеанс."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Выполняется"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Идентификация"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Имя"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Ключ"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Скопировать ключ сеанса"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Тип"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Организация"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Группа"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Нет"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Закреплено"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "В архиве"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Запуск"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Статус"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Модель"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Провайдер"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Среда выполнения"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Длительность выполнения"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Рабочее дерево"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Ветка"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Корень репозитория"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Активность"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Обновлено"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Последняя активность"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Последнее взаимодействие"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Запуск начат"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Запуск завершён"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Информация о сеансе"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Группы"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Переименовать…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Удалить…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Нет групп"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Создать группу"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Добавить группу"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Группы сеансов"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Готово"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Переименовать группу"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Название группы"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Переименовать"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Отмена"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Удалить «%@»?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Удалить группу?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Удалить группу"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Сеансы в этой группе останутся без группы."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway изменён. Закройте и снова откройте раздел «Группы», чтобы продолжить."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "На этом Gateway нет доступных агентов."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Параметры нового сеанса"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Агент"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Создать в рабочем дереве"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Базовая ссылка (необязательно)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Повторить"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Создать"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Не удалось создать сеанс."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Новая сессия"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Параметры нового сеанса"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Непрочитанное"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Сведения…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Подключение…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Повторить загрузку групп сеансов"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Отмена"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Удалить выбранные сеансы?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Удалить сеансы"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Все выбранные сеансы и их расшифровки будут удалены из Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Группы"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Управление группами сеансов"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Готово"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Выбрать"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Восстановить"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Архивировать"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Закреплено"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Сведения…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Переименовать"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Закрепить"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Открепить"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Отметить как непрочитанное"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Закреплено"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Закрепить"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Открепить"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Архивировать"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Удалить"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "поставлено в очередь после изменения маршрута"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Удалите вложения или дождитесь доставки, прежде чем переключать чаты."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Удалите вложения или дождитесь завершения доставки, прежде чем начинать новый чат."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway изменился до начала операции с сеансом."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Удалите вложения или дождитесь доставки, прежде чем начинать новый чат."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Удалите вложения или дождитесь доставки, прежде чем переключать чаты."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Новая сессия"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Параметры нового сеанса…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/sv.json b/apps/.i18n/native/sv.json
index 04e0ce7a598..098563ec96e 100644
--- a/apps/.i18n/native/sv.json
+++ b/apps/.i18n/native/sv.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Användare"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Den här sessionen kan inte arkiveras medan den är aktiv eller körs."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Huvudsessionen kan inte tas bort."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Ta bort bilagor eller vänta på leverans innan du arkiverar eller tar bort den här sessionen."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Körs"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Identitet"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Namn"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Nyckel"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Kopiera sessionsnyckel"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Typ"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Organisation"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grupp"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Ingen"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Fäst"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Arkiverad"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Körning"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Status"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Modell"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Leverantör"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Körmiljö"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Körtid"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Arbetskopia"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Gren"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Repositoriets rot"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Aktivitet"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Uppdaterad"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Senaste aktivitet"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Senaste interaktion"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Körning startad"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Körning avslutad"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Sessionsinformation"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Grupper"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Byt namn…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Radera…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Inga grupper"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Skapa grupp"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Lägg till grupp"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Sessionsgrupper"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Klar"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Byt namn på grupp"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Gruppnamn"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Byt namn"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Avbryt"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Ta bort ”%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Ta bort gruppen?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Ta bort grupp"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Sessioner i den här gruppen blir ogrupperade."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway har ändrats. Stäng och öppna Grupper igen för att fortsätta."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Inga agenter är tillgängliga på denna gateway."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Alternativ för ny session"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Agent"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Skapa i ett arbetsträd"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Basreferens (valfritt)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Försök igen"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Skapa"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Sessionen kunde inte skapas."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Ny session"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Alternativ för ny session"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Oläst"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Visa info…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Ansluter…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Försök läsa in sessionsgrupper igen"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Avbryt"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Ta bort valda sessioner?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Ta bort sessioner"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Varje vald session och dess transkription tas bort från Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Grupper"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Hantera sessionsgrupper"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Klar"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Välj"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Återställ"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Arkivera"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Fästa"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Visa info…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Byt namn"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Fäst"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Lossa"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Markera som oläst"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Fästa"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Fäst"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Lossa"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Arkivera"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Radera"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "köad efter ruttändring"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Ta bort bilagor eller vänta på att leveransen slutförs innan du byter chatt."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Ta bort bilagor eller vänta tills leveransen är klar innan du startar en ny chatt."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway ändrades innan sessionsåtgärden startade."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Ta bort bilagor eller vänta på att leveransen slutförs innan du startar en ny chatt."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Ta bort bilagor eller vänta på att leveransen slutförs innan du byter chatt."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Ny session"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Alternativ för ny session…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/th.json b/apps/.i18n/native/th.json
index d9d55e6e7bb..2b2987b5bf6 100644
--- a/apps/.i18n/native/th.json
+++ b/apps/.i18n/native/th.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "ผู้ใช้"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "ไม่สามารถเก็บเซสชันนี้เข้าคลังขณะที่ยังใช้งานหรือกำลังทำงานอยู่ได้"
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "ไม่สามารถลบเซสชันหลักได้"
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "นำไฟล์แนบออกหรือรอให้ส่งเสร็จก่อนเก็บเซสชันนี้เข้าคลังหรือลบ"
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "กำลังทำงาน"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "ข้อมูลประจำตัว"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "ชื่อ"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "คีย์"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "คัดลอกคีย์เซสชัน"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "ประเภท"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "องค์กร"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "กลุ่ม"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "ไม่มี"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "ปักหมุดแล้ว"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "เก็บเข้าคลังแล้ว"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "การทำงาน"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "สถานะ"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "โมเดล"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "ผู้ให้บริการ"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "รันไทม์"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "ระยะเวลาการทำงาน"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "สาขา"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "รากของ Repository"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "กิจกรรม"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "อัปเดตแล้ว"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "กิจกรรมล่าสุด"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "การโต้ตอบล่าสุด"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "เริ่มการทำงาน"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "สิ้นสุดการทำงาน"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "ข้อมูลเซสชัน"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "กลุ่ม"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "เปลี่ยนชื่อ…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "ลบ…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "ไม่มีกลุ่ม"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "สร้างกลุ่ม"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "เพิ่มกลุ่ม"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "กลุ่มเซสชัน"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "เสร็จสิ้น"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "เปลี่ยนชื่อกลุ่ม"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "ชื่อกลุ่ม"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "เปลี่ยนชื่อ"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "ยกเลิก"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "ลบ “%@” หรือไม่?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "ลบกลุ่มหรือไม่?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "ลบกลุ่ม"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "เซสชันในกลุ่มนี้จะไม่อยู่ในกลุ่มใด"
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway มีการเปลี่ยนแปลง ปิดแล้วเปิดกลุ่มอีกครั้งเพื่อดำเนินการต่อ"
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "ไม่มีเอเจนต์ที่พร้อมใช้งานบน Gateway นี้"
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "ตัวเลือกเซสชันใหม่"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "เอเจนต์"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "สร้างใน worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Base ref (ไม่บังคับ)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "ลองอีกครั้ง"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "สร้าง"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "ไม่สามารถสร้างเซสชันได้"
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "เซสชันใหม่"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "ตัวเลือกเซสชันใหม่"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "ยังไม่ได้อ่าน"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "ดูข้อมูล…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "กำลังเชื่อมต่อ…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "ลองโหลดกลุ่มเซสชันอีกครั้ง"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "ยกเลิก"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "ลบเซสชันที่เลือกหรือไม่?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "ลบเซสชัน"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "เซสชันที่เลือกแต่ละรายการและบันทึกการสนทนาจะถูกลบออกจาก Gateway"
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "กลุ่ม"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "จัดการกลุ่มเซสชัน"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "เสร็จสิ้น"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "เลือก"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "กู้คืน"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "เก็บถาวร"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "ปักหมุดแล้ว"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "ดูข้อมูล…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "เปลี่ยนชื่อ"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "ปักหมุด"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "เลิกปักหมุด"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "ทำเครื่องหมายว่ายังไม่ได้อ่าน"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "ปักหมุดแล้ว"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "ปักหมุด"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "เลิกปักหมุด"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "เก็บถาวร"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "ลบ"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "อยู่ในคิวหลังจากเปลี่ยนเส้นทาง"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "ลบไฟล์แนบหรือรอให้การส่งเสร็จสิ้นก่อนสลับแชท"
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "นำไฟล์แนบออกหรือรอให้การส่งเสร็จสิ้นก่อนเริ่มแชตใหม่"
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway มีการเปลี่ยนแปลงก่อนเริ่มดำเนินการกับเซสชัน"
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "ลบไฟล์แนบหรือรอให้การส่งเสร็จสิ้นก่อนเริ่มแชทใหม่"
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "ลบไฟล์แนบหรือรอให้การส่งเสร็จสิ้นก่อนสลับแชท"
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "เซสชันใหม่"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "ตัวเลือกเซสชันใหม่…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/tr.json b/apps/.i18n/native/tr.json
index 755de2c2d6f..c2fd594d1f1 100644
--- a/apps/.i18n/native/tr.json
+++ b/apps/.i18n/native/tr.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Kullanıcı"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Bu oturum etkinken veya çalışırken arşivlenemez."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Ana oturum silinemez."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Bu oturumu arşivlemeden veya silmeden önce ekleri kaldırın ya da teslim edilmelerini bekleyin."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Çalışıyor"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Kimlik"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Ad"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Anahtar"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Oturum anahtarını kopyala"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Tür"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Kuruluş"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Grup"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Yok"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Sabitlenmiş"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Arşivlenmiş"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Çalıştırma"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Durum"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Model"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Sağlayıcı"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Çalışma zamanı"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Çalıştırma süresi"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Çalışma ağacı"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "Kimlik"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Dal"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Depo kökü"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Etkinlik"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Güncellendi"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Son etkinlik"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Son etkileşim"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Çalıştırma başladı"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Çalıştırma sona erdi"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Oturum Bilgileri"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Gruplar"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Yeniden adlandır…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Sil…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Grup yok"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Grup Oluştur"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Grup Ekle"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Oturum Grupları"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Bitti"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Grubu Yeniden Adlandır"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Grup adı"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Yeniden Adlandır"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "İptal"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "“%@” silinsin mi?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Grup silinsin mi?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Grubu Sil"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Bu gruptaki oturumlar gruptan çıkarılır."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway değişti. Devam etmek için Gruplar'ı kapatıp yeniden açın."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Bu Gateway'de kullanılabilir aracı yok."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Yeni Oturum Seçenekleri"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Aracı"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Bir worktree içinde oluştur"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Temel ref (isteğe bağlı)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Yeniden Dene"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Oluştur"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Oturum oluşturulamadı."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Yeni oturum"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Yeni oturum seçenekleri"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Okunmamış"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Bilgi Al…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Bağlanıyor…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Oturum gruplarını yeniden dene"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "İptal"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Seçili oturumlar silinsin mi?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Oturumları Sil"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Seçili her oturum ve dökümü gateway'den kaldırılacaktır."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Gruplar"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Oturum gruplarını yönet"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Bitti"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Seç"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Geri Yükle"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Arşivle"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Sabitlenmiş"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Bilgi Al…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Yeniden Adlandır"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Sabitle"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Sabitlemeyi Kaldır"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Okunmadı Olarak İşaretle"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Sabitlenmiş"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Sabitle"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Sabitlemeyi Kaldır"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Arşivle"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Sil"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "rota değişikliğinden sonra kuyruğa alındı"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Sohbetleri değiştirmeden önce ekleri kaldırın veya teslimatın tamamlanmasını bekleyin."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Yeni bir sohbet başlatmadan önce ekleri kaldırın veya teslimatın tamamlanmasını bekleyin."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Oturum işlemi başlamadan önce Gateway değişti."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Yeni bir sohbet başlatmadan önce ekleri kaldırın veya teslimatın tamamlanmasını bekleyin."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Sohbetleri değiştirmeden önce ekleri kaldırın veya teslimatın tamamlanmasını bekleyin."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Yeni Oturum"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Yeni Oturum Seçenekleri…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/uk.json b/apps/.i18n/native/uk.json
index ffe30eee470..875502dbcc0 100644
--- a/apps/.i18n/native/uk.json
+++ b/apps/.i18n/native/uk.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Користувач"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Цей сеанс не можна архівувати, доки він активний або виконується."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Основний сеанс не можна видалити."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Видаліть вкладення або дочекайтеся їх доставлення, перш ніж архівувати чи видаляти цей сеанс."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Виконується"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Ідентифікація"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Назва"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Ключ"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Копіювати ключ сеансу"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Тип"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Організація"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Група"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Немає"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Закріплено"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Заархівовано"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Запуск"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Статус"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Модель"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Постачальник"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Середовище виконання"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Тривалість виконання"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Робоче дерево"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Гілка"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Корінь репозиторію"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Активність"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Оновлено"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Остання активність"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Остання взаємодія"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Запуск розпочато"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Запуск завершено"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Відомості про сеанс"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Групи"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Перейменувати…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Видалити…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Немає груп"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Створити групу"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Додати групу"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Групи сеансів"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Готово"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Перейменувати групу"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Назва групи"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Перейменувати"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Скасувати"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Видалити «%@»?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Видалити групу?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Видалити групу"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Сеанси в цій групі більше не будуть згруповані."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway змінено. Закрийте й знову відкрийте розділ «Групи», щоб продовжити."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "На цьому шлюзі немає доступних агентів."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Параметри нового сеансу"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Агент"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Створити в робочому дереві"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Базове посилання (необов’язково)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Повторити"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Створити"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Не вдалося створити сеанс."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Новий сеанс"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Параметри нового сеансу"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Непрочитане"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Переглянути інформацію…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Підключення…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Повторити завантаження груп сеансів"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Скасувати"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Видалити вибрані сеанси?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Видалити сеанси"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Кожен вибраний сеанс і його стенограму буде видалено з Gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Групи"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Керувати групами сеансів"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Готово"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Вибрати"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Відновити"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Архівувати"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Закріплено"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Отримати інформацію…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Перейменувати"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Закріпити"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Відкріпити"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Позначити непрочитаним"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Закріплено"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Закріпити"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Відкріпити"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Архівувати"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Видалити"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "поставлено в чергу після зміни маршруту"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Видаліть вкладення або зачекайте на завершення доставлення, перш ніж перемикати чати."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Видаліть вкладення або дочекайтеся завершення доставки, перш ніж починати новий чат."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway змінився до початку операції із сеансом."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Видаліть вкладення або зачекайте на завершення доставлення, перш ніж починати новий чат."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Видаліть вкладення або зачекайте на завершення доставлення, перш ніж перемикати чати."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Нова сесія"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Параметри нового сеансу…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/vi.json b/apps/.i18n/native/vi.json
index e0e65baa6a8..e189bf76f7b 100644
--- a/apps/.i18n/native/vi.json
+++ b/apps/.i18n/native/vi.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "Người dùng"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "Không thể lưu trữ phiên này khi phiên đang hoạt động hoặc đang chạy."
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "Không thể xóa phiên chính."
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "Hãy xóa tệp đính kèm hoặc chờ gửi xong trước khi lưu trữ hoặc xóa phiên này."
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "Đang chạy"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "Danh tính"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "Tên"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "Khóa"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "Sao chép khóa phiên"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "Loại"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "Tổ chức"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "Nhóm"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "Không có"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "Đã ghim"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "Đã lưu trữ"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "Lần chạy"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "Trạng thái"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "Mô hình"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "Nhà cung cấp"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "Môi trường chạy"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "Thời lượng chạy"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "Worktree"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "Nhánh"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "Thư mục gốc của kho lưu trữ"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "Hoạt động"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "Đã cập nhật"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "Hoạt động gần nhất"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "Lần tương tác gần nhất"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "Lượt chạy đã bắt đầu"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "Lượt chạy đã kết thúc"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "Thông tin phiên"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "Nhóm"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "Đổi tên…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "Xóa…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "Không có nhóm"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "Tạo nhóm"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "Thêm nhóm"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "Nhóm phiên"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "Xong"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "Đổi tên nhóm"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "Tên nhóm"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "Đổi tên"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "Hủy"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "Xóa “%@”?"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "Xóa nhóm?"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "Xóa nhóm"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "Các phiên trong nhóm này sẽ không còn thuộc nhóm nào."
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway đã thay đổi. Hãy đóng rồi mở lại Nhóm để tiếp tục."
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "Không có tác nhân nào khả dụng trên gateway này."
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "Tùy chọn phiên mới"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "Tác nhân"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "Tạo trong một worktree"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "Tham chiếu cơ sở (không bắt buộc)"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "Thử lại"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "Tạo"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "Không thể tạo phiên."
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "Phiên mới"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "Tùy chọn phiên mới"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "Chưa đọc"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "Xem thông tin…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "Đang kết nối…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "Thử tải lại các nhóm phiên"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "Hủy"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "Xóa các phiên đã chọn?"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "Xóa các phiên"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "Mỗi phiên đã chọn và bản ghi của phiên đó sẽ bị xóa khỏi gateway."
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "Nhóm"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "Quản lý nhóm phiên"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "Xong"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "Chọn"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "Khôi phục"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "Lưu trữ"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "Đã ghim"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "Xem thông tin…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "Đổi tên"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "Ghim"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "Bỏ ghim"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "Đánh dấu là chưa đọc"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "Đã ghim"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "Ghim"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "Bỏ ghim"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "Lưu trữ"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "Xóa"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "đã đưa vào hàng đợi sau khi thay đổi tuyến"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "Gỡ tệp đính kèm hoặc chờ gửi xong trước khi chuyển cuộc trò chuyện."
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "Xóa tệp đính kèm hoặc chờ quá trình gửi hoàn tất trước khi bắt đầu cuộc trò chuyện mới."
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway đã thay đổi trước khi thao tác phiên bắt đầu."
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "Gỡ tệp đính kèm hoặc chờ gửi xong trước khi bắt đầu cuộc trò chuyện mới."
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "Gỡ tệp đính kèm hoặc chờ gửi xong trước khi chuyển cuộc trò chuyện."
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "Phiên Mới"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "Tùy chọn phiên mới…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/zh-CN.json b/apps/.i18n/native/zh-CN.json
index fd3b78b4d62..58cf30eaf3e 100644
--- a/apps/.i18n/native/zh-CN.json
+++ b/apps/.i18n/native/zh-CN.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "用户"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "此会话处于活动或运行状态时无法归档。"
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "无法删除主会话。"
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "请移除附件或等待其发送完成，然后再归档或删除此会话。"
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "运行中"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "身份"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "名称"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "密钥"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "复制会话密钥"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "类型"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "组织"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "群组"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "无"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "已置顶"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "已归档"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "运行"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "状态"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "模型"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "提供商"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "运行时"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "运行时长"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "工作树"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "分支"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "仓库根目录"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "活动"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "更新时间"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "最近活动"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "最近交互"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "运行开始时间"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "运行结束时间"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "会话信息"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "群组"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "重命名…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "删除…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "无群组"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "创建群组"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "添加群组"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "会话群组"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "完成"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "重命名群组"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "群组名称"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "重命名"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "取消"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "删除“%@”？"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "删除群组？"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "删除群组"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "此群组中的会话将变为未分组状态。"
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway 已更改。请关闭并重新打开“群组”以继续。"
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "此 Gateway 上没有可用的代理。"
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "新建会话选项"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "代理"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "在工作树中创建"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "基础引用（可选）"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "重试"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "创建"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "无法创建会话。"
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "新建会话"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "新建会话选项"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "未读"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "显示简介…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "正在连接…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "重试加载会话群组"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "取消"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "删除所选会话？"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "删除会话"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "每个所选会话及其转录记录都将从 Gateway 中移除。"
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "群组"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "管理会话分组"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "完成"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "选择"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "恢复"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "归档"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "已置顶"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "显示简介…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "重命名"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "置顶"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "取消置顶"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "标为未读"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "已置顶"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "置顶"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "取消置顶"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "归档"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "删除"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "路由更改后已排队"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "请移除附件或等待发送完成后再切换聊天。"
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "请移除附件或等待发送完成后，再开始新聊天。"
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway 在会话操作开始前已更改。"
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "请移除附件或等待发送完成后再开始新聊天。"
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "请移除附件或等待发送完成后再切换聊天。"
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "新建会话"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "新建会话选项…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/.i18n/native/zh-TW.json b/apps/.i18n/native/zh-TW.json
index 4ed108a5a9e..84e0f23d2f9 100644
--- a/apps/.i18n/native/zh-TW.json
+++ b/apps/.i18n/native/zh-TW.json
@@ -23013,6 +23013,286 @@
       "source": "User",
       "translated": "使用者"
     },
+    {
+      "id": "native.apple.b1cdcb906a43d5d6",
+      "source": "This session cannot be archived while it is active or running.",
+      "translated": "此工作階段在作用中或執行中時無法封存。"
+    },
+    {
+      "id": "native.apple.5817e3f3dab1ee19",
+      "source": "The main session cannot be deleted.",
+      "translated": "無法刪除主要工作階段。"
+    },
+    {
+      "id": "native.apple.a6b8df3f18171c91",
+      "source": "Remove attachments or wait for delivery before archiving or deleting this session.",
+      "translated": "請先移除附件或等待傳送完成，再封存或刪除此工作階段。"
+    },
+    {
+      "id": "native.apple.476b3862e0449857",
+      "source": "Running",
+      "translated": "執行中"
+    },
+    {
+      "id": "native.apple.83b41e41f428cffb",
+      "source": "Identity",
+      "translated": "身分"
+    },
+    {
+      "id": "native.apple.ba6710da42846eed",
+      "source": "Name",
+      "translated": "名稱"
+    },
+    {
+      "id": "native.apple.bdb1928f7e63c4c6",
+      "source": "Key",
+      "translated": "金鑰"
+    },
+    {
+      "id": "native.apple.7259d51423f8def0",
+      "source": "Copy session key",
+      "translated": "複製工作階段金鑰"
+    },
+    {
+      "id": "native.apple.1494b638984ddca3",
+      "source": "Kind",
+      "translated": "類型"
+    },
+    {
+      "id": "native.apple.49cd6c21bdd0d8da",
+      "source": "Organization",
+      "translated": "組織"
+    },
+    {
+      "id": "native.apple.83e2ae5c4c7dbb94",
+      "source": "Group",
+      "translated": "群組"
+    },
+    {
+      "id": "native.apple.1ba465bfa16ed23b",
+      "source": "None",
+      "translated": "無"
+    },
+    {
+      "id": "native.apple.2c7c9e5dc8ad574e",
+      "source": "Pinned",
+      "translated": "已釘選"
+    },
+    {
+      "id": "native.apple.b0d3e265af9f562a",
+      "source": "Archived",
+      "translated": "已封存"
+    },
+    {
+      "id": "native.apple.de94ca2cf7d4d766",
+      "source": "Run",
+      "translated": "執行"
+    },
+    {
+      "id": "native.apple.f7a51dca3268b26c",
+      "source": "Status",
+      "translated": "狀態"
+    },
+    {
+      "id": "native.apple.12678de5fa43321d",
+      "source": "Model",
+      "translated": "模型"
+    },
+    {
+      "id": "native.apple.8ec6bd6001df285d",
+      "source": "Provider",
+      "translated": "提供者"
+    },
+    {
+      "id": "native.apple.f43534cf1ee73605",
+      "source": "Runtime",
+      "translated": "執行階段"
+    },
+    {
+      "id": "native.apple.f0775e602bbe75ed",
+      "source": "Run duration",
+      "translated": "執行時間"
+    },
+    {
+      "id": "native.apple.ecde91d89eab026b",
+      "source": "Worktree",
+      "translated": "工作樹"
+    },
+    {
+      "id": "native.apple.1ef1698bb3ff7166",
+      "source": "ID",
+      "translated": "ID"
+    },
+    {
+      "id": "native.apple.69bc49f9663fa205",
+      "source": "Branch",
+      "translated": "分支"
+    },
+    {
+      "id": "native.apple.aa430e81e52e2354",
+      "source": "Repository root",
+      "translated": "儲存庫根目錄"
+    },
+    {
+      "id": "native.apple.6e851b012a982d38",
+      "source": "Activity",
+      "translated": "活動"
+    },
+    {
+      "id": "native.apple.bf87c6fd92c9315a",
+      "source": "Updated",
+      "translated": "已更新"
+    },
+    {
+      "id": "native.apple.dcb1734cba578b79",
+      "source": "Last activity",
+      "translated": "最近活動"
+    },
+    {
+      "id": "native.apple.58ca290e3f032865",
+      "source": "Last interaction",
+      "translated": "最近互動"
+    },
+    {
+      "id": "native.apple.7020bd521499f3b8",
+      "source": "Run started",
+      "translated": "執行開始時間"
+    },
+    {
+      "id": "native.apple.abb2b24d6378b605",
+      "source": "Run ended",
+      "translated": "執行結束時間"
+    },
+    {
+      "id": "native.apple.cd7c3095a22f80a9",
+      "source": "Session Info",
+      "translated": "工作階段資訊"
+    },
+    {
+      "id": "native.apple.e308b012d84b3b3e",
+      "source": "Groups",
+      "translated": "群組"
+    },
+    {
+      "id": "native.apple.6438f66cfcaefaf7",
+      "source": "Rename…",
+      "translated": "重新命名…"
+    },
+    {
+      "id": "native.apple.58b0f1df4985b0d1",
+      "source": "Delete…",
+      "translated": "刪除…"
+    },
+    {
+      "id": "native.apple.bc70cc0f0b882179",
+      "source": "No groups",
+      "translated": "沒有群組"
+    },
+    {
+      "id": "native.apple.cb3e1fa7783a35d2",
+      "source": "Create Group",
+      "translated": "建立群組"
+    },
+    {
+      "id": "native.apple.4ac72aeb70f107d8",
+      "source": "Add Group",
+      "translated": "加入群組"
+    },
+    {
+      "id": "native.apple.23d628606fe0734f",
+      "source": "Session Groups",
+      "translated": "工作階段群組"
+    },
+    {
+      "id": "native.apple.7777b2d2ec43ed59",
+      "source": "Done",
+      "translated": "完成"
+    },
+    {
+      "id": "native.apple.0b0149661cacfe36",
+      "source": "Rename Group",
+      "translated": "重新命名群組"
+    },
+    {
+      "id": "native.apple.8cbd863aa4d0524f",
+      "source": "Group name",
+      "translated": "群組名稱"
+    },
+    {
+      "id": "native.apple.6021088d5ed9c301",
+      "source": "Rename",
+      "translated": "重新命名"
+    },
+    {
+      "id": "native.apple.e697417338a47751",
+      "source": "Cancel",
+      "translated": "取消"
+    },
+    {
+      "id": "native.apple.cc89328a14af7a23",
+      "source": "Delete “%@”?",
+      "translated": "刪除「%@」？"
+    },
+    {
+      "id": "native.apple.4c09741db2e6c624",
+      "source": "Delete group?",
+      "translated": "刪除群組？"
+    },
+    {
+      "id": "native.apple.ddb1bbbd3c1a9c5e",
+      "source": "Delete Group",
+      "translated": "刪除群組"
+    },
+    {
+      "id": "native.apple.b049c8a4d2805e08",
+      "source": "Sessions in this group become ungrouped.",
+      "translated": "此群組中的工作階段將變為未分組。"
+    },
+    {
+      "id": "native.apple.5aa6082d78027c5f",
+      "source": "Gateway changed. Close and reopen Groups to continue.",
+      "translated": "Gateway 已變更。請關閉並重新開啟「群組」以繼續。"
+    },
+    {
+      "id": "native.apple.bb4b44183929c881",
+      "source": "No agents are available on this gateway.",
+      "translated": "此 Gateway 上沒有可用的代理程式。"
+    },
+    {
+      "id": "native.apple.6c89f35d53506406",
+      "source": "New Session Options",
+      "translated": "新工作階段選項"
+    },
+    {
+      "id": "native.apple.5b0cde807ccb4241",
+      "source": "Agent",
+      "translated": "代理程式"
+    },
+    {
+      "id": "native.apple.124a640f9620d9cd",
+      "source": "Create in a worktree",
+      "translated": "在工作樹中建立"
+    },
+    {
+      "id": "native.apple.632ce245d5575fea",
+      "source": "Base ref (optional)",
+      "translated": "基礎參照（選填）"
+    },
+    {
+      "id": "native.apple.fd81909fc9719a59",
+      "source": "Retry",
+      "translated": "重試"
+    },
+    {
+      "id": "native.apple.a085278be62286b2",
+      "source": "Create",
+      "translated": "建立"
+    },
+    {
+      "id": "native.apple.795ba37f6782cf28",
+      "source": "The session could not be created.",
+      "translated": "無法建立工作階段。"
+    },
     {
       "id": "native.apple.8ec708a3605a2cc3",
       "source": "Search sessions",
@@ -23038,6 +23318,11 @@
       "source": "New session",
       "translated": "新增工作階段"
     },
+    {
+      "id": "native.apple.2ef0e34db02ad255",
+      "source": "New session options",
+      "translated": "新工作階段選項"
+    },
     {
       "id": "native.apple.36753ef2f1ed4264",
       "source": "Rename Session",
@@ -23088,6 +23373,11 @@
       "source": "Unread",
       "translated": "未讀"
     },
+    {
+      "id": "native.apple.f57a4b9c14d31867",
+      "source": "Get Info…",
+      "translated": "取得資訊…"
+    },
     {
       "id": "native.apple.a174cb1027a9b881",
       "source": "Rename…",
@@ -23148,6 +23438,11 @@
       "source": "Connecting…",
       "translated": "連線中…"
     },
+    {
+      "id": "native.apple.79f708b3bc1d3a6c",
+      "source": "Retry session groups",
+      "translated": "重試工作階段群組"
+    },
     {
       "id": "native.apple.63320b6d5138c0db",
       "source": "Pinned",
@@ -23193,6 +23488,41 @@
       "source": "Cancel",
       "translated": "取消"
     },
+    {
+      "id": "native.apple.751e0f6b81cd374a",
+      "source": "Delete selected sessions?",
+      "translated": "刪除所選的工作階段？"
+    },
+    {
+      "id": "native.apple.aa679276581b0058",
+      "source": "Delete Sessions",
+      "translated": "刪除工作階段"
+    },
+    {
+      "id": "native.apple.f837129cbee23297",
+      "source": "Each selected session and its transcript will be removed from the gateway.",
+      "translated": "每個所選的工作階段及其逐字稿都將從 Gateway 中移除。"
+    },
+    {
+      "id": "native.apple.bf09df5e38a7a950",
+      "source": "Groups",
+      "translated": "群組"
+    },
+    {
+      "id": "native.apple.64013cfee5e25305",
+      "source": "Manage session groups",
+      "translated": "管理工作階段群組"
+    },
+    {
+      "id": "native.apple.185f4688f98e244e",
+      "source": "Done",
+      "translated": "完成"
+    },
+    {
+      "id": "native.apple.58133fc5791847e6",
+      "source": "Select",
+      "translated": "選取"
+    },
     {
       "id": "native.apple.b67eaecec1b423ac",
       "source": "No archived sessions",
@@ -23209,30 +23539,15 @@
       "translated": "復原"
     },
     {
-      "id": "native.apple.666ba6eb696e649f",
-      "source": "Archive",
-      "translated": "封存"
-    },
-    {
-      "id": "native.apple.05cb1fecc5844b69",
-      "source": "Pinned",
-      "translated": "已釘選"
+      "id": "native.apple.158cfa096c57bcb9",
+      "source": "Get Info…",
+      "translated": "取得資訊…"
     },
     {
       "id": "native.apple.080fce25e4a9bb61",
       "source": "Rename",
       "translated": "重新命名"
     },
-    {
-      "id": "native.apple.d148288258094aa6",
-      "source": "Pin",
-      "translated": "釘選"
-    },
-    {
-      "id": "native.apple.3c62aaf44e6ab4d4",
-      "source": "Unpin",
-      "translated": "取消釘選"
-    },
     {
       "id": "native.apple.6de479e9d780869a",
       "source": "Fork",
@@ -23248,6 +23563,31 @@
       "source": "Mark Unread",
       "translated": "標示為未讀"
     },
+    {
+      "id": "native.apple.05cb1fecc5844b69",
+      "source": "Pinned",
+      "translated": "已釘選"
+    },
+    {
+      "id": "native.apple.d148288258094aa6",
+      "source": "Pin",
+      "translated": "釘選"
+    },
+    {
+      "id": "native.apple.3c62aaf44e6ab4d4",
+      "source": "Unpin",
+      "translated": "取消釘選"
+    },
+    {
+      "id": "native.apple.666ba6eb696e649f",
+      "source": "Archive",
+      "translated": "封存"
+    },
+    {
+      "id": "native.apple.b09b91392835fe58",
+      "source": "Delete",
+      "translated": "刪除"
+    },
     {
       "id": "native.apple.946b677d8dbf0f37",
       "source": "Hide talk transcript",
@@ -23404,15 +23744,25 @@
       "translated": "路由變更後已排入佇列"
     },
     {
-      "id": "native.apple.710c7bd117a7cc12",
-      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
-      "translated": "請先移除附件或等待傳送完成，再切換聊天。"
+      "id": "native.apple.787047d0da6b8b9f",
+      "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
+      "translated": "請移除附件，或等待傳送問題解決後再開始新的聊天。"
+    },
+    {
+      "id": "native.apple.980f552bb0f96c0f",
+      "source": "Gateway changed before the session operation started.",
+      "translated": "Gateway 在工作階段操作開始前已變更。"
     },
     {
       "id": "native.apple.d93e6fe16ec1b0e5",
       "source": "Remove attachments or wait for delivery to resolve before starting a new chat.",
       "translated": "請先移除附件或等待傳送完成，再開始新的聊天。"
     },
+    {
+      "id": "native.apple.710c7bd117a7cc12",
+      "source": "Remove attachments or wait for delivery to resolve before switching chats.",
+      "translated": "請先移除附件或等待傳送完成，再切換聊天。"
+    },
     {
       "id": "native.apple.87ba543b42696b92",
       "source": "Clear this session's history?",
@@ -23533,6 +23883,11 @@
       "source": "New Session",
       "translated": "新增工作階段"
     },
+    {
+      "id": "native.apple.a7119fbf9d25df5e",
+      "source": "New Session Options…",
+      "translated": "新增工作階段選項…"
+    },
     {
       "id": "native.apple.5361129a24118af6",
       "source": "Refresh",
diff --git a/apps/android/app/src/main/res/values-es/strings.xml b/apps/android/app/src/main/res/values-es/strings.xml
index 68d4c2bc87d..c3d8bd043f9 100644
--- a/apps/android/app/src/main/res/values-es/strings.xml
+++ b/apps/android/app/src/main/res/values-es/strings.xml
@@ -619,7 +619,7 @@
     <string name="native_6b82f7ec6987fff5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Compartir mensaje"</string>
     <string name="native_6b97422ed395a4f7" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Genera un código QR."</string>
     <string name="native_6bdbb891ab45a014" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Altavoz activado"</string>
-    <string name="native_6be2e6236d34642d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"¿Eliminar grupo?"</string>
+    <string name="native_6be2e6236d34642d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"¿Eliminar el grupo?"</string>
     <string name="native_6be36ca49ee85210" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Falta"</string>
     <string name="native_6c12bf40654bb6f2" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Buscar propuestas"</string>
     <string name="native_6c45cb72a36e63d5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"stop"</string>
@@ -1081,7 +1081,7 @@
     <string name="native_bcb06651437caa15" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"%1$s %2$s"</string>
     <string name="native_bd08450d63406844" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Automatización habilitada."</string>
     <string name="native_bd6719b455bcc898" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Memory Get"</string>
-    <string name="native_bdb86505f8062d15" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Archivadas"</string>
+    <string name="native_bdb86505f8062d15" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Archivada"</string>
     <string name="native_bdc090ec61e3fcfc" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Recargar"</string>
     <string name="native_bdff71b20b9cf392" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Buscar automatizaciones"</string>
     <string name="native_be969becb173e0c5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Los teléfonos vinculados y los hosts de nodos aparecerán aquí después del emparejamiento."</string>
diff --git a/apps/android/app/src/main/res/values-fr/strings.xml b/apps/android/app/src/main/res/values-fr/strings.xml
index 133b57313e4..4d7108f158c 100644
--- a/apps/android/app/src/main/res/values-fr/strings.xml
+++ b/apps/android/app/src/main/res/values-fr/strings.xml
@@ -850,7 +850,7 @@
     <string name="native_9193a6bd2430c6df" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"En attente d’association"</string>
     <string name="native_91a6e5ed6ae788f4" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Démarrer ou poursuivre une conversation"</string>
     <string name="native_91e9086800ed776e" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Aucune tâche planifiée"</string>
-    <string name="native_920e413c7d411b61" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Statut"</string>
+    <string name="native_920e413c7d411b61" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"État"</string>
     <string name="native_921ff8493d077a59" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Nœud OpenClaw · Connecté"</string>
     <string name="native_92340695899bd2d8" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Actif"</string>
     <string name="native_92458e650bc168c5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Afficher l’état de débogage du partage d’écran."</string>
diff --git a/apps/android/app/src/main/res/values-hi/strings.xml b/apps/android/app/src/main/res/values-hi/strings.xml
index 5012908490a..67336ee8b44 100644
--- a/apps/android/app/src/main/res/values-hi/strings.xml
+++ b/apps/android/app/src/main/res/values-hi/strings.xml
@@ -619,7 +619,7 @@
     <string name="native_6b82f7ec6987fff5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"संदेश साझा करें"</string>
     <string name="native_6b97422ed395a4f7" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"QR कोड जनरेट करें।"</string>
     <string name="native_6bdbb891ab45a014" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"स्पीकर चालू है"</string>
-    <string name="native_6be2e6236d34642d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"समूह हटाएं?"</string>
+    <string name="native_6be2e6236d34642d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"समूह हटाएँ?"</string>
     <string name="native_6be36ca49ee85210" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"अनुपलब्ध"</string>
     <string name="native_6c12bf40654bb6f2" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"प्रस्ताव खोजें"</string>
     <string name="native_6c45cb72a36e63d5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"stop"</string>
diff --git a/apps/android/app/src/main/res/values-it/strings.xml b/apps/android/app/src/main/res/values-it/strings.xml
index 0203da9880e..00ef037d504 100644
--- a/apps/android/app/src/main/res/values-it/strings.xml
+++ b/apps/android/app/src/main/res/values-it/strings.xml
@@ -1393,7 +1393,7 @@
     <string name="native_f1c3989a92ef10d1" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Scansiona il codice QR per abbinare"</string>
     <string name="native_f2000dce9b5d40c8" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Approvazione negata."</string>
     <string name="native_f200366d0c4352cb" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Impossibile esaminare la proposta di Skill Workshop."</string>
-    <string name="native_f20c879465551f0d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Fissato"</string>
+    <string name="native_f20c879465551f0d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"In evidenza"</string>
     <string name="native_f211f2bf832dda14" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Profilo e dispositivo"</string>
     <string name="native_f22e1435c8dfffc1" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Chiudi selettore livello di riflessione"</string>
     <string name="native_f2316e644b1d2621" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Impossibile mettere il messaggio in coda per inviarlo in seguito."</string>
diff --git a/apps/android/app/src/main/res/values-th/strings.xml b/apps/android/app/src/main/res/values-th/strings.xml
index a25260c5a73..8205bfe7945 100644
--- a/apps/android/app/src/main/res/values-th/strings.xml
+++ b/apps/android/app/src/main/res/values-th/strings.xml
@@ -347,7 +347,7 @@
     <string name="native_39bd8d494d8df83b" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"ระบบทั้งหมดทำงานตามปกติ"</string>
     <string name="native_3a1f56623c408220" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"ไม่สามารถเข้าถึง Gateway ได้"</string>
     <string name="native_3a386d2bb69adffc" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"OC"</string>
-    <string name="native_3a5ecca188c0579c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"อัปเดตเมื่อ"</string>
+    <string name="native_3a5ecca188c0579c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"อัปเดตแล้ว"</string>
     <string name="native_3a65cf1204f18864" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"เชื่อมต่อแล้ว (โหนดออฟไลน์)"</string>
     <string name="native_3a78695388b38b5c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"หน้าแรก"</string>
     <string name="native_3b28b535950f8175" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"การป้อนตามคำบอกกำลังฟังอยู่"</string>
diff --git a/apps/android/app/src/main/res/values-tr/strings.xml b/apps/android/app/src/main/res/values-tr/strings.xml
index f13267650a3..f741c0c08ce 100644
--- a/apps/android/app/src/main/res/values-tr/strings.xml
+++ b/apps/android/app/src/main/res/values-tr/strings.xml
@@ -105,7 +105,7 @@
     <string name="native_100ac08064a6d586" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Yakın zamanda oturum yok"</string>
     <string name="native_1039e92fa05c1279" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Gateway durumu, telefon düğümü hazır olma durumu ve son günlük akışı."</string>
     <string name="native_106808530413298b" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Otomasyon ayrıntısını aç"</string>
-    <string name="native_1093115897879aa3" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Çalışma Zamanı"</string>
+    <string name="native_1093115897879aa3" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Çalışma zamanı"</string>
     <string name="native_1102bd820f68901b" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Aracı %1$s"</string>
     <string name="native_11252dd2410324bc" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Get Goal"</string>
     <string name="native_114c9789813fd2b0" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"OpenClaw %1$s (%2$s)"</string>
diff --git a/apps/android/app/src/main/res/values-uk/strings.xml b/apps/android/app/src/main/res/values-uk/strings.xml
index 343fa0d4290..e85011d8c12 100644
--- a/apps/android/app/src/main/res/values-uk/strings.xml
+++ b/apps/android/app/src/main/res/values-uk/strings.xml
@@ -850,7 +850,7 @@
     <string name="native_9193a6bd2430c6df" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Очікування сполучення"</string>
     <string name="native_91a6e5ed6ae788f4" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Почніть або продовжте розмову"</string>
     <string name="native_91e9086800ed776e" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Немає запланованих завдань"</string>
-    <string name="native_920e413c7d411b61" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Стан"</string>
+    <string name="native_920e413c7d411b61" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Статус"</string>
     <string name="native_921ff8493d077a59" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Вузол OpenClaw · Підключено"</string>
     <string name="native_92340695899bd2d8" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Активні"</string>
     <string name="native_92458e650bc168c5" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Показувати стан налагодження спільного доступу до екрана."</string>
diff --git a/apps/android/app/src/main/res/values-zh-rCN/strings.xml b/apps/android/app/src/main/res/values-zh-rCN/strings.xml
index 9e6c461efd5..8b9fcc5093a 100644
--- a/apps/android/app/src/main/res/values-zh-rCN/strings.xml
+++ b/apps/android/app/src/main/res/values-zh-rCN/strings.xml
@@ -347,7 +347,7 @@
     <string name="native_39bd8d494d8df83b" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"所有系统运行正常"</string>
     <string name="native_3a1f56623c408220" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"无法连接到 Gateway"</string>
     <string name="native_3a386d2bb69adffc" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"OC"</string>
-    <string name="native_3a5ecca188c0579c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"已更新"</string>
+    <string name="native_3a5ecca188c0579c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"更新时间"</string>
     <string name="native_3a65cf1204f18864" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"已连接（节点离线）"</string>
     <string name="native_3a78695388b38b5c" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"首页"</string>
     <string name="native_3b28b535950f8175" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"正在听写"</string>
diff --git a/apps/android/app/src/main/res/values-zh-rTW/strings.xml b/apps/android/app/src/main/res/values-zh-rTW/strings.xml
index 3a19b758325..4a26f972c1c 100644
--- a/apps/android/app/src/main/res/values-zh-rTW/strings.xml
+++ b/apps/android/app/src/main/res/values-zh-rTW/strings.xml
@@ -1418,7 +1418,7 @@
     <string name="native_f502267deff4108d" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"尚無工作階段"</string>
     <string name="native_f5171b47ebca6202" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"已封鎖 %1$s 個應用程式進行轉送。"</string>
     <string name="native_f532ee1f7288365e" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"訊息動作"</string>
-    <string name="native_f5387f9bb6ed7031" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"種類"</string>
+    <string name="native_f5387f9bb6ed7031" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"類型"</string>
     <string name="native_f565318d124534cf" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"取消封存"</string>
     <string name="native_f584049cab5f523e" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"Transcripts"</string>
     <string name="native_f59b46c265d8d38f" formatted="false" tools:ignore="Typos,TypographyDashes,TypographyEllipsis">"最近的工作階段"</string>
diff --git a/apps/ios/Resources/Localizable.xcstrings b/apps/ios/Resources/Localizable.xcstrings
index ff6f9453250..94e75e46740 100644
--- a/apps/ios/Resources/Localizable.xcstrings
+++ b/apps/ios/Resources/Localizable.xcstrings
@@ -9385,6 +9385,142 @@
         }
       }
     },
+    "Add Group": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Add Group"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "添加群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "加入群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Adicionar grupo"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppe hinzufügen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Añadir grupo"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループを追加"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹 추가"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ajouter un groupe"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "समूह जोड़ें"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إضافة مجموعة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aggiungi gruppo"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup Ekle"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Додати групу"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tambahkan Grup"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Dodaj grupę"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เพิ่มกลุ่ม"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Thêm nhóm"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groep toevoegen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "افزودن گروه"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Добавить группу"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Lägg till grupp"
+          }
+        }
+      }
+    },
     "Add Header": {
       "localizations": {
         "en": {
@@ -23393,6 +23529,142 @@
         }
       }
     },
+    "Base ref (optional)": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Base ref (optional)"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "基础引用（可选）"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "基礎參照（選填）"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Referência base (opcional)"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Basis-Ref (optional)"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Referencia base (opcional)"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ベース参照（任意）"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "기준 참조(선택 사항)"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Référence de base (facultatif)"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "बेस रेफ़रेंस (वैकल्पिक)"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "المرجع الأساسي (اختياري)"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Riferimento di base (facoltativo)"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Temel ref (isteğe bağlı)"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Базове посилання (необов’язково)"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ref dasar (opsional)"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Referencja bazowa (opcjonalnie)"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Base ref (ไม่บังคับ)"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tham chiếu cơ sở (không bắt buộc)"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Basisreferentie (optioneel)"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ارجاع پایه (اختیاری)"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Базовая ссылка (необязательно)"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Basreferens (valfritt)"
+          }
+        }
+      }
+    },
     "Blocked": {
       "localizations": {
         "en": {
@@ -23665,6 +23937,142 @@
         }
       }
     },
+    "Branch": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Branch"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "分支"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "分支"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Branch"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Branch"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Rama"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ブランチ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "브랜치"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Branche"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ब्रांच"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "الفرع"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Branch"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Dal"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Гілка"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Branch"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gałąź"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "สาขา"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nhánh"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Branch"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "شاخه"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ветка"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gren"
+          }
+        }
+      }
+    },
     "Browse": {
       "localizations": {
         "en": {
@@ -43793,6 +44201,142 @@
         }
       }
     },
+    "Copy session key": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Copy session key"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "复制会话密钥"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "複製工作階段金鑰"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Copiar chave da sessão"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungsschlüssel kopieren"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Copiar clave de sesión"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッションキーをコピー"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 키 복사"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Copier la clé de session"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र कुंजी कॉपी करें"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نسخ مفتاح الجلسة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Copia chiave della sessione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum anahtarını kopyala"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Копіювати ключ сеансу"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Salin kunci sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kopiuj klucz sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "คัดลอกคีย์เซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sao chép khóa phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessiesleutel kopiëren"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "کپی کلید نشست"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Скопировать ключ сеанса"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kopiera sessionsnyckel"
+          }
+        }
+      }
+    },
     "Copy setup code command": {
       "localizations": {
         "en": {
@@ -47737,6 +48281,142 @@
         }
       }
     },
+    "Create Group": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Create Group"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "创建群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "建立群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Criar grupo"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppe erstellen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Crear grupo"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループを作成"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹 생성"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Créer un groupe"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "समूह बनाएँ"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إنشاء مجموعة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Crea gruppo"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup Oluştur"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Створити групу"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Buat Grup"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Utwórz grupę"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "สร้างกลุ่ม"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tạo nhóm"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groep aanmaken"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ایجاد گروه"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Создать группу"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Skapa grupp"
+          }
+        }
+      }
+    },
     "Create a card or change the filter.": {
       "localizations": {
         "en": {
@@ -47873,6 +48553,142 @@
         }
       }
     },
+    "Create in a worktree": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Create in a worktree"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "在工作树中创建"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "在工作樹中建立"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Criar em uma worktree"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "In einem Worktree erstellen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Crear en un worktree"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ワークツリーに作成"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "워크트리에 생성"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Créer dans un worktree"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "वर्कट्री में बनाएँ"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إنشاء في شجرة عمل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Crea in un worktree"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bir worktree içinde oluştur"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Створити в робочому дереві"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Buat di worktree"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Utwórz w drzewie roboczym"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "สร้างใน worktree"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tạo trong một worktree"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aanmaken in een worktree"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ایجاد در یک worktree"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Создать в рабочем дереве"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Skapa i ett arbetsträd"
+          }
+        }
+      }
+    },
     "Creates a workboard card": {
       "localizations": {
         "en": {
@@ -51545,6 +52361,142 @@
         }
       }
     },
+    "Delete Sessions": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Delete Sessions"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "删除会话"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "刪除工作階段"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Excluir sessões"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungen löschen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Eliminar sesiones"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッションを削除"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 삭제"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Supprimer les sessions"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र हटाएँ"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "حذف الجلسات"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Elimina sessioni"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturumları Sil"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Видалити сеанси"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hapus Sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Usuń sesje"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ลบเซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Xóa các phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessies verwijderen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "حذف نشست‌ها"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Удалить сеансы"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ta bort sessioner"
+          }
+        }
+      }
+    },
     "Delete Session…": {
       "localizations": {
         "en": {
@@ -51817,6 +52769,278 @@
         }
       }
     },
+    "Delete group?": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Delete group?"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "删除群组？"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "刪除群組？"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Excluir grupo?"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppe löschen?"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "¿Eliminar el grupo?"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループを削除しますか？"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹을 삭제하시겠습니까?"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Supprimer le groupe ?"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "समूह हटाएँ?"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "حذف المجموعة؟"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Eliminare il gruppo?"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup silinsin mi?"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Видалити групу?"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hapus grup?"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Usunąć grupę?"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ลบกลุ่มหรือไม่?"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Xóa nhóm?"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groep verwijderen?"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گروه حذف شود؟"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Удалить группу?"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ta bort gruppen?"
+          }
+        }
+      }
+    },
+    "Delete selected sessions?": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Delete selected sessions?"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "删除所选会话？"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "刪除所選的工作階段？"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Excluir as sessões selecionadas?"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ausgewählte Sitzungen löschen?"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "¿Eliminar las sesiones seleccionadas?"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "選択したセッションを削除しますか？"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "선택한 세션을 삭제하시겠습니까?"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Supprimer les sessions sélectionnées ?"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "चुने गए सत्र हटाएँ?"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "حذف الجلسات المحددة؟"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Eliminare le sessioni selezionate?"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Seçili oturumlar silinsin mi?"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Видалити вибрані сеанси?"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hapus sesi yang dipilih?"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Usunąć wybrane sesje?"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ลบเซสชันที่เลือกหรือไม่?"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Xóa các phiên đã chọn?"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Geselecteerde sessies verwijderen?"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نشست‌های انتخاب‌شده حذف شوند؟"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Удалить выбранные сеансы?"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ta bort valda sessioner?"
+          }
+        }
+      }
+    },
     "Delete this automation?": {
       "localizations": {
         "en": {
@@ -59297,6 +60521,142 @@
         }
       }
     },
+    "Each selected session and its transcript will be removed from the gateway.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Each selected session and its transcript will be removed from the gateway."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "每个所选会话及其转录记录都将从 Gateway 中移除。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "每個所選的工作階段及其逐字稿都將從 Gateway 中移除。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Cada sessão selecionada e sua transcrição serão removidas do gateway."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Alle ausgewählten Sitzungen und ihre Transkripte werden aus dem Gateway entfernt."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Cada sesión seleccionada y su transcripción se eliminarán del Gateway."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "選択した各セッションとそのトランスクリプトがGatewayから削除されます。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "선택한 각 세션과 해당 기록이 Gateway에서 삭제됩니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Chaque session sélectionnée et sa transcription seront supprimées du Gateway."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "हर चुना गया सत्र और उसकी प्रतिलिपि Gateway से हटा दी जाएगी।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ستُزال كل جلسة محددة ونصها من Gateway."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ogni sessione selezionata e la relativa trascrizione verranno rimosse dal Gateway."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Seçili her oturum ve dökümü gateway'den kaldırılacaktır."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Кожен вибраний сеанс і його стенограму буде видалено з Gateway."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Setiap sesi yang dipilih beserta transkripnya akan dihapus dari Gateway."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Każda wybrana sesja i jej transkrypcja zostaną usunięte z Gateway."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เซสชันที่เลือกแต่ละรายการและบันทึกการสนทนาจะถูกลบออกจาก Gateway"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Mỗi phiên đã chọn và bản ghi của phiên đó sẽ bị xóa khỏi gateway."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Elke geselecteerde sessie en het bijbehorende transcript worden van de Gateway verwijderd."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "هر نشست انتخاب‌شده و رونوشت آن از Gateway حذف خواهد شد."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Все выбранные сеансы и их расшифровки будут удалены из Gateway."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Varje vald session och dess transkription tas bort från Gateway."
+          }
+        }
+      }
+    },
     "Edit": {
       "localizations": {
         "en": {
@@ -70585,6 +71945,278 @@
         }
       }
     },
+    "Gateway changed before the session operation started.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway changed before the session operation started."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway 在会话操作开始前已更改。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway 在工作階段操作開始前已變更。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "O Gateway foi alterado antes do início da operação da sessão."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Das Gateway wurde geändert, bevor der Sitzungsvorgang gestartet wurde."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "El Gateway cambió antes de que se iniciara la operación de sesión."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッション操作を開始する前にGatewayが変更されました。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 작업이 시작되기 전에 Gateway가 변경되었습니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Le Gateway a changé avant le début de l’opération sur la session."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र संचालन शुरू होने से पहले Gateway बदल गया।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تغيّر Gateway قبل بدء عملية الجلسة."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Il Gateway è cambiato prima dell'inizio dell'operazione sulla sessione."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum işlemi başlamadan önce Gateway değişti."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway змінився до початку операції із сеансом."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway berubah sebelum operasi sesi dimulai."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway zmienił się przed rozpoczęciem operacji na sesji."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway มีการเปลี่ยนแปลงก่อนเริ่มดำเนินการกับเซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway đã thay đổi trước khi thao tác phiên bắt đầu."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "De Gateway is gewijzigd voordat de sessiebewerking is gestart."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway پیش از شروع عملیات نشست تغییر کرد."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway изменился до начала операции с сеансом."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway ändrades innan sessionsåtgärden startade."
+          }
+        }
+      }
+    },
+    "Gateway changed. Close and reopen Groups to continue.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway changed. Close and reopen Groups to continue."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway 已更改。请关闭并重新打开“群组”以继续。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway 已變更。請關閉並重新開啟「群組」以繼續。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "O Gateway foi alterado. Feche e reabra Grupos para continuar."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway wurde geändert. Schließen und öffnen Sie „Gruppen“ erneut, um fortzufahren."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "El Gateway ha cambiado. Cierra y vuelve a abrir Grupos para continuar."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gatewayが変更されました。続行するには「グループ」を閉じて再度開いてください。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway가 변경되었습니다. 계속하려면 그룹을 닫았다가 다시 여세요."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Le Gateway a changé. Fermez et rouvrez Groupes pour continuer."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway बदल गया है। जारी रखने के लिए Groups को बंद करके फिर से खोलें।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تغيّر Gateway. أغلق المجموعات وأعد فتحها للمتابعة."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Il Gateway è cambiato. Chiudi e riapri Gruppi per continuare."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway değişti. Devam etmek için Gruplar'ı kapatıp yeniden açın."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway змінено. Закрийте й знову відкрийте розділ «Групи», щоб продовжити."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway berubah. Tutup dan buka kembali Grup untuk melanjutkan."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway został zmieniony. Zamknij i ponownie otwórz Grupy, aby kontynuować."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway มีการเปลี่ยนแปลง ปิดแล้วเปิดกลุ่มอีกครั้งเพื่อดำเนินการต่อ"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway đã thay đổi. Hãy đóng rồi mở lại Nhóm để tiếp tục."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway gewijzigd. Sluit Groepen en open het opnieuw om door te gaan."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway تغییر کرد. برای ادامه، Groups را ببندید و دوباره باز کنید."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway изменён. Закройте и снова откройте раздел «Группы», чтобы продолжить."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gateway har ändrats. Stäng och öppna Grupper igen för att fortsätta."
+          }
+        }
+      }
+    },
     "Gateway command": {
       "localizations": {
         "en": {
@@ -73441,6 +75073,142 @@
         }
       }
     },
+    "Get Info…": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Get Info…"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "显示简介…"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "取得資訊…"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Obter Informações…"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informationen…"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Obtener información…"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "情報を見る…"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "정보 가져오기…"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Lire les informations…"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "जानकारी पाएँ…"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إحضار المعلومات…"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ottieni informazioni…"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bilgi Al…"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Отримати інформацію…"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Dapatkan Info…"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informacje…"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ดูข้อมูล…"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Xem thông tin…"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Toon info…"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "دریافت اطلاعات…"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Сведения…"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Visa info…"
+          }
+        }
+      }
+    },
     "Get key": {
       "localizations": {
         "en": {
@@ -74257,6 +76025,142 @@
         }
       }
     },
+    "Group": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Group"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupo"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppe"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupo"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groupe"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "समूह"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "المجموعة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppo"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Група"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupa"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "กลุ่ม"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nhóm"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groep"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گروه"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Группа"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupp"
+          }
+        }
+      }
+    },
     "Group name": {
       "localizations": {
         "en": {
@@ -74393,6 +76297,142 @@
         }
       }
     },
+    "Groups": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groups"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupos"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupos"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groupes"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "समूह"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "المجموعات"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppi"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruplar"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Групи"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupy"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "กลุ่ม"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nhóm"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groepen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گروه‌ها"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Группы"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupper"
+          }
+        }
+      }
+    },
     "Header name": {
       "localizations": {
         "en": {
@@ -76841,6 +78881,142 @@
         }
       }
     },
+    "ID": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ID"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "المعرّف"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kimlik"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "شناسه"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "new",
+            "value": "ID"
+          }
+        }
+      }
+    },
     "INSERT INTO cached_transcripts(gateway_id, session_key, agent_id, payload, updated_at)\nSELECT gateway_id, session_key, '', payload, updated_at\nFROM cached_transcripts_pre_v3\nWHERE lower(trim(session_key)) GLOB 'agent:*:*'": {
       "localizations": {
         "en": {
@@ -77385,6 +79561,142 @@
         }
       }
     },
+    "Identity": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identity"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "身份"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "身分"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identidade"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identität"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identidad"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ID"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ID"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identité"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "पहचान"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "الهوية"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identità"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kimlik"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ідентифікація"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identitas"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tożsamość"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ข้อมูลประจำตัว"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Danh tính"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identiteit"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "هویت"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Идентификация"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Identitet"
+          }
+        }
+      }
+    },
     "Idle": {
       "localizations": {
         "en": {
@@ -81737,6 +84049,142 @@
         }
       }
     },
+    "Kind": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kind"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "类型"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "類型"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tipo"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Art"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tipo"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "種類"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "종류"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Type"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "प्रकार"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "النوع"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tipo"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tür"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Тип"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Jenis"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Rodzaj"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ประเภท"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Loại"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Type"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نوع"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Тип"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Typ"
+          }
+        }
+      }
+    },
     "LAN or Tailscale host": {
       "localizations": {
         "en": {
@@ -82145,6 +84593,278 @@
         }
       }
     },
+    "Last activity": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Last activity"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最近活动"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最近活動"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Última atividade"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Letzte Aktivität"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Última actividad"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最終アクティビティ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "최근 활동"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Dernière activité"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "पिछली गतिविधि"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "آخر نشاط"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ultima attività"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Son etkinlik"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Остання активність"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aktivitas terakhir"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ostatnia aktywność"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "กิจกรรมล่าสุด"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hoạt động gần nhất"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Laatste activiteit"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "آخرین فعالیت"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Последняя активность"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Senaste aktivitet"
+          }
+        }
+      }
+    },
+    "Last interaction": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Last interaction"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最近交互"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最近互動"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Última interação"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Letzte Interaktion"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Última interacción"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "最終操作"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "최근 상호작용"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Dernière interaction"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "पिछला इंटरैक्शन"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "آخر تفاعل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ultima interazione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Son etkileşim"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Остання взаємодія"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Interaksi terakhir"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ostatnia interakcja"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "การโต้ตอบล่าสุด"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Lần tương tác gần nhất"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Laatste interactie"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "آخرین تعامل"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Последнее взаимодействие"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Senaste interaktion"
+          }
+        }
+      }
+    },
     "Last issue": {
       "localizations": {
         "en": {
@@ -90305,6 +93025,142 @@
         }
       }
     },
+    "Manage session groups": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Manage session groups"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "管理会话分组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "管理工作階段群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gerenciar grupos de sessões"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungsgruppen verwalten"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gestionar grupos de sesiones"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッショングループを管理"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 그룹 관리"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gérer les groupes de sessions"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र समूह प्रबंधित करें"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إدارة مجموعات الجلسات"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gestisci gruppi di sessioni"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum gruplarını yönet"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Керувати групами сеансів"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kelola grup sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Zarządzaj grupami sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "จัดการกลุ่มเซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Quản lý nhóm phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessiegroepen beheren"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "مدیریت گروه‌های نشست"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Управление группами сеансов"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hantera sessionsgrupper"
+          }
+        }
+      }
+    },
     "Managed cron is installed.": {
       "localizations": {
         "en": {
@@ -96194,7 +99050,551 @@
         "ja-JP": {
           "stringUnit": {
             "state": "translated",
-            "value": "新規セッション"
+            "value": "新規セッション"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "새 세션"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nouvelle session"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "नया सेशन"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "جلسة جديدة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nuova sessione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Yeni Oturum"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Нова сесія"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesi Baru"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nowa sesja"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เซสชันใหม่"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Phiên Mới"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nieuwe sessie"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نشست جدید"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Новая сессия"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ny session"
+          }
+        }
+      }
+    },
+    "New Session Options": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "New Session Options"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新建会话选项"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新工作階段選項"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opções da nova sessão"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Optionen für neue Sitzungen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opciones de nueva sesión"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新規セッションのオプション"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "새 세션 옵션"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Options de la nouvelle session"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "नए सत्र के विकल्प"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "خيارات الجلسة الجديدة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opzioni nuova sessione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Yeni Oturum Seçenekleri"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Параметри нового сеансу"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opsi Sesi Baru"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opcje nowej sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ตัวเลือกเซสชันใหม่"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tùy chọn phiên mới"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opties voor nieuwe sessie"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گزینه‌های نشست جدید"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Параметры нового сеанса"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Alternativ för ny session"
+          }
+        }
+      }
+    },
+    "New Session Options…": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "New Session Options…"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新建会话选项…"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新增工作階段選項…"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opções de Nova Sessão…"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Optionen für neue Sitzung…"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opciones de nueva sesión…"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新規セッションのオプション…"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "새 세션 옵션…"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Options de la nouvelle session…"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "नए सत्र के विकल्प…"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "خيارات جلسة جديدة…"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opzioni nuova sessione…"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Yeni Oturum Seçenekleri…"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Параметри нового сеансу…"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opsi Sesi Baru…"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opcje nowej sesji…"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ตัวเลือกเซสชันใหม่…"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tùy chọn phiên mới…"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Opties voor nieuwe sessie…"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گزینه‌های نشست جدید…"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Параметры нового сеанса…"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Alternativ för ny session…"
+          }
+        }
+      }
+    },
+    "New proposals will appear here when agents draft skills.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "New proposals will appear here when agents draft skills."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "当 Agent 草拟 Skills 时，新提案将显示在此处。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "當 agents 起草 skills 時，新的提案會顯示在這裡。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Novas propostas aparecerão aqui quando os agentes criarem rascunhos de skills."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Neue Vorschläge werden hier angezeigt, wenn Agenten Skills entwerfen."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Las nuevas propuestas aparecerán aquí cuando los agentes redacten skills."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "エージェントが Skills を下書きすると、新しい提案がここに表示されます。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "에이전트가 스킬 초안을 작성하면 새 제안이 여기에 표시됩니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Les nouvelles propositions apparaîtront ici lorsque les agents rédigeront des skills."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "जब एजेंट Skills का ड्राफ़्ट बनाएंगे, तो नए प्रस्ताव यहाँ दिखाई देंगे."
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ستظهر المقترحات الجديدة هنا عندما تقوم الوكلاء بصياغة المهارات."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Le nuove proposte appariranno qui quando gli agenti creeranno bozze di skill."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aracılar skill taslakları oluşturduğunda yeni teklifler burada görünür."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Нові пропозиції з’являться тут, коли агенти створять чернетки Skills."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Proposal baru akan muncul di sini saat agen menyusun skill."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nowe propozycje pojawią się tutaj, gdy agenci opracują skills."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ข้อเสนอใหม่จะแสดงที่นี่เมื่อ Agent ร่าง Skills"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Các đề xuất mới sẽ xuất hiện tại đây khi tác nhân soạn thảo kỹ năng."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nieuwe voorstellen verschijnen hier wanneer agents skills opstellen."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "وقتی عامل‌ها مهارت‌ها را پیش‌نویس کنند، پیشنهادهای جدید اینجا ظاهر می‌شوند."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Новые предложения появятся здесь, когда агенты подготовят Skills."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nya förslag visas här när agenter utformar skills."
+          }
+        }
+      }
+    },
+    "New session": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "New session"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新建会话"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新工作階段"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nova sessão"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Neue Sitzung"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nueva sesión"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "新しいセッション"
           }
         },
         "ko": {
@@ -96212,7 +99612,7 @@
         "hi": {
           "stringUnit": {
             "state": "translated",
-            "value": "नया सेशन"
+            "value": "नया सत्र"
           }
         },
         "ar": {
@@ -96230,19 +99630,19 @@
         "tr": {
           "stringUnit": {
             "state": "translated",
-            "value": "Yeni Oturum"
+            "value": "Yeni oturum"
           }
         },
         "uk": {
           "stringUnit": {
             "state": "translated",
-            "value": "Нова сесія"
+            "value": "Новий сеанс"
           }
         },
         "id": {
           "stringUnit": {
             "state": "translated",
-            "value": "Sesi Baru"
+            "value": "Sesi baru"
           }
         },
         "pl": {
@@ -96260,7 +99660,7 @@
         "vi": {
           "stringUnit": {
             "state": "translated",
-            "value": "Phiên Mới"
+            "value": "Phiên mới"
           }
         },
         "nl": {
@@ -96272,7 +99672,7 @@
         "fa": {
           "stringUnit": {
             "state": "translated",
-            "value": "نشست جدید"
+            "value": "جلسه جدید"
           }
         },
         "ru": {
@@ -96289,274 +99689,138 @@
         }
       }
     },
-    "New proposals will appear here when agents draft skills.": {
-      "localizations": {
-        "en": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "New proposals will appear here when agents draft skills."
-          }
-        },
-        "zh-CN": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "当 Agent 草拟 Skills 时，新提案将显示在此处。"
-          }
-        },
-        "zh-TW": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "當 agents 起草 skills 時，新的提案會顯示在這裡。"
-          }
-        },
-        "pt-BR": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Novas propostas aparecerão aqui quando os agentes criarem rascunhos de skills."
-          }
-        },
-        "de": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Neue Vorschläge werden hier angezeigt, wenn Agenten Skills entwerfen."
-          }
-        },
-        "es": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Las nuevas propuestas aparecerán aquí cuando los agentes redacten skills."
-          }
-        },
-        "ja-JP": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "エージェントが Skills を下書きすると、新しい提案がここに表示されます。"
-          }
-        },
-        "ko": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "에이전트가 스킬 초안을 작성하면 새 제안이 여기에 표시됩니다."
-          }
-        },
-        "fr": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Les nouvelles propositions apparaîtront ici lorsque les agents rédigeront des skills."
-          }
-        },
-        "hi": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "जब एजेंट Skills का ड्राफ़्ट बनाएंगे, तो नए प्रस्ताव यहाँ दिखाई देंगे."
-          }
-        },
-        "ar": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "ستظهر المقترحات الجديدة هنا عندما تقوم الوكلاء بصياغة المهارات."
-          }
-        },
-        "it": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Le nuove proposte appariranno qui quando gli agenti creeranno bozze di skill."
-          }
-        },
-        "tr": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Aracılar skill taslakları oluşturduğunda yeni teklifler burada görünür."
-          }
-        },
-        "uk": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Нові пропозиції з’являться тут, коли агенти створять чернетки Skills."
-          }
-        },
-        "id": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Proposal baru akan muncul di sini saat agen menyusun skill."
-          }
-        },
-        "pl": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Nowe propozycje pojawią się tutaj, gdy agenci opracują skills."
-          }
-        },
-        "th": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "ข้อเสนอใหม่จะแสดงที่นี่เมื่อ Agent ร่าง Skills"
-          }
-        },
-        "vi": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Các đề xuất mới sẽ xuất hiện tại đây khi tác nhân soạn thảo kỹ năng."
-          }
-        },
-        "nl": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Nieuwe voorstellen verschijnen hier wanneer agents skills opstellen."
-          }
-        },
-        "fa": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "وقتی عامل‌ها مهارت‌ها را پیش‌نویس کنند، پیشنهادهای جدید اینجا ظاهر می‌شوند."
-          }
-        },
-        "ru": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Новые предложения появятся здесь, когда агенты подготовят Skills."
-          }
-        },
-        "sv": {
-          "stringUnit": {
-            "state": "translated",
-            "value": "Nya förslag visas här när agenter utformar skills."
-          }
-        }
-      }
-    },
-    "New session": {
+    "New session options": {
       "localizations": {
         "en": {
           "stringUnit": {
             "state": "translated",
-            "value": "New session"
+            "value": "New session options"
           }
         },
         "zh-CN": {
           "stringUnit": {
             "state": "translated",
-            "value": "新建会话"
+            "value": "新建会话选项"
           }
         },
         "zh-TW": {
           "stringUnit": {
             "state": "translated",
-            "value": "新工作階段"
+            "value": "新工作階段選項"
           }
         },
         "pt-BR": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nova sessão"
+            "value": "Opções da nova sessão"
           }
         },
         "de": {
           "stringUnit": {
             "state": "translated",
-            "value": "Neue Sitzung"
+            "value": "Optionen für neue Sitzungen"
           }
         },
         "es": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nueva sesión"
+            "value": "Opciones de nueva sesión"
           }
         },
         "ja-JP": {
           "stringUnit": {
             "state": "translated",
-            "value": "新しいセッション"
+            "value": "新規セッションのオプション"
           }
         },
         "ko": {
           "stringUnit": {
             "state": "translated",
-            "value": "새 세션"
+            "value": "새 세션 옵션"
           }
         },
         "fr": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nouvelle session"
+            "value": "Options de la nouvelle session"
           }
         },
         "hi": {
           "stringUnit": {
             "state": "translated",
-            "value": "नया सत्र"
+            "value": "नए सत्र के विकल्प"
           }
         },
         "ar": {
           "stringUnit": {
             "state": "translated",
-            "value": "جلسة جديدة"
+            "value": "خيارات الجلسة الجديدة"
           }
         },
         "it": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nuova sessione"
+            "value": "Opzioni nuova sessione"
           }
         },
         "tr": {
           "stringUnit": {
             "state": "translated",
-            "value": "Yeni oturum"
+            "value": "Yeni oturum seçenekleri"
           }
         },
         "uk": {
           "stringUnit": {
             "state": "translated",
-            "value": "Новий сеанс"
+            "value": "Параметри нового сеансу"
           }
         },
         "id": {
           "stringUnit": {
             "state": "translated",
-            "value": "Sesi baru"
+            "value": "Opsi sesi baru"
           }
         },
         "pl": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nowa sesja"
+            "value": "Opcje nowej sesji"
           }
         },
         "th": {
           "stringUnit": {
             "state": "translated",
-            "value": "เซสชันใหม่"
+            "value": "ตัวเลือกเซสชันใหม่"
           }
         },
         "vi": {
           "stringUnit": {
             "state": "translated",
-            "value": "Phiên mới"
+            "value": "Tùy chọn phiên mới"
           }
         },
         "nl": {
           "stringUnit": {
             "state": "translated",
-            "value": "Nieuwe sessie"
+            "value": "Opties voor nieuwe sessie"
           }
         },
         "fa": {
           "stringUnit": {
             "state": "translated",
-            "value": "جلسه جدید"
+            "value": "گزینه‌های نشست جدید"
           }
         },
         "ru": {
           "stringUnit": {
             "state": "translated",
-            "value": "Новая сессия"
+            "value": "Параметры нового сеанса"
           }
         },
         "sv": {
           "stringUnit": {
             "state": "translated",
-            "value": "Ny session"
+            "value": "Alternativ för ny session"
           }
         }
       }
@@ -97513,6 +100777,142 @@
         }
       }
     },
+    "No agents are available on this gateway.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "No agents are available on this gateway."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此 Gateway 上没有可用的代理。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此 Gateway 上沒有可用的代理程式。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nenhum agente está disponível neste gateway."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Auf diesem Gateway sind keine Agenten verfügbar."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "No hay agentes disponibles en este Gateway."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "このGatewayでは利用可能なエージェントがありません。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "이 Gateway에서 사용할 수 있는 에이전트가 없습니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aucun agent n’est disponible sur ce Gateway."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "इस Gateway पर कोई एजेंट उपलब्ध नहीं है।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "لا توجد وكلاء متاحة على هذا Gateway."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nessun agente è disponibile su questo gateway."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bu Gateway'de kullanılabilir aracı yok."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "На цьому шлюзі немає доступних агентів."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tidak ada agen yang tersedia di gateway ini."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Na tym gatewayu nie są dostępni żadni agenci."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่มีเอเจนต์ที่พร้อมใช้งานบน Gateway นี้"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không có tác nhân nào khả dụng trên gateway này."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Er zijn geen agents beschikbaar op deze gateway."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "هیچ عاملی در این Gateway در دسترس نیست."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "На этом Gateway нет доступных агентов."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Inga agenter är tillgängliga på denna gateway."
+          }
+        }
+      }
+    },
     "No agents reported": {
       "localizations": {
         "en": {
@@ -100641,6 +104041,142 @@
         }
       }
     },
+    "No groups": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "No groups"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "无群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "沒有群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nenhum grupo"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Keine Gruppen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "No hay grupos"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "グループなし"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "그룹 없음"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aucun groupe"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "कोई समूह नहीं"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "لا توجد مجموعات"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nessun gruppo"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup yok"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Немає груп"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tidak ada grup"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Brak grup"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่มีกลุ่ม"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không có nhóm"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Geen groepen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "هیچ گروهی وجود ندارد"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Нет групп"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Inga grupper"
+          }
+        }
+      }
+    },
     "No instances connected": {
       "localizations": {
         "en": {
@@ -105265,6 +108801,142 @@
         }
       }
     },
+    "None": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "None"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "无"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "無"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nenhum"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Keine"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ninguno"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "なし"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "없음"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aucun"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "कोई नहीं"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "لا شيء"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nessuno"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Yok"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Немає"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tidak ada"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Brak"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่มี"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không có"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Geen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "هیچ‌کدام"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Нет"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ingen"
+          }
+        }
+      }
+    },
     "None reported.": {
       "localizations": {
         "en": {
@@ -113833,6 +117505,142 @@
         }
       }
     },
+    "Organization": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organization"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "组织"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "組織"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organização"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organisation"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organización"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "組織"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "조직"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organisation"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "संगठन"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "المؤسسة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organizzazione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Kuruluş"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Організація"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organisasi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organizacja"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "องค์กร"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tổ chức"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organisatie"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "سازمان"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Организация"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Organisation"
+          }
+        }
+      }
+    },
     "Other": {
       "localizations": {
         "en": {
@@ -129881,6 +133689,142 @@
         }
       }
     },
+    "Remove attachments or wait for delivery before archiving or deleting this session.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Remove attachments or wait for delivery before archiving or deleting this session."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "请移除附件或等待其发送完成，然后再归档或删除此会话。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "請先移除附件或等待傳送完成，再封存或刪除此工作階段。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Remova os anexos ou aguarde a entrega antes de arquivar ou excluir esta sessão."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Entfernen Sie Anhänge oder warten Sie auf deren Zustellung, bevor Sie diese Sitzung archivieren oder löschen."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Elimina los archivos adjuntos o espera a que se entreguen antes de archivar o eliminar esta sesión."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "このセッションをアーカイブまたは削除する前に、添付ファイルを削除するか、配信が完了するまでお待ちください。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "이 세션을 보관하거나 삭제하기 전에 첨부 파일을 제거하거나 전송이 완료될 때까지 기다리세요."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Supprimez les pièces jointes ou attendez leur envoi avant d’archiver ou de supprimer cette session."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "इस सत्र को संग्रहीत करने या हटाने से पहले अटैचमेंट हटाएँ या डिलीवरी की प्रतीक्षा करें।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "أزل المرفقات أو انتظر تسليمها قبل أرشفة هذه الجلسة أو حذفها."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Rimuovi gli allegati o attendi la consegna prima di archiviare o eliminare questa sessione."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bu oturumu arşivlemeden veya silmeden önce ekleri kaldırın ya da teslim edilmelerini bekleyin."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Видаліть вкладення або дочекайтеся їх доставлення, перш ніж архівувати чи видаляти цей сеанс."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hapus lampiran atau tunggu hingga pengiriman selesai sebelum mengarsipkan atau menghapus sesi ini."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Usuń załączniki lub poczekaj na ich dostarczenie przed zarchiwizowaniem albo usunięciem tej sesji."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "นำไฟล์แนบออกหรือรอให้ส่งเสร็จก่อนเก็บเซสชันนี้เข้าคลังหรือลบ"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Hãy xóa tệp đính kèm hoặc chờ gửi xong trước khi lưu trữ hoặc xóa phiên này."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Verwijder bijlagen of wacht op de bezorging voordat u deze sessie archiveert of verwijdert."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "پیش از بایگانی یا حذف این نشست، پیوست‌ها را حذف کنید یا منتظر تحویل آن‌ها بمانید."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Удалите вложения или дождитесь доставки, прежде чем архивировать или удалять этот сеанс."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ta bort bilagor eller vänta på leverans innan du arkiverar eller tar bort den här sessionen."
+          }
+        }
+      }
+    },
     "Remove attachments or wait for delivery to resolve before starting a new chat.": {
       "localizations": {
         "en": {
@@ -131241,6 +135185,142 @@
         }
       }
     },
+    "Repository root": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Repository root"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "仓库根目录"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "儲存庫根目錄"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Raiz do repositório"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Repository-Stammverzeichnis"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Raíz del repositorio"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "リポジトリのルート"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "저장소 루트"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Racine du dépôt"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "रिपॉज़िटरी रूट"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "جذر المستودع"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Radice del repository"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Depo kökü"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Корінь репозиторію"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Root repositori"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Katalog główny repozytorium"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "รากของ Repository"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Thư mục gốc của kho lưu trữ"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Repositoryhoofdmap"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ریشهٔ مخزن"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Корень репозитория"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Repositoriets rot"
+          }
+        }
+      }
+    },
     "Request": {
       "localizations": {
         "en": {
@@ -134369,6 +138449,142 @@
         }
       }
     },
+    "Retry session groups": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Retry session groups"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "重试加载会话群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "重試工作階段群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Tentar carregar os grupos de sessões novamente"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungsgruppen erneut laden"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Reintentar grupos de sesiones"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッショングループを再試行"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 그룹 다시 시도"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Réessayer de charger les groupes de sessions"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र समूहों के लिए फिर से प्रयास करें"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "إعادة محاولة تحميل مجموعات الجلسات"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Riprova gruppi di sessioni"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum gruplarını yeniden dene"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Повторити завантаження груп сеансів"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Coba lagi grup sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ponów próbę wczytania grup sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ลองโหลดกลุ่มเซสชันอีกครั้ง"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Thử tải lại các nhóm phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessiegroepen opnieuw proberen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تلاش مجدد برای گروه‌های نشست"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Повторить загрузку групп сеансов"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Försök läsa in sessionsgrupper igen"
+          }
+        }
+      }
+    },
     "Return to the queue and choose another proposal.": {
       "localizations": {
         "en": {
@@ -137905,6 +142121,278 @@
         }
       }
     },
+    "Run duration": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Run duration"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "运行时长"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "執行時間"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Duração da execução"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ausführungsdauer"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Duración de la ejecución"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "実行時間"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "실행 시간"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Durée d’exécution"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "रन की अवधि"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "مدة التشغيل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Durata dell'esecuzione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Çalıştırma süresi"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Тривалість виконання"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Durasi proses"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Czas trwania uruchomienia"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ระยะเวลาการทำงาน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Thời lượng chạy"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Uitvoeringsduur"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "مدت اجرا"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Длительность выполнения"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Körtid"
+          }
+        }
+      }
+    },
+    "Run ended": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Run ended"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "运行结束时间"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "執行結束時間"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Execução encerrada"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ausführung beendet"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ejecución finalizada"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "実行終了"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "실행 종료"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Fin de l’exécution"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "रन समाप्त हुआ"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "انتهى التشغيل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Esecuzione terminata"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Çalıştırma sona erdi"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Запуск завершено"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Proses berakhir"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Zakończenie uruchomienia"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "สิ้นสุดการทำงาน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Lượt chạy đã kết thúc"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Uitvoering beëindigd"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "اجرا پایان یافت"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Запуск завершён"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Körning avslutad"
+          }
+        }
+      }
+    },
     "Run failed": {
       "localizations": {
         "en": {
@@ -138721,6 +143209,142 @@
         }
       }
     },
+    "Run started": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Run started"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "运行开始时间"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "執行開始時間"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Execução iniciada"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ausführung gestartet"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ejecución iniciada"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "実行開始"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "실행 시작"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Début de l’exécution"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "रन शुरू हुआ"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "بدأ التشغيل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Esecuzione avviata"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Çalıştırma başladı"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Запуск розпочато"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Proses dimulai"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Rozpoczęcie uruchomienia"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เริ่มการทำงาน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Lượt chạy đã bắt đầu"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Uitvoering gestart"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "اجرا آغاز شد"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Запуск начат"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Körning startad"
+          }
+        }
+      }
+    },
     "Run still pending": {
       "localizations": {
         "en": {
@@ -139299,8 +143923,8 @@
         },
         "es": {
           "stringUnit": {
-            "state": "new",
-            "value": "Runtime"
+            "state": "translated",
+            "value": "Entorno de ejecución"
           }
         },
         "ja-JP": {
@@ -145385,6 +150009,142 @@
         }
       }
     },
+    "Select": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Select"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "选择"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "選取"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Selecionar"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Auswählen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Seleccionar"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "選択"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "선택"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sélectionner"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "चुनें"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تحديد"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Seleziona"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Seç"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Вибрати"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Pilih"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Wybierz"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เลือก"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Chọn"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Selecteer"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "انتخاب"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Выбрать"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Välj"
+          }
+        }
+      }
+    },
     "Select refresh to load the proposal body.": {
       "localizations": {
         "en": {
@@ -147697,6 +152457,278 @@
         }
       }
     },
+    "Session Groups": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Session Groups"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "会话群组"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "工作階段群組"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupos da sessão"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungsgruppen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupos de sesiones"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッショングループ"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 그룹"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Groupes de sessions"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सेशन समूह"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "مجموعات الجلسة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Gruppi della sessione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum Grupları"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Групи сеансів"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grup Sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Grupy sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "กลุ่มเซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nhóm phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessiegroepen"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "گروه‌های نشست"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Группы сеансов"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessionsgrupper"
+          }
+        }
+      }
+    },
+    "Session Info": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Session Info"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "会话信息"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "工作階段資訊"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informações da sessão"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungsinformationen"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Información de la sesión"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッション情報"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션 정보"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informations sur la session"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सेशन की जानकारी"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "معلومات الجلسة"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informazioni sulla sessione"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum Bilgileri"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Відомості про сеанс"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Info Sesi"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Informacje o sesji"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ข้อมูลเซสชัน"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Thông tin phiên"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessie-informatie"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "اطلاعات نشست"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Информация о сеансе"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessionsinformation"
+          }
+        }
+      }
+    },
     "Session actions": {
       "localizations": {
         "en": {
@@ -148921,6 +153953,142 @@
         }
       }
     },
+    "Sessions in this group become ungrouped.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessions in this group become ungrouped."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此群组中的会话将变为未分组状态。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此群組中的工作階段將變為未分組。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "As sessões deste grupo ficarão sem grupo."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sitzungen in dieser Gruppe werden aus der Gruppe entfernt."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Las sesiones de este grupo quedarán sin agrupar."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "このグループ内のセッションはグループ化されていない状態になります。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "이 그룹의 세션은 그룹에서 해제됩니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Les sessions de ce groupe ne seront plus regroupées."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "इस समूह के सत्र असमूहीकृत हो जाएँगे।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ستصبح الجلسات في هذه المجموعة غير مصنّفة ضمن مجموعة."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Le sessioni in questo gruppo non saranno più raggruppate."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bu gruptaki oturumlar gruptan çıkarılır."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Сеанси в цій групі більше не будуть згруповані."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesi dalam grup ini tidak akan lagi dikelompokkan."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesje w tej grupie przestaną być przypisane do grupy."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "เซสชันในกลุ่มนี้จะไม่อยู่ในกลุ่มใด"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Các phiên trong nhóm này sẽ không còn thuộc nhóm nào."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessies in deze groep worden uit de groep gehaald."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نشست‌های این گروه از گروه خارج می‌شوند."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Сеансы в этой группе останутся без группы."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessioner i den här gruppen blir ogrupperade."
+          }
+        }
+      }
+    },
     "Sessions unavailable": {
       "localizations": {
         "en": {
@@ -153030,7 +158198,7 @@
         "de": {
           "stringUnit": {
             "state": "translated",
-            "value": "Denkprozess und Tool-Aktivität anzeigen"
+            "value": "Gedankengang und Werkzeugaktivität anzeigen"
           }
         },
         "es": {
@@ -153078,13 +158246,13 @@
         "tr": {
           "stringUnit": {
             "state": "translated",
-            "value": "Akıl yürütmeyi ve araç etkinliğini göster"
+            "value": "Akıl yürütme ve araç etkinliğini göster"
           }
         },
         "uk": {
           "stringUnit": {
             "state": "translated",
-            "value": "Показувати міркування та активність інструментів"
+            "value": "Показувати міркування та дії інструментів"
           }
         },
         "id": {
@@ -153102,7 +158270,7 @@
         "th": {
           "stringUnit": {
             "state": "translated",
-            "value": "แสดงการให้เหตุผลและกิจกรรมของเครื่องมือ"
+            "value": "แสดงกระบวนการให้เหตุผลและการทำงานของเครื่องมือ"
           }
         },
         "vi": {
@@ -168369,6 +173537,142 @@
         }
       }
     },
+    "The main session cannot be deleted.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "The main session cannot be deleted."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "无法删除主会话。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "無法刪除主要工作階段。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "A sessão principal não pode ser excluída."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Die Hauptsitzung kann nicht gelöscht werden."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "La sesión principal no se puede eliminar."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "メインセッションは削除できません。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "기본 세션은 삭제할 수 없습니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "La session principale ne peut pas être supprimée."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "मुख्य सत्र को हटाया नहीं जा सकता।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "لا يمكن حذف الجلسة الرئيسية."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "La sessione principale non può essere eliminata."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Ana oturum silinemez."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Основний сеанс не можна видалити."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesi utama tidak dapat dihapus."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nie można usunąć sesji głównej."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่สามารถลบเซสชันหลักได้"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không thể xóa phiên chính."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "De hoofdsessie kan niet worden verwijderd."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "نشست اصلی قابل حذف نیست."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Основной сеанс нельзя удалить."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Huvudsessionen kan inte tas bort."
+          }
+        }
+      }
+    },
     "The saved TLS certificate pin for %@ no longer matches the gateway certificate. The new certificate is trusted by this device; this is commonly caused by certificate rotation.": {
       "localizations": {
         "en": {
@@ -168913,6 +174217,142 @@
         }
       }
     },
+    "The session could not be created.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "The session could not be created."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "无法创建会话。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "無法建立工作階段。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Não foi possível criar a sessão."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Die Sitzung konnte nicht erstellt werden."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "No se pudo crear la sesión."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "セッションを作成できませんでした。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "세션을 생성할 수 없습니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "La session n’a pas pu être créée."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "सत्र बनाया नहीं जा सका।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تعذّر إنشاء الجلسة."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Non è stato possibile creare la sessione."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Oturum oluşturulamadı."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Не вдалося створити сеанс."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesi tidak dapat dibuat."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nie udało się utworzyć sesji."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่สามารถสร้างเซสชันได้"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không thể tạo phiên."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "De sessie kon niet worden aangemaakt."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "جلسه ایجاد نشد."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Не удалось создать сеанс."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sessionen kunde inte skapas."
+          }
+        }
+      }
+    },
     "The short-term dreaming store is empty.": {
       "localizations": {
         "en": {
@@ -172313,6 +177753,142 @@
         }
       }
     },
+    "This session cannot be archived while it is active or running.": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "This session cannot be archived while it is active or running."
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此会话处于活动或运行状态时无法归档。"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "此工作階段在作用中或執行中時無法封存。"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Esta sessão não pode ser arquivada enquanto estiver ativa ou em execução."
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Diese Sitzung kann nicht archiviert werden, solange sie aktiv ist oder ausgeführt wird."
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Esta sesión no se puede archivar mientras esté activa o en ejecución."
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "このセッションは、アクティブまたは実行中のためアーカイブできません。"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "이 세션은 활성 상태이거나 실행 중인 동안 보관할 수 없습니다."
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Cette session ne peut pas être archivée tant qu’elle est active ou en cours d’exécution."
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "यह सत्र सक्रिय या चल रहा होने के दौरान संग्रहीत नहीं किया जा सकता।"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "لا يمكن أرشفة هذه الجلسة أثناء نشاطها أو تشغيلها."
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Questa sessione non può essere archiviata mentre è attiva o in esecuzione."
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bu oturum etkinken veya çalışırken arşivlenemez."
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Цей сеанс не можна архівувати, доки він активний або виконується."
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Sesi ini tidak dapat diarsipkan saat masih aktif atau berjalan."
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Nie można zarchiwizować tej sesji, gdy jest aktywna lub uruchomiona."
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ไม่สามารถเก็บเซสชันนี้เข้าคลังขณะที่ยังใช้งานหรือกำลังทำงานอยู่ได้"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Không thể lưu trữ phiên này khi phiên đang hoạt động hoặc đang chạy."
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Deze sessie kan niet worden gearchiveerd terwijl deze actief of in uitvoering is."
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "این نشست تا زمانی که فعال یا در حال اجرا است، قابل بایگانی نیست."
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Этот сеанс нельзя архивировать, пока он активен или выполняется."
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Den här sessionen kan inte arkiveras medan den är aktiv eller körs."
+          }
+        }
+      }
+    },
     "Time zone": {
       "localizations": {
         "en": {
@@ -176529,6 +182105,142 @@
         }
       }
     },
+    "Updated": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Updated"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "更新时间"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "已更新"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Atualizado"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aktualisiert"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Actualizado"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "更新日時"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "업데이트됨"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Mis à jour"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "अपडेट किया गया"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "تم التحديث"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Aggiornato"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Güncellendi"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Оновлено"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Diperbarui"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Zaktualizowano"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "อัปเดตแล้ว"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Đã cập nhật"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Bijgewerkt"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "به‌روزرسانی‌شده"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Обновлено"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Uppdaterad"
+          }
+        }
+      }
+    },
     "Updated %@": {
       "localizations": {
         "en": {
@@ -185097,6 +190809,142 @@
         }
       }
     },
+    "Worktree": {
+      "localizations": {
+        "en": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Worktree"
+          }
+        },
+        "zh-CN": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "工作树"
+          }
+        },
+        "zh-TW": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "工作樹"
+          }
+        },
+        "pt-BR": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Árvore de trabalho"
+          }
+        },
+        "de": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Arbeitsbaum"
+          }
+        },
+        "es": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Árbol de trabajo"
+          }
+        },
+        "ja-JP": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ワークツリー"
+          }
+        },
+        "ko": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "fr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Arbre de travail"
+          }
+        },
+        "hi": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "वर्कट्री"
+          }
+        },
+        "ar": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "شجرة العمل"
+          }
+        },
+        "it": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "tr": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Çalışma ağacı"
+          }
+        },
+        "uk": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Робоче дерево"
+          }
+        },
+        "id": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Drzewo robocze"
+          }
+        },
+        "th": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "vi": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "nl": {
+          "stringUnit": {
+            "state": "new",
+            "value": "Worktree"
+          }
+        },
+        "fa": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "درخت کاری"
+          }
+        },
+        "ru": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Рабочее дерево"
+          }
+        },
+        "sv": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "Arbetskopia"
+          }
+        }
+      }
+    },
     "Writing": {
       "localizations": {
         "en": {
diff --git a/apps/macos/Sources/OpenClaw/MacGatewayChatTransport+SessionActions.swift b/apps/macos/Sources/OpenClaw/MacGatewayChatTransport+SessionActions.swift
index 73435c2aac2..5bf3f440c04 100644
--- a/apps/macos/Sources/OpenClaw/MacGatewayChatTransport+SessionActions.swift
+++ b/apps/macos/Sources/OpenClaw/MacGatewayChatTransport+SessionActions.swift
@@ -1,30 +1,117 @@
 import Foundation
 import OpenClawChatUI
+import OpenClawProtocol
 
 extension MacGatewayChatTransport {
-    func acquireSessionMutationRouteLease() async -> OpenClawChatSessionMutationRouteLease? {
+    func acquireNewSessionRouteLease() async -> OpenClawChatNewSessionRouteLease? {
         guard let serverLease = await GatewayConnection.shared.captureServerLease() else { return nil }
         if let outboxGatewayID {
             let currentGatewayID = await MainActor.run { MacChatTranscriptCache.currentGatewayID() }
             guard currentGatewayID == outboxGatewayID else { return nil }
         }
-        let transport = self
-        return OpenClawChatSessionMutationRouteLease { key, label, category, pinned, archived, unread in
-            let target = transport.sessionTarget(for: key)
-            let request = OpenClawChatGatewayRequests.patchSession(
-                sessionKey: target.sessionKey,
-                agentID: target.agentID,
-                label: label,
-                category: category,
-                pinned: pinned,
-                archived: archived,
-                unread: unread)
-            _ = try await GatewayConnection.shared.request(
+        let request: @Sendable (OpenClawChatGatewayRequest) async throws -> Data = { request in
+            try await GatewayConnection.shared.request(
                 method: request.method,
                 params: request.params,
                 timeoutMs: request.timeoutMs,
                 ifCurrentServerLease: serverLease)
         }
+        return OpenClawChatNewSessionRouteLease(
+            listAgents: {
+                let data = try await request(OpenClawChatGatewayRequests.agentsList())
+                let result = try JSONDecoder().decode(AgentsListResult.self, from: data)
+                return OpenClawChatAgentsListResponse(
+                    defaultId: result.defaultid,
+                    agents: result.agents.map {
+                        OpenClawChatAgentChoice(
+                            id: $0.id,
+                            name: $0.name,
+                            workspaceGit: $0.workspacegit)
+                    })
+            },
+            createSession: { key, label, explicitAgentID, parentSessionKey, worktree, worktreeBaseRef in
+                let agentID = explicitAgentID
+                    ?? OpenClawChatSessionKey.agentID(from: key)
+                    ?? parentSessionKey.flatMap { OpenClawChatSessionKey.agentID(from: $0) }
+                let createRequest = OpenClawChatGatewayRequests.createSession(
+                    key: key,
+                    agentID: agentID,
+                    label: label,
+                    parentSessionKey: parentSessionKey,
+                    worktree: worktree,
+                    worktreeBaseRef: worktreeBaseRef)
+                let data = try await request(createRequest)
+                return try JSONDecoder().decode(OpenClawChatCreateSessionResponse.self, from: data)
+            })
+    }
+
+    func acquireSessionGroupsRouteLease() async -> OpenClawChatSessionGroupsRouteLease? {
+        guard let serverLease = await GatewayConnection.shared.captureServerLease() else { return nil }
+        if let outboxGatewayID {
+            let currentGatewayID = await MainActor.run { MacChatTranscriptCache.currentGatewayID() }
+            guard currentGatewayID == outboxGatewayID else { return nil }
+        }
+        let request: @Sendable (OpenClawChatGatewayRequest) async throws -> Data = { request in
+            try await GatewayConnection.shared.request(
+                method: request.method,
+                params: request.params,
+                timeoutMs: request.timeoutMs,
+                ifCurrentServerLease: serverLease)
+        }
+        return OpenClawChatSessionGroupsRouteLease(
+            listGroups: {
+                let data = try await request(OpenClawChatGatewayRequests.sessionGroupsList())
+                return try JSONDecoder().decode(OpenClawChatSessionGroupsResponse.self, from: data)
+            },
+            putGroups: { names in
+                let data = try await request(OpenClawChatGatewayRequests.sessionGroupsPut(names: names))
+                return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+            },
+            renameGroup: { name, to in
+                let data = try await request(OpenClawChatGatewayRequests.sessionGroupsRename(name: name, to: to))
+                return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+            },
+            deleteGroup: { name in
+                let data = try await request(OpenClawChatGatewayRequests.sessionGroupsDelete(name: name))
+                return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+            })
+    }
+
+    func acquireSessionMutationRouteLease() async -> OpenClawChatSessionMutationRouteLease? {
+        guard let serverLease = await GatewayConnection.shared.captureServerLease() else { return nil }
+        if let outboxGatewayID {
+            let currentGatewayID = await MainActor.run { MacChatTranscriptCache.currentGatewayID() }
+            guard currentGatewayID == outboxGatewayID else { return nil }
+        }
+        let transport = self
+        return OpenClawChatSessionMutationRouteLease(
+            patchSession: { key, label, category, pinned, archived, unread in
+                let target = transport.sessionTarget(for: key)
+                let request = OpenClawChatGatewayRequests.patchSession(
+                    sessionKey: target.sessionKey,
+                    agentID: target.agentID,
+                    label: label,
+                    category: category,
+                    pinned: pinned,
+                    archived: archived,
+                    unread: unread)
+                _ = try await GatewayConnection.shared.request(
+                    method: request.method,
+                    params: request.params,
+                    timeoutMs: request.timeoutMs,
+                    ifCurrentServerLease: serverLease)
+            },
+            deleteSession: { key in
+                let target = transport.sessionTarget(for: key)
+                let request = OpenClawChatGatewayRequests.deleteSession(
+                    sessionKey: target.sessionKey,
+                    agentID: target.agentID)
+                _ = try await GatewayConnection.shared.request(
+                    method: request.method,
+                    params: request.params,
+                    timeoutMs: request.timeoutMs,
+                    ifCurrentServerLease: serverLease)
+            })
     }
 
     func forkSession(parentKey: String) async throws -> String {
diff --git a/apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift b/apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift
index 42b82507c0d..018185af8be 100644
--- a/apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift
+++ b/apps/macos/Sources/OpenClaw/WebChatSwiftUI.swift
@@ -226,6 +226,45 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
             sessions: decoded.sessions)
     }
 
+    func listAgents() async throws -> OpenClawChatAgentsListResponse? {
+        let data = try await GatewayConnection.shared.request(OpenClawChatGatewayRequests.agentsList())
+        let result = try JSONDecoder().decode(AgentsListResult.self, from: data)
+        return OpenClawChatAgentsListResponse(
+            defaultId: result.defaultid,
+            agents: result.agents.map {
+                OpenClawChatAgentChoice(
+                    id: $0.id,
+                    name: $0.name,
+                    workspaceGit: $0.workspacegit)
+            })
+    }
+
+    func listSessionGroups() async throws -> OpenClawChatSessionGroupsResponse? {
+        let data = try await GatewayConnection.shared.request(OpenClawChatGatewayRequests.sessionGroupsList())
+        return try JSONDecoder().decode(OpenClawChatSessionGroupsResponse.self, from: data)
+    }
+
+    func putSessionGroups(names: [String]) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        let request = OpenClawChatGatewayRequests.sessionGroupsPut(names: names)
+        let data = try await GatewayConnection.shared.request(request)
+        return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+    }
+
+    func renameSessionGroup(
+        name: String,
+        to: String) async throws -> OpenClawChatSessionGroupsMutationResponse
+    {
+        let request = OpenClawChatGatewayRequests.sessionGroupsRename(name: name, to: to)
+        let data = try await GatewayConnection.shared.request(request)
+        return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+    }
+
+    func deleteSessionGroup(name: String) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        let request = OpenClawChatGatewayRequests.sessionGroupsDelete(name: name)
+        let data = try await GatewayConnection.shared.request(request)
+        return try JSONDecoder().decode(OpenClawChatSessionGroupsMutationResponse.self, from: data)
+    }
+
     func setSessionModel(sessionKey: String, model: String?) async throws {
         let target = self.sessionTarget(for: sessionKey)
         _ = try await self.patchSessionModel(
@@ -460,7 +499,25 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
         parentSessionKey: String?,
         worktree: Bool?) async throws -> OpenClawChatCreateSessionResponse
     {
-        let agentID = OpenClawChatSessionKey.agentID(from: key)
+        try await self.createSession(
+            key: key,
+            label: label,
+            agentID: nil,
+            parentSessionKey: parentSessionKey,
+            worktree: worktree,
+            worktreeBaseRef: nil)
+    }
+
+    func createSession(
+        key: String,
+        label: String?,
+        agentID explicitAgentID: String?,
+        parentSessionKey: String?,
+        worktree: Bool?,
+        worktreeBaseRef: String?) async throws -> OpenClawChatCreateSessionResponse
+    {
+        let agentID = explicitAgentID
+            ?? OpenClawChatSessionKey.agentID(from: key)
             ?? parentSessionKey.flatMap { OpenClawChatSessionKey.agentID(from: $0) }
             ?? self.routingIdentity.currentAgentID()
         let request = OpenClawChatGatewayRequests.createSession(
@@ -468,7 +525,8 @@ struct MacGatewayChatTransport: OpenClawChatTransport {
             agentID: agentID,
             label: label,
             parentSessionKey: parentSessionKey,
-            worktree: worktree)
+            worktree: worktree,
+            worktreeBaseRef: worktreeBaseRef)
         let data = try await GatewayConnection.shared.request(request)
         return try JSONDecoder().decode(OpenClawChatCreateSessionResponse.self, from: data)
     }
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatGatewayRequest.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatGatewayRequest.swift
index aa128fe4d2b..e804611b7d4 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatGatewayRequest.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatGatewayRequest.swift
@@ -130,12 +130,46 @@ public enum OpenClawChatGatewayRequests {
             timeoutMs: timeoutMs)
     }
 
+    public static func sessionGroupsList() -> OpenClawChatGatewayRequest {
+        OpenClawChatGatewayRequest(
+            method: "sessions.groups.list",
+            timeoutMs: self.defaultTimeoutMs)
+    }
+
+    public static func sessionGroupsPut(names: [String]) -> OpenClawChatGatewayRequest {
+        OpenClawChatGatewayRequest(
+            method: "sessions.groups.put",
+            params: ["names": AnyCodable(names)],
+            timeoutMs: self.mutationTimeoutMs)
+    }
+
+    public static func sessionGroupsRename(
+        name: String,
+        to: String) -> OpenClawChatGatewayRequest
+    {
+        OpenClawChatGatewayRequest(
+            method: "sessions.groups.rename",
+            params: [
+                "name": AnyCodable(name),
+                "to": AnyCodable(to),
+            ],
+            timeoutMs: self.mutationTimeoutMs)
+    }
+
+    public static func sessionGroupsDelete(name: String) -> OpenClawChatGatewayRequest {
+        OpenClawChatGatewayRequest(
+            method: "sessions.groups.delete",
+            params: ["name": AnyCodable(name)],
+            timeoutMs: self.mutationTimeoutMs)
+    }
+
     public static func createSession(
         key: String,
         agentID: String?,
         label: String?,
         parentSessionKey: String?,
-        worktree: Bool?) -> OpenClawChatGatewayRequest
+        worktree: Bool?,
+        worktreeBaseRef: String? = nil) -> OpenClawChatGatewayRequest
     {
         var params = ["key": AnyCodable(key)]
         self.add(agentID, to: &params, key: "agentId")
@@ -144,6 +178,7 @@ public enum OpenClawChatGatewayRequests {
         if let worktree {
             params["worktree"] = AnyCodable(worktree)
         }
+        self.add(worktreeBaseRef, to: &params, key: "worktreeBaseRef")
         return OpenClawChatGatewayRequest(
             method: "sessions.create",
             params: params,
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift
new file mode 100644
index 00000000000..a7e09b29d56
--- /dev/null
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionManagementViews.swift
@@ -0,0 +1,637 @@
+import Foundation
+import Observation
+import SwiftUI
+#if os(macOS)
+import AppKit
+#elseif os(iOS)
+import UIKit
+#endif
+
+enum ChatSessionBatchAction: Sendable, Equatable {
+    case pin
+    case unpin
+    case archive
+    case delete
+}
+
+struct ChatSessionBatchResult: Sendable, Equatable {
+    let succeededKeys: [String]
+    let errorsByKey: [String: String]
+}
+
+enum ChatSessionBatchValidationError: LocalizedError {
+    case cannotArchive
+    case cannotDelete
+    case attachmentOwnerPinned
+
+    var errorDescription: String? {
+        switch self {
+        case .cannotArchive:
+            String(localized: "This session cannot be archived while it is active or running.")
+        case .cannotDelete:
+            String(localized: "The main session cannot be deleted.")
+        case .attachmentOwnerPinned:
+            String(localized: "Remove attachments or wait for delivery before archiving or deleting this session.")
+        }
+    }
+}
+
+enum ChatSessionBatchMutationRunner {
+    static func run(
+        keys: [String],
+        maxConcurrent: Int = 4,
+        operation: @escaping @Sendable (String) async throws -> Void) async -> ChatSessionBatchResult
+    {
+        guard !keys.isEmpty else {
+            return ChatSessionBatchResult(succeededKeys: [], errorsByKey: [:])
+        }
+        let limit = max(1, min(maxConcurrent, keys.count))
+        var succeeded: [(Int, String)] = []
+        var failures: [String: String] = [:]
+        await withTaskGroup(of: (Int, String, String?).self) { group in
+            var nextIndex = 0
+            while nextIndex < limit {
+                let index = nextIndex
+                let key = keys[index]
+                group.addTask {
+                    do {
+                        try await operation(key)
+                        return (index, key, nil)
+                    } catch {
+                        return (index, key, error.localizedDescription)
+                    }
+                }
+                nextIndex += 1
+            }
+            while let (index, key, error) = await group.next() {
+                if let error {
+                    failures[key] = error
+                } else {
+                    succeeded.append((index, key))
+                }
+                if nextIndex < keys.count {
+                    let pendingIndex = nextIndex
+                    let pendingKey = keys[pendingIndex]
+                    group.addTask {
+                        do {
+                            try await operation(pendingKey)
+                            return (pendingIndex, pendingKey, nil)
+                        } catch {
+                            return (pendingIndex, pendingKey, error.localizedDescription)
+                        }
+                    }
+                    nextIndex += 1
+                }
+            }
+        }
+        return ChatSessionBatchResult(
+            succeededKeys: succeeded.sorted { $0.0 < $1.0 }.map(\.1),
+            errorsByKey: failures)
+    }
+}
+
+struct ChatSessionInspectorDetails: Equatable {
+    let title: String
+    let key: String
+    let kind: String?
+    let agentID: String?
+    let group: String?
+    let runState: String?
+    let model: String?
+    let provider: String?
+    let runtime: String?
+    let runDurationMs: Double?
+    let worktreeID: String?
+    let worktreeBranch: String?
+    let worktreeRoot: String?
+    let updatedAt: Double?
+    let lastActivityAt: Double?
+    let lastInteractionAt: Double?
+    let startedAt: Double?
+    let endedAt: Double?
+
+    init(session: OpenClawChatSessionEntry) {
+        self.title = ChatSessionSidebarModel.displayName(for: session)
+        self.key = session.key
+        self.kind = Self.normalized(session.kind)
+        self.agentID = Self.normalized(OpenClawChatSessionKey.agentID(from: session.key))
+        self.group = Self.normalized(session.category)
+        self.runState = Self.runState(for: session)
+        self.model = Self.normalized(session.model)
+        self.provider = Self.normalized(session.modelProvider)
+        self.runtime = Self.normalized(session.agentRuntime?.id)
+        self.runDurationMs = session.runtimeMs
+        self.worktreeID = Self.normalized(session.worktree?.id)
+        self.worktreeBranch = Self.normalized(session.worktree?.branch)
+        self.worktreeRoot = Self.normalized(session.worktree?.repoRoot)
+        self.updatedAt = session.updatedAt
+        self.lastActivityAt = session.lastActivityAt
+        self.lastInteractionAt = session.lastInteractionAt
+        self.startedAt = session.startedAt
+        self.endedAt = session.endedAt
+    }
+
+    private static func normalized(_ value: String?) -> String? {
+        let value = value?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return value?.isEmpty == false ? value : nil
+    }
+
+    private static func runState(for session: OpenClawChatSessionEntry) -> String? {
+        if session.hasActiveRun == true || session.hasActiveSubagentRun == true {
+            return String(localized: "Running")
+        }
+        return self.normalized(session.status)
+    }
+}
+
+@MainActor
+struct ChatSessionInspectorSheet: View {
+    @Bindable var viewModel: OpenClawChatViewModel
+    let session: OpenClawChatSessionEntry
+
+    @Environment(\.dismiss) private var dismiss
+    @State private var displayedSession: OpenClawChatSessionEntry
+    @State private var groups: [OpenClawChatSessionGroup] = []
+    @State private var isMutatingGroup = false
+    @State private var errorText: String?
+
+    init(viewModel: OpenClawChatViewModel, session: OpenClawChatSessionEntry) {
+        self.viewModel = viewModel
+        self.session = session
+        _displayedSession = State(initialValue: session)
+    }
+
+    private var details: ChatSessionInspectorDetails {
+        ChatSessionInspectorDetails(session: self.displayedSession)
+    }
+
+    var body: some View {
+        NavigationStack {
+            Form {
+                Section("Identity") {
+                    LabeledContent("Name", value: self.details.title)
+                    HStack(alignment: .firstTextBaseline) {
+                        LabeledContent("Key", value: self.details.key)
+                        Button {
+                            Self.copy(self.details.key)
+                        } label: {
+                            Image(systemName: "doc.on.doc")
+                        }
+                        .buttonStyle(.borderless)
+                        .help("Copy session key")
+                    }
+                    self.optionalRow("Kind", self.details.kind)
+                    self.optionalRow("Agent", self.details.agentID)
+                }
+
+                Section("Organization") {
+                    Picker("Group", selection: self.groupSelection) {
+                        Text("None")
+                            .font(OpenClawChatTypography.body)
+                            .tag("")
+                        ForEach(self.groups) { group in
+                            Text(verbatim: group.name)
+                                .font(OpenClawChatTypography.body)
+                                .tag(group.name)
+                        }
+                    }
+                    .disabled(self.isMutatingGroup)
+                    Toggle("Pinned", isOn: self.pinnedBinding)
+                        .font(OpenClawChatTypography.body)
+                    Toggle("Archived", isOn: self.archivedBinding)
+                        .font(OpenClawChatTypography.body)
+                        .disabled(!self.displayedSession.isArchived && !ChatSessionSidebarModel.canArchiveSession(
+                            self.displayedSession,
+                            mainSessionKey: self.viewModel.resolvedMainSessionKey))
+                }
+
+                Section("Run") {
+                    self.optionalRow("Status", self.details.runState)
+                    self.optionalRow("Model", self.details.model)
+                    self.optionalRow("Provider", self.details.provider)
+                    self.optionalRow("Runtime", self.details.runtime)
+                    if let duration = self.details.runDurationMs {
+                        LabeledContent("Run duration", value: Self.duration(duration))
+                    }
+                }
+
+                if self.details.worktreeID != nil || self.details.worktreeBranch != nil ||
+                    self.details.worktreeRoot != nil
+                {
+                    Section("Worktree") {
+                        self.optionalRow("ID", self.details.worktreeID)
+                        self.optionalRow("Branch", self.details.worktreeBranch)
+                        self.optionalRow("Repository root", self.details.worktreeRoot)
+                    }
+                }
+
+                Section("Activity") {
+                    self.timestampRow("Updated", self.details.updatedAt)
+                    self.timestampRow("Last activity", self.details.lastActivityAt)
+                    self.timestampRow("Last interaction", self.details.lastInteractionAt)
+                    self.timestampRow("Run started", self.details.startedAt)
+                    self.timestampRow("Run ended", self.details.endedAt)
+                }
+
+                if let errorText {
+                    Section {
+                        Text(errorText)
+                            .font(OpenClawChatTypography.caption)
+                            .foregroundStyle(OpenClawChatTheme.danger)
+                    }
+                }
+            }
+            .navigationTitle("Session Info")
+            .toolbar {
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Done") { self.dismiss() }
+                        .font(OpenClawChatTypography.body)
+                }
+            }
+            // Keyed to the catalog revision so group create/rename/delete while
+            // the inspector is open refreshes the picker instead of going stale.
+            .task(id: self.viewModel.sessionGroupsRevision) {
+                do {
+                    self.groups = try await self.viewModel.fetchSessionGroups()
+                } catch {
+                    self.errorText = error.localizedDescription
+                }
+            }
+            .onChange(of: self.viewModel.sessions) {
+                if let refreshed = self.viewModel.sessions.first(where: { $0.key == self.displayedSession.key }) {
+                    self.displayedSession = refreshed
+                }
+            }
+        }
+        #if os(macOS)
+        .frame(minWidth: 520, minHeight: 620)
+        #endif
+    }
+
+    private var groupSelection: Binding<String> {
+        Binding(
+            get: { self.displayedSession.category ?? "" },
+            set: { next in
+                let previous = self.displayedSession.category
+                let nextGroup = next.isEmpty ? nil : next
+                self.displayedSession.category = nextGroup
+                self.isMutatingGroup = true
+                Task {
+                    defer { self.isMutatingGroup = false }
+                    do {
+                        try await self.viewModel.setSessionGroup(
+                            key: self.displayedSession.key,
+                            group: nextGroup)
+                        self.errorText = nil
+                    } catch {
+                        self.displayedSession.category = previous
+                        self.errorText = error.localizedDescription
+                    }
+                }
+            })
+    }
+
+    private var pinnedBinding: Binding<Bool> {
+        Binding(
+            get: { self.displayedSession.isPinned },
+            set: { pinned in
+                self.displayedSession.pinned = pinned
+                self.viewModel.setSessionPinned(key: self.displayedSession.key, pinned: pinned)
+            })
+    }
+
+    private var archivedBinding: Binding<Bool> {
+        Binding(
+            get: { self.displayedSession.isArchived },
+            set: { archived in
+                self.displayedSession.archived = archived
+                self.viewModel.setSessionArchived(key: self.displayedSession.key, archived: archived)
+            })
+    }
+
+    @ViewBuilder
+    private func optionalRow(_ title: LocalizedStringKey, _ value: String?) -> some View {
+        if let value {
+            LabeledContent(title, value: value)
+        }
+    }
+
+    @ViewBuilder
+    private func timestampRow(_ title: LocalizedStringKey, _ timestamp: Double?) -> some View {
+        if let timestamp, timestamp > 0 {
+            LabeledContent(title, value: Date(timeIntervalSince1970: timestamp / 1000).formatted(
+                date: .abbreviated,
+                time: .standard))
+        }
+    }
+
+    private static func duration(_ milliseconds: Double) -> String {
+        Duration.seconds(milliseconds / 1000).formatted(.units(allowed: [.hours, .minutes, .seconds]))
+    }
+
+    private static func copy(_ value: String) {
+        #if os(macOS)
+        NSPasteboard.general.clearContents()
+        NSPasteboard.general.setString(value, forType: .string)
+        #elseif os(iOS)
+        UIPasteboard.general.string = value
+        #endif
+    }
+}
+
+@MainActor
+struct ChatSessionGroupsSheet: View {
+    @Bindable var viewModel: OpenClawChatViewModel
+    @Environment(\.dismiss) private var dismiss
+    @State private var groups: [OpenClawChatSessionGroup] = []
+    @State private var newGroupName = ""
+    @State private var renameTarget: OpenClawChatSessionGroup?
+    @State private var renameText = ""
+    @State private var deleteTarget: OpenClawChatSessionGroup?
+    @State private var routeLease: OpenClawChatSessionGroupsRouteLease?
+    @State private var isLoading = true
+    @State private var isMutating = false
+    @State private var errorText: String?
+
+    var body: some View {
+        NavigationStack {
+            List {
+                Section("Groups") {
+                    ForEach(self.groups) { group in
+                        HStack {
+                            Text(verbatim: group.name)
+                                .font(OpenClawChatTypography.body)
+                            Spacer()
+                            Menu {
+                                Button("Rename…") {
+                                    self.renameText = group.name
+                                    self.renameTarget = group
+                                }
+                                Button("Delete…", role: .destructive) {
+                                    self.deleteTarget = group
+                                }
+                            } label: {
+                                Image(systemName: "ellipsis.circle")
+                            }
+                            #if os(macOS)
+                            .menuStyle(.borderlessButton)
+                            #endif
+                            .disabled(self.isMutating)
+                        }
+                    }
+                    if self.groups.isEmpty, !self.isLoading {
+                        Text("No groups")
+                            .font(OpenClawChatTypography.body)
+                            .foregroundStyle(.secondary)
+                    }
+                }
+                Section("Create Group") {
+                    TextField("Group name", text: self.$newGroupName)
+                        .font(OpenClawChatTypography.body)
+                        .disabled(self.isMutating)
+                    Button("Add Group") {
+                        guard !self.isMutating else { return }
+                        let name = self.newGroupName
+                        self.isMutating = true
+                        Task { await self.createGroup(named: name) }
+                    }
+                    .font(OpenClawChatTypography.body)
+                    .disabled(
+                        self.isMutating ||
+                            self.newGroupName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                }
+                if let errorText {
+                    Section {
+                        Text(errorText)
+                            .font(OpenClawChatTypography.caption)
+                            .foregroundStyle(OpenClawChatTheme.danger)
+                    }
+                }
+            }
+            .overlay { if self.isLoading { ProgressView() } }
+            .navigationTitle("Session Groups")
+            .toolbar {
+                ToolbarItem(placement: .confirmationAction) {
+                    Button("Done") { self.dismiss() }
+                        .font(OpenClawChatTypography.body)
+                }
+            }
+            // Keyed to the catalog revision so remote group mutations (reason
+            // "groups" events) refresh an open manager instead of going stale.
+            .task(id: self.viewModel.sessionGroupsRevision) { await self.loadGroups() }
+            .alert(
+                "Rename Group",
+                isPresented: Binding(
+                    get: { self.renameTarget != nil },
+                    set: { if !$0 { self.renameTarget = nil } }))
+            {
+                TextField("Group name", text: self.$renameText)
+                    .font(OpenClawChatTypography.body)
+                Button("Rename") {
+                    guard !self.isMutating, let target = self.renameTarget else { return }
+                    let name = self.renameText
+                    self.isMutating = true
+                    Task { await self.renameGroup(target, to: name) }
+                }
+                .disabled(self.isMutating)
+                Button("Cancel", role: .cancel) { self.renameTarget = nil }
+            }
+            .confirmationDialog(
+                    self.deleteTarget.map { String(format: String(localized: "Delete “%@”?"), $0.name) }
+                        ?? String(localized: "Delete group?"),
+                    isPresented: Binding(
+                        get: { self.deleteTarget != nil },
+                        set: { if !$0 { self.deleteTarget = nil } }))
+            {
+                Button("Delete Group", role: .destructive) {
+                    guard !self.isMutating, let target = self.deleteTarget else { return }
+                    self.isMutating = true
+                    Task { await self.deleteGroup(target) }
+                }
+                .disabled(self.isMutating)
+                } message: {
+                    Text("Sessions in this group become ungrouped.")
+                        .font(OpenClawChatTypography.body)
+                }
+        }
+        #if os(macOS)
+        .frame(minWidth: 420, minHeight: 420)
+        #endif
+    }
+
+    private func loadGroups() async {
+        self.isLoading = true
+        defer { self.isLoading = false }
+        do {
+            let routeLease = try await self.viewModel.sessionGroupsRouteLease()
+            self.routeLease = routeLease
+            self.groups = try await self.viewModel.fetchSessionGroups(using: routeLease)
+            self.errorText = nil
+        } catch {
+            self.routeLease = nil
+            self.errorText = error.localizedDescription
+        }
+    }
+
+    private func createGroup(named name: String) async {
+        defer { self.isMutating = false }
+        guard let routeLease = self.routeLease else {
+            self.errorText = String(localized: "Gateway changed. Close and reopen Groups to continue.")
+            return
+        }
+        do {
+            self.groups = try await self.viewModel.createSessionGroup(
+                named: name,
+                using: routeLease)
+            self.newGroupName = ""
+            self.errorText = nil
+        } catch {
+            self.errorText = error.localizedDescription
+        }
+    }
+
+    private func renameGroup(_ target: OpenClawChatSessionGroup, to name: String) async {
+        defer { self.isMutating = false }
+        defer { self.renameTarget = nil }
+        guard let routeLease = self.routeLease else {
+            self.errorText = String(localized: "Gateway changed. Close and reopen Groups to continue.")
+            return
+        }
+        do {
+            self.groups = try await self.viewModel.renameSessionGroup(
+                target.name,
+                to: name,
+                using: routeLease)
+            self.errorText = nil
+        } catch {
+            self.errorText = error.localizedDescription
+        }
+    }
+
+    private func deleteGroup(_ target: OpenClawChatSessionGroup) async {
+        defer { self.isMutating = false }
+        defer { self.deleteTarget = nil }
+        guard let routeLease = self.routeLease else {
+            self.errorText = String(localized: "Gateway changed. Close and reopen Groups to continue.")
+            return
+        }
+        do {
+            self.groups = try await self.viewModel.deleteSessionGroup(target.name, using: routeLease)
+            self.errorText = nil
+        } catch {
+            self.errorText = error.localizedDescription
+        }
+    }
+}
+
+@MainActor
+struct ChatNewSessionOptionsPopover: View {
+    @Bindable var viewModel: OpenClawChatViewModel
+    let onComplete: () -> Void
+
+    @State private var agents: [OpenClawChatAgentChoice] = []
+    @State private var selectedAgentID = ""
+    @State private var usesWorktree = false
+    @State private var baseRef = ""
+    @State private var isLoading = true
+    @State private var isCreating = false
+    @State private var routeLease: OpenClawChatNewSessionRouteLease?
+    @State private var errorText: String?
+
+    private var selectedAgent: OpenClawChatAgentChoice? {
+        self.agents.first { $0.id == self.selectedAgentID }
+    }
+
+    private func loadOptions() async {
+        self.isLoading = true
+        self.errorText = nil
+        defer { self.isLoading = false }
+        do {
+            let routeLease = try await self.viewModel.newSessionRouteLease()
+            let response = try await routeLease.listAgents()
+            // An empty catalog must not retain the lease: a stray defaultId would
+            // enable Create for an agent the gateway never offered.
+            guard let response, !response.agents.isEmpty else {
+                self.errorText = String(localized: "No agents are available on this gateway.")
+                return
+            }
+            self.routeLease = routeLease
+            self.agents = response.agents
+            self.selectedAgentID = response.agents.contains(where: { $0.id == response.defaultId })
+                ? response.defaultId
+                : response.agents[0].id
+        } catch {
+            self.errorText = error.localizedDescription
+        }
+    }
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 14) {
+            Text("New Session Options")
+                .font(OpenClawChatTypography.body(size: 15, weight: .semibold, relativeTo: .headline))
+            Picker("Agent", selection: self.$selectedAgentID) {
+                ForEach(self.agents) { agent in
+                    Text(verbatim: agent.displayName)
+                        .font(OpenClawChatTypography.body)
+                        .tag(agent.id)
+                }
+            }
+            .disabled(self.isLoading || self.agents.isEmpty)
+            Toggle("Create in a worktree", isOn: self.$usesWorktree)
+                .font(OpenClawChatTypography.body)
+                .disabled(self.selectedAgent?.workspaceGit == false)
+            if self.usesWorktree {
+                TextField("Base ref (optional)", text: self.$baseRef)
+                    .font(OpenClawChatTypography.body)
+            }
+            if let errorText {
+                Text(errorText)
+                    .font(OpenClawChatTypography.caption)
+                    .foregroundStyle(OpenClawChatTheme.danger)
+            }
+            HStack {
+                if self.errorText != nil, self.routeLease == nil {
+                    Button("Retry") {
+                        Task { await self.loadOptions() }
+                    }
+                    .font(OpenClawChatTypography.body)
+                }
+                Spacer()
+                Button("Create") {
+                    guard !self.isCreating, let routeLease = self.routeLease else { return }
+                    self.isCreating = true
+                    self.errorText = nil
+                    let baseRef = self.baseRef.trimmingCharacters(in: .whitespacesAndNewlines)
+                    Task {
+                        defer { self.isCreating = false }
+                        let created = await self.viewModel.startNewSession(
+                            agentID: self.selectedAgentID,
+                            worktree: self.usesWorktree,
+                            worktreeBaseRef: baseRef.isEmpty ? nil : baseRef,
+                            using: routeLease)
+                        // Keep inputs on failure; dismissing would discard the
+                        // selected agent/worktree while no session exists.
+                        if created {
+                            self.onComplete()
+                        } else {
+                            self.errorText = self.viewModel.errorText
+                                ?? String(localized: "The session could not be created.")
+                        }
+                    }
+                }
+                .font(OpenClawChatTypography.body)
+                .keyboardShortcut(.defaultAction)
+                .disabled(
+                    self.isLoading || self.isCreating || self.selectedAgentID.isEmpty || self.routeLease == nil)
+            }
+        }
+        .padding(16)
+        .frame(width: 320)
+        .task { await self.loadOptions() }
+        .onChange(of: self.selectedAgentID) {
+            if self.selectedAgent?.workspaceGit == false {
+                self.usesWorktree = false
+            }
+        }
+    }
+}
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift
index 64dbb1f88d5..e4f9ea5c429 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebar.swift
@@ -9,6 +9,12 @@ struct ChatSessionSidebar: View {
     @State private var sessionPendingDeletion: OpenClawChatSessionEntry?
     @State private var sessionPendingRename: OpenClawChatSessionEntry?
     @State private var renameText = ""
+    @State private var groups: [OpenClawChatSessionGroup] = []
+    @State private var groupRefreshNonce = 0
+    @State private var groupLoadFailed = false
+    @State private var inspectedSession: OpenClawChatSessionEntry?
+    @State private var isPresentingNewSessionOptions = false
+    @AppStorage("openclaw.chat.collapsedSessionGroups") private var collapsedSessionGroups = ""
 
     var body: some View {
         let sections = ChatSessionSidebarModel.sections(
@@ -16,11 +22,36 @@ struct ChatSessionSidebar: View {
             currentSessionKey: self.viewModel.sessionKey,
             mainSessionKey: self.viewModel.resolvedMainSessionKey,
             activeAgentID: self.viewModel.activeAgentId,
+            groups: self.groups,
             query: self.query)
         List(selection: self.selectionBinding) {
             ForEach(sections) { section in
-                if let title = section.title {
-                    Section(title) { self.rows(section.nodes) }
+                if section.id.hasPrefix("group:"), let title = section.title {
+                    Section {
+                        if !self.isGroupCollapsed(title) || !self.query
+                            .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+                        {
+                            self.rows(section.nodes)
+                        }
+                    } header: {
+                        Button {
+                            self.toggleGroupCollapsed(title)
+                        } label: {
+                            HStack {
+                                Image(systemName: self.isGroupCollapsed(title) ? "chevron.right" : "chevron.down")
+                                Text(verbatim: title)
+                                    .font(OpenClawChatTypography.caption)
+                            }
+                        }
+                        .buttonStyle(.plain)
+                    }
+                } else if let title = section.title {
+                    Section {
+                        self.rows(section.nodes)
+                    } header: {
+                        Text(LocalizedStringKey(title))
+                            .font(OpenClawChatTypography.caption)
+                    }
                 } else {
                     self.rows(section.nodes)
                 }
@@ -43,20 +74,45 @@ struct ChatSessionSidebar: View {
         .safeAreaInset(edge: .bottom, spacing: 0) { self.connectionFooter }
         .toolbar {
             ToolbarItem {
-                Button {
-                    Task { await self.viewModel.startNewSession() }
-                } label: {
-                    chatWindowActionLabel("New Session", systemImage: "square.and.pencil")
+                HStack(spacing: 2) {
+                    Button {
+                        Task { await self.viewModel.startNewSession() }
+                    } label: {
+                        chatWindowActionLabel("New Session", systemImage: "square.and.pencil")
+                    }
+                    .help(String(localized: "New session"))
+                    Button {
+                        self.isPresentingNewSessionOptions = true
+                    } label: {
+                        Image(systemName: "chevron.down")
+                    }
+                    .help(String(localized: "New session options"))
+                    .popover(isPresented: self.$isPresentingNewSessionOptions) {
+                        ChatNewSessionOptionsPopover(viewModel: self.viewModel) {
+                            self.isPresentingNewSessionOptions = false
+                        }
+                    }
                 }
-                .help(String(localized: "New session"))
             }
         }
-        .task { self.viewModel.refreshSessions(limit: 200) }
+        .task(id: self.groupRefreshID) {
+            self.viewModel.refreshSessions(limit: 200)
+            do {
+                let groups = try await self.viewModel.fetchSessionGroups()
+                self.groups = groups
+                self.groupLoadFailed = false
+            } catch {
+                self.groupLoadFailed = true
+            }
+        }
         .onChange(of: self.viewModel.healthOK) { previous, current in
             if !previous, current {
                 self.viewModel.refreshSessions(limit: 200)
             }
         }
+        .sheet(item: self.$inspectedSession) { session in
+            ChatSessionInspectorSheet(viewModel: self.viewModel, session: session)
+        }
         .alert(
             String(localized: "Rename Session"),
             isPresented: self.isPresentingRenameAlert)
@@ -100,6 +156,12 @@ struct ChatSessionSidebar: View {
             })
     }
 
+    private var groupRefreshID: String {
+        let categories = self.viewModel.sessions.compactMap(\.category).sorted().joined(separator: "|")
+        let revision = self.viewModel.sessionGroupsRevision
+        return "\(self.viewModel.healthOK)|\(categories)|\(revision)|\(self.groupRefreshNonce)"
+    }
+
     private var deleteDialogTitle: String {
         let name = self.sessionPendingDeletion.map(ChatSessionSidebarModel.displayName(for:)) ?? ""
         return String(format: String(localized: "Delete “%@”?"), name)
@@ -170,6 +232,12 @@ struct ChatSessionSidebar: View {
 
     @ViewBuilder
     private func contextMenu(for session: OpenClawChatSessionEntry) -> some View {
+        Button {
+            self.inspectedSession = session
+        } label: {
+            self.actionLabel(String(localized: "Get Info…"), systemImage: "info.circle")
+        }
+        Divider()
         Button {
             self.renameText = session.label ?? session.displayName ?? ""
             self.sessionPendingRename = session
@@ -226,6 +294,18 @@ struct ChatSessionSidebar: View {
         }
     }
 
+    private func isGroupCollapsed(_ name: String) -> Bool {
+        Set(self.collapsedSessionGroups.split(separator: "\u{1F}").map(String.init)).contains(name)
+    }
+
+    private func toggleGroupCollapsed(_ name: String) {
+        var names = Set(self.collapsedSessionGroups.split(separator: "\u{1F}").map(String.init))
+        if !names.insert(name).inserted {
+            names.remove(name)
+        }
+        self.collapsedSessionGroups = names.sorted().joined(separator: "\u{1F}")
+    }
+
     private func actionLabel(_ title: String, systemImage: String) -> some View {
         Label(title, systemImage: systemImage)
             .font(OpenClawChatTypography.body(size: 13, weight: .regular, relativeTo: .body))
@@ -256,6 +336,15 @@ struct ChatSessionSidebar: View {
                 .font(OpenClawChatTypography.caption)
                 .foregroundStyle(.secondary)
             Spacer(minLength: 0)
+            if self.groupLoadFailed {
+                Button {
+                    self.groupRefreshNonce += 1
+                } label: {
+                    Image(systemName: "arrow.clockwise")
+                }
+                .buttonStyle(.borderless)
+                .help(String(localized: "Retry session groups"))
+            }
         }
         .padding(.horizontal, 12)
         .padding(.vertical, 8)
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift
index 5b2a5f13dff..6d546ebe3e7 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessionSidebarModel.swift
@@ -49,6 +49,7 @@ enum ChatSessionSidebarModel {
         currentSessionKey: String,
         mainSessionKey: String = "main",
         activeAgentID: String? = nil,
+        groups: [OpenClawChatSessionGroup] = [],
         query: String) -> [Section]
     {
         let visible = self.visibleSessions(
@@ -57,19 +58,33 @@ enum ChatSessionSidebarModel {
             mainSessionKey: mainSessionKey,
             activeAgentID: activeAgentID,
             query: query)
-        // Pin state owns section placement. Cross-section parent links become
-        // roots so a child's own Pin/Unpin action always has visible effect.
+        // Pin state owns first placement. Group sections then preserve the
+        // same tree builder, so grouped parent/child rosters still nest.
         let pinned = self.tree(from: visible.filter { $0.pinned == true })
-        let recent = self.tree(from: visible.filter { $0.pinned != true })
+        let unpinned = visible.filter { $0.pinned != true }
+        let orderedGroups = groups.sorted { lhs, rhs in
+            lhs.position == rhs.position ? lhs.name < rhs.name : lhs.position < rhs.position
+        }
+        let groupNames = Set(orderedGroups.map(\.name))
+        let recent = self.tree(from: unpinned.filter { session in
+            guard let category = session.category else { return true }
+            return !groupNames.contains(category)
+        })
 
         var result: [Section] = []
         if !pinned.isEmpty {
             result.append(Section(id: "pinned", title: "Pinned", nodes: pinned))
         }
+        for group in orderedGroups {
+            let nodes = self.tree(from: unpinned.filter { $0.category == group.name })
+            if !nodes.isEmpty {
+                result.append(Section(id: "group:\(group.name)", title: group.name, nodes: nodes))
+            }
+        }
         if !recent.isEmpty {
             result.append(Section(
                 id: "recent",
-                title: pinned.isEmpty ? nil : "Recent",
+                title: result.isEmpty ? nil : "Recent",
                 nodes: recent))
         }
         return result
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift
index d762dbc3065..e0df42f87ec 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift
@@ -242,6 +242,74 @@ public struct OpenClawChatSessionWorktree: Codable, Sendable, Hashable {
     public let repoRoot: String?
 }
 
+public struct OpenClawChatAgentRuntime: Codable, Sendable, Hashable {
+    public let id: String
+    public let fallback: String?
+    public let source: String?
+}
+
+public struct OpenClawChatSessionGroup: Codable, Identifiable, Sendable, Hashable {
+    public var id: String {
+        self.name
+    }
+
+    public let name: String
+    public let position: Int
+
+    public init(name: String, position: Int) {
+        self.name = name
+        self.position = position
+    }
+}
+
+public struct OpenClawChatSessionGroupsResponse: Codable, Sendable, Equatable {
+    public let groups: [OpenClawChatSessionGroup]
+
+    public init(groups: [OpenClawChatSessionGroup]) {
+        self.groups = groups
+    }
+}
+
+public struct OpenClawChatSessionGroupsMutationResponse: Codable, Sendable, Equatable {
+    public let ok: Bool
+    public let groups: [OpenClawChatSessionGroup]
+    public let updatedSessions: Int?
+
+    public init(ok: Bool, groups: [OpenClawChatSessionGroup], updatedSessions: Int? = nil) {
+        self.ok = ok
+        self.groups = groups
+        self.updatedSessions = updatedSessions
+    }
+}
+
+public struct OpenClawChatAgentChoice: Codable, Identifiable, Sendable, Hashable {
+    public let id: String
+    public let name: String?
+    public let workspaceGit: Bool?
+
+    public init(id: String, name: String? = nil, workspaceGit: Bool? = nil) {
+        self.id = id
+        self.name = name
+        self.workspaceGit = workspaceGit
+    }
+
+    public var displayName: String {
+        let normalized = self.name?.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let normalized, !normalized.isEmpty else { return self.id }
+        return normalized
+    }
+}
+
+public struct OpenClawChatAgentsListResponse: Codable, Sendable, Equatable {
+    public let defaultId: String
+    public let agents: [OpenClawChatAgentChoice]
+
+    public init(defaultId: String, agents: [OpenClawChatAgentChoice]) {
+        self.defaultId = defaultId
+        self.agents = agents
+    }
+}
+
 public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashable {
     public var id: String {
         self.key
@@ -274,6 +342,10 @@ public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashabl
     public var hasActiveRun: Bool?
     public var hasActiveSubagentRun: Bool?
     public var worktree: OpenClawChatSessionWorktree?
+    public var startedAt: Double?
+    public var endedAt: Double?
+    public var runtimeMs: Double?
+    public var agentRuntime: OpenClawChatAgentRuntime?
 
     public var systemSent: Bool?
     public var abortedLastRun: Bool?
@@ -336,7 +408,11 @@ public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashabl
         hasActiveSubagentRun: Bool? = nil,
         worktree: OpenClawChatSessionWorktree? = nil,
         fastMode: OpenClawChatFastMode? = nil,
-        effectiveFastMode: OpenClawChatFastMode? = nil)
+        effectiveFastMode: OpenClawChatFastMode? = nil,
+        startedAt: Double? = nil,
+        endedAt: Double? = nil,
+        runtimeMs: Double? = nil,
+        agentRuntime: OpenClawChatAgentRuntime? = nil)
     {
         self.key = key
         self.kind = kind
@@ -364,6 +440,10 @@ public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashabl
         self.hasActiveRun = hasActiveRun
         self.hasActiveSubagentRun = hasActiveSubagentRun
         self.worktree = worktree
+        self.startedAt = startedAt
+        self.endedAt = endedAt
+        self.runtimeMs = runtimeMs
+        self.agentRuntime = agentRuntime
         self.systemSent = systemSent
         self.abortedLastRun = abortedLastRun
         self.thinkingLevel = thinkingLevel
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift
index 468d5c34180..bf0885d9671 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift
@@ -27,6 +27,13 @@ struct ChatSessionsSheet: View {
     @State private var isLoadingScoped = false
     @State private var renameTarget: OpenClawChatSessionEntry?
     @State private var renameText = ""
+    @State private var isSelecting = false
+    @State private var selectedSessionKeys: Set<String> = []
+    @State private var batchErrors: [String: String] = [:]
+    @State private var isRunningBatch = false
+    @State private var pendingBatchAction: ChatSessionBatchAction?
+    @State private var inspectedSession: OpenClawChatSessionEntry?
+    @State private var isPresentingGroups = false
 
     /// Live view-model sessions serve the default active list; search and the
     /// archived scope fetch one-shot lists (server-side search with local
@@ -43,13 +50,17 @@ struct ChatSessionsSheet: View {
         self.usesScopedFetch ? self.scopedSessions : self.viewModel.sessions
     }
 
+    private var displayedSessionKeys: [String] {
+        self.displayedSessions.map(\.key)
+    }
+
     private var scopedFetchID: String {
         "\(self.scope.rawValue)|\(self.trimmedSearchText.lowercased())"
     }
 
     var body: some View {
         NavigationStack {
-            List {
+            List(selection: self.$selectedSessionKeys) {
                 Section {
                     ForEach(self.displayedSessions) { session in
                         self.sessionRow(session)
@@ -76,11 +87,22 @@ struct ChatSessionsSheet: View {
             }
             .searchable(text: self.$searchText, prompt: "Search sessions")
             .navigationTitle("Sessions")
+            .safeAreaInset(edge: .bottom, spacing: 0) {
+                if self.isSelecting, self.scope == .active {
+                    self.batchActionBar
+                }
+            }
             .toolbar {
                 #if os(macOS)
                 ToolbarItem(placement: .automatic) {
                     self.refreshButton
                 }
+                ToolbarItem(placement: .automatic) {
+                    self.groupsButton
+                }
+                ToolbarItem(placement: .automatic) {
+                    if self.scope == .active { self.selectButton }
+                }
                 ToolbarItem(placement: .primaryAction) {
                     self.closeButton
                 }
@@ -88,6 +110,12 @@ struct ChatSessionsSheet: View {
                 ToolbarItem(placement: .topBarLeading) {
                     self.refreshButton
                 }
+                ToolbarItem(placement: .topBarLeading) {
+                    self.groupsButton
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    if self.scope == .active { self.selectButton }
+                }
                 ToolbarItem(placement: .topBarTrailing) {
                     self.closeButton
                 }
@@ -99,6 +127,21 @@ struct ChatSessionsSheet: View {
             .onAppear {
                 self.viewModel.refreshSessions(limit: OpenClawChatViewModel.sessionListFetchLimit)
             }
+            .onChange(of: self.scope) {
+                self.isSelecting = false
+                self.selectedSessionKeys = []
+                self.batchErrors = [:]
+            }
+            .onChange(of: self.scopedFetchID) {
+                // A changed query must not retain destructive targets hidden by
+                // the new result set.
+                self.selectedSessionKeys = []
+                self.batchErrors = [:]
+            }
+            .onChange(of: self.displayedSessionKeys) {
+                self.selectedSessionKeys.formIntersection(self.displayedSessionKeys)
+                self.batchErrors = self.batchErrors.filter { self.displayedSessionKeys.contains($0.key) }
+            }
             .alert(
                 "Rename Session",
                 isPresented: Binding(
@@ -125,7 +168,27 @@ struct ChatSessionsSheet: View {
                         .font(OpenClawChatTypography.body)
                 }
             }
+            .sheet(isPresented: self.$isPresentingGroups) {
+                ChatSessionGroupsSheet(viewModel: self.viewModel)
+            }
+            .sheet(item: self.$inspectedSession) { session in
+                ChatSessionInspectorSheet(viewModel: self.viewModel, session: session)
+            }
+            .confirmationDialog(
+                "Delete selected sessions?",
+                isPresented: Binding(
+                    get: { self.pendingBatchAction == .delete },
+                    set: { if !$0 { self.pendingBatchAction = nil } }))
+            {
+                Button("Delete Sessions", role: .destructive) {
+                    Task { await self.runBatch(.delete) }
+                }
+            } message: {
+                Text("Each selected session and its transcript will be removed from the gateway.")
+                    .font(OpenClawChatTypography.body)
+            }
         }
+        .modifier(ChatSessionSelectionModeModifier(isSelecting: self.isSelecting && self.scope == .active))
     }
 
     private var refreshButton: some View {
@@ -145,6 +208,31 @@ struct ChatSessionsSheet: View {
         }
     }
 
+    private var groupsButton: some View {
+        Button {
+            self.isPresentingGroups = true
+        } label: {
+            Label {
+                Text("Groups")
+                    .font(OpenClawChatTypography.body)
+            } icon: {
+                Image(systemName: "folder")
+            }
+        }
+        .help("Manage session groups")
+    }
+
+    private var selectButton: some View {
+        Button(self.isSelecting ? "Done" : "Select") {
+            self.isSelecting.toggle()
+            if !self.isSelecting {
+                self.selectedSessionKeys = []
+                self.batchErrors = [:]
+            }
+        }
+        .font(OpenClawChatTypography.body)
+    }
+
     private var emptyState: some View {
         VStack(spacing: 6) {
             if self.isLoadingScoped {
@@ -157,7 +245,17 @@ struct ChatSessionsSheet: View {
         }
     }
 
+    @ViewBuilder
     private func sessionRow(_ session: OpenClawChatSessionEntry) -> some View {
+        if self.isSelecting, self.scope == .active {
+            self.sessionRowContent(session)
+                .tag(session.key)
+        } else {
+            self.interactiveSessionRow(session)
+        }
+    }
+
+    private func interactiveSessionRow(_ session: OpenClawChatSessionEntry) -> some View {
         let archiveActionTitle = LocalizedStringKey(session.isArchived
             ? String(localized: "Restore")
             : String(localized: "Archive"))
@@ -175,106 +273,152 @@ struct ChatSessionsSheet: View {
                 self.viewModel.switchSession(to: session.key)
                 self.dismiss()
             }
-        } label: {
-            HStack(spacing: 8) {
-                VStack(alignment: .leading, spacing: 4) {
-                    Text(session.displayName ?? session.key)
-                        .font(OpenClawChatTypography.mono(size: 17, relativeTo: .body))
-                        .lineLimit(1)
-                    if let updatedAt = session.updatedAt, updatedAt > 0 {
-                        Text(Date(timeIntervalSince1970: updatedAt / 1000).formatted(
-                            date: .abbreviated,
-                            time: .shortened))
-                            .font(OpenClawChatTypography.caption)
-                            .foregroundStyle(.secondary)
+        } label: { self.sessionRowContent(session) }
+            .swipeActions(edge: .leading, allowsFullSwipe: true) {
+                if !session.isArchived {
+                    Button {
+                        self.viewModel.setSessionPinned(key: session.key, pinned: !session.isPinned)
+                        self.refreshScopedSessionsSoon()
+                    } label: {
+                        self.actionLabel(
+                            session.isPinned ? "Unpin" : "Pin",
+                            systemImage: session.isPinned ? "pin.slash" : "pin")
                     }
+                    .tint(OpenClawChatTheme.accent)
                 }
-                Spacer(minLength: 0)
-                if session.isPinned {
-                    Image(systemName: "pin.fill")
-                        .font(.system(size: 12))
-                        .foregroundStyle(.secondary)
-                        .accessibilityLabel("Pinned")
+            }
+            .swipeActions(edge: .trailing, allowsFullSwipe: false) {
+                if session.isArchived || ChatSessionSidebarModel.canArchiveSession(
+                    session,
+                    mainSessionKey: self.viewModel.resolvedMainSessionKey)
+                {
+                    Button {
+                        self.viewModel.setSessionArchived(key: session.key, archived: !session.isArchived)
+                        self.refreshScopedSessionsSoon()
+                    } label: {
+                        self.actionLabel(
+                            archiveActionTitle,
+                            systemImage: session.isArchived ? "tray.and.arrow.up" : "archivebox")
+                    }
+                    .tint(session.isArchived ? OpenClawChatTheme.accent : OpenClawChatTheme.danger)
                 }
             }
-        }
-        .swipeActions(edge: .leading, allowsFullSwipe: true) {
-            if !session.isArchived {
+            .contextMenu {
                 Button {
-                    self.viewModel.setSessionPinned(key: session.key, pinned: !session.isPinned)
-                    self.refreshScopedSessionsSoon()
+                    self.inspectedSession = session
                 } label: {
-                    self.actionLabel(
-                        session.isPinned ? "Unpin" : "Pin",
-                        systemImage: session.isPinned ? "pin.slash" : "pin")
+                    self.actionLabel("Get Info…", systemImage: "info.circle")
                 }
-                .tint(OpenClawChatTheme.accent)
-            }
-        }
-        .swipeActions(edge: .trailing, allowsFullSwipe: false) {
-            if session.isArchived || ChatSessionSidebarModel.canArchiveSession(
-                session,
-                mainSessionKey: self.viewModel.resolvedMainSessionKey)
-            {
+                Divider()
                 Button {
-                    self.viewModel.setSessionArchived(key: session.key, archived: !session.isArchived)
-                    self.refreshScopedSessionsSoon()
+                    self.renameText = session.displayName ?? ""
+                    self.renameTarget = session
                 } label: {
-                    self.actionLabel(
-                        archiveActionTitle,
-                        systemImage: session.isArchived ? "tray.and.arrow.up" : "archivebox")
+                    self.actionLabel("Rename", systemImage: "pencil")
+                }
+                if !session.isArchived {
+                    Button {
+                        self.viewModel.setSessionPinned(key: session.key, pinned: !session.isPinned)
+                        self.refreshScopedSessionsSoon()
+                    } label: {
+                        self.actionLabel(
+                            session.isPinned ? "Unpin" : "Pin",
+                            systemImage: session.isPinned ? "pin.slash" : "pin")
+                    }
+                }
+                if session.isArchived || ChatSessionSidebarModel.canArchiveSession(
+                    session,
+                    mainSessionKey: self.viewModel.resolvedMainSessionKey)
+                {
+                    Button {
+                        self.viewModel.setSessionArchived(key: session.key, archived: !session.isArchived)
+                        self.refreshScopedSessionsSoon()
+                    } label: {
+                        self.actionLabel(
+                            archiveActionTitle,
+                            systemImage: session.isArchived ? "tray.and.arrow.up" : "archivebox")
+                    }
                 }
-                .tint(session.isArchived ? OpenClawChatTheme.accent : OpenClawChatTheme.danger)
-            }
-        }
-        .contextMenu {
-            Button {
-                self.renameText = session.displayName ?? ""
-                self.renameTarget = session
-            } label: {
-                self.actionLabel("Rename", systemImage: "pencil")
-            }
-            if !session.isArchived {
                 Button {
-                    self.viewModel.setSessionPinned(key: session.key, pinned: !session.isPinned)
-                    self.refreshScopedSessionsSoon()
+                    Task { await self.viewModel.forkSession(key: session.key) }
                 } label: {
                     self.actionLabel(
-                        session.isPinned ? "Unpin" : "Pin",
-                        systemImage: session.isPinned ? "pin.slash" : "pin")
+                        LocalizedStringKey(String(localized: "Fork")),
+                        systemImage: "arrow.triangle.branch")
                 }
-            }
-            if session.isArchived || ChatSessionSidebarModel.canArchiveSession(
-                session,
-                mainSessionKey: self.viewModel.resolvedMainSessionKey)
-            {
                 Button {
-                    self.viewModel.setSessionArchived(key: session.key, archived: !session.isArchived)
+                    self.viewModel.setSessionUnread(key: session.key, unread: session.unread != true)
                     self.refreshScopedSessionsSoon()
                 } label: {
                     self.actionLabel(
-                        archiveActionTitle,
-                        systemImage: session.isArchived ? "tray.and.arrow.up" : "archivebox")
+                        LocalizedStringKey(session.unread == true
+                            ? String(localized: "Mark Read")
+                            : String(localized: "Mark Unread")),
+                        systemImage: session.unread == true ? "envelope.open" : "envelope.badge")
+                }
+            }
+    }
+
+    private func sessionRowContent(_ session: OpenClawChatSessionEntry) -> some View {
+        HStack(spacing: 8) {
+            VStack(alignment: .leading, spacing: 4) {
+                Text(session.displayName ?? session.key)
+                    .font(OpenClawChatTypography.mono(size: 17, relativeTo: .body))
+                    .lineLimit(1)
+                if let updatedAt = session.updatedAt, updatedAt > 0 {
+                    Text(Date(timeIntervalSince1970: updatedAt / 1000).formatted(
+                        date: .abbreviated,
+                        time: .shortened))
+                        .font(OpenClawChatTypography.caption)
+                        .foregroundStyle(.secondary)
+                }
+                if let error = self.batchErrors[session.key] {
+                    Text(error)
+                        .font(OpenClawChatTypography.caption)
+                        .foregroundStyle(OpenClawChatTheme.danger)
+                        .lineLimit(2)
                 }
             }
-            Button {
-                Task { await self.viewModel.forkSession(key: session.key) }
-            } label: {
-                self.actionLabel(
-                    LocalizedStringKey(String(localized: "Fork")),
-                    systemImage: "arrow.triangle.branch")
+            Spacer(minLength: 0)
+            if session.isPinned {
+                Image(systemName: "pin.fill")
+                    .font(.system(size: 12))
+                    .foregroundStyle(.secondary)
+                    .accessibilityLabel("Pinned")
             }
-            Button {
-                self.viewModel.setSessionUnread(key: session.key, unread: session.unread != true)
-                self.refreshScopedSessionsSoon()
-            } label: {
-                self.actionLabel(
-                    LocalizedStringKey(session.unread == true
-                        ? String(localized: "Mark Read")
-                        : String(localized: "Mark Unread")),
-                    systemImage: session.unread == true ? "envelope.open" : "envelope.badge")
+        }
+    }
+
+    private var batchActionBar: some View {
+        HStack(spacing: 12) {
+            Button("Pin") { Task { await self.runBatch(.pin) } }
+            Button("Unpin") { Task { await self.runBatch(.unpin) } }
+            Button("Archive") { Task { await self.runBatch(.archive) } }
+            Spacer()
+            Button("Delete", role: .destructive) {
+                self.pendingBatchAction = .delete
             }
         }
+        .font(OpenClawChatTypography.body)
+        .buttonStyle(.borderless)
+        .disabled(self.selectedSessionKeys.isEmpty || self.isRunningBatch)
+        .padding(.horizontal, 16)
+        .padding(.vertical, 10)
+        .background(.bar)
+    }
+
+    private func runBatch(_ action: ChatSessionBatchAction) async {
+        self.pendingBatchAction = nil
+        guard !self.selectedSessionKeys.isEmpty else { return }
+        self.isRunningBatch = true
+        defer { self.isRunningBatch = false }
+        let selectedSessions = self.displayedSessions.filter { self.selectedSessionKeys.contains($0.key) }
+        let result = await self.viewModel.performSessionBatch(
+            sessions: selectedSessions,
+            action: action)
+        self.batchErrors = result.errorsByKey
+        self.selectedSessionKeys = Set(result.errorsByKey.keys)
+        self.refreshScopedSessionsSoon()
     }
 
     private func actionLabel(_ title: LocalizedStringKey, systemImage: String) -> some View {
@@ -316,3 +460,15 @@ struct ChatSessionsSheet: View {
         }
     }
 }
+
+private struct ChatSessionSelectionModeModifier: ViewModifier {
+    let isSelecting: Bool
+
+    func body(content: Content) -> some View {
+        #if os(macOS)
+        content
+        #else
+        content.environment(\.editMode, .constant(self.isSelecting ? .active : .inactive))
+        #endif
+    }
+}
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift
index ac5e2d716ef..4423da271f2 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift
@@ -151,11 +151,17 @@ public struct OpenClawChatSessionMutationRouteLease: Sendable {
         _ pinned: Bool?,
         _ archived: Bool?,
         _ unread: Bool?) async throws -> Void
+    public typealias DeleteSession = @Sendable (_ key: String) async throws -> Void
 
     private let patchSessionImpl: PatchSession
+    private let deleteSessionImpl: DeleteSession?
 
-    public init(patchSession: @escaping PatchSession) {
+    public init(
+        patchSession: @escaping PatchSession,
+        deleteSession: DeleteSession? = nil)
+    {
         self.patchSessionImpl = patchSession
+        self.deleteSessionImpl = deleteSession
     }
 
     public func patchSession(
@@ -168,6 +174,101 @@ public struct OpenClawChatSessionMutationRouteLease: Sendable {
     {
         try await self.patchSessionImpl(key, label, category, pinned, archived, unread)
     }
+
+    public func deleteSession(key: String) async throws {
+        guard let deleteSessionImpl else {
+            throw OpenClawChatTransportSendError.notDispatched
+        }
+        try await deleteSessionImpl(key)
+    }
+}
+
+/// One physical gateway connection captured while a group catalog is shown.
+/// Group replacement submits the complete catalog, so list and mutations must
+/// never retarget independently when the selected gateway changes.
+public struct OpenClawChatSessionGroupsRouteLease: Sendable {
+    public typealias ListGroups = @Sendable () async throws -> OpenClawChatSessionGroupsResponse?
+    public typealias PutGroups = @Sendable ([String]) async throws -> OpenClawChatSessionGroupsMutationResponse
+    public typealias RenameGroup = @Sendable (String, String) async throws -> OpenClawChatSessionGroupsMutationResponse
+    public typealias DeleteGroup = @Sendable (String) async throws -> OpenClawChatSessionGroupsMutationResponse
+
+    private let listGroupsImpl: ListGroups
+    private let putGroupsImpl: PutGroups
+    private let renameGroupImpl: RenameGroup
+    private let deleteGroupImpl: DeleteGroup
+
+    public init(
+        listGroups: @escaping ListGroups,
+        putGroups: @escaping PutGroups,
+        renameGroup: @escaping RenameGroup,
+        deleteGroup: @escaping DeleteGroup)
+    {
+        self.listGroupsImpl = listGroups
+        self.putGroupsImpl = putGroups
+        self.renameGroupImpl = renameGroup
+        self.deleteGroupImpl = deleteGroup
+    }
+
+    public func listGroups() async throws -> OpenClawChatSessionGroupsResponse? {
+        try await self.listGroupsImpl()
+    }
+
+    public func putGroups(names: [String]) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        try await self.putGroupsImpl(names)
+    }
+
+    public func renameGroup(name: String, to: String) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        try await self.renameGroupImpl(name, to)
+    }
+
+    public func deleteGroup(name: String) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        try await self.deleteGroupImpl(name)
+    }
+}
+
+/// One physical gateway connection captured while new-session options are
+/// shown. Agent capabilities and the resulting create request share the route.
+public struct OpenClawChatNewSessionRouteLease: Sendable {
+    public typealias ListAgents = @Sendable () async throws -> OpenClawChatAgentsListResponse?
+    public typealias CreateSession = @Sendable (
+        _ key: String,
+        _ label: String?,
+        _ agentID: String?,
+        _ parentSessionKey: String?,
+        _ worktree: Bool?,
+        _ worktreeBaseRef: String?) async throws -> OpenClawChatCreateSessionResponse
+
+    private let listAgentsImpl: ListAgents
+    private let createSessionImpl: CreateSession
+
+    public init(
+        listAgents: @escaping ListAgents,
+        createSession: @escaping CreateSession)
+    {
+        self.listAgentsImpl = listAgents
+        self.createSessionImpl = createSession
+    }
+
+    public func listAgents() async throws -> OpenClawChatAgentsListResponse? {
+        try await self.listAgentsImpl()
+    }
+
+    public func createSession(
+        key: String,
+        label: String?,
+        agentID: String?,
+        parentSessionKey: String?,
+        worktree: Bool?,
+        worktreeBaseRef: String?) async throws -> OpenClawChatCreateSessionResponse
+    {
+        try await self.createSessionImpl(
+            key,
+            label,
+            agentID,
+            parentSessionKey,
+            worktree,
+            worktreeBaseRef)
+    }
 }
 
 /// The transport rejected a send before it reached its request channel. This
@@ -279,6 +380,13 @@ public protocol OpenClawChatTransport: Sendable {
         label: String?,
         parentSessionKey: String?,
         worktree: Bool?) async throws -> OpenClawChatCreateSessionResponse
+    func createSession(
+        key: String,
+        label: String?,
+        agentID: String?,
+        parentSessionKey: String?,
+        worktree: Bool?,
+        worktreeBaseRef: String?) async throws -> OpenClawChatCreateSessionResponse
 
     func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload
     func requestFullMessage(sessionKey: String, messageID: String) async throws -> OpenClawChatMessage?
@@ -310,6 +418,13 @@ public protocol OpenClawChatTransport: Sendable {
         limit: Int?,
         search: String?,
         archived: Bool) async throws -> OpenClawChatSessionsListResponse
+    func listAgents() async throws -> OpenClawChatAgentsListResponse?
+    func acquireNewSessionRouteLease() async -> OpenClawChatNewSessionRouteLease?
+    func listSessionGroups() async throws -> OpenClawChatSessionGroupsResponse?
+    func putSessionGroups(names: [String]) async throws -> OpenClawChatSessionGroupsMutationResponse
+    func renameSessionGroup(name: String, to: String) async throws -> OpenClawChatSessionGroupsMutationResponse
+    func deleteSessionGroup(name: String) async throws -> OpenClawChatSessionGroupsMutationResponse
+    func acquireSessionGroupsRouteLease() async -> OpenClawChatSessionGroupsRouteLease?
     func patchSession(
         key: String,
         label: String??,
@@ -409,15 +524,43 @@ extension OpenClawChatTransport {
 
     public func acquireSessionMutationRouteLease() async -> OpenClawChatSessionMutationRouteLease? {
         let transport = self
-        return OpenClawChatSessionMutationRouteLease { key, label, category, pinned, archived, unread in
-            try await transport.patchSession(
-                key: key,
-                label: label,
-                category: category,
-                pinned: pinned,
-                archived: archived,
-                unread: unread)
-        }
+        return OpenClawChatSessionMutationRouteLease(
+            patchSession: { key, label, category, pinned, archived, unread in
+                try await transport.patchSession(
+                    key: key,
+                    label: label,
+                    category: category,
+                    pinned: pinned,
+                    archived: archived,
+                    unread: unread)
+            },
+            deleteSession: { key in
+                try await transport.deleteSession(key: key)
+            })
+    }
+
+    public func acquireSessionGroupsRouteLease() async -> OpenClawChatSessionGroupsRouteLease? {
+        let transport = self
+        return OpenClawChatSessionGroupsRouteLease(
+            listGroups: { try await transport.listSessionGroups() },
+            putGroups: { try await transport.putSessionGroups(names: $0) },
+            renameGroup: { try await transport.renameSessionGroup(name: $0, to: $1) },
+            deleteGroup: { try await transport.deleteSessionGroup(name: $0) })
+    }
+
+    public func acquireNewSessionRouteLease() async -> OpenClawChatNewSessionRouteLease? {
+        let transport = self
+        return OpenClawChatNewSessionRouteLease(
+            listAgents: { try await transport.listAgents() },
+            createSession: { key, label, agentID, parentSessionKey, worktree, worktreeBaseRef in
+                try await transport.createSession(
+                    key: key,
+                    label: label,
+                    agentID: agentID,
+                    parentSessionKey: parentSessionKey,
+                    worktree: worktree,
+                    worktreeBaseRef: worktreeBaseRef)
+            })
     }
 
     public func sendMessage(
@@ -449,6 +592,32 @@ extension OpenClawChatTransport {
             userInfo: [NSLocalizedDescriptionKey: "sessions.create not supported by this transport"])
     }
 
+    public func createSession(
+        key: String,
+        label: String?,
+        agentID: String?,
+        parentSessionKey: String?,
+        worktree: Bool?,
+        worktreeBaseRef: String?) async throws -> OpenClawChatCreateSessionResponse
+    {
+        // Fail closed: a transport on this default cannot honor agent/base-ref
+        // selection; delegating would report success while creating the wrong session.
+        guard agentID == nil, worktreeBaseRef == nil else {
+            throw NSError(
+                domain: "OpenClawChatTransport",
+                code: 0,
+                userInfo: [
+                    NSLocalizedDescriptionKey:
+                        "sessions.create agent/base-ref options not supported by this transport",
+                ])
+        }
+        return try await self.createSession(
+            key: key,
+            label: label,
+            parentSessionKey: parentSessionKey,
+            worktree: worktree)
+    }
+
     public func setActiveSessionKey(_: String) async throws {}
 
     public func waitForRunCompletion(runId _: String, timeoutMs _: Int) async -> OpenClawChatRunObservation {
@@ -499,6 +668,38 @@ extension OpenClawChatTransport {
         try await self.listSessions(limit: limit, search: nil, archived: archived)
     }
 
+    public func listAgents() async throws -> OpenClawChatAgentsListResponse? {
+        nil
+    }
+
+    public func listSessionGroups() async throws -> OpenClawChatSessionGroupsResponse? {
+        nil
+    }
+
+    public func putSessionGroups(names _: [String]) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.groups.put not supported by this transport"])
+    }
+
+    public func renameSessionGroup(
+        name _: String,
+        to _: String) async throws -> OpenClawChatSessionGroupsMutationResponse
+    {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.groups.rename not supported by this transport"])
+    }
+
+    public func deleteSessionGroup(name _: String) async throws -> OpenClawChatSessionGroupsMutationResponse {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.groups.delete not supported by this transport"])
+    }
+
     public func patchSession(
         key _: String,
         label _: String?? = nil,
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift
index 2fcb3839a13..b736e756d3c 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionActions.swift
@@ -11,8 +11,290 @@ extension OpenClawChatViewModel {
         Task { await self.fetchSessions(limit: limit, sessionSnapshot: context) }
     }
 
-    public func startNewSession(worktree: Bool = false) async {
-        await self.performStartNewSession(worktree: worktree)
+    /// Returns true only when a session switch happened (create or reset
+    /// fallback); callers keep UI like the new-session popover open on failure.
+    @discardableResult
+    func performStartNewSession(
+        agentID: String? = nil,
+        worktree: Bool,
+        worktreeBaseRef: String? = nil,
+        routeLease: OpenClawChatNewSessionRouteLease? = nil) async -> Bool
+    {
+        guard !self.blocksAttachmentOwnerChange else {
+            self.errorText = String(
+                localized: "Remove attachments or wait for delivery to resolve before starting a new chat.")
+            return false
+        }
+        let normalizedAgentID = agentID?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+        let requestedAgentID = normalizedAgentID?.isEmpty == false ? normalizedAgentID : nil
+        let requested = self.generatedNewSessionKey(agentID: requestedAgentID)
+        // Only authoritative identities decide agent ownership; scanning the roster
+        // could adopt an unrelated agent and hand sessions.create a cross-agent parent.
+        let currentAgentID = (
+            OpenClawChatSessionKey.agentID(from: self.sessionKey) ??
+                self.activeAgentId ??
+                OpenClawChatSessionKey.agentID(from: self.resolvedMainSessionKey))?
+            .lowercased()
+        let parentSessionKey = requestedAgentID == nil || requestedAgentID == currentAgentID
+            ? self.sessionKey
+            : nil
+        let next: String
+        do {
+            let created = if let routeLease {
+                try await routeLease.createSession(
+                    key: requested,
+                    label: nil,
+                    agentID: requestedAgentID,
+                    parentSessionKey: parentSessionKey,
+                    worktree: worktree ? true : nil,
+                    worktreeBaseRef: worktree ? worktreeBaseRef : nil)
+            } else {
+                try await self.transport.createSession(
+                    key: requested,
+                    label: nil,
+                    agentID: requestedAgentID,
+                    parentSessionKey: parentSessionKey,
+                    worktree: worktree ? true : nil,
+                    worktreeBaseRef: worktree ? worktreeBaseRef : nil)
+            }
+            let createdKey = created.key.trimmingCharacters(in: .whitespacesAndNewlines)
+            next = createdKey.isEmpty ? requested : createdKey
+        } catch {
+            if Self.isUnsupportedCreateSessionError(error) {
+                // Reset only mimics a plain new chat; agent/worktree selections were
+                // not honored, so advanced requests surface the error instead of
+                // silently resetting the current session.
+                guard requestedAgentID == nil, !worktree else {
+                    chatUILogger.error("sessions.create unsupported; advanced options not honored")
+                    self.errorText = error.localizedDescription
+                    return false
+                }
+                chatUILogger.info("sessions.create unsupported; falling back to sessions.reset")
+                await self.performReset()
+                return true
+            }
+            chatUILogger.error("sessions.create failed \(error.localizedDescription, privacy: .public)")
+            self.errorText = error.localizedDescription
+            return false
+        }
+        guard !self.blocksAttachmentOwnerChange else {
+            self.errorText = String(
+                localized: "Remove attachments or wait for delivery to resolve before starting a new chat.")
+            return false
+        }
+        self.adoptCreatedSession(next)
+        return true
+    }
+
+    static func isUnsupportedCreateSessionError(_ error: Error) -> Bool {
+        let nsError = error as NSError
+        return nsError.domain == "OpenClawChatTransport"
+            && nsError.localizedDescription == "sessions.create not supported by this transport"
+    }
+
+    @discardableResult
+    public func startNewSession(
+        agentID: String? = nil,
+        worktree: Bool = false,
+        worktreeBaseRef: String? = nil) async -> Bool
+    {
+        await self.performStartNewSession(
+            agentID: agentID,
+            worktree: worktree,
+            worktreeBaseRef: worktreeBaseRef)
+    }
+
+    @discardableResult
+    func startNewSession(
+        agentID: String,
+        worktree: Bool,
+        worktreeBaseRef: String?,
+        using routeLease: OpenClawChatNewSessionRouteLease) async -> Bool
+    {
+        await self.performStartNewSession(
+            agentID: agentID,
+            worktree: worktree,
+            worktreeBaseRef: worktreeBaseRef,
+            routeLease: routeLease)
+    }
+
+    func newSessionRouteLease() async throws -> OpenClawChatNewSessionRouteLease {
+        guard let routeLease = await self.transport.acquireNewSessionRouteLease() else {
+            throw OpenClawChatTransportSendError.notDispatched
+        }
+        return routeLease
+    }
+
+    public func fetchSessionGroups() async throws -> [OpenClawChatSessionGroup] {
+        let routeLease = try await self.sessionGroupsRouteLease()
+        return try await self.fetchSessionGroups(using: routeLease)
+    }
+
+    func sessionGroupsRouteLease() async throws -> OpenClawChatSessionGroupsRouteLease {
+        guard let routeLease = await self.transport.acquireSessionGroupsRouteLease() else {
+            throw OpenClawChatTransportSendError.notDispatched
+        }
+        return routeLease
+    }
+
+    func fetchSessionGroups(
+        using routeLease: OpenClawChatSessionGroupsRouteLease) async throws -> [OpenClawChatSessionGroup]
+    {
+        let response = try await routeLease.listGroups()
+        return (response?.groups ?? []).sorted { lhs, rhs in
+            lhs.position == rhs.position ? lhs.name < rhs.name : lhs.position < rhs.position
+        }
+    }
+
+    @discardableResult
+    func createSessionGroup(
+        named rawName: String,
+        using routeLease: OpenClawChatSessionGroupsRouteLease) async throws -> [OpenClawChatSessionGroup]
+    {
+        let name = rawName.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !name.isEmpty else { return try await self.fetchSessionGroups(using: routeLease) }
+        // Read-modify-write matches web group creation (app-sidebar-session-groups,
+        // custom-groups); the gateway has no atomic add/CAS. A concurrent edit can
+        // lose catalog names/order only — session categories are untouched by
+        // sessions.groups.put, so memberships survive. Accepted tradeoff until the
+        // gateway grows a revisioned groups API.
+        let current = try await self.fetchSessionGroups(using: routeLease)
+        let response = try await routeLease.putGroups(names: current.map(\.name) + [name])
+        self.sessionGroupsRevision += 1
+        return response.groups
+    }
+
+    @discardableResult
+    func renameSessionGroup(
+        _ name: String,
+        to rawName: String,
+        using routeLease: OpenClawChatSessionGroupsRouteLease) async throws -> [OpenClawChatSessionGroup]
+    {
+        let nextName = rawName.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !nextName.isEmpty else { return try await self.fetchSessionGroups(using: routeLease) }
+        let response = try await routeLease.renameGroup(name: name, to: nextName)
+        self.sessionGroupsRevision += 1
+        self.refreshSessions(limit: Self.sessionListFetchLimit)
+        return response.groups
+    }
+
+    @discardableResult
+    func deleteSessionGroup(
+        _ name: String,
+        using routeLease: OpenClawChatSessionGroupsRouteLease) async throws -> [OpenClawChatSessionGroup]
+    {
+        let response = try await routeLease.deleteGroup(name: name)
+        self.sessionGroupsRevision += 1
+        self.refreshSessions(limit: Self.sessionListFetchLimit)
+        return response.groups
+    }
+
+    public func setSessionGroup(key: String, group: String?) async throws {
+        let normalized = group?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let nextGroup = normalized?.isEmpty == false ? normalized : nil
+        let routeLease = await self.transport.acquireSessionMutationRouteLease()
+        guard let routeLease else { throw OpenClawChatTransportSendError.notDispatched }
+        try await routeLease.patchSession(
+            key: key,
+            label: nil,
+            category: .some(nextGroup),
+            pinned: nil,
+            archived: nil,
+            unread: nil)
+        if let index = self.sessions.firstIndex(where: { $0.key == key }) {
+            self.sessions[index].category = nextGroup
+        }
+        self.refreshSessions(limit: Self.sessionListFetchLimit)
+    }
+
+    func performSessionBatch(
+        sessions selectedSessions: [OpenClawChatSessionEntry],
+        action: ChatSessionBatchAction) async -> ChatSessionBatchResult
+    {
+        let orderedKeys = selectedSessions.map(\.key)
+        let entries = Dictionary(uniqueKeysWithValues: selectedSessions.map { ($0.key, $0) })
+        let mainSessionKey = self.resolvedMainSessionKey
+        let attachmentBlockedKeys = self.isAttachmentOwnerPinned
+            ? Set(selectedSessions.filter {
+                self.matchesCurrentSessionKey(incoming: $0.key, current: self.sessionKey)
+            }.map(\.key))
+            : []
+        let routeLease = await self.transport.acquireSessionMutationRouteLease()
+        guard let routeLease else {
+            return ChatSessionBatchResult(
+                succeededKeys: [],
+                errorsByKey: Dictionary(uniqueKeysWithValues: orderedKeys.map {
+                    ($0, String(localized: "Gateway changed before the session operation started."))
+                }))
+        }
+        let result = await ChatSessionBatchMutationRunner.run(keys: orderedKeys) { key in
+            if let entry = entries[key] {
+                switch action {
+                case .archive where !ChatSessionSidebarModel.canArchiveSession(
+                    entry,
+                    mainSessionKey: mainSessionKey):
+                    throw ChatSessionBatchValidationError.cannotArchive
+                case .delete where !ChatSessionSidebarModel.canDeleteSession(
+                    key: key,
+                    mainSessionKey: mainSessionKey):
+                    throw ChatSessionBatchValidationError.cannotDelete
+                case .archive where attachmentBlockedKeys.contains(key),
+                     .delete where attachmentBlockedKeys.contains(key):
+                    throw ChatSessionBatchValidationError.attachmentOwnerPinned
+                default:
+                    break
+                }
+            }
+            switch action {
+            case .pin:
+                try await routeLease.patchSession(
+                    key: key,
+                    label: nil,
+                    category: nil,
+                    pinned: true,
+                    archived: nil,
+                    unread: nil)
+            case .unpin:
+                try await routeLease.patchSession(
+                    key: key,
+                    label: nil,
+                    category: nil,
+                    pinned: false,
+                    archived: nil,
+                    unread: nil)
+            case .archive:
+                try await routeLease.patchSession(
+                    key: key,
+                    label: nil,
+                    category: nil,
+                    pinned: nil,
+                    archived: true,
+                    unread: nil)
+            case .delete:
+                try await routeLease.deleteSession(key: key)
+            }
+        }
+        let succeeded = Set(result.succeededKeys)
+        switch action {
+        case .pin, .unpin:
+            let pinned = action == .pin
+            for index in self.sessions.indices where succeeded.contains(self.sessions[index].key) {
+                self.sessions[index].pinned = pinned
+                self.sessions[index].pinnedAt = pinned ? Date().timeIntervalSince1970 * 1000 : nil
+            }
+            self.sessions = OpenClawChatSessionListOrganizer.organize(self.sessions)
+        case .archive, .delete:
+            self.sessions.removeAll { succeeded.contains($0.key) }
+            if succeeded.contains(where: {
+                self.matchesCurrentSessionKey(incoming: $0, current: self.sessionKey)
+            }) {
+                self.switchSession(to: self.resolvedMainSessionKey)
+            }
+        }
+        self.refreshSessions(limit: Self.sessionListFetchLimit)
+        return result
     }
 
     public func requestSessionReset() {
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+TransportEvents.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+TransportEvents.swift
index 65cf6899bca..df05a6d9474 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+TransportEvents.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+TransportEvents.swift
@@ -33,6 +33,16 @@ extension OpenClawChatViewModel {
             let context = self.currentSessionSnapshot()
             Task { await self.pollHealthIfNeeded(force: false, sessionSnapshot: context) }
         case let .sessionsChanged(change):
+            // Group-catalog mutations from any client arrive as reason "groups"
+            // (mirrors web ui/src/lib/sessions); bump the revision so views keyed
+            // on it refetch. Rename/delete also rewrite member sessions' category
+            // values, so refresh sessions too or inspectors keep stale placement.
+            if change.reason == "groups" {
+                self.sessionGroupsRevision += 1
+                let context = self.currentSessionSnapshot()
+                Task { await self.fetchSessions(limit: 50, sessionSnapshot: context) }
+                return
+            }
             guard change.reason == "patch" || change.reason == "command-metadata" else { return }
             let context = self.currentSessionSnapshot()
             Task { await self.fetchSessions(limit: 50, sessionSnapshot: context) }
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
index 1b099271f13..b04dabd8715 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift
@@ -3,7 +3,8 @@ import Observation
 import OpenClawKit
 import OSLog
 
-private let chatUILogger = Logger(subsystem: "ai.openclaw", category: "OpenClawChatUI")
+// Module-internal: ChatViewModel extension files share this logger.
+let chatUILogger = Logger(subsystem: "ai.openclaw", category: "OpenClawChatUI")
 
 @MainActor
 @Observable
@@ -81,6 +82,10 @@ public final class OpenClawChatViewModel {
     public var attachments: [OpenClawPendingAttachment] = []
     /// Setter is module-internal for the health/outbox extension only.
     public internal(set) var healthOK: Bool = false
+    /// Bumped after every successful group-catalog mutation so views keyed on it
+    /// refetch; catalog-only changes (e.g. creating an empty group) alter no
+    /// session rows and would otherwise stay stale until reconnect.
+    public internal(set) var sessionGroupsRevision = 0
 
     /// True when this view model owns a gateway-scoped durable text outbox.
     public var supportsOfflineTextOutbox: Bool {
@@ -754,7 +759,8 @@ public final class OpenClawChatViewModel {
         self.blocksAttachmentOwnerChange
     }
 
-    private var blocksAttachmentOwnerChange: Bool {
+    /// Module-internal: the session-actions extension guards sessions.create with it.
+    var blocksAttachmentOwnerChange: Bool {
         self.attachmentOwnerIsActive() ||
             self.isSendingAttachmentDraft ||
             self.attachmentStagingCount > 0 ||
@@ -1176,38 +1182,10 @@ extension OpenClawChatViewModel {
         self.applySessionSwitch(to: sessionKey, intent: .externalSync)
     }
 
-    func performStartNewSession(worktree: Bool) async {
-        guard !self.blocksAttachmentOwnerChange else {
-            self.errorText = String(
-                localized: "Remove attachments or wait for delivery to resolve before starting a new chat.")
-            return
-        }
-        let requested = self.generatedNewSessionKey()
-        let parentSessionKey = self.sessionKey
-        let next: String
-        do {
-            let created = try await transport.createSession(
-                key: requested,
-                label: nil,
-                parentSessionKey: parentSessionKey,
-                worktree: worktree ? true : nil)
-            let createdKey = created.key.trimmingCharacters(in: .whitespacesAndNewlines)
-            next = createdKey.isEmpty ? requested : createdKey
-        } catch {
-            if Self.isUnsupportedCreateSessionError(error) {
-                chatUILogger.info("sessions.create unsupported; falling back to sessions.reset")
-                await self.performReset()
-                return
-            }
-            chatUILogger.error("sessions.create failed \(error.localizedDescription, privacy: .public)")
-            self.errorText = error.localizedDescription
-            return
-        }
-        guard !self.blocksAttachmentOwnerChange else {
-            self.errorText = String(
-                localized: "Remove attachments or wait for delivery to resolve before starting a new chat.")
-            return
-        }
+    /// Adopts a freshly created session key: full composer-preserving switch plus
+    /// session-owned state reset. Module-internal so the session-actions extension
+    /// does not need access to the private switch members.
+    func adoptCreatedSession(_ next: String) {
         self.prepareComposerForSessionSwitch(to: next)
         self.advanceSessionGeneration()
         self.sessionKey = next
@@ -1237,12 +1215,6 @@ extension OpenClawChatViewModel {
         clearPendingRuns(reason: nil)
     }
 
-    private static func isUnsupportedCreateSessionError(_ error: Error) -> Bool {
-        let nsError = error as NSError
-        return nsError.domain == "OpenClawChatTransport"
-            && nsError.localizedDescription == "sessions.create not supported by this transport"
-    }
-
     func performReset() async {
         self.isLoading = true
         self.errorText = nil
@@ -1572,9 +1544,11 @@ extension OpenClawChatViewModel {
         return normalized
     }
 
-    private func generatedNewSessionKey() -> String {
+    /// Module-internal: the session-actions extension derives new-session keys.
+    func generatedNewSessionKey(agentID explicitAgentID: String? = nil) -> String {
         let baseKey = "ios-\(UUID().uuidString.lowercased())"
-        guard let agentID = OpenClawChatSessionKey.agentID(from: sessionKey) ??
+        guard let agentID = explicitAgentID ??
+            OpenClawChatSessionKey.agentID(from: sessionKey) ??
             activeAgentId ??
             OpenClawChatSessionKey.agentID(from: resolvedMainSessionKey) ??
             sessions.lazy.compactMap({ OpenClawChatSessionKey.agentID(from: $0.key) }).first
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift
index 984154cca4f..6b2c54e60a0 100644
--- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatWindowShell.swift
@@ -18,6 +18,7 @@ public struct OpenClawChatWindowShell: View {
     @State private var isConfirmingClearHistory = false
     @State private var isPresentingSessions = false
     @State private var isRenamingSession = false
+    @State private var isPresentingNewSessionOptions = false
     @State private var renameSessionKey: String?
     @State private var renameText = ""
     private let userAccent: Color?
@@ -348,6 +349,12 @@ public struct OpenClawChatWindowShell: View {
             }
             .keyboardShortcut("n", modifiers: [.command])
 
+            Button {
+                self.isPresentingNewSessionOptions = true
+            } label: {
+                chatWindowActionLabel("New Session Options…", systemImage: "slider.horizontal.3")
+            }
+
             Button {
                 self.viewModel.refresh()
                 self.viewModel.refreshSessions(limit: 200)
@@ -484,6 +491,11 @@ public struct OpenClawChatWindowShell: View {
         } label: {
             chatWindowActionLabel("Session", systemImage: "ellipsis.circle")
         }
+        .popover(isPresented: self.$isPresentingNewSessionOptions) {
+            ChatNewSessionOptionsPopover(viewModel: self.viewModel) {
+                self.isPresentingNewSessionOptions = false
+            }
+        }
         .menuIndicator(.hidden)
         .help("Session actions")
     }
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatGatewayRequestTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatGatewayRequestTests.swift
index ea68269cba1..5487df15520 100644
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatGatewayRequestTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatGatewayRequestTests.swift
@@ -126,11 +126,30 @@ struct ChatGatewayRequestTests {
             agentID: "reviewer",
             label: nil,
             parentSessionKey: "global",
-            worktree: true)
+            worktree: true,
+            worktreeBaseRef: " origin/release ")
         #expect(create.params["key"]?.value as? String == "agent:reviewer:new")
         #expect(create.params["agentId"]?.value as? String == "reviewer")
         #expect(create.params["parentSessionKey"]?.value as? String == "global")
         #expect(create.params["worktree"]?.value as? Bool == true)
+        #expect(create.params["worktreeBaseRef"]?.value as? String == "origin/release")
+    }
+
+    @Test func `session group requests encode exact gateway contracts`() {
+        let list = OpenClawChatGatewayRequests.sessionGroupsList()
+        let put = OpenClawChatGatewayRequests.sessionGroupsPut(names: ["Work", "Personal"])
+        let rename = OpenClawChatGatewayRequests.sessionGroupsRename(name: "Work", to: "Projects")
+        let delete = OpenClawChatGatewayRequests.sessionGroupsDelete(name: "Personal")
+
+        #expect(list.method == "sessions.groups.list")
+        #expect(list.params.isEmpty)
+        #expect(put.method == "sessions.groups.put")
+        #expect(put.params["names"]?.value as? [String] == ["Work", "Personal"])
+        #expect(rename.method == "sessions.groups.rename")
+        #expect(rename.params["name"]?.value as? String == "Work")
+        #expect(rename.params["to"]?.value as? String == "Projects")
+        #expect(delete.method == "sessions.groups.delete")
+        #expect(delete.params["name"]?.value as? String == "Personal")
     }
 
     @Test func `rename clear archive and fork use session mutation contracts`() {
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatSessionSidebarModelTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatSessionSidebarModelTests.swift
index 6dad24b3863..82df6a9f351 100644
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatSessionSidebarModelTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatSessionSidebarModelTests.swift
@@ -11,6 +11,7 @@ struct ChatSessionSidebarModelTests {
         pinned: Bool? = nil,
         archived: Bool? = nil,
         unread: Bool? = nil,
+        category: String? = nil,
         parentSessionKey: String? = nil,
         spawnedBy: String? = nil,
         childSessions: [String]? = nil,
@@ -38,6 +39,7 @@ struct ChatSessionSidebarModelTests {
             modelProvider: nil,
             model: nil,
             contextTokens: nil,
+            category: category,
             pinned: pinned,
             archived: archived,
             unread: unread,
@@ -75,6 +77,39 @@ struct ChatSessionSidebarModelTests {
         #expect(sections[0].title == nil)
     }
 
+    @Test func `gateway groups render between pinned and recent and retain trees`() {
+        let sections = ChatSessionSidebarModel.sections(
+            sessions: [
+                self.entry(key: "pinned", pinned: true),
+                self.entry(key: "parent", category: "Projects", childSessions: ["child"]),
+                self.entry(key: "child", category: "Projects", parentSessionKey: "parent"),
+                self.entry(key: "recent"),
+            ],
+            currentSessionKey: "recent",
+            groups: [OpenClawChatSessionGroup(name: "Projects", position: 0)],
+            query: "")
+
+        #expect(sections.map(\.id) == ["pinned", "group:Projects", "recent"])
+        #expect(sections[1].nodes.map(\.id) == ["parent"])
+        #expect(sections[1].nodes[0].children.map(\.id) == ["child"])
+    }
+
+    @Test func `group placement uses exact gateway category names`() {
+        let sections = ChatSessionSidebarModel.sections(
+            sessions: [
+                self.entry(key: "exact", category: "Projects"),
+                self.entry(key: "case", category: "projects"),
+                self.entry(key: "spaces", category: " Projects "),
+            ],
+            currentSessionKey: "exact",
+            groups: [OpenClawChatSessionGroup(name: "Projects", position: 0)],
+            query: "")
+
+        #expect(sections.map(\.id) == ["group:Projects", "recent"])
+        #expect(sections[0].sessions.map(\.key) == ["exact"])
+        #expect(Set(sections[1].sessions.map(\.key)) == Set(["case", "spaces"]))
+    }
+
     @Test func `pinned descendants move to pinned section independently`() {
         let sections = ChatSessionSidebarModel.sections(
             sessions: [
@@ -197,6 +232,10 @@ struct ChatSessionSidebarModelTests {
           "hasActiveRun": true,
           "hasActiveSubagentRun": true,
           "lastInteractionAt": 1700000000000,
+          "startedAt": 1700000001000,
+          "endedAt": 1700000003000,
+          "runtimeMs": 2000,
+          "agentRuntime": {"id": "codex", "fallback": "openclaw", "source": "session"},
           "worktree": {"id": "wt-1", "branch": "feature/chat", "repoRoot": "/repo"}
         }
         """.data(using: .utf8))
@@ -210,11 +249,58 @@ struct ChatSessionSidebarModelTests {
         #expect(entry.hasActiveRun == true)
         #expect(entry.hasActiveSubagentRun == true)
         #expect(entry.lastInteractionAt == 1_700_000_000_000)
+        #expect(entry.startedAt == 1_700_000_001_000)
+        #expect(entry.endedAt == 1_700_000_003_000)
+        #expect(entry.runtimeMs == 2000)
+        #expect(entry.agentRuntime?.id == "codex")
         #expect(entry.worktree?.id == "wt-1")
         #expect(entry.worktree?.branch == "feature/chat")
         #expect(entry.worktree?.repoRoot == "/repo")
     }
 
+    @Test func `inspector derives gateway metadata without composer overrides`() {
+        let session = OpenClawChatSessionEntry(
+            key: "agent:reviewer:child",
+            kind: "subagent",
+            displayName: "Review",
+            surface: nil,
+            subject: nil,
+            room: nil,
+            space: nil,
+            updatedAt: 1_700_000_000_000,
+            sessionId: "session-1",
+            systemSent: nil,
+            abortedLastRun: nil,
+            thinkingLevel: "high",
+            verboseLevel: "full",
+            inputTokens: nil,
+            outputTokens: nil,
+            totalTokens: nil,
+            modelProvider: "openai",
+            model: "gpt-5.6",
+            contextTokens: nil,
+            category: "Projects",
+            hasActiveRun: true,
+            worktree: OpenClawChatSessionWorktree(
+                id: "wt-1",
+                branch: "feature/review",
+                repoRoot: "/repo"),
+            runtimeMs: 1500,
+            agentRuntime: OpenClawChatAgentRuntime(id: "codex", fallback: nil, source: "session"))
+
+        let details = ChatSessionInspectorDetails(session: session)
+
+        #expect(details.title == "Review")
+        #expect(details.agentID == "reviewer")
+        #expect(details.group == "Projects")
+        #expect(details.runState == "Running")
+        #expect(details.model == "gpt-5.6")
+        #expect(details.provider == "openai")
+        #expect(details.runtime == "codex")
+        #expect(details.runDurationMs == 1500)
+        #expect(details.worktreeBranch == "feature/review")
+    }
+
     @Test func `tree nests children and bubbles run failure and unread badges`() {
         let nodes = ChatSessionSidebarModel.tree(from: [
             self.entry(key: "parent", childSessions: ["child"]),
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelSessionActionTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelSessionActionTests.swift
index 380a602b1e5..79bc1359692 100644
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelSessionActionTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelSessionActionTests.swift
@@ -5,10 +5,32 @@ import Testing
 
 private actor SessionActionTransportState {
     var forkedParentKeys: [String] = []
+    var patchedKeys: [String] = []
+    var deletedKeys: [String] = []
+    var groupPuts: [[String]] = []
+    var createdAgentIDs: [String?] = []
+    var createdParentKeys: [String?] = []
 
     func recordFork(_ key: String) {
         self.forkedParentKeys.append(key)
     }
+
+    func recordPatch(_ key: String) {
+        self.patchedKeys.append(key)
+    }
+
+    func recordGroupPut(_ names: [String]) {
+        self.groupPuts.append(names)
+    }
+
+    func recordDelete(_ key: String) {
+        self.deletedKeys.append(key)
+    }
+
+    func recordCreate(agentID: String?, parentKey: String?) {
+        self.createdAgentIDs.append(agentID)
+        self.createdParentKeys.append(parentKey)
+    }
 }
 
 private final class SessionActionTransport: @unchecked Sendable, OpenClawChatTransport {
@@ -45,6 +67,59 @@ private final class SessionActionTransport: @unchecked Sendable, OpenClawChatTra
         return "forked"
     }
 
+    func patchSession(
+        key: String,
+        label _: String??,
+        category _: String??,
+        pinned _: Bool?,
+        archived _: Bool?,
+        unread _: Bool?) async throws
+    {
+        await self.state.recordPatch(key)
+    }
+
+    func acquireSessionGroupsRouteLease() async -> OpenClawChatSessionGroupsRouteLease? {
+        let state = self.state
+        return OpenClawChatSessionGroupsRouteLease(
+            listGroups: {
+                OpenClawChatSessionGroupsResponse(groups: [
+                    OpenClawChatSessionGroup(name: "Existing", position: 0),
+                ])
+            },
+            putGroups: { names in
+                await state.recordGroupPut(names)
+                return OpenClawChatSessionGroupsMutationResponse(
+                    ok: true,
+                    groups: names.enumerated().map {
+                        OpenClawChatSessionGroup(name: $0.element, position: $0.offset)
+                    })
+            },
+            renameGroup: { _, _ in
+                OpenClawChatSessionGroupsMutationResponse(ok: true, groups: [])
+            },
+            deleteGroup: { _ in
+                OpenClawChatSessionGroupsMutationResponse(ok: true, groups: [])
+            })
+    }
+
+    func acquireNewSessionRouteLease() async -> OpenClawChatNewSessionRouteLease? {
+        let state = self.state
+        return OpenClawChatNewSessionRouteLease(
+            listAgents: {
+                OpenClawChatAgentsListResponse(
+                    defaultId: "worker",
+                    agents: [OpenClawChatAgentChoice(id: "worker", workspaceGit: true)])
+            },
+            createSession: { key, _, agentID, parentKey, _, _ in
+                await state.recordCreate(agentID: agentID, parentKey: parentKey)
+                return OpenClawChatCreateSessionResponse(ok: true, key: key, sessionId: nil)
+            })
+    }
+
+    func deleteSession(key: String) async throws {
+        await self.state.recordDelete(key)
+    }
+
     func requestHealth(timeoutMs _: Int) async throws -> Bool {
         true
     }
@@ -56,10 +131,192 @@ private final class SessionActionTransport: @unchecked Sendable, OpenClawChatTra
     func forkedParentKeys() async -> [String] {
         await self.state.forkedParentKeys
     }
+
+    func patchedKeys() async -> [String] {
+        await self.state.patchedKeys
+    }
+
+    func groupPuts() async -> [[String]] {
+        await self.state.groupPuts
+    }
+
+    func deletedKeys() async -> [String] {
+        await self.state.deletedKeys
+    }
+
+    func createdAgentIDs() async -> [String?] {
+        await self.state.createdAgentIDs
+    }
+
+    func createdParentKeys() async -> [String?] {
+        await self.state.createdParentKeys
+    }
+}
+
+private actor BatchMutationProbe {
+    private(set) var active = 0
+    private(set) var maximumActive = 0
+    private(set) var visited: [String] = []
+
+    func begin(_ key: String) {
+        self.active += 1
+        self.maximumActive = max(self.maximumActive, self.active)
+        self.visited.append(key)
+    }
+
+    func end() {
+        self.active -= 1
+    }
+}
+
+private struct BatchTestError: LocalizedError {
+    var errorDescription: String? {
+        "rejected"
+    }
 }
 
 @MainActor
 struct ChatViewModelSessionActionTests {
+    @Test func `batch mutations continue after per-row failure with bounded fan-out`() async {
+        let probe = BatchMutationProbe()
+        let result = await ChatSessionBatchMutationRunner.run(
+            keys: ["a", "b", "c", "d", "e"],
+            maxConcurrent: 2)
+        { key in
+            await probe.begin(key)
+            try? await Task.sleep(for: .milliseconds(10))
+            await probe.end()
+            if key == "c" { throw BatchTestError() }
+        }
+
+        #expect(result.succeededKeys == ["a", "b", "d", "e"])
+        #expect(result.errorsByKey == ["c": "rejected"])
+        #expect(await probe.maximumActive == 2)
+        #expect(await Set(probe.visited) == Set(["a", "b", "c", "d", "e"]))
+    }
+
+    @Test func `batch mutation includes selected server-search entry outside live roster`() async {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
+        let searchResult = self.entry(key: "older-search-result")
+
+        let result = await viewModel.performSessionBatch(sessions: [searchResult], action: .pin)
+
+        #expect(result.succeededKeys == ["older-search-result"])
+        #expect(result.errorsByKey.isEmpty)
+        #expect(await transport.patchedKeys() == ["older-search-result"])
+    }
+
+    @Test func `group create lists and replaces through one captured route lease`() async throws {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
+        let lease = try await viewModel.sessionGroupsRouteLease()
+
+        let groups = try await viewModel.createSessionGroup(named: "New", using: lease)
+
+        #expect(groups.map(\.name) == ["Existing", "New"])
+        #expect(await transport.groupPuts() == [["Existing", "New"]])
+        // Catalog-only mutations must bump the revision so sidebar group fetches
+        // keyed on it refetch instead of staying stale until reconnect.
+        #expect(viewModel.sessionGroupsRevision == 1)
+    }
+
+    @Test func `remote group mutations bump the catalog revision`() async {
+        let transport = SessionActionTransport()
+        let viewModel = await MainActor.run {
+            OpenClawChatViewModel(sessionKey: "main", transport: transport)
+        }
+
+        await MainActor.run {
+            viewModel.handleTransportEvent(.sessionsChanged(.init(sessionKey: nil, reason: "groups")))
+            viewModel.handleTransportEvent(.sessionsChanged(.init(sessionKey: nil, reason: "unrelated")))
+        }
+
+        #expect(await MainActor.run { viewModel.sessionGroupsRevision } == 1)
+    }
+
+    @Test func `batch delete rejects current session while attachment owner is pinned`() async {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "worker", transport: transport)
+        viewModel.attachments = [OpenClawPendingAttachment(
+            url: nil,
+            data: Data([1]),
+            fileName: "draft.png",
+            mimeType: "image/png",
+            preview: nil)]
+
+        let result = await viewModel.performSessionBatch(
+            sessions: [self.entry(key: "worker")],
+            action: .delete)
+
+        #expect(result.succeededKeys.isEmpty)
+        #expect(result.errorsByKey["worker"] != nil)
+        #expect(await transport.deletedKeys().isEmpty)
+    }
+
+    @Test func `new session options list and create through one captured route lease`() async throws {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
+        let lease = try await viewModel.newSessionRouteLease()
+        let response = try await lease.listAgents()
+
+        await viewModel.startNewSession(
+            agentID: response?.defaultId ?? "",
+            worktree: true,
+            worktreeBaseRef: "main",
+            using: lease)
+
+        #expect(await transport.createdAgentIDs() == ["worker"])
+    }
+
+    @Test func `unsupported create with advanced options fails without resetting`() async throws {
+        // SessionActionTransport relies on the protocol's default createSession,
+        // which throws the canonical unsupported error; the worktree request must
+        // surface it instead of taking the plain-new reset fallback.
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
+
+        let created = await viewModel.startNewSession(worktree: true)
+
+        #expect(created == false)
+        #expect(viewModel.sessionKey == "main")
+        #expect(viewModel.errorText != nil)
+    }
+
+    @Test func `ambiguous agent ownership omits the parent session`() async throws {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
+        // Roster entries must not decide the current agent: "main" is unscoped and
+        // no active agent is set, so agent selection crosses an ownership boundary.
+        viewModel.sessions = [self.entry(key: "agent:worker:main")]
+        let lease = try await viewModel.newSessionRouteLease()
+
+        await viewModel.startNewSession(
+            agentID: "worker",
+            worktree: false,
+            worktreeBaseRef: nil,
+            using: lease)
+
+        #expect(await transport.createdParentKeys() == [nil])
+    }
+
+    @Test func `active agent identity preserves parent for an unscoped current key`() async throws {
+        let transport = SessionActionTransport()
+        let viewModel = OpenClawChatViewModel(
+            sessionKey: "main",
+            transport: transport,
+            activeAgentId: "worker")
+        let lease = try await viewModel.newSessionRouteLease()
+
+        await viewModel.startNewSession(
+            agentID: "worker",
+            worktree: false,
+            worktreeBaseRef: nil,
+            using: lease)
+
+        #expect(await transport.createdParentKeys() == ["main"])
+    }
+
     @Test func `fork does not mutate gateway while session switching is blocked`() async {
         let transport = SessionActionTransport()
         let viewModel = OpenClawChatViewModel(sessionKey: "main", transport: transport)
@@ -103,4 +360,27 @@ struct ChatViewModelSessionActionTests {
         }
         Issue.record("timed out waiting for session action condition")
     }
+
+    private func entry(key: String) -> OpenClawChatSessionEntry {
+        OpenClawChatSessionEntry(
+            key: key,
+            kind: nil,
+            displayName: nil,
+            surface: nil,
+            subject: nil,
+            room: nil,
+            space: nil,
+            updatedAt: nil,
+            sessionId: nil,
+            systemSent: nil,
+            abortedLastRun: nil,
+            thinkingLevel: nil,
+            verboseLevel: nil,
+            inputTokens: nil,
+            outputTokens: nil,
+            totalTokens: nil,
+            modelProvider: nil,
+            model: nil,
+            contextTokens: nil)
+    }
 }
diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift
index 9bebdbcc25e..e72a71c4e24 100644
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift
@@ -5675,6 +5675,40 @@ struct ChatViewModelTests {
         #expect(await transport.lastSentRunId() == nil)
     }
 
+    @Test func `default create session overload rejects unsupported agent and base ref options`() async throws {
+        let (transport, _) = await makeViewModel(historyResponses: [historyPayload()])
+
+        await #expect(throws: (any Error).self) {
+            _ = try await transport.createSession(
+                key: "next",
+                label: nil,
+                agentID: nil,
+                parentSessionKey: nil,
+                worktree: true,
+                worktreeBaseRef: "release/2026.7")
+        }
+        await #expect(throws: (any Error).self) {
+            _ = try await transport.createSession(
+                key: "next",
+                label: nil,
+                agentID: "reviewer",
+                parentSessionKey: nil,
+                worktree: nil,
+                worktreeBaseRef: nil)
+        }
+        #expect(await transport.createdSessionKeys().isEmpty)
+
+        let created = try await transport.createSession(
+            key: "next",
+            label: nil,
+            agentID: nil,
+            parentSessionKey: nil,
+            worktree: nil,
+            worktreeBaseRef: nil)
+        #expect(created.key == "next")
+        #expect(await transport.createdSessionKeys() == ["next"])
+    }
+
     @Test func `new trigger keeps selected global agent scope`() async throws {
         let (transport, vm) = await makeViewModel(
             sessionKey: "global",
diff --git a/docs/platforms/mac/webchat.md b/docs/platforms/mac/webchat.md
index 9bfcabf1261..19e12f46539 100644
--- a/docs/platforms/mac/webchat.md
+++ b/docs/platforms/mac/webchat.md
@@ -9,8 +9,8 @@ The macOS menu bar app embeds the WebChat UI as a native SwiftUI view. It connec
 
 The full chat window is a native split view:
 
-- **Sessions sidebar**: searchable session list with pinned and recent sections. Spawned child sessions nest beneath their parent when the Gateway provides hierarchy metadata; collapsed parents summarize running, failed, and unread descendants. Context menus support rename, pin, fork, read/unread, archive/restore, copy session key, and delete. A toolbar button (or Cmd-N) creates a real new session via `sessions.create`.
-- **Window toolbar**: context-usage ring (tokens and session cost, with a compact action), model controls, and a session actions menu. Models are grouped by provider with the default provider first, while pinned and recent models remain at the top. The controls can inherit or override the model's thinking level, choose tool-call verbosity, and toggle Fast responses. The menu can rename or fork the current session and update its pin, read, or archive state. **Sessions…** (Shift-Cmd-S) opens the Active/Archived manager for gateway search, rename, pin, archive, and restore. Separate menu checkmarks show or hide assistant reasoning and tool activity; both are on by default and remembered across launches.
+- **Sessions sidebar**: searchable session list with pinned, gateway-backed group, and recent sections. Spawned child sessions nest beneath their parent inside each section; collapsed parents summarize running, failed, and unread descendants. Context menus support session info, rename, pin, fork, read/unread, archive/restore, copy session key, and delete. The primary new-session action (or Cmd-N) creates immediately via `sessions.create`; its adjacent options popover can select an agent and request a managed worktree with an optional base ref.
+- **Window toolbar**: context-usage ring (tokens and session cost, with a compact action), model controls, and a session actions menu. Models are grouped by provider with the default provider first, while pinned and recent models remain at the top. The controls can inherit or override the model's thinking level, choose tool-call verbosity, and toggle Fast responses. The menu can rename or fork the current session and update its pin, read, or archive state. **Sessions…** (Shift-Cmd-S) opens the Active/Archived manager for gateway search, group management, session inspection, rename, pin, archive, and restore. Select mode applies pin, unpin, archive, or delete to several active sessions while keeping individual failures visible. Separate menu checkmarks show or hide assistant reasoning and tool activity; both are on by default and remembered across launches.
 - **Transcript and composer**: assistant messages render as plain text with an avatar, user messages as accent bubbles. Pending agent questions render as native cards with single- or multi-select options, free-text **Other** answers, expiry countdowns, and shared terminal state. Empty chats offer desktop starter prompts. Typing `/` opens slash-command autocomplete backed by `commands.list`, with arrow/Tab/Return/Escape keyboard navigation. Right-click a message to copy its visible Markdown without hidden reasoning. Truncated assistant messages also offer **Open Full Message**, which loads a selectable Markdown reader. Use **Listen** for gateway TTS with a local speech fallback.
 - **Voice controls**: the composer can start or stop the existing macOS Talk Mode without replacing its menu-bar overlay. While Talk Mode is active, the composer shows its listening/thinking/speaking state, live audio activity, and an expandable rolling transcript. Right-click the Talk button to choose **System Default** or a connected microphone; this is the same microphone selection used by Voice Wake and push-to-talk. If a selected microphone disconnects, the active Talk session falls back to the system default and tries the selection again the next time Talk Mode starts. A separate microphone action records a voice note when Talk Mode does not own audio capture.
 
@@ -49,6 +49,7 @@ Disable the feature entirely with **Settings → General → Quick Chat**; the s
 - Data plane: Gateway WS methods `chat.history`, `chat.message.get`, `chat.send`, `chat.abort`, `chat.inject`, plus `question.list` and `question.resolve`, and events `chat`, `agent`, `presence`, `tick`, `health`; question cards follow `question.requested` and `question.resolved` events and refresh from `question.list` after reconnects.
 - `chat.history` returns a display-normalized transcript: inline directive tags are stripped from visible text, plain-text tool-call XML payloads (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`, including truncated blocks) and leaked model control tokens are stripped, pure silent-token assistant rows such as exact `NO_REPLY`/`no_reply` are omitted, and oversized rows can be replaced with a truncated placeholder.
 - Session: defaults to the primary session as above; the UI can switch between sessions.
+- Session groups: `sessions.groups.list`, `sessions.groups.put`, `sessions.groups.rename`, and `sessions.groups.delete` own the group catalog. Membership is the session `category` updated through `sessions.patch`.
 - Unread state: after a session activates and its live history loads successfully, the app clears that session's unread marker. Failed history loads do not clear it; a transient patch failure retries on the next activation.
 - Onboarding uses a dedicated session to keep first-run setup separate.
 - Offline cache: the app keeps a small read-only cache of recent chat sessions and transcripts per gateway (`~/Library/Application Support/OpenClaw/chat-cache.sqlite`): cold opens paint the last known transcript immediately and refresh once the Gateway responds, and recent chats stay browsable while disconnected (sending stays disabled until the connection is back).

From ad3b8e0b6f140d432ad26c8cac93b94d7f3372ac Mon Sep 17 00:00:00 2001
From: Alix-007 <li.long15@xydigit.com>
Date: Sat, 18 Jul 2026 21:11:14 +0800
Subject: [PATCH 66/76] fix(memory): bound qmd taskkill cleanup (#109265)

* fix(memory): bound qmd taskkill cleanup

* test(memory): satisfy qmd process lint
---
 .../src/host/qmd-process.test.ts              | 144 ++++++++++++++++--
 .../memory-host-sdk/src/host/qmd-process.ts   | 101 +++++++++---
 2 files changed, 214 insertions(+), 31 deletions(-)

diff --git a/packages/memory-host-sdk/src/host/qmd-process.test.ts b/packages/memory-host-sdk/src/host/qmd-process.test.ts
index 4c735544dca..ed54a7230fd 100644
--- a/packages/memory-host-sdk/src/host/qmd-process.test.ts
+++ b/packages/memory-host-sdk/src/host/qmd-process.test.ts
@@ -17,14 +17,12 @@ import {
 import { MAX_SAFE_TIMEOUT_DELAY_MS } from "../../../gateway-client/src/timeouts.js";
 
 const spawnMock = vi.hoisted(() => vi.fn());
-const spawnSyncMock = vi.hoisted(() => vi.fn());
 
 vi.mock("node:child_process", async () => {
   const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
   return {
     ...actual,
     spawn: spawnMock,
-    spawnSync: spawnSyncMock,
   };
 });
 
@@ -41,19 +39,33 @@ function createMockChild(params: { pid?: number } = {}) {
     pid?: number;
     stdout: EventEmitter & { setEncoding: ReturnType<typeof vi.fn> };
     stderr: EventEmitter & { setEncoding: ReturnType<typeof vi.fn> };
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
     kill: ReturnType<typeof vi.fn>;
+    unref: ReturnType<typeof vi.fn>;
     closeWith: (code?: number | null, signal?: NodeJS.Signals | null) => void;
   };
   child.pid = params.pid;
   child.stdout = Object.assign(new EventEmitter(), { setEncoding: vi.fn() });
   child.stderr = Object.assign(new EventEmitter(), { setEncoding: vi.fn() });
+  child.exitCode = null;
+  child.signalCode = null;
   child.kill = vi.fn();
+  child.unref = vi.fn();
   child.closeWith = (code: number | null = 0, signal: NodeJS.Signals | null = null) => {
+    child.exitCode = code;
+    child.signalCode = signal;
     child.emit("close", code, signal);
   };
   return child;
 }
 
+function createClosingTaskkillChild(code = 0) {
+  const child = createMockChild();
+  queueMicrotask(() => child.closeWith(code));
+  return child;
+}
+
 let fixtureRoot = "";
 let tempDir = "";
 let platformSpy: MockInstance<() => NodeJS.Platform> | null = null;
@@ -90,6 +102,8 @@ beforeEach(async () => {
   await fs.mkdir(tempDir, { recursive: true });
   process.env.SystemRoot = "C:\\Windows";
   delete process.env.WINDIR;
+  spawnMock.mockReset();
+  spawnMock.mockImplementation(() => createClosingTaskkillChild());
 });
 
 afterEach(() => {
@@ -100,8 +114,6 @@ afterEach(() => {
   restoreEnvValue("WINDIR", originalWindir);
   platformSpy?.mockReturnValue("win32");
   spawnMock.mockReset();
-  spawnSyncMock.mockReset();
-  spawnSyncMock.mockReturnValue({ status: 0 });
   tempDir = "";
 });
 
@@ -191,7 +203,7 @@ describe("checkQmdBinaryAvailability", () => {
     await expect(
       checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
     ).resolves.toEqual({ available: true });
-    expect(spawnSyncMock).toHaveBeenCalledWith(taskkillPath, ["/PID", String(child.pid), "/T"], {
+    expect(spawnMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", String(child.pid), "/T"], {
       stdio: "ignore",
       windowsHide: true,
     });
@@ -204,24 +216,103 @@ describe("checkQmdBinaryAvailability", () => {
       queueMicrotask(() => child.emit("spawn"));
       return child;
     });
-    spawnSyncMock.mockReset();
-    spawnSyncMock.mockReturnValueOnce({ status: 1 }).mockReturnValueOnce({ status: 0 });
+    spawnMock.mockImplementationOnce(() => createClosingTaskkillChild(1));
 
     await expect(
       checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
     ).resolves.toEqual({ available: true });
+    await vi.waitFor(() => expect(spawnMock).toHaveBeenCalledTimes(3));
 
-    expect(spawnSyncMock).toHaveBeenNthCalledWith(1, taskkillPath, ["/PID", "12345", "/T"], {
+    expect(spawnMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12345", "/T"], {
       stdio: "ignore",
       windowsHide: true,
     });
-    expect(spawnSyncMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12345", "/T", "/F"], {
+    expect(spawnMock).toHaveBeenNthCalledWith(3, taskkillPath, ["/PID", "12345", "/T", "/F"], {
       stdio: "ignore",
       windowsHide: true,
     });
     expect(child.kill).not.toHaveBeenCalled();
   });
 
+  it("keeps the event loop responsive and does not retry a pid after taskkill times out", async () => {
+    vi.useFakeTimers();
+    const child = createMockChild({ pid: 12346 });
+    const taskkill = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("spawn"));
+      return child;
+    });
+    spawnMock.mockReturnValueOnce(taskkill);
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: true });
+
+    const heartbeat = vi.fn();
+    setTimeout(heartbeat, 1);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(heartbeat).toHaveBeenCalledOnce();
+    expect(taskkill.kill).not.toHaveBeenCalled();
+    expect(taskkill.unref).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(4_999);
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(spawnMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12346", "/T"], {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    expect(taskkill.kill).toHaveBeenCalledWith("SIGKILL");
+    expect(taskkill.unref).toHaveBeenCalledOnce();
+    expect(child.kill).toHaveBeenCalledWith();
+  });
+
+  it("keeps a timed-out taskkill result when kill synchronously emits an error", async () => {
+    vi.useFakeTimers();
+    const child = createMockChild({ pid: 12347 });
+    const taskkill = createMockChild();
+    taskkill.kill.mockImplementationOnce(() => {
+      taskkill.emit("error", new Error("taskkill kill failed"));
+      return true;
+    });
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("spawn"));
+      return child;
+    });
+    spawnMock.mockReturnValueOnce(taskkill);
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: true });
+
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(taskkill.kill).toHaveBeenCalledWith("SIGKILL");
+    expect(child.kill).toHaveBeenCalledWith();
+  });
+
+  it("does not retry taskkill after the qmd child exits", async () => {
+    const child = createMockChild({ pid: 12348 });
+    const taskkill = createMockChild();
+    spawnMock.mockImplementationOnce(() => {
+      queueMicrotask(() => child.emit("spawn"));
+      return child;
+    });
+    spawnMock.mockReturnValueOnce(taskkill);
+
+    await expect(
+      checkQmdBinaryAvailability({ command: "qmd", env: process.env, cwd: tempDir }),
+    ).resolves.toEqual({ available: true });
+
+    child.closeWith(0);
+    taskkill.closeWith(1);
+    await new Promise<void>((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(spawnMock).toHaveBeenCalledTimes(2);
+    expect(child.kill).not.toHaveBeenCalled();
+  });
+
   it("returns unavailable when the qmd process cannot be spawned", async () => {
     const child = createMockChild();
     const err = Object.assign(new Error("spawn qmd ENOENT"), { code: "ENOENT" });
@@ -252,7 +343,7 @@ describe("checkQmdBinaryAvailability", () => {
     const child = createMockChild();
     const err = Object.assign(new Error("spawn qmd ENOENT"), { code: "ENOENT" });
     spawnMock.mockImplementationOnce(() => {
-      queueMicrotask(() => child.emit("close"));
+      queueMicrotask(() => child.closeWith());
       queueMicrotask(() => child.emit("error", err));
       return child;
     });
@@ -520,13 +611,44 @@ describe("runCliCommand", () => {
 
     await expect(pending).rejects.toThrow("qmd query test timed out after 1ms");
 
-    expect(spawnSyncMock).toHaveBeenCalledWith(taskkillPath, ["/PID", "12346", "/T", "/F"], {
+    expect(spawnMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12346", "/T", "/F"], {
       stdio: "ignore",
       windowsHide: true,
     });
     expect(child.kill).not.toHaveBeenCalledWith("SIGKILL");
   });
 
+  it("falls back to direct SIGKILL when Windows taskkill times out", async () => {
+    vi.useFakeTimers();
+    const child = createMockChild({ pid: 12347 });
+    const taskkill = createMockChild();
+    spawnMock.mockReturnValueOnce(child);
+    spawnMock.mockReturnValueOnce(taskkill);
+
+    const pending = runCliCommand({
+      commandSummary: "qmd query test",
+      spawnInvocation: { command: "qmd", argv: ["query", "test", "--json"] },
+      env: process.env,
+      cwd: tempDir,
+      maxOutputChars: 10_000,
+      timeoutMs: 1,
+    });
+
+    const timeoutAssertion = expect(pending).rejects.toThrow("qmd query test timed out after 1ms");
+    await vi.advanceTimersByTimeAsync(1);
+    await timeoutAssertion;
+    expect(child.kill).not.toHaveBeenCalledWith("SIGKILL");
+
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(spawnMock).toHaveBeenNthCalledWith(2, taskkillPath, ["/PID", "12347", "/T", "/F"], {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    expect(taskkill.kill).toHaveBeenCalledWith("SIGKILL");
+    expect(taskkill.unref).toHaveBeenCalledOnce();
+    expect(child.kill).toHaveBeenCalledWith("SIGKILL");
+  });
+
   it.each(["stdout", "stderr"] as const)(
     "rejects when %s stream emits an error",
     async (streamName) => {
diff --git a/packages/memory-host-sdk/src/host/qmd-process.ts b/packages/memory-host-sdk/src/host/qmd-process.ts
index 4c3c7ec486a..7a0936f6cad 100644
--- a/packages/memory-host-sdk/src/host/qmd-process.ts
+++ b/packages/memory-host-sdk/src/host/qmd-process.ts
@@ -1,5 +1,5 @@
 // Memory Host SDK module implements qmd process behavior.
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { statSync } from "node:fs";
 import path from "node:path";
 import { resolveSafeTimeoutDelayMs } from "../../../gateway-client/src/timeouts.js";
@@ -14,10 +14,15 @@ type CliSpawnInvocation = {
 
 type QmdChildProcess = {
   pid?: number;
+  exitCode: number | null;
+  signalCode: NodeJS.Signals | null;
   kill: (signal?: NodeJS.Signals) => boolean;
 };
 
+type WindowsTaskkillResult = "success" | "failure" | "timed-out";
+
 const DEFAULT_WINDOWS_SYSTEM_ROOT = "C:\\Windows";
+const WINDOWS_TASKKILL_TIMEOUT_MS = 5_000;
 
 export type QmdBinaryUnavailableReason = "binary" | "workspace-cwd";
 
@@ -104,7 +109,7 @@ export async function checkQmdBinaryAvailability(params: {
     });
     const timeoutMs = resolveSafeTimeoutDelayMs(params.timeoutMs ?? 2_000, { minMs: 0 });
     const timer = setTimeout(() => {
-      signalQmdProcessTree(child, "SIGKILL");
+      void signalQmdProcessTree(child, "SIGKILL");
       finish({
         available: false,
         reason: "binary",
@@ -117,7 +122,7 @@ export async function checkQmdBinaryAvailability(params: {
     });
     child.once("spawn", () => {
       didSpawn = true;
-      signalQmdProcessTree(child);
+      void signalQmdProcessTree(child);
       finish({ available: true });
     });
     child.once("close", () => {
@@ -217,14 +222,14 @@ export async function runCliCommand(params: {
       params.timeoutMs === undefined ? undefined : resolveSafeTimeoutDelayMs(params.timeoutMs);
     const timer = timeoutMs
       ? setTimeout(() => {
-          signalQmdProcessTree(child, "SIGKILL");
+          void signalQmdProcessTree(child, "SIGKILL");
           settle(() =>
             reject(new Error(`${params.commandSummary} timed out after ${timeoutMs}ms`)),
           );
         }, timeoutMs)
       : null;
     const onAbort = () => {
-      signalQmdProcessTree(child, "SIGKILL");
+      void signalQmdProcessTree(child, "SIGKILL");
       settle(() => reject(abortReason(signal, params.commandSummary)));
     };
     function settle(run: () => void): void {
@@ -261,7 +266,7 @@ export async function runCliCommand(params: {
         if (settled) {
           return;
         }
-        signalQmdProcessTree(child, "SIGKILL");
+        void signalQmdProcessTree(child, "SIGKILL");
         settle(() =>
           reject(
             new Error(`${params.commandSummary} ${streamName} error: ${error.message}`, {
@@ -356,7 +361,57 @@ function resolveWindowsTaskkillPath(env: Record<string, string | undefined> = pr
   return path.win32.join(systemRoot, "System32", "taskkill.exe");
 }
 
-function signalQmdProcessTree(child: QmdChildProcess, signal?: NodeJS.Signals): void {
+function runWindowsTaskkill(params: {
+  taskkillPath: string;
+  args: string[];
+}): Promise<WindowsTaskkillResult> {
+  return new Promise((resolve) => {
+    let taskkill: ReturnType<typeof spawn>;
+    try {
+      taskkill = spawn(params.taskkillPath, params.args, {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {
+      resolve("failure");
+      return;
+    }
+
+    let settled = false;
+    const finish = (result: WindowsTaskkillResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    taskkill.once("error", () => finish("failure"));
+    taskkill.once("close", (code) => finish(code === 0 ? "success" : "failure"));
+    const timeout = setTimeout(() => {
+      // Fix the timeout result before kill() can synchronously emit an error.
+      finish("timed-out");
+      try {
+        taskkill.kill("SIGKILL");
+      } catch {
+        // The retained qmd child handle remains the final fallback below.
+      }
+      taskkill.unref();
+      // Do not wait for a stalled system utility after its deadline. Its late
+      // events stay guarded by finish(), while qmd cleanup uses the child handle.
+    }, WINDOWS_TASKKILL_TIMEOUT_MS);
+    timeout.unref?.();
+  });
+}
+
+function isQmdChildAlive(child: QmdChildProcess): boolean {
+  return child.exitCode === null && child.signalCode === null;
+}
+
+async function signalQmdProcessTree(
+  child: QmdChildProcess,
+  signal?: NodeJS.Signals,
+): Promise<void> {
   if (shouldUseQmdProcessGroup() && typeof child.pid === "number") {
     try {
       if (signal === undefined) {
@@ -369,30 +424,36 @@ function signalQmdProcessTree(child: QmdChildProcess, signal?: NodeJS.Signals):
       // Fall back to the direct child if the process group already disappeared.
     }
   }
-  if (!shouldUseQmdProcessGroup() && typeof child.pid === "number") {
+  if (!shouldUseQmdProcessGroup() && typeof child.pid === "number" && isQmdChildAlive(child)) {
     const taskkillPath = resolveWindowsTaskkillPath();
     const args = ["/PID", String(child.pid), "/T"];
     if (signal === "SIGKILL") {
       args.push("/F");
     }
-    const result = spawnSync(taskkillPath, args, { stdio: "ignore", windowsHide: true });
-    if (!result.error && result.status === 0) {
+    const result = await runWindowsTaskkill({ taskkillPath, args });
+    if (result === "success") {
       return;
     }
-    if (signal !== "SIGKILL") {
-      const forceResult = spawnSync(taskkillPath, [...args, "/F"], {
-        stdio: "ignore",
-        windowsHide: true,
-      });
-      if (!forceResult.error && forceResult.status === 0) {
+    // taskkill /T requires a live root PID. Retrying an exited, reusable PID
+    // can target an unrelated process tree.
+    if (signal !== "SIGKILL" && result !== "timed-out" && isQmdChildAlive(child)) {
+      const forceResult = await runWindowsTaskkill({ taskkillPath, args: [...args, "/F"] });
+      if (forceResult === "success") {
         return;
       }
     }
   }
-  if (signal === undefined) {
-    child.kill();
-  } else {
-    child.kill(signal);
+  if (!isQmdChildAlive(child)) {
+    return;
+  }
+  try {
+    if (signal === undefined) {
+      child.kill();
+    } else {
+      child.kill(signal);
+    }
+  } catch {
+    // The child may already have exited while asynchronous tree cleanup ran.
   }
 }
 

From 42133d0c3c3ed95e4c791c4d2ecf461df2497f0a Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 14:13:06 +0100
Subject: [PATCH 67/76] feat(mac): show native notification permission in
 dashboard Notifications settings (#110646)

* feat(mac): show native notification permission in dashboard Notifications settings

The Mac app's embedded Control UI showed the web-push section as
Unsupported/Not subscribed even though the app delivers notifications
natively. The dashboard now installs an openclawNotifications WebKit
bridge (status / request-permission / send-test) and the Notifications
settings page renders native permission state with Enable, Open System
Settings, and Send test actions when hosted in the Mac app. Browsers
keep the existing web-push UI. The notifications section renderer moved
out of the oversized config view module.

* fix(ui): break config view import cycle and satisfy lint/deadcode/i18n gates

Move the notifications section props to a leaf contract (no view.ts
type import), unexport the status-event constant, use bracket access
for the injected dunder global, default-case the status switch, and
refresh the native i18n inventory line offset.
---
 apps/.i18n/native-source.json                 |   2 +-
 ...hboardWindowController+Notifications.swift |  88 ++++++
 .../OpenClaw/DashboardWindowController.swift  |   5 +-
 .../DashboardNotificationsBridgeTests.swift   |  32 +++
 docs/platforms/macos.md                       |   3 +
 docs/web/control-ui.md                        |   2 +
 ui/src/app/bootstrap.ts                       |   4 +
 ui/src/app/context.ts                         |   2 +
 ui/src/app/native-notifications.test.ts       | 140 ++++++++++
 ui/src/app/native-notifications.ts            | 111 ++++++++
 ui/src/i18n/locales/en.ts                     |   6 +
 ui/src/pages/config/config-page.ts            |   8 +
 ui/src/pages/config/notifications-section.ts  | 261 ++++++++++++++++++
 ui/src/pages/config/settings-search.ts        |   3 +
 ui/src/pages/config/view.ts                   | 168 +----------
 15 files changed, 671 insertions(+), 164 deletions(-)
 create mode 100644 apps/macos/Sources/OpenClaw/DashboardWindowController+Notifications.swift
 create mode 100644 apps/macos/Tests/OpenClawIPCTests/DashboardNotificationsBridgeTests.swift
 create mode 100644 ui/src/app/native-notifications.test.ts
 create mode 100644 ui/src/app/native-notifications.ts
 create mode 100644 ui/src/pages/config/notifications-section.ts

diff --git a/apps/.i18n/native-source.json b/apps/.i18n/native-source.json
index f453d3de337..4cb36bf09f4 100644
--- a/apps/.i18n/native-source.json
+++ b/apps/.i18n/native-source.json
@@ -29171,7 +29171,7 @@
     },
     {
       "kind": "conditional-branch",
-      "line": 878,
+      "line": 881,
       "path": "apps/macos/Sources/OpenClaw/DashboardWindowController.swift",
       "source": "[\\(host)]",
       "surface": "apple",
diff --git a/apps/macos/Sources/OpenClaw/DashboardWindowController+Notifications.swift b/apps/macos/Sources/OpenClaw/DashboardWindowController+Notifications.swift
new file mode 100644
index 00000000000..1fc8648bbec
--- /dev/null
+++ b/apps/macos/Sources/OpenClaw/DashboardWindowController+Notifications.swift
@@ -0,0 +1,88 @@
+import Foundation
+import UserNotifications
+import WebKit
+
+enum DashboardNotificationsRequest: String {
+    case status
+    case requestPermission = "request-permission"
+    case sendTest = "send-test"
+}
+
+@MainActor
+final class DashboardNotificationsMessageHandler: NSObject, WKScriptMessageHandler {
+    weak var owner: DashboardWindowController?
+
+    func userContentController(_: WKUserContentController, didReceive message: WKScriptMessage) {
+        self.owner?.receiveNotificationsMessage(message)
+    }
+}
+
+extension DashboardWindowController {
+    static let notificationsMessageHandlerName = "openclawNotifications"
+
+    static func notificationsRequest(from body: Any) -> DashboardNotificationsRequest? {
+        guard let payload = body as? [String: Any],
+              let type = payload["type"] as? String
+        else {
+            return nil
+        }
+        return DashboardNotificationsRequest(rawValue: type)
+    }
+
+    static func notificationsPermissionLabel(for status: UNAuthorizationStatus) -> String {
+        switch status {
+        case .authorized, .provisional:
+            "granted"
+        case .denied:
+            "denied"
+        case .notDetermined:
+            "notDetermined"
+        default:
+            // .ephemeral is unavailable by name on macOS and cannot occur here;
+            // map it and future cases to notDetermined so the UI offers the
+            // permission request instead of claiming access.
+            "notDetermined"
+        }
+    }
+
+    func receiveNotificationsMessage(_ message: WKScriptMessage) {
+        guard message.name == Self.notificationsMessageHandlerName,
+              message.webView === self.webView,
+              message.frameInfo.isMainFrame,
+              Self.isTrustedLinkSource(message.frameInfo.request.url, dashboardURL: self.currentURL)
+        else {
+            return
+        }
+        guard let request = Self.notificationsRequest(from: message.body) else { return }
+
+        switch request {
+        case .status:
+            Task { await self.publishNotificationsStatus() }
+        case .requestPermission:
+            Task {
+                _ = await PermissionManager.ensure([.notifications], interactive: true)
+                await self.publishNotificationsStatus()
+            }
+        case .sendTest:
+            Task {
+                _ = await NotificationManager().send(
+                    title: "OpenClaw",
+                    body: "Test notification",
+                    sound: nil)
+                await self.publishNotificationsStatus()
+            }
+        }
+    }
+
+    private func publishNotificationsStatus() async {
+        let settings = await UNUserNotificationCenter.current().notificationSettings()
+        let permission = Self.notificationsPermissionLabel(for: settings.authorizationStatus)
+        // Keep a global snapshot so late subscribers can read status without a bridge round-trip.
+        _ = try? await self.webView.evaluateJavaScript(
+            """
+            window.__OPENCLAW_NATIVE_NOTIFICATIONS__ = {permission:"\(permission)"};
+            window.dispatchEvent(new CustomEvent('openclaw:native-notifications-status', \
+            {detail:window.__OPENCLAW_NATIVE_NOTIFICATIONS__}));
+            """)
+    }
+}
diff --git a/apps/macos/Sources/OpenClaw/DashboardWindowController.swift b/apps/macos/Sources/OpenClaw/DashboardWindowController.swift
index a9bdd564b20..0b21cee9bfb 100644
--- a/apps/macos/Sources/OpenClaw/DashboardWindowController.swift
+++ b/apps/macos/Sources/OpenClaw/DashboardWindowController.swift
@@ -87,7 +87,7 @@ final class DashboardWindowController: NSWindowController, WKNavigationDelegate,
     private static let windowDragMessageHandlerName = "openclawWindowDrag"
     private static let updateMessageHandlerName = "openclawUpdate"
 
-    private let webView: DashboardWebView
+    let webView: DashboardWebView
     private let linkBrowser: DashboardLinkBrowserView
     private let linkBrowserItem: NSSplitViewItem
     private let linkBrowserSplitView: DashboardLinkSplitView
@@ -137,6 +137,8 @@ final class DashboardWindowController: NSWindowController, WKNavigationDelegate,
         config.userContentController.add(linkMessageHandler, name: Self.linkMessageHandlerName)
         let windowDragMessageHandler = DashboardWindowDragMessageHandler()
         config.userContentController.add(windowDragMessageHandler, name: Self.windowDragMessageHandlerName)
+        let notificationsMessageHandler = DashboardNotificationsMessageHandler()
+        config.userContentController.add(notificationsMessageHandler, name: Self.notificationsMessageHandlerName)
         let updateMessageHandler = DashboardUpdateMessageHandler()
         self.updateMessageHandler = updateMessageHandler
         if shouldEnableUpdateBridge {
@@ -200,6 +202,7 @@ final class DashboardWindowController: NSWindowController, WKNavigationDelegate,
         self.linkBrowserItem.isCollapsed = true
         linkMessageHandler.owner = self
         windowDragMessageHandler.owner = self
+        notificationsMessageHandler.owner = self
         updateMessageHandler.owner = self
         self.webView.navigationDelegate = self
         self.webView.uiDelegate = self
diff --git a/apps/macos/Tests/OpenClawIPCTests/DashboardNotificationsBridgeTests.swift b/apps/macos/Tests/OpenClawIPCTests/DashboardNotificationsBridgeTests.swift
new file mode 100644
index 00000000000..f2c23e9b2e4
--- /dev/null
+++ b/apps/macos/Tests/OpenClawIPCTests/DashboardNotificationsBridgeTests.swift
@@ -0,0 +1,32 @@
+import Testing
+import UserNotifications
+@testable import OpenClaw
+
+@MainActor
+struct DashboardNotificationsBridgeTests {
+    @Test func `parses notification requests`() {
+        #expect(DashboardWindowController.notificationsRequest(from: ["type": "status"]) == .status)
+        #expect(DashboardWindowController.notificationsRequest(
+            from: ["type": "request-permission"]) == .requestPermission)
+        #expect(DashboardWindowController.notificationsRequest(
+            from: ["type": "send-test"]) == .sendTest)
+    }
+
+    @Test func `rejects invalid notification requests`() {
+        #expect(DashboardWindowController.notificationsRequest(from: ["type": "unknown"]) == nil)
+        #expect(DashboardWindowController.notificationsRequest(from: "status") == nil)
+    }
+
+    @Test func `maps notification permission labels`() throws {
+        #expect(DashboardWindowController.notificationsPermissionLabel(for: .authorized) == "granted")
+        #expect(DashboardWindowController.notificationsPermissionLabel(for: .provisional) == "granted")
+        // Ephemeral (unavailable by name on macOS, raw value 4) cannot occur here
+        // and maps to notDetermined with the rest of the default branch.
+        let ephemeral = try #require(UNAuthorizationStatus(rawValue: 4))
+        #expect(DashboardWindowController.notificationsPermissionLabel(
+            for: ephemeral) == "notDetermined")
+        #expect(DashboardWindowController.notificationsPermissionLabel(for: .denied) == "denied")
+        #expect(DashboardWindowController.notificationsPermissionLabel(
+            for: .notDetermined) == "notDetermined")
+    }
+}
diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md
index ec70be7944f..329422a51b8 100644
--- a/docs/platforms/macos.md
+++ b/docs/platforms/macos.md
@@ -110,6 +110,9 @@ See [Gateway on macOS](/platforms/mac/bundled-gateway) for manual recovery.
   permission attribution while the CLI runtime owns shared node policy.
 - Remote-mode SSH tunnels or direct Gateway connections.
 
+In the embedded Control UI, **Settings → Notifications** shows the app's native
+notification permission instead of browser push because the app delivers notifications natively.
+
 The app does **not** replace the Gateway or general CLI docs. Gateway
 configuration, providers, plugins, channels, tools, and security live in their
 own docs.
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 9df3e47c303..dfb055b15f4 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -455,6 +455,8 @@ states that need your input rather than waiting.
 
 The Control UI ships a `manifest.webmanifest` and a service worker, so modern browsers can install it as a standalone PWA. Web Push lets the Gateway wake the installed PWA with notifications even when the tab or browser window is not open.
 
+Inside the macOS app, the Notifications settings page shows the app's native notification permission instead of browser push because the app delivers notifications natively.
+
 If the page shows **Protocol mismatch** right after an OpenClaw update, first reopen the dashboard with `openclaw dashboard` and hard-refresh. If it still fails, clear site data for the dashboard origin or test in a private browser window; an old tab or browser service-worker cache can keep running a pre-update Control UI bundle against the newer Gateway.
 
 | Surface                                            | What it does                                                                 |
diff --git a/ui/src/app/bootstrap.ts b/ui/src/app/bootstrap.ts
index 5ba6551e634..1ad36ea4b64 100644
--- a/ui/src/app/bootstrap.ts
+++ b/ui/src/app/bootstrap.ts
@@ -36,6 +36,7 @@ import { syncCustomThemeStyleTag } from "./custom-theme.ts";
 import { createApplicationGateway } from "./gateway-store.ts";
 import { createNativeChatDrafts } from "./native-bridge.ts";
 import { startNativeLinkRouting } from "./native-link-routing.ts";
+import { createNativeNotificationsCapability } from "./native-notifications.ts";
 import { createApplicationOverlays } from "./overlays.ts";
 import {
   loadSettings,
@@ -319,6 +320,7 @@ export function bootstrapApplication(): ApplicationRuntime {
   const theme = createApplicationTheme(settings);
   const nativeChatDrafts = createNativeChatDrafts();
   const nativeLinkRouting = startNativeLinkRouting();
+  const nativeNotifications = createNativeNotificationsCapability();
   const webPush = createWebPushCapability(gateway);
   const skillWorkshopRevision = createSkillWorkshopRevisionHandoff();
   applyStartupPresentation(settings);
@@ -390,6 +392,7 @@ export function bootstrapApplication(): ApplicationRuntime {
     navigation,
     theme,
     nativeChatDrafts,
+    nativeNotifications,
     webPush,
     skillWorkshopRevision,
     navigate: (routeId, options) => {
@@ -447,6 +450,7 @@ export function bootstrapApplication(): ApplicationRuntime {
       theme.dispose();
       nativeChatDrafts.dispose();
       nativeLinkRouting.dispose();
+      nativeNotifications?.dispose();
       webPush.dispose();
       skillWorkshopRevision.clear();
     },
diff --git a/ui/src/app/context.ts b/ui/src/app/context.ts
index db48815717f..e31ac77c557 100644
--- a/ui/src/app/context.ts
+++ b/ui/src/app/context.ts
@@ -12,6 +12,7 @@ import type { AgentSelectionCapability } from "./agent-selection.ts";
 import type { ApplicationConfigCapability } from "./config.ts";
 import type { ApplicationGateway } from "./gateway.ts";
 import type { NativeChatDrafts } from "./native-bridge.ts";
+import type { NativeNotificationsCapability } from "./native-notifications.ts";
 import type { ApplicationOverlays } from "./overlays.ts";
 import type { ThemeMode } from "./theme.ts";
 import type { WebPushCapability } from "./web-push.ts";
@@ -73,6 +74,7 @@ export type ApplicationContext<TRouteId extends string = string> = {
   readonly navigation: ApplicationNavigationPreferences;
   readonly theme: ApplicationTheme;
   readonly nativeChatDrafts: NativeChatDrafts;
+  readonly nativeNotifications: NativeNotificationsCapability | null;
   readonly webPush: WebPushCapability;
   readonly skillWorkshopRevision: ApplicationSkillWorkshopRevisionHandoff;
   readonly navigate: (routeId: TRouteId, options?: ApplicationNavigationOptions) => void;
diff --git a/ui/src/app/native-notifications.test.ts b/ui/src/app/native-notifications.test.ts
new file mode 100644
index 00000000000..3b6b01c783e
--- /dev/null
+++ b/ui/src/app/native-notifications.test.ts
@@ -0,0 +1,140 @@
+/* @vitest-environment jsdom */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createNativeNotificationsCapability,
+  type NativeNotificationsCapability,
+} from "./native-notifications.ts";
+
+// Wire contract shared with the Mac app bridge; asserted literally on purpose.
+const NATIVE_NOTIFICATIONS_STATUS_EVENT = "openclaw:native-notifications-status";
+
+type NativeNotificationsMessage = {
+  type: "status" | "request-permission" | "send-test";
+};
+
+type NativeNotificationsTestWindow = Window & {
+  __OPENCLAW_NATIVE_NOTIFICATIONS__?: unknown;
+};
+
+let capability: NativeNotificationsCapability | null = null;
+
+afterEach(() => {
+  capability?.dispose();
+  capability = null;
+  Reflect.deleteProperty(
+    window as NativeNotificationsTestWindow,
+    "__OPENCLAW_NATIVE_NOTIFICATIONS__",
+  );
+  vi.unstubAllGlobals();
+});
+
+function installBridge() {
+  const postMessage = vi.fn<(message: NativeNotificationsMessage) => void>();
+  vi.stubGlobal("webkit", {
+    messageHandlers: { openclawNotifications: { postMessage } },
+  });
+  return postMessage;
+}
+
+describe("native notifications", () => {
+  it("returns null without the WebKit bridge", () => {
+    expect(createNativeNotificationsCapability()).toBeNull();
+  });
+
+  it("posts status on create", () => {
+    const postMessage = installBridge();
+
+    capability = createNativeNotificationsCapability();
+
+    expect(capability?.snapshot).toEqual({ permission: "unknown" });
+    expect(postMessage).toHaveBeenCalledWith({ type: "status" });
+  });
+
+  it("seeds status from the native snapshot", () => {
+    installBridge();
+    (window as NativeNotificationsTestWindow)["__OPENCLAW_NATIVE_NOTIFICATIONS__"] = {
+      permission: "granted",
+    };
+
+    capability = createNativeNotificationsCapability();
+
+    expect(capability?.snapshot).toEqual({ permission: "granted" });
+  });
+
+  it("publishes valid status events", () => {
+    installBridge();
+    capability = createNativeNotificationsCapability();
+    const listener = vi.fn();
+    capability?.subscribe(listener);
+
+    window.dispatchEvent(
+      new CustomEvent(NATIVE_NOTIFICATIONS_STATUS_EVENT, {
+        detail: { permission: "denied" },
+      }),
+    );
+
+    expect(capability?.snapshot).toEqual({ permission: "denied" });
+    expect(listener).toHaveBeenCalledWith({ permission: "denied" });
+  });
+
+  it("ignores invalid status event details", () => {
+    installBridge();
+    capability = createNativeNotificationsCapability();
+    const listener = vi.fn();
+    capability?.subscribe(listener);
+
+    window.dispatchEvent(
+      new CustomEvent(NATIVE_NOTIFICATIONS_STATUS_EVENT, {
+        detail: { permission: "authorized" },
+      }),
+    );
+
+    expect(capability?.snapshot).toEqual({ permission: "unknown" });
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("reposts status when the window focuses", () => {
+    const postMessage = installBridge();
+    capability = createNativeNotificationsCapability();
+    postMessage.mockClear();
+
+    window.dispatchEvent(new Event("focus"));
+
+    expect(postMessage).toHaveBeenCalledWith({ type: "status" });
+  });
+
+  it("posts permission and test actions", () => {
+    const postMessage = installBridge();
+    capability = createNativeNotificationsCapability();
+    postMessage.mockClear();
+
+    capability?.requestPermission();
+    capability?.sendTest();
+
+    expect(postMessage.mock.calls).toEqual([
+      [{ type: "request-permission" }],
+      [{ type: "send-test" }],
+    ]);
+  });
+
+  it("removes listeners on dispose", () => {
+    const postMessage = installBridge();
+    capability = createNativeNotificationsCapability();
+    const listener = vi.fn();
+    capability?.subscribe(listener);
+    capability?.dispose();
+    capability = null;
+    postMessage.mockClear();
+
+    window.dispatchEvent(new Event("focus"));
+    window.dispatchEvent(
+      new CustomEvent(NATIVE_NOTIFICATIONS_STATUS_EVENT, {
+        detail: { permission: "granted" },
+      }),
+    );
+
+    expect(postMessage).not.toHaveBeenCalled();
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
diff --git a/ui/src/app/native-notifications.ts b/ui/src/app/native-notifications.ts
new file mode 100644
index 00000000000..509af04e064
--- /dev/null
+++ b/ui/src/app/native-notifications.ts
@@ -0,0 +1,111 @@
+export type NativeNotificationsPermission = "granted" | "denied" | "notDetermined";
+
+type NativeNotificationsSnapshot = {
+  permission: NativeNotificationsPermission | "unknown";
+};
+
+type NativeNotificationsMessage =
+  | { type: "status" }
+  | { type: "request-permission" }
+  | { type: "send-test" };
+
+type WebKitNotificationsMessageHandler = {
+  postMessage(message: NativeNotificationsMessage): void;
+};
+
+type NativeNotificationsWindow = Window & {
+  __OPENCLAW_NATIVE_NOTIFICATIONS__?: unknown;
+  webkit?: {
+    messageHandlers?: {
+      openclawNotifications?: WebKitNotificationsMessageHandler;
+    };
+  };
+};
+
+// Wire contract with the Mac app's dashboard bridge (DashboardWindowController+Notifications.swift).
+const NATIVE_NOTIFICATIONS_STATUS_EVENT = "openclaw:native-notifications-status";
+
+export type NativeNotificationsCapability = {
+  readonly snapshot: NativeNotificationsSnapshot;
+  subscribe(listener: (snapshot: NativeNotificationsSnapshot) => void): () => void;
+  requestPermission(): void;
+  sendTest(): void;
+  dispose(): void;
+};
+
+function isNativeNotificationsPermission(value: unknown): value is NativeNotificationsPermission {
+  return value === "granted" || value === "denied" || value === "notDetermined";
+}
+
+function snapshotFrom(value: unknown): NativeNotificationsSnapshot | null {
+  if (typeof value !== "object" || value === null || !("permission" in value)) {
+    return null;
+  }
+  return isNativeNotificationsPermission(value.permission)
+    ? { permission: value.permission }
+    : null;
+}
+
+function getNativeNotificationsPoster():
+  | WebKitNotificationsMessageHandler["postMessage"]
+  | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+  const handler = (window as NativeNotificationsWindow).webkit?.messageHandlers
+    ?.openclawNotifications;
+  return handler?.postMessage.bind(handler);
+}
+
+export function createNativeNotificationsCapability(): NativeNotificationsCapability | null {
+  const postMessage = getNativeNotificationsPoster();
+  if (!postMessage) {
+    return null;
+  }
+
+  const nativeWindow = window as NativeNotificationsWindow;
+  let snapshot = snapshotFrom(nativeWindow["__OPENCLAW_NATIVE_NOTIFICATIONS__"]) ?? {
+    permission: "unknown" as const,
+  };
+  const listeners = new Set<(snapshot: NativeNotificationsSnapshot) => void>();
+
+  const publish = (next: NativeNotificationsSnapshot) => {
+    snapshot = next;
+    for (const listener of listeners) {
+      listener(snapshot);
+    }
+  };
+  const handleStatus = (event: Event) => {
+    const next = snapshotFrom((event as CustomEvent<unknown>).detail);
+    if (next) {
+      publish(next);
+    }
+  };
+  // Permission may change in System Settings while the app is backgrounded.
+  const refreshStatus = () => postMessage({ type: "status" });
+
+  window.addEventListener(NATIVE_NOTIFICATIONS_STATUS_EVENT, handleStatus);
+  window.addEventListener("focus", refreshStatus);
+  refreshStatus();
+
+  return {
+    get snapshot() {
+      return snapshot;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    requestPermission() {
+      postMessage({ type: "request-permission" });
+    },
+    sendTest() {
+      postMessage({ type: "send-test" });
+    },
+    dispose() {
+      window.removeEventListener(NATIVE_NOTIFICATIONS_STATUS_EVENT, handleStatus);
+      window.removeEventListener("focus", refreshStatus);
+      listeners.clear();
+    },
+  };
+}
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 3a5f8e393e4..7222308f3a1 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -1211,9 +1211,12 @@ export const en: TranslationMap = {
     syncedHint: "Synced across your devices through the gateway.",
     notifications: {
       title: "Push notifications",
+      nativeTitle: "Notifications",
       hint: "Receive browser push notifications from your gateway.",
+      nativeHint: "Notifications are shown natively by the OpenClaw app on this Mac.",
       unavailableHint: "Not available in this browser.",
       unavailable: "Unavailable",
+      checking: "Checking...",
       granted: "Granted",
       denied: "Denied",
       notRequested: "Not requested",
@@ -1231,8 +1234,11 @@ export const en: TranslationMap = {
       sendTest: "Send test",
       subscribing: "Subscribing...",
       enable: "Enable notifications",
+      openSystemSettings: "Open System Settings",
       blockedHint:
         "Notifications are blocked. Update your browser site permissions to allow notifications.",
+      nativeBlockedHint:
+        "Notifications are disabled for OpenClaw in macOS. Allow them in System Settings > Notifications.",
     },
     appearance: {
       theme: "Theme",
diff --git a/ui/src/pages/config/config-page.ts b/ui/src/pages/config/config-page.ts
index d74d9782c84..533b1943dd9 100644
--- a/ui/src/pages/config/config-page.ts
+++ b/ui/src/pages/config/config-page.ts
@@ -293,6 +293,10 @@ export class ConfigPage extends OpenClawLightDomElement {
       (gateway, notify) => gateway.subscribe(notify),
       (gateway) => this.synchronizeSystemInfoGateway(gateway),
     )
+    .watch(
+      () => this.context?.nativeNotifications ?? undefined,
+      (nativeNotifications, notify) => nativeNotifications.subscribe(notify),
+    )
     .watch(
       () => this.context?.webPush,
       (webPush, notify) => webPush.subscribe(notify),
@@ -813,6 +817,10 @@ export class ConfigPage extends OpenClawLightDomElement {
       excludeSections,
       includeVirtualSections: this.pageId === "appearance" || this.pageId === "notifications",
       settingsLayout: this.pageId === "advanced" ? "accordion" : undefined,
+      nativeNotifications: this.context.nativeNotifications?.snapshot,
+      onNativeNotificationsRequestPermission: () =>
+        this.context.nativeNotifications?.requestPermission(),
+      onNativeNotificationsSendTest: () => this.context.nativeNotifications?.sendTest(),
       webPush: this.context.webPush.snapshot,
       onWebPushSubscribe: () => void this.context.webPush.enable(),
       onWebPushUnsubscribe: () => void this.context.webPush.disable(),
diff --git a/ui/src/pages/config/notifications-section.ts b/ui/src/pages/config/notifications-section.ts
new file mode 100644
index 00000000000..c017ae6c9df
--- /dev/null
+++ b/ui/src/pages/config/notifications-section.ts
@@ -0,0 +1,261 @@
+import { html, nothing } from "lit";
+import type { NativeNotificationsPermission } from "../../app/native-notifications.ts";
+import { icons } from "../../components/icons.ts";
+import {
+  renderSettingsRow,
+  renderSettingsStatus,
+  renderSettingsValue,
+} from "../../components/settings-ui.ts";
+import { t } from "../../i18n/index.ts";
+import { COMMUNICATION_SETTINGS_TARGET_IDS } from "./settings-targets.ts";
+
+export type WebPushUiState = {
+  supported: boolean;
+  permission: NotificationPermission | "unsupported";
+  subscribed: boolean;
+  loading: boolean;
+  error?: string | null;
+};
+
+// Leaf props contract: view.ts imports this module, so importing ConfigProps
+// back from view.ts would create an import cycle. ConfigProps is structurally
+// assignable to this subset.
+type NotificationsSectionProps = {
+  connected: boolean;
+  nativeNotifications?: { permission: NativeNotificationsPermission | "unknown" };
+  onNativeNotificationsRequestPermission?: () => void;
+  onNativeNotificationsSendTest?: () => void;
+  webPush?: WebPushUiState;
+  onWebPushSubscribe?: () => void;
+  onWebPushUnsubscribe?: () => void;
+  onWebPushTest?: () => void;
+};
+
+function nativeNotificationsStatus(permission: NativeNotificationsPermission | "unknown"): {
+  kind: "ok" | "danger" | "accent" | "muted";
+  label: string;
+} {
+  switch (permission) {
+    case "granted":
+      return { kind: "ok", label: t("configView.notifications.granted") };
+    case "denied":
+      return { kind: "danger", label: t("configView.notifications.denied") };
+    case "notDetermined":
+      return { kind: "accent", label: t("configView.notifications.notRequested") };
+    default:
+      return { kind: "muted", label: t("configView.notifications.checking") };
+  }
+}
+
+export function renderNotificationsSection(props: NotificationsSectionProps) {
+  const native = props.nativeNotifications;
+  if (native) {
+    const status = nativeNotificationsStatus(native.permission);
+    const actionButton =
+      native.permission === "notDetermined"
+        ? html`
+            <button
+              class="btn primary"
+              @click=${() => props.onNativeNotificationsRequestPermission?.()}
+            >
+              ${t("configView.notifications.enable")}
+            </button>
+          `
+        : native.permission === "denied"
+          ? html`
+              <button class="btn" @click=${() => props.onNativeNotificationsRequestPermission?.()}>
+                ${t("configView.notifications.openSystemSettings")}
+              </button>
+            `
+          : native.permission === "granted"
+            ? html`
+                <button class="btn primary" @click=${() => props.onNativeNotificationsSendTest?.()}>
+                  ${icons.send} ${t("configView.notifications.sendTest")}
+                </button>
+              `
+            : nothing;
+
+    return html`
+      <div class="settings-page">
+        <section class="settings-section" id=${COMMUNICATION_SETTINGS_TARGET_IDS.notifications}>
+          <div class="settings-section__header">
+            <h2 class="settings-section__heading">${t("configView.notifications.nativeTitle")}</h2>
+            <div class="settings-section__actions">${renderSettingsStatus(status)}</div>
+          </div>
+          <p class="settings-section__desc">${t("configView.notifications.nativeHint")}</p>
+          <div class="settings-group">
+            ${renderSettingsRow({
+              title: t("configView.notifications.permission"),
+              control: renderSettingsValue(status.label),
+            })}
+            ${actionButton !== nothing
+              ? html`
+                  <div class="settings-row">
+                    <div class="settings-row__control">${actionButton}</div>
+                  </div>
+                `
+              : nothing}
+            ${native.permission === "denied"
+              ? renderSettingsRow({
+                  title: t("configView.notifications.blocked"),
+                  description: t("configView.notifications.nativeBlockedHint"),
+                  control: renderSettingsStatus({
+                    kind: "danger",
+                    label: t("configView.notifications.denied"),
+                  }),
+                })
+              : nothing}
+          </div>
+        </section>
+      </div>
+    `;
+  }
+
+  const push = props.webPush;
+  if (!push) {
+    return html`
+      <div class="settings-page">
+        <section class="settings-section" id=${COMMUNICATION_SETTINGS_TARGET_IDS.notifications}>
+          <div class="settings-section__header">
+            <h2 class="settings-section__heading">${t("configView.notifications.title")}</h2>
+            <div class="settings-section__actions">
+              ${renderSettingsStatus({
+                kind: "muted",
+                label: t("configView.notifications.unavailable"),
+              })}
+            </div>
+          </div>
+          <div class="settings-group">
+            <div class="settings-row">
+              <div class="settings-row__text">
+                <span class="settings-row__desc">
+                  ${t("configView.notifications.unavailableHint")}
+                </span>
+              </div>
+            </div>
+          </div>
+        </section>
+      </div>
+    `;
+  }
+
+  const permissionLabel =
+    push.permission === "granted"
+      ? t("configView.notifications.granted")
+      : push.permission === "denied"
+        ? t("configView.notifications.denied")
+        : push.permission === "default"
+          ? t("configView.notifications.notRequested")
+          : t("configView.notifications.unsupported");
+  const subscriptionLabel = push.subscribed
+    ? t("configView.notifications.subscribed")
+    : t("configView.notifications.notSubscribed");
+  const statusLabel = !push.supported
+    ? t("configView.notifications.unsupported")
+    : push.permission === "denied"
+      ? t("configView.notifications.blocked")
+      : push.subscribed
+        ? t("configView.notifications.subscribed")
+        : t("configView.notifications.ready");
+  const statusKind = !push.supported
+    ? ("muted" as const)
+    : push.permission === "denied"
+      ? ("danger" as const)
+      : push.subscribed
+        ? ("ok" as const)
+        : ("accent" as const);
+
+  const actionButtons =
+    push.supported && push.permission !== "denied"
+      ? push.subscribed
+        ? html`
+            <button
+              class="btn"
+              ?disabled=${push.loading || !props.connected}
+              @click=${() => props.onWebPushUnsubscribe?.()}
+            >
+              ${icons.x} ${t("configView.notifications.unsubscribe")}
+            </button>
+            <button
+              class="btn primary"
+              ?disabled=${push.loading || !props.connected}
+              @click=${() => props.onWebPushTest?.()}
+            >
+              ${icons.send} ${t("configView.notifications.sendTest")}
+            </button>
+          `
+        : html`
+            <button
+              class="btn primary"
+              ?disabled=${push.loading || !props.connected}
+              @click=${() => props.onWebPushSubscribe?.()}
+            >
+              ${push.loading ? icons.loader : nothing}
+              ${push.loading
+                ? t("configView.notifications.subscribing")
+                : t("configView.notifications.enable")}
+            </button>
+          `
+      : nothing;
+
+  return html`
+    <div class="settings-page">
+      <section class="settings-section" id=${COMMUNICATION_SETTINGS_TARGET_IDS.notifications}>
+        <div class="settings-section__header">
+          <h2 class="settings-section__heading">${t("configView.notifications.title")}</h2>
+          <div class="settings-section__actions">
+            ${renderSettingsStatus({ kind: statusKind, label: statusLabel })}
+          </div>
+        </div>
+        <p class="settings-section__desc">${t("configView.notifications.hint")}</p>
+        <div class="settings-group">
+          ${renderSettingsRow({
+            title: t("configView.notifications.browserSupport"),
+            control: renderSettingsValue(
+              push.supported
+                ? t("configView.notifications.available")
+                : t("configView.notifications.notSupported"),
+            ),
+          })}
+          ${renderSettingsRow({
+            title: t("configView.notifications.permission"),
+            control: renderSettingsValue(permissionLabel),
+          })}
+          ${renderSettingsRow({
+            title: t("configView.notifications.status"),
+            control: renderSettingsStatus({
+              kind: push.subscribed ? "ok" : "muted",
+              label: subscriptionLabel,
+            }),
+          })}
+          ${actionButtons !== nothing
+            ? html`
+                <div class="settings-row">
+                  <div class="settings-row__control">${actionButtons}</div>
+                </div>
+              `
+            : nothing}
+          ${push.permission === "denied"
+            ? renderSettingsRow({
+                title: t("configView.notifications.blocked"),
+                description: t("configView.notifications.blockedHint"),
+                control: renderSettingsStatus({
+                  kind: "danger",
+                  label: t("configView.notifications.denied"),
+                }),
+              })
+            : nothing}
+          ${push.error
+            ? html`
+                <div class="settings-row">
+                  <div class="settings-row__text">
+                    <span class="cfg-field__error">${push.error}</span>
+                  </div>
+                </div>
+              `
+            : nothing}
+        </div>
+      </section>
+    </div>
+  `;
+}
diff --git a/ui/src/pages/config/settings-search.ts b/ui/src/pages/config/settings-search.ts
index 1cddf93e3d9..1949e6afb24 100644
--- a/ui/src/pages/config/settings-search.ts
+++ b/ui/src/pages/config/settings-search.ts
@@ -183,6 +183,9 @@ const COMMUNICATION_SETTINGS_BLOCKS = {
       "configView.notifications.subscribed",
       "configView.notifications.notSubscribed",
       "configView.notifications.enable",
+      "configView.notifications.nativeTitle",
+      "configView.notifications.nativeHint",
+      "configView.notifications.openSystemSettings",
     ],
     aliases: "vapid gateway",
   },
diff --git a/ui/src/pages/config/view.ts b/ui/src/pages/config/view.ts
index c7e6e23b07c..6aedc7b69b5 100644
--- a/ui/src/pages/config/view.ts
+++ b/ui/src/pages/config/view.ts
@@ -4,6 +4,7 @@ import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
 import { html, nothing } from "lit";
 import type { QueueMode } from "../../../../src/auto-reply/reply/queue/types.js";
 import type { ConfigUiHints } from "../../api/types.ts";
+import type { NativeNotificationsPermission } from "../../app/native-notifications.ts";
 import {
   normalizeChatFollowUpMode,
   normalizeChatSendShortcut,
@@ -49,11 +50,9 @@ import { t } from "../../i18n/index.ts";
 import type { ConfigAutoSaveStatus } from "../../lib/config/index.ts";
 import { isJson5Warm, parseJson5Text, warmJson5 } from "../../lib/json5-runtime.ts";
 import type { RealtimeTalkInputDevice } from "../chat/realtime-talk-input.ts";
+import { renderNotificationsSection, type WebPushUiState } from "./notifications-section.ts";
 import { renderSettingsSelectRow } from "./settings-select-row.ts";
-import {
-  APPEARANCE_SETTINGS_TARGET_IDS,
-  COMMUNICATION_SETTINGS_TARGET_IDS,
-} from "./settings-targets.ts";
+import { APPEARANCE_SETTINGS_TARGET_IDS } from "./settings-targets.ts";
 
 // The config editor is where JSON5 text first appears; warm the parser with
 // the page instead of racing the first raw-draft keystroke.
@@ -67,14 +66,6 @@ const TEXT_SCALE_LABELS: Record<TextScaleStop, string> = {
   140: "configView.textSizes.xxl",
 };
 
-type WebPushUiState = {
-  supported: boolean;
-  permission: NotificationPermission | "unsupported";
-  subscribed: boolean;
-  loading: boolean;
-  error?: string | null;
-};
-
 type SettingsMicrophoneState = {
   devices: RealtimeTalkInputDevice[];
   selectedDeviceId: string;
@@ -203,6 +194,9 @@ export type ConfigProps = {
   includeVirtualSections?: boolean;
   /** Layout mode: "tabs" (default flat scroll) or "accordion" (grouped collapsible). */
   settingsLayout?: "tabs" | "accordion";
+  nativeNotifications?: { permission: NativeNotificationsPermission | "unknown" };
+  onNativeNotificationsRequestPermission?: () => void;
+  onNativeNotificationsSendTest?: () => void;
   webPush?: WebPushUiState;
   onWebPushSubscribe?: () => void;
   onWebPushUnsubscribe?: () => void;
@@ -908,156 +902,6 @@ function focusCustomThemeImportInput() {
   });
 }
 
-function renderNotificationsSection(props: ConfigProps) {
-  const push = props.webPush;
-  if (!push) {
-    return html`
-      <div class="settings-page">
-        <section class="settings-section" id=${COMMUNICATION_SETTINGS_TARGET_IDS.notifications}>
-          <div class="settings-section__header">
-            <h2 class="settings-section__heading">${t("configView.notifications.title")}</h2>
-            <div class="settings-section__actions">
-              ${renderSettingsStatus({
-                kind: "muted",
-                label: t("configView.notifications.unavailable"),
-              })}
-            </div>
-          </div>
-          <div class="settings-group">
-            <div class="settings-row">
-              <div class="settings-row__text">
-                <span class="settings-row__desc">
-                  ${t("configView.notifications.unavailableHint")}
-                </span>
-              </div>
-            </div>
-          </div>
-        </section>
-      </div>
-    `;
-  }
-
-  const permissionLabel =
-    push.permission === "granted"
-      ? t("configView.notifications.granted")
-      : push.permission === "denied"
-        ? t("configView.notifications.denied")
-        : push.permission === "default"
-          ? t("configView.notifications.notRequested")
-          : t("configView.notifications.unsupported");
-  const subscriptionLabel = push.subscribed
-    ? t("configView.notifications.subscribed")
-    : t("configView.notifications.notSubscribed");
-  const statusLabel = !push.supported
-    ? t("configView.notifications.unsupported")
-    : push.permission === "denied"
-      ? t("configView.notifications.blocked")
-      : push.subscribed
-        ? t("configView.notifications.subscribed")
-        : t("configView.notifications.ready");
-  const statusKind = !push.supported
-    ? ("muted" as const)
-    : push.permission === "denied"
-      ? ("danger" as const)
-      : push.subscribed
-        ? ("ok" as const)
-        : ("accent" as const);
-
-  const actionButtons =
-    push.supported && push.permission !== "denied"
-      ? push.subscribed
-        ? html`
-            <button
-              class="btn"
-              ?disabled=${push.loading || !props.connected}
-              @click=${() => props.onWebPushUnsubscribe?.()}
-            >
-              ${icons.x} ${t("configView.notifications.unsubscribe")}
-            </button>
-            <button
-              class="btn primary"
-              ?disabled=${push.loading || !props.connected}
-              @click=${() => props.onWebPushTest?.()}
-            >
-              ${icons.send} ${t("configView.notifications.sendTest")}
-            </button>
-          `
-        : html`
-            <button
-              class="btn primary"
-              ?disabled=${push.loading || !props.connected}
-              @click=${() => props.onWebPushSubscribe?.()}
-            >
-              ${push.loading ? icons.loader : nothing}
-              ${push.loading
-                ? t("configView.notifications.subscribing")
-                : t("configView.notifications.enable")}
-            </button>
-          `
-      : nothing;
-
-  return html`
-    <div class="settings-page">
-      <section class="settings-section" id=${COMMUNICATION_SETTINGS_TARGET_IDS.notifications}>
-        <div class="settings-section__header">
-          <h2 class="settings-section__heading">${t("configView.notifications.title")}</h2>
-          <div class="settings-section__actions">
-            ${renderSettingsStatus({ kind: statusKind, label: statusLabel })}
-          </div>
-        </div>
-        <p class="settings-section__desc">${t("configView.notifications.hint")}</p>
-        <div class="settings-group">
-          ${renderSettingsRow({
-            title: t("configView.notifications.browserSupport"),
-            control: renderSettingsValue(
-              push.supported
-                ? t("configView.notifications.available")
-                : t("configView.notifications.notSupported"),
-            ),
-          })}
-          ${renderSettingsRow({
-            title: t("configView.notifications.permission"),
-            control: renderSettingsValue(permissionLabel),
-          })}
-          ${renderSettingsRow({
-            title: t("configView.notifications.status"),
-            control: renderSettingsStatus({
-              kind: push.subscribed ? "ok" : "muted",
-              label: subscriptionLabel,
-            }),
-          })}
-          ${actionButtons !== nothing
-            ? html`
-                <div class="settings-row">
-                  <div class="settings-row__control">${actionButtons}</div>
-                </div>
-              `
-            : nothing}
-          ${push.permission === "denied"
-            ? renderSettingsRow({
-                title: t("configView.notifications.blocked"),
-                description: t("configView.notifications.blockedHint"),
-                control: renderSettingsStatus({
-                  kind: "danger",
-                  label: t("configView.notifications.denied"),
-                }),
-              })
-            : nothing}
-          ${push.error
-            ? html`
-                <div class="settings-row">
-                  <div class="settings-row__text">
-                    <span class="cfg-field__error">${push.error}</span>
-                  </div>
-                </div>
-              `
-            : nothing}
-        </div>
-      </section>
-    </div>
-  `;
-}
-
 function renderSettingsMicrophoneField(props: ConfigProps) {
   const microphone = props.microphone;
   if (!microphone || !props.onMicrophoneSelect) {

From b5d9573dcaf62ed15d89d7e46004e73a481cdd4e Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Sat, 18 Jul 2026 07:39:16 +0100
Subject: [PATCH 68/76] fix: pause hidden session catalog polling

---
 ui/src/components/app-sidebar-session-data.ts | 14 ++++-
 .../app-sidebar-cases/catalog-live-events.ts  | 59 ++++++++++++++++++-
 2 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/ui/src/components/app-sidebar-session-data.ts b/ui/src/components/app-sidebar-session-data.ts
index 3823ee8d50c..6a1f17c46bd 100644
--- a/ui/src/components/app-sidebar-session-data.ts
+++ b/ui/src/components/app-sidebar-session-data.ts
@@ -175,12 +175,11 @@ export abstract class AppSidebarSessionDataElement extends AppSidebarBase {
 
   override updated() {
     this.syncSessionsScrollObserver();
-    const snapshot = this.context?.gateway.snapshot;
     if (this.context) {
       this.synchronizeSessionCatalogAgent(this.expandedAgentId());
     }
     if (
-      !sessionCatalogListClient(snapshot, this.connected) ||
+      !this.visibleSessionCatalogClient() ||
       this.sessionCatalogLive.timer ||
       this.sessionCatalogLive.requestGeneration === this.sessionCatalogGeneration
     ) {
@@ -189,6 +188,13 @@ export abstract class AppSidebarSessionDataElement extends AppSidebarBase {
     void this.refreshSessionCatalogs();
   }
 
+  private visibleSessionCatalogClient(): GatewayBrowserClient | null {
+    if (document.visibilityState === "hidden") {
+      return null;
+    }
+    return sessionCatalogListClient(this.context?.gateway.snapshot, this.connected);
+  }
+
   private synchronizeSessionCatalogAgent(agentId: string) {
     if (agentId === this.sessionCatalogAgentId) {
       return;
@@ -265,7 +271,9 @@ export abstract class AppSidebarSessionDataElement extends AppSidebarBase {
   }
 
   private async refreshSessionCatalogs() {
-    const client = sessionCatalogListClient(this.context?.gateway.snapshot, this.connected);
+    // Hidden pages resume through the coalesced activation handler. Starting
+    // here without a timer makes catalog state updates poll at request latency.
+    const client = this.visibleSessionCatalogClient();
     if (!client) {
       return;
     }
diff --git a/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts b/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
index 1f03de248fa..e527c16904b 100644
--- a/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
@@ -1,7 +1,14 @@
 import { describe, expect, it, vi } from "vitest";
+import type { SessionsCatalogListResult } from "../../../../packages/gateway-protocol/src/index.ts";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
 import type { ApplicationGatewaySnapshot } from "../../app/context.ts";
-import { catalogPage, createGatewayHarness, createSessions, mountSidebar } from "../app-sidebar.ts";
+import {
+  catalogPage,
+  createGatewayHarness,
+  createSessions,
+  deferred,
+  mountSidebar,
+} from "../app-sidebar.ts";
 import "../../components/app-sidebar.ts";
 
 describe("AppSidebar session catalog pagination", () => {
@@ -44,6 +51,56 @@ describe("AppSidebar session catalog pagination", () => {
     }
   });
 
+  it("stays paused when an in-flight catalog refresh finishes in a hidden tab", async () => {
+    vi.useFakeTimers();
+    let visibility: DocumentVisibilityState = "visible";
+    const visibilitySpy = vi
+      .spyOn(document, "visibilityState", "get")
+      .mockImplementation(() => visibility);
+    try {
+      const pending = deferred<SessionsCatalogListResult>();
+      const request = vi
+        .fn()
+        .mockReturnValueOnce(pending.promise)
+        .mockResolvedValue(catalogPage([]));
+      const gateway = createGatewayHarness({ request } as unknown as GatewayBrowserClient);
+      gateway.publish({
+        hello: {
+          features: { methods: ["sessions.catalog.list"] },
+        } as ApplicationGatewaySnapshot["hello"],
+      });
+      const { sidebar } = await mountSidebar(
+        gateway.gateway,
+        createSessions("main", ["agent:main:main"]),
+      );
+      sidebar.connected = true;
+      await sidebar.updateComplete;
+      await vi.advanceTimersByTimeAsync(0);
+      expect(request).toHaveBeenCalledTimes(1);
+
+      visibility = "hidden";
+      document.dispatchEvent(new Event("visibilitychange"));
+      pending.resolve(catalogPage([]));
+      await vi.advanceTimersByTimeAsync(0);
+      await sidebar.updateComplete;
+      await vi.advanceTimersByTimeAsync(60_000);
+      expect(request).toHaveBeenCalledTimes(1);
+
+      visibility = "visible";
+      document.dispatchEvent(new Event("visibilitychange"));
+      globalThis.dispatchEvent(new Event("focus"));
+      await vi.advanceTimersByTimeAsync(49);
+      expect(request).toHaveBeenCalledTimes(1);
+      await vi.advanceTimersByTimeAsync(1);
+      expect(request).toHaveBeenCalledTimes(2);
+      await vi.advanceTimersByTimeAsync(0);
+      expect(request).toHaveBeenCalledTimes(2);
+    } finally {
+      visibilitySpy.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
   it("does not poll an older Gateway that does not advertise session catalogs", async () => {
     vi.useFakeTimers();
     try {

From e4fd904f8ae6422c801532cff24d033cf28b65b5 Mon Sep 17 00:00:00 2001
From: Shakker <shakkerdroid@gmail.com>
Date: Sat, 18 Jul 2026 08:03:41 +0100
Subject: [PATCH 69/76] test: cover hidden catalog polling across reconnects
 (#110705)

---
 .../app-sidebar-cases/catalog-live-events.ts  | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts b/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
index e527c16904b..bd0291de152 100644
--- a/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
+++ b/ui/src/test-helpers/app-sidebar-cases/catalog-live-events.ts
@@ -101,6 +101,61 @@ describe("AppSidebar session catalog pagination", () => {
     }
   });
 
+  it("stays paused through a Gateway reconnect while the tab is hidden", async () => {
+    vi.useFakeTimers();
+    let visibility: DocumentVisibilityState = "visible";
+    const visibilitySpy = vi
+      .spyOn(document, "visibilityState", "get")
+      .mockImplementation(() => visibility);
+    try {
+      const foregroundRequest = deferred<SessionsCatalogListResult>();
+      const request = vi
+        .fn()
+        .mockResolvedValueOnce(catalogPage([]))
+        .mockReturnValue(foregroundRequest.promise);
+      const gateway = createGatewayHarness({ request } as unknown as GatewayBrowserClient);
+      gateway.publish({
+        hello: {
+          features: { methods: ["sessions.catalog.list"] },
+        } as ApplicationGatewaySnapshot["hello"],
+      });
+      const { sidebar } = await mountSidebar(
+        gateway.gateway,
+        createSessions("main", ["agent:main:main"]),
+      );
+      sidebar.connected = true;
+      await sidebar.updateComplete;
+      await vi.advanceTimersByTimeAsync(0);
+      expect(request).toHaveBeenCalledTimes(1);
+
+      visibility = "hidden";
+      document.dispatchEvent(new Event("visibilitychange"));
+      gateway.publish({ connected: false, reconnecting: true, hello: null });
+      await sidebar.updateComplete;
+      gateway.publish({
+        connected: true,
+        reconnecting: false,
+        hello: {
+          features: { methods: ["sessions.catalog.list"] },
+        } as ApplicationGatewaySnapshot["hello"],
+      });
+      await sidebar.updateComplete;
+      await vi.advanceTimersByTimeAsync(60_000);
+      expect(request).toHaveBeenCalledTimes(1);
+
+      visibility = "visible";
+      document.dispatchEvent(new Event("visibilitychange"));
+      globalThis.dispatchEvent(new Event("focus"));
+      await vi.advanceTimersByTimeAsync(50);
+      expect(request).toHaveBeenCalledTimes(2);
+      foregroundRequest.resolve(catalogPage([]));
+      await vi.advanceTimersByTimeAsync(0);
+    } finally {
+      visibilitySpy.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
   it("does not poll an older Gateway that does not advertise session catalogs", async () => {
     vi.useFakeTimers();
     try {

From 9710a1339e3ca63ccc51ee79d2dd0c8c00917726 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 14:40:45 +0100
Subject: [PATCH 70/76] refactor(canvas): promote inline-widget hosting and
 show_widget to core (#110475)

* refactor(canvas): promote inline widgets to core

* docs(agents): note discord show_widget ownership at core registration

* ci: retrigger after GitHub scheduling outage

* fix(canvas): satisfy dead-code and test type checks
---
 docs/tools/show-widget.md                     |  14 +-
 docs/web/control-ui.md                        |   2 +-
 extensions/canvas/doctor-contract-api.test.ts | 152 ++++++++++
 extensions/canvas/doctor-contract-api.ts      | 128 +++++++++
 extensions/canvas/index.test.ts               |  61 +---
 extensions/canvas/index.ts                    |  47 +---
 extensions/canvas/openclaw.plugin.json        |   2 +-
 extensions/canvas/runtime-api.ts              |  12 +-
 extensions/canvas/src/documents.test.ts       | 265 ------------------
 extensions/canvas/src/host/server.test.ts     |  37 +--
 extensions/canvas/src/host/server.ts          |  37 +--
 extensions/canvas/src/tool-schema.ts          |   9 -
 extensions/canvas/src/widget-tool.ts          | 123 --------
 src/agents/core-tool-factory-descriptors.ts   |   1 +
 src/agents/openclaw-tools.client-caps.test.ts |  23 +-
 src/agents/openclaw-tools.ts                  |  11 +
 src/agents/tool-catalog.ts                    |   8 +
 src/canvas/constants.test.ts                  |  31 ++
 src/canvas/constants.ts                       |  33 +++
 src/canvas/documents.test.ts                  | 187 ++++++++++++
 .../canvas/src => src/canvas}/documents.ts    | 135 +++------
 src/canvas/serve.runtime.test.ts              | 102 +++++++
 src/canvas/serve.runtime.ts                   |  99 +++++++
 .../src => src/canvas}/widget-tool.test.ts    |  55 ++--
 src/canvas/widget-tool.ts                     |  78 ++++++
 src/canvas/wrap.ts                            |  53 ++++
 src/gateway/server-http.ts                    |  24 +-
 src/gateway/server-runtime-state.ts           |  13 +-
 src/gateway/server.impl.ts                    |   4 +-
 src/media/web-media.test.ts                   |  29 +-
 src/media/web-media.ts                        |   6 +-
 src/plugins/tools.optional.test.ts            |  41 +--
 32 files changed, 1033 insertions(+), 789 deletions(-)
 create mode 100644 extensions/canvas/doctor-contract-api.test.ts
 create mode 100644 extensions/canvas/doctor-contract-api.ts
 delete mode 100644 extensions/canvas/src/documents.test.ts
 delete mode 100644 extensions/canvas/src/widget-tool.ts
 create mode 100644 src/canvas/constants.test.ts
 create mode 100644 src/canvas/constants.ts
 create mode 100644 src/canvas/documents.test.ts
 rename {extensions/canvas/src => src/canvas}/documents.ts (76%)
 create mode 100644 src/canvas/serve.runtime.test.ts
 create mode 100644 src/canvas/serve.runtime.ts
 rename {extensions/canvas/src => src/canvas}/widget-tool.test.ts (73%)
 create mode 100644 src/canvas/widget-tool.ts
 create mode 100644 src/canvas/wrap.ts

diff --git a/docs/tools/show-widget.md b/docs/tools/show-widget.md
index 8c863cdf909..66b87b6efbc 100644
--- a/docs/tools/show-widget.md
+++ b/docs/tools/show-widget.md
@@ -8,11 +8,11 @@ read_when:
   - You need the show_widget input, security, or retention contract
 ---
 
-`show_widget` shows a self-contained HTML widget on the user's current surface. The Canvas plugin renders it inline in the Control UI, iOS, Android, and macOS chat transcripts; Linux uses the browser Control UI. In a Discord session with [Activities](/channels/discord-activities) enabled, the Discord plugin posts an **Open widget** button that launches it as an Activity.
+`show_widget` is a core tool that shows a self-contained HTML widget on the user's current surface. OpenClaw renders it inline in the Control UI, iOS, Android, and macOS chat transcripts; Linux uses the browser Control UI. In a Discord session with [Activities](/channels/discord-activities) enabled, the Discord plugin posts an **Open widget** button that launches it as an Activity.
 
 ## How widgets work
 
-When the agent calls `show_widget`, the Canvas plugin wraps `widget_code` in a minimal HTML document, stores it as a Canvas document, and returns a preview handle. The Control UI renders that handle as a sandboxed iframe directly under the tool call, while native apps use an isolated web view. Both restore the widget after history reload.
+When the agent calls `show_widget`, OpenClaw core wraps `widget_code` in a minimal HTML document, stores it as a Canvas document, and returns a preview handle. The Control UI renders that handle as a sandboxed iframe directly under the tool call, while native apps use an isolated web view. Both restore the widget after history reload.
 
 For browser embedding, the wrapper document injects two small host bridges around the widget code:
 
@@ -21,7 +21,7 @@ For browser embedding, the wrapper document injects two small host bridges aroun
 
 Everything else stays inside the frame: the document runs in an opaque origin with a strict Content Security Policy, so widget scripts cannot reach the Control UI, the Gateway, or the network.
 
-The Canvas implementation is available only when the originating Gateway client declares the `inline-widgets` capability. The Control UI and supported native apps declare this capability automatically. The Discord implementation is available only in Discord sessions with Activities configured. Other channel runs do not receive `show_widget`.
+The core implementation is available only when the originating Gateway client declares the `inline-widgets` capability. The Control UI and supported native apps declare this capability automatically. The Discord implementation is available only in Discord sessions with Activities configured. Other channel runs do not receive `show_widget`.
 
 Capability transport covers embedded, Codex app-server, and CLI-backed model backends. Grant-authenticated MCP callers and direct HTTP tool-invoke callers remain fail closed because they do not declare client capabilities.
 
@@ -34,12 +34,12 @@ Both implementations use the same required fields:
 </ParamField>
 
 <ParamField path="widget_code" type="string" required>
-  Self-contained HTML or SVG. For Canvas-backed clients, input beginning with `<svg` after trimming is rendered in SVG mode; maximum length is 262,144 characters. Discord accepts a complete HTML document or body fragment up to 48 KiB.
+  Self-contained HTML or SVG. For inline-widget clients, input beginning with `<svg` after trimming is rendered in SVG mode; maximum length is 262,144 characters. Discord accepts a complete HTML document or body fragment up to 48 KiB.
 </ParamField>
 
 Discord also accepts optional `button_label` text for the Activity launch button. The Canvas schema intentionally omits this Discord-only field.
 
-The Canvas result includes a preview handle, so the Control UI and supported native apps render the widget directly from the tool call and restore it after history reload. Discord returns the stored widget and posted-message identifiers.
+The core result includes a Canvas preview handle, so the Control UI and supported native apps render the widget directly from the tool call and restore it after history reload. Discord returns the stored widget and posted-message identifiers.
 
 `discord_widget` remains registered as a deprecated alias for one release. New agent calls should use `show_widget`.
 
@@ -66,7 +66,7 @@ Accepted prompts appear in the transcript as regular user messages and start a n
 
 Widget documents use restrictive Content Security Policies. Inline style and script are allowed, while external fetches and resource loads are blocked. Keep all markup, styles, scripts, and image data inside `widget_code`.
 
-The Control UI iframe always omits `allow-same-origin`, even when the global embed mode is `trusted`, so widget scripts cannot read the parent application origin. Native clients use isolated, nonpersistent web views and block navigation away from the hosted widget. The Canvas host also serves widget documents with a `Content-Security-Policy: sandbox allow-scripts` response header, so direct rendering still runs the widget in an opaque origin instead of an application origin. Only render widget code you are willing to execute in that isolated frame.
+The Control UI iframe always omits `allow-same-origin`, even when the global embed mode is `trusted`, so widget scripts cannot read the parent application origin. Native clients use isolated, nonpersistent web views and block navigation away from the hosted widget. The core document host also serves widgets with a `Content-Security-Policy: sandbox allow-scripts` response header, so direct rendering still runs the widget in an opaque origin instead of an application origin. Only render widget code you are willing to execute in that isolated frame.
 
 The iframe also follows [`gateway.controlUi.embedSandbox`](/web/control-ui#hosted-embeds). The default `scripts` tier supports interactive widgets while preserving origin isolation.
 
@@ -76,5 +76,5 @@ Canvas retains at most 32 widgets per session (or per agent when no session is a
 
 - [Control UI hosted embeds](/web/control-ui#hosted-embeds)
 - [Discord Activities](/channels/discord-activities)
-- [Canvas plugin](/plugins/reference/canvas)
+- [Canvas node controls](/plugins/reference/canvas)
 - [Gateway protocol client capabilities](/gateway/protocol#client-capabilities)
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index dfb055b15f4..f3314dcae9b 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -489,7 +489,7 @@ Web Push is independent of the iOS APNS relay path (see [Configuration](/gateway
 
 Assistant messages can render hosted web content inline with the `[embed ...]` shortcode. The iframe sandbox policy is controlled by `gateway.controlUi.embedSandbox`:
 
-The bundled Canvas plugin provides [`show_widget`](/tools/show-widget) to render self-contained SVG or HTML directly from a tool call. The browser and supported native chat clients advertise the `inline-widgets` Gateway capability, and the resulting Canvas document remains available when chat history reloads. Discord Activities provide the same tool name on Discord; other channel-originated runs do not receive it.
+The core [`show_widget`](/tools/show-widget) tool renders self-contained SVG or HTML directly from a tool call. The browser and supported native chat clients advertise the `inline-widgets` Gateway capability, and the resulting Canvas document remains available when chat history reloads. Discord Activities provide the same tool name on Discord; other channel-originated runs do not receive it.
 
 <Tabs>
   <Tab title="strict">
diff --git a/extensions/canvas/doctor-contract-api.test.ts b/extensions/canvas/doctor-contract-api.test.ts
new file mode 100644
index 00000000000..494c4d026bc
--- /dev/null
+++ b/extensions/canvas/doctor-contract-api.test.ts
@@ -0,0 +1,152 @@
+import fs from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import type { PluginDoctorStateMigration } from "openclaw/plugin-sdk/runtime-doctor";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { stateMigrations } from "./doctor-contract-api.js";
+
+const tempDirs: string[] = [];
+const migration = stateMigrations[0];
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+async function createTempDir(label: string): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(tmpdir(), label));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function migrationParams(params: {
+  stateDir: string;
+  customRoot?: string;
+}): Parameters<PluginDoctorStateMigration["detectLegacyState"]>[0] {
+  const config = params.customRoot
+    ? ({
+        plugins: {
+          entries: {
+            canvas: { config: { host: { root: params.customRoot } } },
+          },
+        },
+      } as OpenClawConfig)
+    : ({} as OpenClawConfig);
+  return {
+    config,
+    env: process.env,
+    stateDir: params.stateDir,
+    oauthDir: path.join(params.stateDir, "credentials"),
+    context: { openPluginStateKeyedStore: () => undefined as never },
+  };
+}
+
+describe("Canvas doctor state migration", () => {
+  it("ignores the default core document root", async () => {
+    const stateDir = await createTempDir("openclaw-canvas-doctor-state-");
+    await fs.mkdir(path.join(stateDir, "canvas", "documents", "cv_default"), {
+      recursive: true,
+    });
+
+    await expect(migration?.detectLegacyState(migrationParams({ stateDir }))).resolves.toBeNull();
+  });
+
+  it("moves custom-root documents into the stable core layout", async () => {
+    const stateDir = await createTempDir("openclaw-canvas-doctor-state-");
+    const customRoot = await createTempDir("openclaw-canvas-doctor-custom-");
+    const legacyDocumentDir = path.join(customRoot, "documents", "cv_existing");
+    await fs.mkdir(path.join(legacyDocumentDir, "collection.media"), { recursive: true });
+    await fs.writeFile(path.join(legacyDocumentDir, "index.html"), "<p>existing</p>", "utf8");
+    await fs.writeFile(
+      path.join(legacyDocumentDir, "collection.media", "asset.txt"),
+      "asset",
+      "utf8",
+    );
+    const params = migrationParams({ stateDir, customRoot });
+
+    await expect(migration?.detectLegacyState(params)).resolves.toEqual({
+      preview: [
+        `- Canvas documents: ${path.join(customRoot, "documents")} -> ${path.join(stateDir, "canvas", "documents")} (1 document(s))`,
+      ],
+    });
+    const result = await migration?.migrateLegacyState(params);
+
+    expect(result).toEqual({
+      changes: ["Migrated 1 Canvas document(s) into core storage"],
+      warnings: [],
+    });
+    await expect(
+      fs.readFile(path.join(stateDir, "canvas", "documents", "cv_existing", "index.html"), "utf8"),
+    ).resolves.toBe("<p>existing</p>");
+    await expect(
+      fs.readFile(
+        path.join(stateDir, "canvas", "documents", "cv_existing", "collection.media", "asset.txt"),
+        "utf8",
+      ),
+    ).resolves.toBe("asset");
+    await expect(fs.access(legacyDocumentDir)).rejects.toThrow();
+  });
+
+  it("leaves a conflicting legacy document in place", async () => {
+    const stateDir = await createTempDir("openclaw-canvas-doctor-state-");
+    const customRoot = await createTempDir("openclaw-canvas-doctor-custom-");
+    const legacyDocumentDir = path.join(customRoot, "documents", "cv_conflict");
+    const coreDocumentDir = path.join(stateDir, "canvas", "documents", "cv_conflict");
+    await fs.mkdir(legacyDocumentDir, { recursive: true });
+    await fs.mkdir(coreDocumentDir, { recursive: true });
+    await fs.writeFile(path.join(legacyDocumentDir, "index.html"), "legacy", "utf8");
+    await fs.writeFile(path.join(coreDocumentDir, "index.html"), "core", "utf8");
+
+    const result = await migration?.migrateLegacyState(migrationParams({ stateDir, customRoot }));
+
+    expect(result?.changes).toEqual([]);
+    expect(result?.warnings).toHaveLength(1);
+    await expect(fs.readFile(path.join(legacyDocumentDir, "index.html"), "utf8")).resolves.toBe(
+      "legacy",
+    );
+    await expect(fs.readFile(path.join(coreDocumentDir, "index.html"), "utf8")).resolves.toBe(
+      "core",
+    );
+  });
+
+  it("cleans partial copies and retries the migration", async () => {
+    const stateDir = await createTempDir("openclaw-canvas-doctor-state-");
+    const customRoot = await createTempDir("openclaw-canvas-doctor-custom-");
+    const legacyDocumentDir = path.join(customRoot, "documents", "cv_retry");
+    const coreDocumentsDir = path.join(stateDir, "canvas", "documents");
+    const coreDocumentDir = path.join(coreDocumentsDir, "cv_retry");
+    await fs.mkdir(legacyDocumentDir, { recursive: true });
+    await fs.writeFile(path.join(legacyDocumentDir, "index.html"), "complete", "utf8");
+    const params = migrationParams({ stateDir, customRoot });
+    const copy = vi.spyOn(fs, "cp").mockImplementationOnce(async (_source, destination) => {
+      const destinationPath =
+        typeof destination === "string" ? destination : fileURLToPath(destination);
+      await fs.mkdir(destinationPath, { recursive: true });
+      await fs.writeFile(path.join(destinationPath, "index.html"), "partial", "utf8");
+      throw new Error("interrupted copy");
+    });
+
+    const failed = await migration?.migrateLegacyState(params);
+
+    expect(failed?.changes).toEqual([]);
+    expect(failed?.warnings).toHaveLength(1);
+    await expect(fs.access(coreDocumentDir)).rejects.toThrow();
+    await expect(fs.readFile(path.join(legacyDocumentDir, "index.html"), "utf8")).resolves.toBe(
+      "complete",
+    );
+    expect(
+      (await fs.readdir(coreDocumentsDir)).filter((name) => name.startsWith(".canvas-migrate-")),
+    ).toEqual([]);
+
+    copy.mockRestore();
+    await expect(migration?.migrateLegacyState(params)).resolves.toEqual({
+      changes: ["Migrated 1 Canvas document(s) into core storage"],
+      warnings: [],
+    });
+    await expect(fs.readFile(path.join(coreDocumentDir, "index.html"), "utf8")).resolves.toBe(
+      "complete",
+    );
+  });
+});
diff --git a/extensions/canvas/doctor-contract-api.ts b/extensions/canvas/doctor-contract-api.ts
new file mode 100644
index 00000000000..5a48339852e
--- /dev/null
+++ b/extensions/canvas/doctor-contract-api.ts
@@ -0,0 +1,128 @@
+// Canvas doctor contract migrates documents from configured host roots into core storage.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolvePluginConfigObject } from "openclaw/plugin-sdk/plugin-config-runtime";
+import type { PluginDoctorStateMigration } from "openclaw/plugin-sdk/runtime-doctor";
+import {
+  asOptionalRecord as readRecord,
+  readStringValue as readString,
+} from "openclaw/plugin-sdk/string-coerce-runtime";
+import { resolveUserPath } from "openclaw/plugin-sdk/text-utility-runtime";
+
+type StateMigrationParams = Parameters<PluginDoctorStateMigration["detectLegacyState"]>[0];
+
+function resolveLegacyDocumentsDir(params: StateMigrationParams): string | null {
+  const pluginConfig = resolvePluginConfigObject(params.config, "canvas");
+  const configuredRoot = readString(readRecord(pluginConfig?.host)?.root)?.trim();
+  if (!configuredRoot) {
+    return null;
+  }
+  const legacyDir = path.join(
+    path.resolve(resolveUserPath(configuredRoot, params.env)),
+    "documents",
+  );
+  const coreDir = path.resolve(params.stateDir, "canvas", "documents");
+  return legacyDir === coreDir ? null : legacyDir;
+}
+
+async function listDocumentIds(documentsDir: string): Promise<string[]> {
+  try {
+    return (await fs.readdir(documentsDir, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .toSorted();
+  } catch {
+    return [];
+  }
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+  try {
+    await fs.access(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const stateMigrations: PluginDoctorStateMigration[] = [
+  {
+    id: "canvas-custom-root-documents-to-core",
+    label: "Canvas documents in a custom host root",
+    async detectLegacyState(params) {
+      const legacyDir = resolveLegacyDocumentsDir(params);
+      if (!legacyDir) {
+        return null;
+      }
+      const documentIds = await listDocumentIds(legacyDir);
+      if (documentIds.length === 0) {
+        return null;
+      }
+      const coreDir = path.resolve(params.stateDir, "canvas", "documents");
+      return {
+        preview: [
+          `- Canvas documents: ${legacyDir} -> ${coreDir} (${documentIds.length} document(s))`,
+        ],
+      };
+    },
+    async migrateLegacyState(params) {
+      const changes: string[] = [];
+      const warnings: string[] = [];
+      const legacyDir = resolveLegacyDocumentsDir(params);
+      if (!legacyDir) {
+        return { changes, warnings };
+      }
+      const documentIds = await listDocumentIds(legacyDir);
+      if (documentIds.length === 0) {
+        return { changes, warnings };
+      }
+
+      const coreDir = path.resolve(params.stateDir, "canvas", "documents");
+      await fs.mkdir(coreDir, { recursive: true });
+      let migrated = 0;
+      for (const documentId of documentIds) {
+        const sourceDir = path.join(legacyDir, documentId);
+        const targetDir = path.join(coreDir, documentId);
+        let tempParent: string | undefined;
+        try {
+          if (await pathExists(targetDir)) {
+            throw new Error("core target already exists");
+          }
+          tempParent = await fs.mkdtemp(path.join(coreDir, ".canvas-migrate-"));
+          const tempDocumentDir = path.join(tempParent, documentId);
+          await fs.cp(sourceDir, tempDocumentDir, {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+          });
+          if (await pathExists(targetDir)) {
+            throw new Error("core target was created during migration");
+          }
+          // Publish only a complete same-filesystem copy; interrupted copies stay invisible.
+          await fs.rename(tempDocumentDir, targetDir);
+          await fs.rm(sourceDir, { recursive: true, force: true });
+          migrated += 1;
+        } catch (error) {
+          warnings.push(
+            `Skipped Canvas document ${documentId}; core target may already exist: ${String(error)}`,
+          );
+        } finally {
+          if (tempParent) {
+            await fs.rm(tempParent, { recursive: true, force: true }).catch(() => undefined);
+          }
+        }
+      }
+      if (migrated > 0) {
+        changes.push(`Migrated ${migrated} Canvas document(s) into core storage`);
+      }
+      try {
+        if ((await fs.readdir(legacyDir)).length === 0) {
+          await fs.rmdir(legacyDir);
+        }
+      } catch {
+        // A retained or concurrently created document keeps the legacy directory in place.
+      }
+      return { changes, warnings };
+    },
+  },
+];
diff --git a/extensions/canvas/index.test.ts b/extensions/canvas/index.test.ts
index 3258379e641..3d478fa750c 100644
--- a/extensions/canvas/index.test.ts
+++ b/extensions/canvas/index.test.ts
@@ -7,7 +7,6 @@ import type {
 import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import canvasPlugin from "./index.js";
-import { SHOW_WIDGET_REQUIRED_CLIENT_CAPS } from "./src/tool-schema.js";
 
 const VALID_A2UI_V08_JSONL = [
   JSON.stringify({
@@ -31,11 +30,9 @@ const mocks = vi.hoisted(() => {
     close: vi.fn(async () => {}),
   };
   const toolExecute = vi.fn(async () => ({ content: [{ type: "text", text: "ok" }] }));
-  const widgetToolExecute = vi.fn(async () => ({ content: [{ type: "text", text: "widget" }] }));
   return {
     httpHandler,
     createCanvasHttpRouteHandler: vi.fn(() => httpHandler),
-    resolveCanvasHttpPathToLocalPath: vi.fn(() => "/tmp/canvas-asset"),
     createDefaultCanvasCliDependencies: vi.fn(() => ({ deps: true })),
     registerNodesCanvasCommands: vi.fn(),
     toolExecute,
@@ -46,14 +43,6 @@ const mocks = vi.hoisted(() => {
       parameters: {},
       execute: toolExecute,
     })),
-    widgetToolExecute,
-    createShowWidgetTool: vi.fn(() => ({
-      label: "Show Widget",
-      name: "show_widget",
-      description: "Show Widget",
-      parameters: {},
-      execute: widgetToolExecute,
-    })),
   };
 });
 
@@ -61,10 +50,6 @@ vi.mock("./src/http-route.js", () => ({
   createCanvasHttpRouteHandler: mocks.createCanvasHttpRouteHandler,
 }));
 
-vi.mock("./src/documents.js", () => ({
-  resolveCanvasHttpPathToLocalPath: mocks.resolveCanvasHttpPathToLocalPath,
-}));
-
 vi.mock("./src/cli.js", () => ({
   createDefaultCanvasCliDependencies: mocks.createDefaultCanvasCliDependencies,
   registerNodesCanvasCommands: mocks.registerNodesCanvasCommands,
@@ -74,10 +59,6 @@ vi.mock("./src/tool.js", () => ({
   createCanvasTool: mocks.createCanvasTool,
 }));
 
-vi.mock("./src/widget-tool.js", () => ({
-  createShowWidgetTool: mocks.createShowWidgetTool,
-}));
-
 function registerCanvas() {
   const routes: Array<Parameters<OpenClawPluginApi["registerHttpRoute"]>[0]> = [];
   const services: Array<Parameters<OpenClawPluginApi["registerService"]>[0]> = [];
@@ -157,22 +138,15 @@ describe("Canvas plugin entry", () => {
     expect(mocks.httpHandler.close).toHaveBeenCalledTimes(1);
   });
 
-  it("defers Canvas resolver, CLI, and tool implementations until use", async () => {
+  it("defers Canvas CLI and tool implementations until use", async () => {
     const { resolvers, tools, cliFeatures } = registerCanvas();
 
-    expect(resolvers).toHaveLength(1);
-    expect(tools).toHaveLength(2);
-    expect(tools.map(({ opts }) => opts?.name)).toEqual([undefined, "show_widget"]);
+    expect(resolvers).toHaveLength(0);
+    expect(tools).toHaveLength(1);
+    expect(tools.map(({ opts }) => opts?.name)).toEqual([undefined]);
     expect(cliFeatures).toHaveLength(1);
-    expect(mocks.resolveCanvasHttpPathToLocalPath).not.toHaveBeenCalled();
     expect(mocks.createDefaultCanvasCliDependencies).not.toHaveBeenCalled();
     expect(mocks.createCanvasTool).not.toHaveBeenCalled();
-    expect(mocks.createShowWidgetTool).not.toHaveBeenCalled();
-
-    await expect(resolvers[0]?.("/__openclaw__/canvas/documents/id/index.html")).resolves.toBe(
-      "/tmp/canvas-asset",
-    );
-    expect(mocks.resolveCanvasHttpPathToLocalPath).toHaveBeenCalledTimes(1);
 
     await cliFeatures[0]?.registrar({
       program: {} as never,
@@ -196,12 +170,10 @@ describe("Canvas plugin entry", () => {
       expect(Array.isArray(tool)).toBe(false);
       return tool as AnyAgentTool;
     });
-    expect(registeredTools.map((tool) => tool.name)).toEqual(["canvas", "show_widget"]);
-    expect(registeredTools[1]?.requiredClientCaps).toEqual(SHOW_WIDGET_REQUIRED_CLIENT_CAPS);
+    expect(registeredTools.map((tool) => tool.name)).toEqual(["canvas"]);
     expect(mocks.createCanvasTool).not.toHaveBeenCalled();
-    expect(mocks.createShowWidgetTool).not.toHaveBeenCalled();
 
-    const [canvasTool, showWidgetTool] = registeredTools;
+    const [canvasTool] = registeredTools;
     await canvasTool?.execute("tool-call", { action: "hide" });
     expect(mocks.createCanvasTool).toHaveBeenCalledWith({
       config: {},
@@ -209,27 +181,6 @@ describe("Canvas plugin entry", () => {
       agentSessionKey: "agent:main:canvas",
     });
     expect(mocks.toolExecute).toHaveBeenCalledWith("tool-call", { action: "hide" });
-
-    await showWidgetTool?.execute("widget-call", {
-      title: "Status",
-      widget_code: "<p>ready</p>",
-    });
-    expect(mocks.createShowWidgetTool).toHaveBeenCalledWith({
-      config: {},
-      sessionId: "session-1",
-      agentId: "agent-1",
-    });
-    expect(mocks.widgetToolExecute).toHaveBeenCalledWith("widget-call", {
-      title: "Status",
-      widget_code: "<p>ready</p>",
-    });
-
-    const showWidgetRegistration = tools[1];
-    if (!showWidgetRegistration || typeof showWidgetRegistration.tool !== "function") {
-      throw new Error("expected show_widget factory registration");
-    }
-    const discordShowWidget = showWidgetRegistration.tool({ messageChannel: "discord" });
-    expect(discordShowWidget).toBeNull();
   });
 
   it.each([
diff --git a/extensions/canvas/index.ts b/extensions/canvas/index.ts
index 82f3f8b4af2..00ac41ab714 100644
--- a/extensions/canvas/index.ts
+++ b/extensions/canvas/index.ts
@@ -11,11 +11,7 @@ import { definePluginEntry, type AnyAgentTool } from "openclaw/plugin-sdk/plugin
 import { validateSupportedA2UIJsonl } from "./src/a2ui-jsonl.js";
 import { canvasConfigSchema, isCanvasHostEnabled } from "./src/config.js";
 import { A2UI_PATH, CANVAS_HOST_PATH, CANVAS_WS_PATH } from "./src/host/a2ui-shared.js";
-import {
-  CanvasToolSchema,
-  SHOW_WIDGET_REQUIRED_CLIENT_CAPS,
-  ShowWidgetToolSchema,
-} from "./src/tool-schema.js";
+import { CanvasToolSchema } from "./src/tool-schema.js";
 
 const CANVAS_NODE_COMMANDS = [
   "canvas.present",
@@ -53,26 +49,6 @@ function createLazyCanvasTool(params: {
   };
 }
 
-function createLazyShowWidgetTool(params: {
-  config?: OpenClawConfig;
-  sessionId?: string;
-  agentId?: string;
-}): AnyAgentTool {
-  const loadTool = createLazyRuntimeModule(() =>
-    import("./src/widget-tool.js").then(({ createShowWidgetTool }) => createShowWidgetTool(params)),
-  );
-  return {
-    label: "Show Widget",
-    name: "show_widget",
-    description:
-      "Show an interactive, self-contained HTML or SVG widget to the user on their current surface. Inline all required code and data. In web chat, a global sendPrompt(text) function submits text to the chat as if the user typed it — wire it to buttons or controls to build interactive widgets. It only works after the user clicks inside the widget (plain conversational text only; slash commands are rejected), so never call it automatically.",
-    parameters: ShowWidgetToolSchema,
-    requiredClientCaps: SHOW_WIDGET_REQUIRED_CLIENT_CAPS,
-    execute: async (...args: Parameters<AnyAgentTool["execute"]>) =>
-      await (await loadTool()).execute(...args),
-  };
-}
-
 export default definePluginEntry({
   id: "canvas",
   name: "Canvas",
@@ -134,14 +110,6 @@ export default definePluginEntry({
           await httpRouteHandler?.close();
         },
       });
-      const loadResolveCanvasHttpPathToLocalPath = createLazyRuntimeModule(() =>
-        import("./src/documents.js").then(
-          ({ resolveCanvasHttpPathToLocalPath }) => resolveCanvasHttpPathToLocalPath,
-        ),
-      );
-      api.registerHostedMediaResolver(async (mediaUrl) => {
-        return (await loadResolveCanvasHttpPathToLocalPath())(mediaUrl);
-      });
     }
     api.registerNodeInvokePolicy({
       commands: CANVAS_NODE_COMMANDS,
@@ -181,19 +149,6 @@ export default definePluginEntry({
         agentSessionKey: ctx.sessionKey,
       }),
     );
-    api.registerTool(
-      (ctx) =>
-        // Discord owns show_widget for Discord sessions; keep the two factories
-        // mutually exclusive before plugin tool names are de-duplicated.
-        ctx.messageChannel !== "discord" && isCanvasHostEnabled(ctx.runtimeConfig ?? ctx.config)
-          ? createLazyShowWidgetTool({
-              config: ctx.runtimeConfig ?? ctx.config,
-              sessionId: ctx.sessionId,
-              agentId: ctx.agentId,
-            })
-          : null,
-      { name: "show_widget" },
-    );
     api.registerNodeCliFeature(
       async ({ program }) => {
         const { createDefaultCanvasCliDependencies, registerNodesCanvasCommands } =
diff --git a/extensions/canvas/openclaw.plugin.json b/extensions/canvas/openclaw.plugin.json
index 40d095ce342..72b3abe1b5a 100644
--- a/extensions/canvas/openclaw.plugin.json
+++ b/extensions/canvas/openclaw.plugin.json
@@ -8,7 +8,7 @@
   "description": "Experimental Canvas control and A2UI rendering surfaces for paired nodes.",
   "skills": ["./skills"],
   "contracts": {
-    "tools": ["canvas", "show_widget"]
+    "tools": ["canvas"]
   },
   "configContracts": {
     "compatibilityMigrationPaths": ["canvasHost"]
diff --git a/extensions/canvas/runtime-api.ts b/extensions/canvas/runtime-api.ts
index 607251f64b8..87c0f733ccb 100644
--- a/extensions/canvas/runtime-api.ts
+++ b/extensions/canvas/runtime-api.ts
@@ -1,7 +1,4 @@
-/**
- * Runtime API exports for Canvas plugin host, document, CLI, and capability
- * helpers.
- */
+/** Runtime API exports for Canvas plugin host, CLI, and capability helpers. */
 export {
   canvasConfigSchema,
   isCanvasHostEnabled,
@@ -23,13 +20,6 @@ export {
   type CanvasHostHandler,
   type CanvasHostServer,
 } from "./src/host/server.js";
-export {
-  buildCanvasDocumentEntryUrl,
-  createCanvasDocument,
-  resolveCanvasDocumentAssets,
-  resolveCanvasDocumentDir,
-  resolveCanvasHttpPathToLocalPath,
-} from "./src/documents.js";
 export {
   registerNodesCanvasCommands,
   type CanvasCliDependencies,
diff --git a/extensions/canvas/src/documents.test.ts b/extensions/canvas/src/documents.test.ts
deleted file mode 100644
index 0613f834e7c..00000000000
--- a/extensions/canvas/src/documents.test.ts
+++ /dev/null
@@ -1,265 +0,0 @@
-// Canvas tests cover documents plugin behavior.
-import { mkdtemp, mkdir, writeFile, readFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import {
-  buildCanvasDocumentEntryUrl,
-  createCanvasDocument,
-  resolveCanvasDocumentAssets,
-  resolveCanvasDocumentDir,
-  resolveCanvasHttpPathToLocalPath,
-} from "./documents.js";
-
-const tempDirs: string[] = [];
-
-afterEach(async () => {
-  await Promise.all(
-    tempDirs.splice(0).map(async (dir) => {
-      await import("node:fs/promises").then((fs) => fs.rm(dir, { recursive: true, force: true }));
-    }),
-  );
-});
-
-describe("canvas documents", () => {
-  it("builds entry urls for materialized path documents under managed storage", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-    const workspaceDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-workspace-"));
-    tempDirs.push(workspaceDir);
-    await mkdir(path.join(workspaceDir, "player"), { recursive: true });
-    await writeFile(path.join(workspaceDir, "player/index.html"), "<div>ok</div>", "utf8");
-
-    const document = await createCanvasDocument(
-      {
-        kind: "html_bundle",
-        entrypoint: {
-          type: "path",
-          value: "player/index.html",
-        },
-      },
-      { stateDir, workspaceDir },
-    );
-
-    expect(document.entryUrl).toContain("/__openclaw__/canvas/documents/");
-    expect(document.localEntrypoint).toBe("index.html");
-    expect(resolveCanvasDocumentDir(document.id, { stateDir })).toContain(stateDir);
-  });
-
-  it("normalizes nested local entrypoint urls", () => {
-    const url = buildCanvasDocumentEntryUrl("cv_example", "collection.media/index.html");
-    expect(url).toBe("/__openclaw__/canvas/documents/cv_example/collection.media/index.html");
-  });
-
-  it("encodes special characters in hosted entrypoint path segments", () => {
-    const url = buildCanvasDocumentEntryUrl("cv_example", "bundle#1/entry%20point?.html");
-    expect(url).toBe(
-      "/__openclaw__/canvas/documents/cv_example/bundle%231/entry%2520point%3F.html",
-    );
-  });
-
-  it("materializes inline html bundles as index documents", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-
-    const document = await createCanvasDocument(
-      {
-        kind: "html_bundle",
-        title: "Preview",
-        entrypoint: {
-          type: "html",
-          value:
-            "<!doctype html><html><head><style>.demo{color:red}</style></head><body><div class='demo'>Front</div></body></html>",
-        },
-      },
-      { stateDir },
-    );
-
-    const indexHtml = await import("node:fs/promises").then((fs) =>
-      fs.readFile(
-        path.join(resolveCanvasDocumentDir(document.id, { stateDir }), "index.html"),
-        "utf8",
-      ),
-    );
-
-    expect(indexHtml).toContain("<div class='demo'>Front</div>");
-    expect(indexHtml).toContain("<style>.demo{color:red}</style>");
-    expect(document.title).toBe("Preview");
-    expect(document.entryUrl).toBe(`/__openclaw__/canvas/documents/${document.id}/index.html`);
-  });
-
-  it("reuses a supplied stable document id by replacing the prior materialized view", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-
-    const first = await createCanvasDocument(
-      {
-        id: "status-card",
-        kind: "html_bundle",
-        entrypoint: { type: "html", value: "<div>first</div>" },
-      },
-      { stateDir },
-    );
-    const second = await createCanvasDocument(
-      {
-        id: "status-card",
-        kind: "html_bundle",
-        entrypoint: { type: "html", value: "<div>second</div>" },
-      },
-      { stateDir },
-    );
-
-    expect(first.id).toBe("status-card");
-    expect(second.id).toBe("status-card");
-
-    const indexHtml = await import("node:fs/promises").then((fs) =>
-      fs.readFile(
-        path.join(resolveCanvasDocumentDir(second.id, { stateDir }), "index.html"),
-        "utf8",
-      ),
-    );
-    expect(indexHtml).toContain("second");
-    expect(indexHtml).not.toContain("first");
-  });
-
-  it("exposes stable managed asset urls for copied canvas assets", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-    const workspaceDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-workspace-"));
-    tempDirs.push(workspaceDir);
-    await mkdir(path.join(workspaceDir, "collection.media"), { recursive: true });
-    await writeFile(path.join(workspaceDir, "collection.media/audio.mp3"), "audio", "utf8");
-
-    const document = await createCanvasDocument(
-      {
-        kind: "html_bundle",
-        entrypoint: {
-          type: "html",
-          value:
-            '<audio controls><source src="collection.media/audio.mp3" type="audio/mpeg" /></audio>',
-        },
-        assets: [
-          {
-            logicalPath: "collection.media/audio.mp3",
-            sourcePath: "collection.media/audio.mp3",
-            contentType: "audio/mpeg",
-          },
-        ],
-      },
-      { stateDir, workspaceDir },
-    );
-
-    expect(resolveCanvasDocumentAssets(document, { stateDir })).toEqual([
-      {
-        logicalPath: "collection.media/audio.mp3",
-        contentType: "audio/mpeg",
-        localPath: path.join(
-          resolveCanvasDocumentDir(document.id, { stateDir }),
-          "collection.media/audio.mp3",
-        ),
-        url: `/__openclaw__/canvas/documents/${document.id}/collection.media/audio.mp3`,
-      },
-    ]);
-    expect(
-      resolveCanvasDocumentAssets(document, {
-        baseUrl: "http://127.0.0.1:19003",
-        stateDir,
-      }),
-    ).toEqual([
-      {
-        logicalPath: "collection.media/audio.mp3",
-        contentType: "audio/mpeg",
-        localPath: path.join(
-          resolveCanvasDocumentDir(document.id, { stateDir }),
-          "collection.media/audio.mp3",
-        ),
-        url: `http://127.0.0.1:19003/__openclaw__/canvas/documents/${document.id}/collection.media/audio.mp3`,
-      },
-    ]);
-  });
-
-  it("wraps local pdf documents in an index viewer page", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-    const workspaceDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-workspace-"));
-    tempDirs.push(workspaceDir);
-    await writeFile(path.join(workspaceDir, "demo.pdf"), "%PDF-1.4", "utf8");
-
-    const document = await createCanvasDocument(
-      {
-        kind: "document",
-        entrypoint: {
-          type: "path",
-          value: "demo.pdf",
-        },
-      },
-      { stateDir, workspaceDir },
-    );
-
-    expect(document.entryUrl).toBe(`/__openclaw__/canvas/documents/${document.id}/index.html`);
-    const indexHtml = await readFile(
-      path.join(resolveCanvasDocumentDir(document.id, { stateDir }), "index.html"),
-      "utf8",
-    );
-    expect(indexHtml).toContain('type="application/pdf"');
-    expect(indexHtml).toContain('data="demo.pdf"');
-  });
-
-  it("wraps remote pdf urls in an index viewer page", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-
-    const document = await createCanvasDocument(
-      {
-        kind: "document",
-        entrypoint: {
-          type: "url",
-          value: "https://example.com/demo.pdf",
-        },
-      },
-      { stateDir },
-    );
-
-    expect(document.entryUrl).toBe(`/__openclaw__/canvas/documents/${document.id}/index.html`);
-    const indexHtml = await readFile(
-      path.join(resolveCanvasDocumentDir(document.id, { stateDir }), "index.html"),
-      "utf8",
-    );
-    expect(indexHtml).toContain('type="application/pdf"');
-    expect(indexHtml).toContain('data="https://example.com/demo.pdf"');
-  });
-
-  it("rejects traversal-style document ids in hosted canvas paths", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-
-    expect(
-      resolveCanvasHttpPathToLocalPath(
-        "/__openclaw__/canvas/documents/../collection.media/index.html",
-        { stateDir },
-      ),
-    ).toBeNull();
-  });
-
-  it("rejects malformed encoded hosted canvas document paths", async () => {
-    const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-documents-"));
-    tempDirs.push(stateDir);
-    const documentId = "cv_malformed";
-    const documentDir = resolveCanvasDocumentDir(documentId, { stateDir });
-    await mkdir(documentDir, { recursive: true });
-    await writeFile(path.join(documentDir, "%E0%A4%A.html"), "literal-percent-name", "utf8");
-
-    expect(
-      resolveCanvasHttpPathToLocalPath(
-        `/__openclaw__/canvas/documents/${documentId}/%E0%A4%A.html`,
-        { stateDir },
-      ),
-    ).toBeNull();
-    expect(
-      resolveCanvasHttpPathToLocalPath(
-        `/__openclaw__/canvas/documents/${documentId}/%25E0%25A4%25A.html`,
-        { stateDir },
-      ),
-    ).toBe(path.join(documentDir, "%E0%A4%A.html"));
-  });
-});
diff --git a/extensions/canvas/src/host/server.test.ts b/extensions/canvas/src/host/server.test.ts
index 0bff446ee6a..1834bc74cff 100644
--- a/extensions/canvas/src/host/server.test.ts
+++ b/extensions/canvas/src/host/server.test.ts
@@ -434,47 +434,16 @@ describe("canvas host", () => {
     }
   });
 
-  it("serves sandbox-marked documents with a CSP sandbox header and no live reload", async () => {
+  it("leaves managed document requests to the core host", async () => {
     const dir = await createCaseDir();
-    const docDir = path.join(dir, "documents", "widget-1");
-    await fs.mkdir(docDir, { recursive: true });
-    await fs.writeFile(
-      path.join(docDir, "manifest.json"),
-      JSON.stringify({ id: "widget-1", cspSandbox: "scripts" }),
-      "utf8",
-    );
-    await fs.writeFile(path.join(docDir, "index.html"), "<html><body>widget</body></html>", "utf8");
-    const plainDir = path.join(dir, "documents", "plain-1");
-    await fs.mkdir(plainDir, { recursive: true });
-    await fs.writeFile(
-      path.join(plainDir, "manifest.json"),
-      JSON.stringify({ id: "plain-1" }),
-      "utf8",
-    );
-    await fs.writeFile(
-      path.join(plainDir, "index.html"),
-      "<html><body>plain</body></html>",
-      "utf8",
-    );
     const handler = await createTestCanvasHostHandler(dir);
 
     try {
-      const widget = await captureHandlerResponse(
+      const response = await captureHandlerResponse(
         handler,
         `${CANVAS_HOST_PATH}/documents/widget-1/index.html`,
       );
-      expect(widget.status).toBe(200);
-      // Opaque origin on direct navigation: widget script must not run as the app origin.
-      expect(widget.headers["content-security-policy"]).toBe("sandbox allow-scripts");
-      expect(widget.body).toContain("widget");
-      expect(widget.body).not.toContain(CANVAS_WS_PATH);
-
-      const plain = await captureHandlerResponse(
-        handler,
-        `${CANVAS_HOST_PATH}/documents/plain-1/index.html`,
-      );
-      expect(plain.status).toBe(200);
-      expect(plain.headers["content-security-policy"]).toBeUndefined();
+      expect(response.handled).toBe(false);
     } finally {
       await handler.close();
     }
diff --git a/extensions/canvas/src/host/server.ts b/extensions/canvas/src/host/server.ts
index 729c4af192f..9951d69a94c 100644
--- a/extensions/canvas/src/host/server.ts
+++ b/extensions/canvas/src/host/server.ts
@@ -219,28 +219,6 @@ async function prepareCanvasRoot(rootDir: string) {
   return rootReal;
 }
 
-/** Reads the owning document manifest to decide whether HTML gets a CSP sandbox header. */
-async function resolveDocumentCspSandbox(
-  rootReal: string,
-  realPath: string,
-): Promise<"scripts" | undefined> {
-  const relative = path.relative(rootReal, realPath);
-  const segments = relative.split(path.sep);
-  if (segments[0] !== "documents" || segments.length < 3) {
-    return undefined;
-  }
-  try {
-    const manifestRaw = await fs.readFile(
-      path.join(rootReal, segments[0], segments[1] ?? "", "manifest.json"),
-      "utf8",
-    );
-    const manifest = JSON.parse(manifestRaw) as { cspSandbox?: unknown };
-    return manifest.cspSandbox === "scripts" ? "scripts" : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 function resolveDefaultCanvasRoot(): string {
   return path.join(resolveStateDir(), "canvas");
 }
@@ -375,6 +353,11 @@ export async function createCanvasHostHandler(
         urlPath = urlPath === basePath ? "/" : urlPath.slice(basePath.length) || "/";
       }
 
+      // Core owns managed transcript documents; this host keeps only Canvas/A2UI files.
+      if (urlPath === "/documents" || urlPath.startsWith("/documents/")) {
+        return false;
+      }
+
       if (req.method !== "GET" && req.method !== "HEAD") {
         res.statusCode = 405;
         res.setHeader("Content-Type", "text/plain; charset=utf-8");
@@ -416,16 +399,6 @@ export async function createCanvasHostHandler(
       if (mime === "text/html") {
         const html = data.toString("utf8");
         res.setHeader("Content-Type", "text/html; charset=utf-8");
-        // Sandbox-marked documents (agent-authored widgets) must get an opaque
-        // origin even when navigated to directly; the iframe sandbox attribute
-        // only protects embedded views. Skips live reload: its bridge script is
-        // useless without same-origin access.
-        const cspSandbox = await resolveDocumentCspSandbox(rootReal, realPath);
-        if (cspSandbox) {
-          res.setHeader("Content-Security-Policy", "sandbox allow-scripts");
-          res.end(html);
-          return true;
-        }
         res.end(injectCanvasRuntime(html, { liveReload }));
         return true;
       }
diff --git a/extensions/canvas/src/tool-schema.ts b/extensions/canvas/src/tool-schema.ts
index d8988392e6d..caacc7ab367 100644
--- a/extensions/canvas/src/tool-schema.ts
+++ b/extensions/canvas/src/tool-schema.ts
@@ -23,15 +23,6 @@ const CANVAS_ACTIONS = [
 /** Snapshot formats accepted by the Canvas tool. */
 const CANVAS_SNAPSHOT_FORMATS = ["png", "jpg", "jpeg"] as const;
 
-/** Gateway capability required for inline transcript widgets. */
-export const SHOW_WIDGET_REQUIRED_CLIENT_CAPS = ["inline-widgets"];
-
-/** TypeBox schema for inline chat widgets. */
-export const ShowWidgetToolSchema = Type.Object({
-  title: Type.String(),
-  widget_code: Type.String(),
-});
-
 /** TypeBox schema for the model-facing Canvas tool arguments. */
 export const CanvasToolSchema = Type.Object({
   action: stringEnum(CANVAS_ACTIONS),
diff --git a/extensions/canvas/src/widget-tool.ts b/extensions/canvas/src/widget-tool.ts
deleted file mode 100644
index fc622323d35..00000000000
--- a/extensions/canvas/src/widget-tool.ts
+++ /dev/null
@@ -1,123 +0,0 @@
-/** Agent-facing inline chat widget tool. */
-import { createHash } from "node:crypto";
-import { jsonResult, readStringParam } from "openclaw/plugin-sdk/channel-actions";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
-import type { AnyAgentTool } from "openclaw/plugin-sdk/plugin-entry";
-import { escapeHtml } from "openclaw/plugin-sdk/text-utility-runtime";
-import { assertWidgetHtmlSize, WidgetHtmlInputError } from "openclaw/plugin-sdk/widget-html";
-import { resolveCanvasHostConfig } from "./config.js";
-import { createCanvasDocument } from "./documents.js";
-import { SHOW_WIDGET_REQUIRED_CLIENT_CAPS, ShowWidgetToolSchema } from "./tool-schema.js";
-
-export const WIDGET_CODE_MAX_CHARS = 262_144;
-export const WIDGET_MAX_PER_SCOPE = 32;
-
-type ShowWidgetToolOptions = {
-  config?: OpenClawConfig;
-  sessionId?: string;
-  agentId?: string;
-  stateDir?: string;
-};
-
-function buildWidgetDocument(title: string, widgetCode: string): string {
-  const isSvg = /^<svg/i.test(widgetCode);
-  const bodyClass = isSvg ? ' class="svg-widget"' : "";
-  // Inline scripts may drive the widget; CSP blocks resource loads, while preview metadata
-  // prevents the iframe from inheriting same-origin access to the parent application.
-  // The size reporter lets the embedding chat fit the iframe to the content; the
-  // parent clamps reported heights, so widget code cannot abuse the channel.
-  const sizeReporter =
-    "<script>(()=>{if(!window.parent||window.parent===window)return;" +
-    // documentElement.scrollHeight reports the viewport for short content, so
-    // measure the body box, which tracks the actual widget height.
-    "let last=0;const report=()=>{const b=document.body;if(!b)return;" +
-    "const h=Math.ceil(Math.max(b.scrollHeight,b.offsetHeight,b.getBoundingClientRect().height));" +
-    'if(h&&h!==last){last=h;window.parent.postMessage({type:"openclaw:widget-size",height:h},"*");}};' +
-    "addEventListener('load',report);new ResizeObserver(report).observe(document.body);" +
-    "setTimeout(report,50);setTimeout(report,500);})();</script>";
-  // The prompt bridge precedes widget code so inline handlers can reference
-  // sendPrompt() immediately. It creates the prompt channel itself and offers
-  // one endpoint to the embedding chat at parse time — before any widget code
-  // can run, steal the endpoint, or navigate the frame — so the chat's
-  // first-offer-wins adoption is always bound to this document. The send
-  // endpoint stays private to this closure, and sendPrompt requires transient
-  // user activation, so widget code cannot auto-send without a real user
-  // gesture; the chat additionally validates, requires a focused visible
-  // frame, and rate limits every prompt.
-  // Everything sendPrompt later touches is snapshotted here, before widget
-  // code exists, so prototype patches (MessagePort.postMessage, the
-  // userActivation getter) by widget code cannot leak the endpoint or fake a
-  // gesture. Fail closed: no observable transient user activation, no send.
-  const promptBridge =
-    "<script>(()=>{if(!window.parent||window.parent===window)return;" +
-    "const c=new MessageChannel();" +
-    "const post=c.port1.postMessage.bind(c.port1);" +
-    "let act=null;" +
-    "try{const ua=navigator.userActivation;" +
-    'const d=ua&&Object.getOwnPropertyDescriptor(Object.getPrototypeOf(ua),"isActive");' +
-    "if(d&&d.get)act=d.get.bind(ua);}catch{}" +
-    'window.parent.postMessage({type:"openclaw:widget-prompt-offer"},"*",[c.port2]);' +
-    "window.sendPrompt=text=>{if(!act||act()!==true)return;" +
-    'post({type:"openclaw:widget-prompt",prompt:String(text)});};})();</script>';
-  return `<!doctype html>
-<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src data:;"><title>${escapeHtml(title)}</title><style>:root{color-scheme:light dark}*{box-sizing:border-box}html,body{margin:0}body{font:14px system-ui,sans-serif}.svg-widget{display:grid;place-items:center}.svg-widget>svg{max-width:100%}</style></head><body${bodyClass}>${promptBridge}${widgetCode}${sizeReporter}</body></html>`;
-}
-
-function resolveRetentionScope(options: ShowWidgetToolOptions): string {
-  const scope = options.sessionId
-    ? `session:${options.sessionId}`
-    : `agent:${options.agentId ?? "default"}`;
-  return createHash("sha256").update(scope).digest("hex");
-}
-
-/** Creates a self-contained widget hosted by the Canvas plugin. */
-export function createShowWidgetTool(options: ShowWidgetToolOptions = {}): AnyAgentTool {
-  return {
-    label: "Show Widget",
-    name: "show_widget",
-    description:
-      "Show an interactive, self-contained HTML or SVG widget to the user on their current surface. Inline all required code and data. In web chat, a global sendPrompt(text) function submits text to the chat as if the user typed it — wire it to buttons or controls to build interactive widgets. It only works after the user clicks inside the widget (plain conversational text only; slash commands are rejected), so never call it automatically.",
-    parameters: ShowWidgetToolSchema,
-    requiredClientCaps: SHOW_WIDGET_REQUIRED_CLIENT_CAPS,
-    execute: async (_toolCallId, args) => {
-      const params = args as Record<string, unknown>;
-      const title = readStringParam(params, "title", { required: true });
-      const rawWidgetCode = readStringParam(params, "widget_code", {
-        required: true,
-        trim: false,
-      });
-      if (!rawWidgetCode.trim()) {
-        throw new WidgetHtmlInputError("widget_code required");
-      }
-      assertWidgetHtmlSize(rawWidgetCode, WIDGET_CODE_MAX_CHARS, {
-        inputName: "widget_code",
-        unit: "characters",
-      });
-      const widgetCode = rawWidgetCode.trim();
-      const canvasRootDir = resolveCanvasHostConfig({ config: options.config }).root;
-      const document = await createCanvasDocument(
-        {
-          kind: "html_bundle",
-          title,
-          entrypoint: { type: "html", value: buildWidgetDocument(title, widgetCode) },
-          surface: "assistant_message",
-          retentionScope: resolveRetentionScope(options),
-          // Direct navigation to the hosted URL must not run widget script as the
-          // Control UI origin; the host serves this doc with a CSP sandbox header.
-          cspSandbox: "scripts",
-        },
-        {
-          stateDir: options.stateDir,
-          canvasRootDir,
-          maxDocumentsPerScope: WIDGET_MAX_PER_SCOPE,
-        },
-      );
-      return jsonResult({
-        kind: "canvas",
-        presentation: { target: "assistant_message", title, sandbox: "scripts" },
-        view: { id: document.id, url: document.entryUrl },
-        text: `Widget hosted at ${document.entryUrl}`,
-      });
-    },
-  };
-}
diff --git a/src/agents/core-tool-factory-descriptors.ts b/src/agents/core-tool-factory-descriptors.ts
index 133b5c4d13d..787c272ff87 100644
--- a/src/agents/core-tool-factory-descriptors.ts
+++ b/src/agents/core-tool-factory-descriptors.ts
@@ -34,6 +34,7 @@ const CORE_TOOL_FACTORY_DESCRIPTORS = [
   { name: "nodes", family: "openclaw" },
   { name: "pdf", family: "openclaw" },
   { name: "session_status", family: "openclaw" },
+  { name: "show_widget", family: "openclaw" },
   { name: "sessions", family: "openclaw" },
   { name: "sessions_history", family: "openclaw" },
   { name: "sessions_list", family: "openclaw" },
diff --git a/src/agents/openclaw-tools.client-caps.test.ts b/src/agents/openclaw-tools.client-caps.test.ts
index 293d6b834d4..9a8295a3edb 100644
--- a/src/agents/openclaw-tools.client-caps.test.ts
+++ b/src/agents/openclaw-tools.client-caps.test.ts
@@ -2,16 +2,7 @@
 import { describe, expect, it, vi } from "vitest";
 
 vi.mock("./openclaw-plugin-tools.js", () => ({
-  resolveOpenClawPluginToolsForOptions: () => [
-    {
-      name: "show_widget",
-      label: "Show widget",
-      description: "Test capability-gated tool",
-      parameters: { type: "object", properties: {} },
-      requiredClientCaps: ["inline-widgets"],
-      execute: async () => ({ content: [], details: {} }),
-    },
-  ],
+  resolveOpenClawPluginToolsForOptions: () => [],
 }));
 
 import { createOpenClawCodingTools } from "./agent-tools.js";
@@ -44,6 +35,12 @@ describe("gateway client capability tool filtering", () => {
     );
   });
 
+  it("keeps the core widget tool out of Discord sessions", () => {
+    expect(
+      hasWidget(createOpenClawTools({ agentChannel: "discord", clientCaps: ["inline-widgets"] })),
+    ).toBe(false);
+  });
+
   it("only exposes screen to UI-command clients", () => {
     expect(hasScreen(createOpenClawTools())).toBe(false);
     expect(hasScreen(createOpenClawTools({ clientCaps: ["ui-commands"] }))).toBe(true);
@@ -73,9 +70,7 @@ describe("gateway client capability tool filtering", () => {
     expect(hasWidget(tools)).toBe(false);
   });
 
-  it("filters gated tools on plugin-only construction plans", () => {
-    // Regression: plugin-only plans bypass createOpenClawTools, which used to
-    // skip the capability gate entirely for narrow allowlists.
+  it("does not add the core widget tool to plugin-only construction plans", () => {
     const plan = {
       includeBaseCodingTools: false,
       includeShellTools: false,
@@ -97,6 +92,6 @@ describe("gateway client capability tool filtering", () => {
           toolConstructionPlan: plan,
         }),
       ),
-    ).toBe(true);
+    ).toBe(false);
   });
 });
diff --git a/src/agents/openclaw-tools.ts b/src/agents/openclaw-tools.ts
index d60801c58e1..2cbc3cbc12b 100644
--- a/src/agents/openclaw-tools.ts
+++ b/src/agents/openclaw-tools.ts
@@ -4,6 +4,7 @@ import type {
   SourceReplyDeliveryMode,
   TaskSuggestionDeliveryMode,
 } from "../auto-reply/get-reply-options.types.js";
+import { createShowWidgetTool } from "../canvas/widget-tool.js";
 import type { ChatType } from "../channels/chat-type.js";
 import type { InboundEventKind } from "../channels/inbound-event/kind.js";
 import type { ConversationReadInvocationOrigin } from "../channels/plugins/conversation-read-origin.js";
@@ -522,6 +523,16 @@ export function createOpenClawTools(
         })
       : []),
     ...(messageTool && includeMessageTool ? [messageTool] : []),
+    // Discord sessions get the Discord plugin's own show_widget (Activities
+    // delivery); registering the core tool there would collide on the name.
+    ...(options?.agentChannel === "discord"
+      ? []
+      : [
+          createShowWidgetTool({
+            sessionId: options?.sessionId,
+            agentId: sessionAgentId,
+          }),
+        ]),
     ...collectPresentOpenClawTools([heartbeatTool]),
     createTtsTool({
       agentChannel: options?.agentChannel,
diff --git a/src/agents/tool-catalog.ts b/src/agents/tool-catalog.ts
index 6cd4e419674..27d52a60df0 100644
--- a/src/agents/tool-catalog.ts
+++ b/src/agents/tool-catalog.ts
@@ -294,6 +294,14 @@ const CORE_TOOL_DEFINITIONS: CoreToolDefinition[] = [
     sectionId: "ui",
     profiles: [],
   },
+  {
+    id: "show_widget",
+    label: "show_widget",
+    description: "Show an interactive widget on supported chat surfaces",
+    sectionId: "ui",
+    profiles: [],
+    includeInOpenClawGroup: true,
+  },
   {
     id: "message",
     label: "message",
diff --git a/src/canvas/constants.test.ts b/src/canvas/constants.test.ts
new file mode 100644
index 00000000000..c7ca7e9dabc
--- /dev/null
+++ b/src/canvas/constants.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import {
+  isCanvasDocumentHttpPath,
+  resolveCanvasNodeCapability,
+  withCoreCanvasNodeCapability,
+} from "./constants.js";
+
+describe("core canvas contracts", () => {
+  it("keeps document auth scoped to the stable Canvas path", () => {
+    expect(isCanvasDocumentHttpPath("/__openclaw__/canvas/documents/cv_1/index.html")).toBe(true);
+    expect(isCanvasDocumentHttpPath("/__openclaw__/canvas/index.html")).toBe(false);
+    expect(
+      resolveCanvasNodeCapability([
+        "/encoded-path",
+        "/__openclaw__/canvas/documents/cv_1/index.html",
+      ]),
+    ).toEqual({ surface: "canvas", scopeKey: "canvas:canvas" });
+  });
+
+  it("advertises one core-owned canvas surface with the historical scope key", () => {
+    expect(
+      withCoreCanvasNodeCapability([
+        { surface: "canvas", scopeKey: "canvas:canvas" },
+        { surface: "files", scopeKey: "files:files" },
+      ]),
+    ).toEqual([
+      { surface: "canvas", scopeKey: "canvas:canvas" },
+      { surface: "files", scopeKey: "files:files" },
+    ]);
+  });
+});
diff --git a/src/canvas/constants.ts b/src/canvas/constants.ts
new file mode 100644
index 00000000000..1cc248ada8a
--- /dev/null
+++ b/src/canvas/constants.ts
@@ -0,0 +1,33 @@
+import type { PluginNodeCapabilitySurface } from "../gateway/plugin-node-capability.js";
+
+/** Stable Gateway path used by chat clients for hosted Canvas content. */
+const CANVAS_HOST_PATH = "/__openclaw__/canvas";
+export const CANVAS_DOCUMENTS_PATH = `${CANVAS_HOST_PATH}/documents`;
+
+/** Keep the historical Canvas plugin scope so existing capability URLs remain valid. */
+const CANVAS_NODE_CAPABILITY: PluginNodeCapabilitySurface = {
+  surface: "canvas",
+  scopeKey: "canvas:canvas",
+};
+
+/** Returns true only for the core-owned Canvas document subtree. */
+export function isCanvasDocumentHttpPath(pathname: string): boolean {
+  return pathname.startsWith(`${CANVAS_DOCUMENTS_PATH}/`);
+}
+
+/** Resolves auth for any canonicalized candidate targeting core Canvas documents. */
+export function resolveCanvasNodeCapability(
+  pathCandidates: readonly string[],
+): PluginNodeCapabilitySurface | undefined {
+  return pathCandidates.some(isCanvasDocumentHttpPath) ? CANVAS_NODE_CAPABILITY : undefined;
+}
+
+/** Adds the core Canvas surface while removing stale plugin-owned duplicates. */
+export function withCoreCanvasNodeCapability(
+  surfaces: readonly PluginNodeCapabilitySurface[],
+): PluginNodeCapabilitySurface[] {
+  return [
+    CANVAS_NODE_CAPABILITY,
+    ...surfaces.filter((entry) => entry.surface.trim() !== CANVAS_NODE_CAPABILITY.surface),
+  ];
+}
diff --git a/src/canvas/documents.test.ts b/src/canvas/documents.test.ts
new file mode 100644
index 00000000000..7ae254f1030
--- /dev/null
+++ b/src/canvas/documents.test.ts
@@ -0,0 +1,187 @@
+// Core Canvas document storage and URL contract coverage.
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createCanvasDocument,
+  resolveCanvasDocumentsDir,
+  resolveCanvasHttpPathToLocalPath,
+} from "./documents.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createTempDir(label = "openclaw-canvas-documents-"): Promise<string> {
+  const dir = await mkdtemp(path.join(tmpdir(), label));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function resolveCanvasDocumentDir(stateDir: string, documentId: string): string {
+  return path.join(resolveCanvasDocumentsDir(stateDir), documentId);
+}
+
+describe("canvas documents", () => {
+  it("builds entry urls for materialized path documents under managed storage", async () => {
+    const stateDir = await createTempDir();
+    const workspaceDir = await createTempDir("openclaw-canvas-documents-workspace-");
+    await mkdir(path.join(workspaceDir, "player"), { recursive: true });
+    await writeFile(path.join(workspaceDir, "player/index.html"), "<div>ok</div>", "utf8");
+
+    const document = await createCanvasDocument(
+      {
+        kind: "html_bundle",
+        entrypoint: { type: "path", value: "player/index.html" },
+      },
+      { stateDir, workspaceDir },
+    );
+
+    expect(document.entryUrl).toContain("/__openclaw__/canvas/documents/");
+    expect(document.localEntrypoint).toBe("index.html");
+    expect(resolveCanvasDocumentDir(stateDir, document.id)).toContain(stateDir);
+  });
+
+  it("materializes inline html bundles as index documents", async () => {
+    const stateDir = await createTempDir();
+    const document = await createCanvasDocument(
+      {
+        kind: "html_bundle",
+        title: "Preview",
+        entrypoint: {
+          type: "html",
+          value:
+            "<!doctype html><html><head><style>.demo{color:red}</style></head><body><div class='demo'>Front</div></body></html>",
+        },
+      },
+      { stateDir },
+    );
+
+    const indexHtml = await readFile(
+      path.join(resolveCanvasDocumentDir(stateDir, document.id), "index.html"),
+      "utf8",
+    );
+    expect(indexHtml).toContain("<div class='demo'>Front</div>");
+    expect(indexHtml).toContain("<style>.demo{color:red}</style>");
+    expect(document.title).toBe("Preview");
+    expect(document.entryUrl).toBe(`/__openclaw__/canvas/documents/${document.id}/index.html`);
+  });
+
+  it("reuses a supplied stable id by replacing the prior materialized view", async () => {
+    const stateDir = await createTempDir();
+    const first = await createCanvasDocument(
+      {
+        id: "status-card",
+        kind: "html_bundle",
+        entrypoint: { type: "html", value: "<div>first</div>" },
+      },
+      { stateDir },
+    );
+    const second = await createCanvasDocument(
+      {
+        id: "status-card",
+        kind: "html_bundle",
+        entrypoint: { type: "html", value: "<div>second</div>" },
+      },
+      { stateDir },
+    );
+
+    expect(first.id).toBe("status-card");
+    expect(second.id).toBe("status-card");
+    const indexHtml = await readFile(
+      path.join(resolveCanvasDocumentDir(stateDir, second.id), "index.html"),
+      "utf8",
+    );
+    expect(indexHtml).toContain("second");
+    expect(indexHtml).not.toContain("first");
+  });
+
+  it("copies declared assets into managed storage", async () => {
+    const stateDir = await createTempDir();
+    const workspaceDir = await createTempDir("openclaw-canvas-documents-workspace-");
+    await mkdir(path.join(workspaceDir, "collection.media"), { recursive: true });
+    await writeFile(path.join(workspaceDir, "collection.media/audio.mp3"), "audio", "utf8");
+
+    const document = await createCanvasDocument(
+      {
+        kind: "html_bundle",
+        entrypoint: { type: "html", value: "<audio></audio>" },
+        assets: [
+          {
+            logicalPath: "collection.media/audio.mp3",
+            sourcePath: "collection.media/audio.mp3",
+            contentType: "audio/mpeg",
+          },
+        ],
+      },
+      { stateDir, workspaceDir },
+    );
+
+    expect(document.assets).toEqual([
+      { logicalPath: "collection.media/audio.mp3", contentType: "audio/mpeg" },
+    ]);
+    await expect(
+      readFile(
+        path.join(resolveCanvasDocumentDir(stateDir, document.id), "collection.media/audio.mp3"),
+        "utf8",
+      ),
+    ).resolves.toBe("audio");
+  });
+
+  it("wraps local and remote PDF documents in index viewer pages", async () => {
+    const stateDir = await createTempDir();
+    const workspaceDir = await createTempDir("openclaw-canvas-documents-workspace-");
+    await writeFile(path.join(workspaceDir, "demo.pdf"), "%PDF-1.4", "utf8");
+    const localDocument = await createCanvasDocument(
+      { kind: "document", entrypoint: { type: "path", value: "demo.pdf" } },
+      { stateDir, workspaceDir },
+    );
+    const remoteDocument = await createCanvasDocument(
+      {
+        kind: "document",
+        entrypoint: { type: "url", value: "https://example.com/demo.pdf" },
+      },
+      { stateDir },
+    );
+
+    const localHtml = await readFile(
+      path.join(resolveCanvasDocumentDir(stateDir, localDocument.id), "index.html"),
+      "utf8",
+    );
+    const remoteHtml = await readFile(
+      path.join(resolveCanvasDocumentDir(stateDir, remoteDocument.id), "index.html"),
+      "utf8",
+    );
+    expect(localHtml).toContain('data="demo.pdf"');
+    expect(remoteHtml).toContain('data="https://example.com/demo.pdf"');
+  });
+
+  it("rejects traversal and malformed encoded hosted paths", async () => {
+    const stateDir = await createTempDir();
+    expect(
+      resolveCanvasHttpPathToLocalPath(
+        "/__openclaw__/canvas/documents/../collection.media/index.html",
+        { stateDir },
+      ),
+    ).toBeNull();
+
+    const documentDir = resolveCanvasDocumentDir(stateDir, "cv_malformed");
+    await mkdir(documentDir, { recursive: true });
+    await writeFile(path.join(documentDir, "%E0%A4%A.html"), "literal-percent-name", "utf8");
+    expect(
+      resolveCanvasHttpPathToLocalPath(
+        "/__openclaw__/canvas/documents/cv_malformed/%E0%A4%A.html",
+        { stateDir },
+      ),
+    ).toBeNull();
+    expect(
+      resolveCanvasHttpPathToLocalPath(
+        "/__openclaw__/canvas/documents/cv_malformed/%25E0%25A4%25A.html",
+        { stateDir },
+      ),
+    ).toBe(path.join(documentDir, "%E0%A4%A.html"));
+  });
+});
diff --git a/extensions/canvas/src/documents.ts b/src/canvas/documents.ts
similarity index 76%
rename from extensions/canvas/src/documents.ts
rename to src/canvas/documents.ts
index e8d1c9f2ef8..83c5d7c1e1e 100644
--- a/extensions/canvas/src/documents.ts
+++ b/src/canvas/documents.ts
@@ -1,14 +1,12 @@
-/**
- * Canvas document materialization helpers for hosted HTML, media, documents,
- * and asset manifests.
- */
+/** Core Canvas document materialization and hosted-path resolution. */
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { root as fsRoot, sanitizeUntrustedFileName } from "openclaw/plugin-sdk/security-runtime";
-import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
-import { escapeHtml, resolveUserPath } from "openclaw/plugin-sdk/text-utility-runtime";
-import { CANVAS_HOST_PATH } from "./host/a2ui.js";
+import { resolveStateDir } from "../config/paths.js";
+import { sanitizeUntrustedFileName } from "../infra/fs-safe-advanced.js";
+import { root as fsRoot } from "../infra/fs-safe.js";
+import { resolveUserPath } from "../utils.js";
+import { CANVAS_DOCUMENTS_PATH } from "./constants.js";
 
 type CanvasDocumentKind = "html_bundle" | "url_embed" | "document" | "image" | "video_asset";
 
@@ -32,11 +30,11 @@ type CanvasDocumentCreateInput = {
   assets?: CanvasDocumentAsset[];
   surface?: "assistant_message" | "tool_card" | "sidebar";
   retentionScope?: string;
-  /** Serve the document with a CSP sandbox header so direct opens get an opaque origin. */
+  /** Serve with a CSP sandbox header so direct opens get an opaque origin. */
   cspSandbox?: "scripts";
 };
 
-type CanvasDocumentManifest = {
+export type CanvasDocumentManifest = {
   id: string;
   kind: CanvasDocumentKind;
   title?: string;
@@ -54,14 +52,14 @@ type CanvasDocumentManifest = {
   }>;
 };
 
-type CanvasDocumentResolvedAsset = {
-  logicalPath: string;
-  contentType?: string;
-  url: string;
-  localPath: string;
-};
-
-const CANVAS_DOCUMENTS_DIR_NAME = "documents";
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
 
 function isPdfPathLike(value: string): boolean {
   return /\.pdf(?:[?#].*)?$/i.test(value.trim());
@@ -72,6 +70,16 @@ function buildPdfWrapper(url: string): string {
   return `<!doctype html><html><body style="margin:0;background:#e5e7eb;"><object data="${escaped}" type="application/pdf" style="width:100%;height:100vh;border:0;"><iframe src="${escaped}" style="width:100%;height:100vh;border:0;"></iframe><p style="padding:16px;font:14px system-ui,sans-serif;">Unable to render PDF preview. <a href="${escaped}" target="_blank" rel="noopener noreferrer">Open PDF</a>.</p></object></body></html>`;
 }
 
+function hasControlCharacter(value: string): boolean {
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code < 0x20 || code === 0x7f) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function normalizeLogicalPath(value: string): string {
   const normalized = value.replaceAll("\\", "/").replace(/^\/+/, "");
   const parts = normalized.split("/").filter(Boolean);
@@ -86,16 +94,6 @@ function normalizeLogicalPath(value: string): string {
   return parts.join("/");
 }
 
-function hasControlCharacter(value: string): boolean {
-  for (const char of value) {
-    const code = char.charCodeAt(0);
-    if (code < 0x20 || code === 0x7f) {
-      return true;
-    }
-  }
-  return false;
-}
-
 function canvasDocumentId(): string {
   return `cv_${randomUUID().replaceAll("-", "")}`;
 }
@@ -113,13 +111,9 @@ function normalizeCanvasDocumentId(value: string): string {
   return normalized;
 }
 
-function resolveCanvasRootDir(rootDir?: string, stateDir = resolveStateDir()): string {
-  const resolved = rootDir?.trim() ? resolveUserPath(rootDir) : path.join(stateDir, "canvas");
-  return path.resolve(resolved);
-}
-
-function resolveCanvasDocumentsDir(rootDir?: string, stateDir = resolveStateDir()): string {
-  return path.join(resolveCanvasRootDir(rootDir, stateDir), CANVAS_DOCUMENTS_DIR_NAME);
+/** Stable root for existing and newly created Canvas documents. */
+export function resolveCanvasDocumentsDir(stateDir = resolveStateDir()): string {
+  return path.resolve(stateDir, "canvas", "documents");
 }
 
 async function pruneCanvasDocumentsForScope(params: {
@@ -168,34 +162,27 @@ async function pruneCanvasDocumentsForScope(params: {
 }
 
 /** Resolves the on-disk directory for one Canvas document id. */
-export function resolveCanvasDocumentDir(
-  documentId: string,
-  options?: { rootDir?: string; stateDir?: string },
-): string {
-  return path.join(resolveCanvasDocumentsDir(options?.rootDir, options?.stateDir), documentId);
+function resolveCanvasDocumentDir(documentId: string, options?: { stateDir?: string }): string {
+  return path.join(resolveCanvasDocumentsDir(options?.stateDir), documentId);
 }
 
 /** Builds the hosted URL path for a Canvas document entrypoint. */
-export function buildCanvasDocumentEntryUrl(documentId: string, entrypoint: string): string {
+function buildCanvasDocumentEntryUrl(documentId: string, entrypoint: string): string {
   const normalizedEntrypoint = normalizeLogicalPath(entrypoint);
   const encodedEntrypoint = normalizedEntrypoint
     .split("/")
     .map((segment) => encodeURIComponent(segment))
     .join("/");
-  return `${CANVAS_HOST_PATH}/${CANVAS_DOCUMENTS_DIR_NAME}/${encodeURIComponent(documentId)}/${encodedEntrypoint}`;
+  return `${CANVAS_DOCUMENTS_PATH}/${encodeURIComponent(documentId)}/${encodedEntrypoint}`;
 }
 
-function buildCanvasDocumentAssetUrl(documentId: string, logicalPath: string): string {
-  return buildCanvasDocumentEntryUrl(documentId, logicalPath);
-}
-
-/** Maps a Canvas hosted document URL path back to a local file path. */
+/** Maps a Canvas hosted document URL path back to its managed local file. */
 export function resolveCanvasHttpPathToLocalPath(
   requestPath: string,
-  options?: { rootDir?: string; stateDir?: string },
+  options?: { stateDir?: string },
 ): string | null {
   const trimmed = requestPath.trim();
-  const prefix = `${CANVAS_HOST_PATH}/${CANVAS_DOCUMENTS_DIR_NAME}/`;
+  const prefix = `${CANVAS_DOCUMENTS_PATH}/`;
   if (!trimmed.startsWith(prefix)) {
     return null;
   }
@@ -222,16 +209,12 @@ export function resolveCanvasHttpPathToLocalPath(
   try {
     const documentId = normalizeCanvasDocumentId(rawDocumentId);
     const normalizedEntrypoint = normalizeLogicalPath(entrySegments.join("/"));
-    const documentsDir = path.resolve(
-      resolveCanvasDocumentsDir(options?.rootDir, options?.stateDir),
-    );
+    const documentsDir = resolveCanvasDocumentsDir(options?.stateDir);
     const candidatePath = path.resolve(
       resolveCanvasDocumentDir(documentId, options),
       normalizedEntrypoint,
     );
-    if (
-      !(candidatePath === documentsDir || candidatePath.startsWith(`${documentsDir}${path.sep}`))
-    ) {
+    if (!candidatePath.startsWith(`${documentsDir}${path.sep}`)) {
       return null;
     }
     return candidatePath;
@@ -242,13 +225,6 @@ export function resolveCanvasHttpPathToLocalPath(
 
 type CanvasDocumentRoot = Awaited<ReturnType<typeof fsRoot>>;
 
-async function writeManifest(
-  root: CanvasDocumentRoot,
-  manifest: CanvasDocumentManifest,
-): Promise<void> {
-  await root.writeJson("manifest.json", manifest, { space: 2 });
-}
-
 async function copyAssets(
   root: CanvasDocumentRoot,
   assets: CanvasDocumentAsset[] | undefined,
@@ -299,10 +275,7 @@ async function materializeEntrypoint(
         entryUrl: buildCanvasDocumentEntryUrl(path.basename(rootDir), fileName),
       };
     }
-    return {
-      externalUrl: entrypoint.value,
-      entryUrl: entrypoint.value,
-    };
+    return { externalUrl: entrypoint.value, entryUrl: entrypoint.value };
   }
 
   const resolvedPath = entrypoint.value.startsWith("~")
@@ -346,16 +319,12 @@ export async function createCanvasDocument(
   options?: {
     stateDir?: string;
     workspaceDir?: string;
-    canvasRootDir?: string;
     maxDocumentsPerScope?: number;
   },
 ): Promise<CanvasDocumentManifest> {
   const workspaceDir = options?.workspaceDir ?? process.cwd();
   const id = input.id?.trim() ? normalizeCanvasDocumentId(input.id) : canvasDocumentId();
-  const rootDir = resolveCanvasDocumentDir(id, {
-    stateDir: options?.stateDir,
-    rootDir: options?.canvasRootDir,
-  });
+  const rootDir = resolveCanvasDocumentDir(id, { stateDir: options?.stateDir });
   await fs.rm(rootDir, { recursive: true, force: true }).catch(() => undefined);
   await fs.mkdir(rootDir, { recursive: true });
   const root = await fsRoot(rootDir);
@@ -377,34 +346,14 @@ export async function createCanvasDocument(
     ...(entry.externalUrl ? { externalUrl: entry.externalUrl } : {}),
     assets,
   };
-  await writeManifest(root, manifest);
+  await root.writeJson("manifest.json", manifest, { space: 2 });
   if (input.retentionScope && options?.maxDocumentsPerScope) {
     // Bounded transcript widgets cannot grow managed Canvas storage without limit.
     await pruneCanvasDocumentsForScope({
-      documentsDir: resolveCanvasDocumentsDir(options.canvasRootDir, options.stateDir),
+      documentsDir: resolveCanvasDocumentsDir(options.stateDir),
       retentionScope: input.retentionScope,
       maxDocuments: options.maxDocumentsPerScope,
     });
   }
   return manifest;
 }
-
-/** Resolves manifest assets to local paths and hosted URLs. */
-export function resolveCanvasDocumentAssets(
-  manifest: CanvasDocumentManifest,
-  options?: { baseUrl?: string; stateDir?: string; canvasRootDir?: string },
-): CanvasDocumentResolvedAsset[] {
-  const baseUrl = options?.baseUrl?.trim().replace(/\/+$/, "");
-  const documentDir = resolveCanvasDocumentDir(manifest.id, {
-    stateDir: options?.stateDir,
-    rootDir: options?.canvasRootDir,
-  });
-  return manifest.assets.map((asset) => ({
-    logicalPath: asset.logicalPath,
-    ...(asset.contentType ? { contentType: asset.contentType } : {}),
-    localPath: path.join(documentDir, asset.logicalPath),
-    url: baseUrl
-      ? `${baseUrl}${buildCanvasDocumentAssetUrl(manifest.id, asset.logicalPath)}`
-      : buildCanvasDocumentAssetUrl(manifest.id, asset.logicalPath),
-  }));
-}
diff --git a/src/canvas/serve.runtime.test.ts b/src/canvas/serve.runtime.test.ts
new file mode 100644
index 00000000000..8e638054b59
--- /dev/null
+++ b/src/canvas/serve.runtime.test.ts
@@ -0,0 +1,102 @@
+// Core Canvas document HTTP response coverage.
+import { mkdtemp, rm } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createCanvasDocument } from "./documents.js";
+import { handleCanvasDocumentHttpRequest } from "./serve.runtime.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function createStateDir(): Promise<string> {
+  const stateDir = await mkdtemp(path.join(tmpdir(), "openclaw-canvas-serve-"));
+  tempDirs.push(stateDir);
+  vi.stubEnv("OPENCLAW_STATE_DIR", stateDir);
+  return stateDir;
+}
+
+async function capture(url: string, method = "GET") {
+  const response = {
+    statusCode: 200,
+    headers: {} as Record<string, number | string | string[]>,
+    body: Buffer.alloc(0) as Buffer,
+    setHeader(name: string, value: number | string | readonly string[]) {
+      this.headers[name.toLowerCase()] = typeof value === "object" ? [...value] : value;
+      return this;
+    },
+    end(chunk?: string | Buffer) {
+      this.body = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk ?? "");
+      return this;
+    },
+  };
+  const handled = await handleCanvasDocumentHttpRequest(
+    { method, url } as IncomingMessage,
+    response as unknown as ServerResponse,
+  );
+  return { handled, ...response, text: response.body.toString("utf8") };
+}
+
+describe("core canvas document host", () => {
+  it("serves sandbox-marked HTML with the stable CSP header and no mutation", async () => {
+    const stateDir = await createStateDir();
+    const html = "<html><body>widget</body></html>";
+    const document = await createCanvasDocument(
+      {
+        id: "widget-1",
+        kind: "html_bundle",
+        entrypoint: { type: "html", value: html },
+        cspSandbox: "scripts",
+      },
+      { stateDir },
+    );
+
+    const response = await capture(document.entryUrl);
+    expect(response.handled).toBe(true);
+    expect(response.statusCode).toBe(200);
+    expect(response.headers["content-type"]).toBe("text/html; charset=utf-8");
+    expect(response.headers["cache-control"]).toBe("no-store");
+    expect(response.headers["content-security-policy"]).toBe("sandbox allow-scripts");
+    expect(response.text).toBe(html);
+  });
+
+  it("omits the sandbox response header for unmarked documents", async () => {
+    const stateDir = await createStateDir();
+    const document = await createCanvasDocument(
+      {
+        id: "plain-1",
+        kind: "html_bundle",
+        entrypoint: { type: "html", value: "<html><body>plain</body></html>" },
+      },
+      { stateDir },
+    );
+
+    const response = await capture(document.entryUrl);
+    expect(response.statusCode).toBe(200);
+    expect(response.headers["content-security-policy"]).toBeUndefined();
+  });
+
+  it("rejects unsupported methods and traversal paths", async () => {
+    await createStateDir();
+    const methodResponse = await capture(
+      "/__openclaw__/canvas/documents/widget-1/index.html",
+      "POST",
+    );
+    expect(methodResponse.statusCode).toBe(405);
+    expect(methodResponse.text).toBe("Method Not Allowed");
+
+    const traversalResponse = await capture(
+      "/__openclaw__/canvas/documents/../widget-1/index.html",
+    );
+    expect(traversalResponse.handled).toBe(false);
+
+    const missingResponse = await capture("/__openclaw__/canvas/documents/widget-1/index.html");
+    expect(missingResponse.statusCode).toBe(404);
+    expect(missingResponse.text).toBe("not found");
+  });
+});
diff --git a/src/canvas/serve.runtime.ts b/src/canvas/serve.runtime.ts
new file mode 100644
index 00000000000..9f66b123615
--- /dev/null
+++ b/src/canvas/serve.runtime.ts
@@ -0,0 +1,99 @@
+/** Gateway runtime for core-owned Canvas document HTTP responses. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import path from "node:path";
+import { detectMime } from "@openclaw/media-core/mime";
+import { FsSafeError, root as fsRoot } from "../infra/fs-safe.js";
+import {
+  resolveCanvasDocumentsDir,
+  resolveCanvasHttpPathToLocalPath,
+  type CanvasDocumentManifest,
+} from "./documents.js";
+
+async function readRootFile(root: Awaited<ReturnType<typeof fsRoot>>, relativePath: string) {
+  try {
+    const opened = await root.open(relativePath);
+    try {
+      return { data: await opened.handle.readFile(), realPath: opened.realPath };
+    } finally {
+      await opened.handle.close().catch(() => {});
+    }
+  } catch (error) {
+    if (error instanceof FsSafeError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function resolveDocumentSandbox(
+  root: Awaited<ReturnType<typeof fsRoot>>,
+  relativePath: string,
+): Promise<"scripts" | undefined> {
+  const documentId = relativePath.split(path.sep)[0];
+  if (!documentId) {
+    return undefined;
+  }
+  const opened = await readRootFile(root, path.join(documentId, "manifest.json"));
+  if (!opened) {
+    return undefined;
+  }
+  try {
+    const manifest = JSON.parse(opened.data.toString("utf8")) as CanvasDocumentManifest;
+    return manifest.cspSandbox === "scripts" ? "scripts" : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Serves one managed Canvas document request. */
+export async function handleCanvasDocumentHttpRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  const localPath = resolveCanvasHttpPathToLocalPath(req.url ?? "");
+  if (!localPath) {
+    return false;
+  }
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.end("Method Not Allowed");
+    return true;
+  }
+
+  try {
+    const documentsDir = resolveCanvasDocumentsDir();
+    const relativePath = path.relative(documentsDir, localPath);
+    const root = await fsRoot(documentsDir);
+    const opened = await readRootFile(root, relativePath);
+    if (!opened) {
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.end("not found");
+      return true;
+    }
+
+    const lowerPath = opened.realPath.toLowerCase();
+    const mime =
+      lowerPath.endsWith(".html") || lowerPath.endsWith(".htm")
+        ? "text/html"
+        : ((await detectMime({ filePath: opened.realPath })) ?? "application/octet-stream");
+    res.setHeader("Cache-Control", "no-store");
+    if (mime === "text/html") {
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      if ((await resolveDocumentSandbox(root, relativePath)) === "scripts") {
+        res.setHeader("Content-Security-Policy", "sandbox allow-scripts");
+      }
+      res.end(opened.data.toString("utf8"));
+      return true;
+    }
+    res.setHeader("Content-Type", mime);
+    res.end(opened.data);
+    return true;
+  } catch (error) {
+    res.statusCode = error instanceof FsSafeError ? 404 : 500;
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.end(error instanceof FsSafeError ? "not found" : "error");
+    return true;
+  }
+}
diff --git a/extensions/canvas/src/widget-tool.test.ts b/src/canvas/widget-tool.test.ts
similarity index 73%
rename from extensions/canvas/src/widget-tool.test.ts
rename to src/canvas/widget-tool.test.ts
index 7cd47069c68..e3d9b7423f9 100644
--- a/extensions/canvas/src/widget-tool.test.ts
+++ b/src/canvas/widget-tool.test.ts
@@ -1,15 +1,15 @@
-// Covers inline widget validation, materialization, preview extraction, and retention.
+// Core inline widget validation, byte stability, materialization, and retention.
+import { createHash } from "node:crypto";
 import { access, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { resolveCanvasDocumentDir } from "./documents.js";
-import {
-  createShowWidgetTool,
-  WIDGET_CODE_MAX_CHARS,
-  WIDGET_MAX_PER_SCOPE,
-} from "./widget-tool.js";
+import { resolveCanvasDocumentsDir } from "./documents.js";
+import { createShowWidgetTool } from "./widget-tool.js";
+import { buildWidgetDocument } from "./wrap.js";
 
+const WIDGET_CODE_MAX_CHARS = 262_144;
+const WIDGET_MAX_PER_SCOPE = 32;
 const tempDirs: string[] = [];
 
 afterEach(async () => {
@@ -23,6 +23,10 @@ async function createStateDir(): Promise<string> {
   return stateDir;
 }
 
+function resolveCanvasDocumentDir(stateDir: string, documentId: string): string {
+  return path.join(resolveCanvasDocumentsDir(stateDir), documentId);
+}
+
 async function executeWidget(params: {
   stateDir: string;
   sessionId?: string;
@@ -42,8 +46,6 @@ async function executeWidget(params: {
   if (!text) {
     throw new Error("expected widget tool text result");
   }
-  // Parse the canvas-handle JSON directly; the web chat's extraction of this
-  // shape is covered by ui/src/pages/chat/components/chat-tool-cards.node.test.ts.
   const parsed = JSON.parse(text) as {
     kind?: string;
     presentation?: { target?: string; title?: string; sandbox?: string };
@@ -58,6 +60,18 @@ async function executeWidget(params: {
 }
 
 describe("show_widget", () => {
+  it("keeps the pre-move wrapped document bytes stable", () => {
+    const html = buildWidgetDocument(
+      "Status <live>",
+      '<SvG viewBox="0 0 10 10"><circle r="4" /></SvG>',
+    );
+
+    expect(Buffer.byteLength(html)).toBe(1558);
+    expect(createHash("sha256").update(html).digest("hex")).toBe(
+      "ba5fd66ce29e864415c60fecc2b03290c05f1d66bd02b47de39ced8afec6e65c",
+    );
+  });
+
   it("rejects empty and oversized widget code", async () => {
     const stateDir = await createStateDir();
     const tool = createShowWidgetTool({ stateDir, sessionId: "validation" });
@@ -73,7 +87,7 @@ describe("show_widget", () => {
     ).rejects.toThrow(`widget_code exceeds maximum size (${WIDGET_CODE_MAX_CHARS} characters)`);
   });
 
-  it("wraps SVG widgets with the sandbox CSP and SVG layout", async () => {
+  it("wraps SVG widgets with the stable result and sandbox contracts", async () => {
     const stateDir = await createStateDir();
     const { viewId, url, sandbox, text } = await executeWidget({
       stateDir,
@@ -90,7 +104,7 @@ describe("show_widget", () => {
     });
     expect(sandbox).toBe("scripts");
     const html = await readFile(
-      path.join(resolveCanvasDocumentDir(viewId, { stateDir }), "index.html"),
+      path.join(resolveCanvasDocumentDir(stateDir, viewId), "index.html"),
       "utf8",
     );
     expect(html).toContain(
@@ -98,41 +112,30 @@ describe("show_widget", () => {
     );
     expect(html).toContain("<title>&lt;Status&gt;</title>");
     expect(html).toContain('<body class="svg-widget"><script>');
-    expect(html).toContain('</script><SvG viewBox="0 0 10 10">');
-    // The embedding chat fits the iframe to the reported content height.
     expect(html).toContain("openclaw:widget-size");
     const manifest = JSON.parse(
       await readFile(
-        path.join(resolveCanvasDocumentDir(viewId, { stateDir }), "manifest.json"),
+        path.join(resolveCanvasDocumentDir(stateDir, viewId), "manifest.json"),
         "utf8",
       ),
     ) as { cspSandbox?: string };
-    // The host keys the served CSP sandbox header off this manifest field.
     expect(manifest.cspSandbox).toBe("scripts");
   });
 
-  it("wraps HTML fragments without SVG layout", async () => {
+  it("keeps the prompt bridge ahead of HTML widget code", async () => {
     const stateDir = await createStateDir();
     const { viewId } = await executeWidget({
       stateDir,
       widgetCode: "<section><button>Run</button><script>document.title='ready'</script></section>",
     });
     const html = await readFile(
-      path.join(resolveCanvasDocumentDir(viewId, { stateDir }), "index.html"),
+      path.join(resolveCanvasDocumentDir(stateDir, viewId), "index.html"),
       "utf8",
     );
 
-    expect(html).toContain("<section><button>Run</button><script>");
     expect(html).not.toContain('<body class="svg-widget">');
-    // The prompt bridge must precede widget code so inline handlers can
-    // reference sendPrompt() while the widget's own scripts run.
     expect(html.indexOf("window.sendPrompt")).toBeLessThan(html.indexOf("<section>"));
-    // Prompts flow over a channel the bridge creates and offers to the chat at
-    // parse time, never directly to window.parent; the send endpoint stays
-    // private to the bridge closure and requires transient user activation.
     expect(html).toContain("openclaw:widget-prompt-offer");
-    // Natives are snapshotted before widget code runs: the bound port endpoint
-    // and the native userActivation getter cannot be patched away.
     expect(html).toContain("navigator.userActivation");
     expect(html).toContain("c.port1.postMessage.bind(c.port1)");
     expect(html).toContain('post({type:"openclaw:widget-prompt"');
@@ -149,7 +152,7 @@ describe("show_widget", () => {
       await executeWidget({ stateDir, widgetCode: `<p>${index}</p>` });
     }
 
-    await expect(access(resolveCanvasDocumentDir(first.viewId, { stateDir }))).rejects.toThrow();
+    await expect(access(resolveCanvasDocumentDir(stateDir, first.viewId))).rejects.toThrow();
     const entries = await readdir(path.join(stateDir, "canvas", "documents"));
     expect(entries).toHaveLength(WIDGET_MAX_PER_SCOPE);
   });
diff --git a/src/canvas/widget-tool.ts b/src/canvas/widget-tool.ts
new file mode 100644
index 00000000000..ed8b6b9ec70
--- /dev/null
+++ b/src/canvas/widget-tool.ts
@@ -0,0 +1,78 @@
+/** Agent-facing inline chat widget tool. */
+import { createHash } from "node:crypto";
+import { Type } from "typebox";
+import { type AnyAgentTool, jsonResult, readStringParam } from "../agents/tools/common.js";
+import { assertWidgetHtmlSize, WidgetHtmlInputError } from "../plugin-sdk/widget-html.js";
+import { createCanvasDocument } from "./documents.js";
+import { buildWidgetDocument } from "./wrap.js";
+
+const SHOW_WIDGET_REQUIRED_CLIENT_CAPS = ["inline-widgets"];
+const WIDGET_CODE_MAX_CHARS = 262_144;
+const WIDGET_MAX_PER_SCOPE = 32;
+
+const ShowWidgetToolSchema = Type.Object({
+  title: Type.String(),
+  widget_code: Type.String(),
+});
+
+type ShowWidgetToolOptions = {
+  sessionId?: string;
+  agentId?: string;
+  stateDir?: string;
+};
+
+function resolveRetentionScope(options: ShowWidgetToolOptions): string {
+  const scope = options.sessionId
+    ? `session:${options.sessionId}`
+    : `agent:${options.agentId ?? "default"}`;
+  return createHash("sha256").update(scope).digest("hex");
+}
+
+/** Creates a self-contained widget hosted by OpenClaw core. */
+export function createShowWidgetTool(options: ShowWidgetToolOptions = {}): AnyAgentTool {
+  return {
+    label: "Show Widget",
+    name: "show_widget",
+    description:
+      "Show an interactive, self-contained HTML or SVG widget to the user on their current surface. Inline all required code and data. In web chat, a global sendPrompt(text) function submits text to the chat as if the user typed it — wire it to buttons or controls to build interactive widgets. It only works after the user clicks inside the widget (plain conversational text only; slash commands are rejected), so never call it automatically.",
+    parameters: ShowWidgetToolSchema,
+    requiredClientCaps: SHOW_WIDGET_REQUIRED_CLIENT_CAPS,
+    execute: async (_toolCallId, args) => {
+      const params = args as Record<string, unknown>;
+      const title = readStringParam(params, "title", { required: true });
+      const rawWidgetCode = readStringParam(params, "widget_code", {
+        required: true,
+        trim: false,
+      });
+      if (!rawWidgetCode.trim()) {
+        throw new WidgetHtmlInputError("widget_code required");
+      }
+      assertWidgetHtmlSize(rawWidgetCode, WIDGET_CODE_MAX_CHARS, {
+        inputName: "widget_code",
+        unit: "characters",
+      });
+      const widgetCode = rawWidgetCode.trim();
+      const document = await createCanvasDocument(
+        {
+          kind: "html_bundle",
+          title,
+          entrypoint: { type: "html", value: buildWidgetDocument(title, widgetCode) },
+          surface: "assistant_message",
+          retentionScope: resolveRetentionScope(options),
+          // Direct navigation must not run widget script as the Control UI origin.
+          cspSandbox: "scripts",
+        },
+        {
+          stateDir: options.stateDir,
+          maxDocumentsPerScope: WIDGET_MAX_PER_SCOPE,
+        },
+      );
+      return jsonResult({
+        kind: "canvas",
+        presentation: { target: "assistant_message", title, sandbox: "scripts" },
+        view: { id: document.id, url: document.entryUrl },
+        text: `Widget hosted at ${document.entryUrl}`,
+      });
+    },
+  };
+}
diff --git a/src/canvas/wrap.ts b/src/canvas/wrap.ts
new file mode 100644
index 00000000000..d568007a98f
--- /dev/null
+++ b/src/canvas/wrap.ts
@@ -0,0 +1,53 @@
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+/** Wraps agent-authored widget markup in the stable isolated Canvas document shell. */
+export function buildWidgetDocument(title: string, widgetCode: string): string {
+  const isSvg = /^<svg/i.test(widgetCode);
+  const bodyClass = isSvg ? ' class="svg-widget"' : "";
+  // Inline scripts may drive the widget; CSP blocks resource loads, while preview metadata
+  // prevents the iframe from inheriting same-origin access to the parent application.
+  // The size reporter lets the embedding chat fit the iframe to the content; the
+  // parent clamps reported heights, so widget code cannot abuse the channel.
+  const sizeReporter =
+    "<script>(()=>{if(!window.parent||window.parent===window)return;" +
+    // documentElement.scrollHeight reports the viewport for short content, so
+    // measure the body box, which tracks the actual widget height.
+    "let last=0;const report=()=>{const b=document.body;if(!b)return;" +
+    "const h=Math.ceil(Math.max(b.scrollHeight,b.offsetHeight,b.getBoundingClientRect().height));" +
+    'if(h&&h!==last){last=h;window.parent.postMessage({type:"openclaw:widget-size",height:h},"*");}};' +
+    "addEventListener('load',report);new ResizeObserver(report).observe(document.body);" +
+    "setTimeout(report,50);setTimeout(report,500);})();</script>";
+  // The prompt bridge precedes widget code so inline handlers can reference
+  // sendPrompt() immediately. It creates the prompt channel itself and offers
+  // one endpoint to the embedding chat at parse time — before any widget code
+  // can run, steal the endpoint, or navigate the frame — so the chat's
+  // first-offer-wins adoption is always bound to this document. The send
+  // endpoint stays private to this closure, and sendPrompt requires transient
+  // user activation, so widget code cannot auto-send without a real user
+  // gesture; the chat additionally validates, requires a focused visible
+  // frame, and rate limits every prompt.
+  // Everything sendPrompt later touches is snapshotted here, before widget
+  // code exists, so prototype patches (MessagePort.postMessage, the
+  // userActivation getter) by widget code cannot leak the endpoint or fake a
+  // gesture. Fail closed: no observable transient user activation, no send.
+  const promptBridge =
+    "<script>(()=>{if(!window.parent||window.parent===window)return;" +
+    "const c=new MessageChannel();" +
+    "const post=c.port1.postMessage.bind(c.port1);" +
+    "let act=null;" +
+    "try{const ua=navigator.userActivation;" +
+    'const d=ua&&Object.getOwnPropertyDescriptor(Object.getPrototypeOf(ua),"isActive");' +
+    "if(d&&d.get)act=d.get.bind(ua);}catch{}" +
+    'window.parent.postMessage({type:"openclaw:widget-prompt-offer"},"*",[c.port2]);' +
+    "window.sendPrompt=text=>{if(!act||act()!==true)return;" +
+    'post({type:"openclaw:widget-prompt",prompt:String(text)});};})();</script>';
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; img-src data:;"><title>${escapeHtml(title)}</title><style>:root{color-scheme:light dark}*{box-sizing:border-box}html,body{margin:0}body{font:14px system-ui,sans-serif}.svg-widget{display:grid;place-items:center}.svg-widget>svg{max-width:100%}</style></head><body${bodyClass}>${promptBridge}${widgetCode}${sizeReporter}</body></html>`;
+}
diff --git a/src/gateway/server-http.ts b/src/gateway/server-http.ts
index b710b5e0a55..dd59b0268fe 100644
--- a/src/gateway/server-http.ts
+++ b/src/gateway/server-http.ts
@@ -9,6 +9,7 @@ import {
 import { createServer as createHttpsServer } from "node:https";
 import type { TlsOptions } from "node:tls";
 import type { WebSocketServer } from "ws";
+import { isCanvasDocumentHttpPath } from "../canvas/constants.js";
 import { resolveBundledChannelGatewayAuthBypassPaths } from "../channels/plugins/gateway-auth-bypass.js";
 import { getRuntimeConfig } from "../config/io.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
@@ -94,6 +95,8 @@ type ResolvePluginNodeCapabilityRoute = (
 
 const getControlUiModule = createLazyRuntimeModule(() => import("./control-ui.js"));
 
+const getCanvasServeModule = createLazyRuntimeModule(() => import("../canvas/serve.runtime.js"));
+
 const getEmbeddingsHttpModule = createLazyRuntimeModule(() => import("./embeddings-http.js"));
 
 const getManagedImageAttachmentsModule = createLazyRuntimeModule(
@@ -562,9 +565,8 @@ export function createGatewayHttpServer(opts: {
         req.url = scopedNodeCapability.rewrittenUrl;
       }
       const scopedRequestPath = scopedNodeCapability.pathname;
-      const pluginPathContext = handlePluginRequest
-        ? resolvePluginRoutePathContext(scopedRequestPath)
-        : null;
+      const pluginPathContext = resolvePluginRoutePathContext(scopedRequestPath);
+      const nodeCapability = resolvePluginNodeCapabilityRoute?.(pluginPathContext);
       const resolvedAuthValue = getResolvedAuth();
       const handleControlUiRequest = async () =>
         (await getControlUiModule()).handleControlUiHttpRequest(req, res, {
@@ -735,14 +737,9 @@ export function createGatewayHttpServer(opts: {
           },
         });
       }
-      if (
-        handlePluginRequest &&
-        pluginPathContext &&
-        resolvePluginNodeCapabilityRoute?.(pluginPathContext)
-      ) {
-        const nodeCapability = resolvePluginNodeCapabilityRoute(pluginPathContext);
+      if (nodeCapability) {
         requestStages.push({
-          name: "plugin-node-capability-auth",
+          name: "node-capability-auth",
           run: async () => {
             if (!nodeCapability) {
               return false;
@@ -768,6 +765,13 @@ export function createGatewayHttpServer(opts: {
           },
         });
       }
+      if (nodeCapability && isCanvasDocumentHttpPath(scopedRequestPath)) {
+        requestStages.push({
+          name: "canvas-documents",
+          run: async () =>
+            await (await getCanvasServeModule()).handleCanvasDocumentHttpRequest(req, res),
+        });
+      }
       if (
         controlUiEnabled &&
         isControlUiPluginManagerRequest({
diff --git a/src/gateway/server-runtime-state.ts b/src/gateway/server-runtime-state.ts
index 40fa9209c19..c9f92e510e4 100644
--- a/src/gateway/server-runtime-state.ts
+++ b/src/gateway/server-runtime-state.ts
@@ -10,6 +10,7 @@ import type { AddressInfo } from "node:net";
 import type { Duplex } from "node:stream";
 import { WebSocketServer } from "ws";
 import { resolveMcpAppSandboxPort } from "../agents/mcp-app-sandbox.js";
+import { resolveCanvasNodeCapability } from "../canvas/constants.js";
 import type { CliDeps } from "../cli/deps.types.js";
 import type { createSubsystemLogger } from "../logging/subsystem.js";
 import type { PluginRegistry } from "../plugins/registry.js";
@@ -252,11 +253,15 @@ export async function createGatewayRuntimeState(params: {
     const shouldEnforcePluginGatewayAuth = (pathContext: PluginRoutePathContext): boolean => {
       return shouldEnforceGatewayAuthForPluginPath(resolvePluginRouteRegistry(), pathContext);
     };
-    const resolvePluginNodeCapabilityRoute = (pathContext: PluginRoutePathContext) =>
-      // Capability routes are selected from the current pinned registry so auth decisions and
-      // node-capability dispatch agree when plugin routes are reloaded.
-      findMatchingPluginNodeCapabilityRoute(resolvePluginRouteRegistry(), pathContext)
+    const resolvePluginNodeCapabilityRoute = (pathContext: PluginRoutePathContext) => {
+      const coreCanvasCapability = resolveCanvasNodeCapability(pathContext.candidates);
+      if (coreCanvasCapability) {
+        return coreCanvasCapability;
+      }
+      // Plugin capability routes follow the current pinned registry so auth and dispatch agree.
+      return findMatchingPluginNodeCapabilityRoute(resolvePluginRouteRegistry(), pathContext)
         ?.nodeCapability;
+    };
 
     const bindHosts = await resolveGatewayListenHosts(params.bindHost);
     if (!isLoopbackHost(params.bindHost)) {
diff --git a/src/gateway/server.impl.ts b/src/gateway/server.impl.ts
index 63877cfb9ca..4b0b05d68b5 100644
--- a/src/gateway/server.impl.ts
+++ b/src/gateway/server.impl.ts
@@ -8,6 +8,7 @@ import {
 } from "../agents/embedded-agent-runner/run-state.js";
 import { clearSessionSuspensionTimers } from "../agents/session-suspension.js";
 import { getTotalPendingReplies } from "../auto-reply/reply/dispatcher-registry.js";
+import { withCoreCanvasNodeCapability } from "../canvas/constants.js";
 import {
   getLoadedChannelPluginEntryById,
   listLoadedChannelPlugins,
@@ -2037,7 +2038,8 @@ export async function startGatewayServer(
         port,
         gatewayHost: bindHost ?? undefined,
         pluginSurfaceScheme,
-        getPluginNodeCapabilities: () => listPluginNodeCapabilities(pluginRegistry),
+        getPluginNodeCapabilities: () =>
+          withCoreCanvasNodeCapability(listPluginNodeCapabilities(pluginRegistry)),
         resolvedAuth,
         getResolvedAuth,
         getRequiredSharedGatewaySessionGeneration: () =>
diff --git a/src/media/web-media.test.ts b/src/media/web-media.test.ts
index 6e3a04c1679..bbacce85133 100644
--- a/src/media/web-media.test.ts
+++ b/src/media/web-media.test.ts
@@ -33,21 +33,6 @@ let canvasPngFile = "";
 let workspaceDir = "";
 let workspacePngFile = "";
 
-function installCanvasMediaResolver() {
-  const registry = createEmptyPluginRegistry();
-  registry.hostedMediaResolvers = [
-    {
-      pluginId: "canvas",
-      resolver: (mediaUrl) =>
-        mediaUrl === `${CANVAS_HOST_PATH}/documents/cv_test/collection.media/tiny.png`
-          ? canvasPngFile
-          : null,
-      source: "test",
-    },
-  ];
-  setActivePluginRegistry(registry);
-}
-
 beforeAll(async () => {
   ({
     effectiveImageBytesCap,
@@ -75,7 +60,6 @@ beforeAll(async () => {
   );
   await fs.mkdir(path.dirname(canvasPngFile), { recursive: true });
   await fs.writeFile(canvasPngFile, Buffer.from(TINY_PNG_BASE64, "base64"));
-  installCanvasMediaResolver();
 });
 
 afterAll(async () => {
@@ -329,7 +313,6 @@ describe("loadWebMedia", () => {
   });
 
   it("loads browser-style canvas media paths as managed local files", async () => {
-    installCanvasMediaResolver();
     const result = await loadWebMedia(
       `${CANVAS_HOST_PATH}/documents/cv_test/collection.media/tiny.png`,
       { maxBytes: 1024 * 1024 },
@@ -349,20 +332,14 @@ describe("loadWebMedia", () => {
         source: "test",
       },
       {
-        pluginId: "canvas",
-        resolver: (mediaUrl) =>
-          mediaUrl === `${CANVAS_HOST_PATH}/documents/cv_test/collection.media/tiny.png`
-            ? canvasPngFile
-            : null,
+        pluginId: "hosted-media",
+        resolver: (mediaUrl) => (mediaUrl === "/__test__/hosted/tiny.png" ? canvasPngFile : null),
         source: "test",
       },
     ];
     setActivePluginRegistry(registry);
 
-    const result = await loadWebMedia(
-      `${CANVAS_HOST_PATH}/documents/cv_test/collection.media/tiny.png`,
-      { maxBytes: 1024 * 1024 },
-    );
+    const result = await loadWebMedia("/__test__/hosted/tiny.png", { maxBytes: 1024 * 1024 });
 
     expect(result.kind).toBe("image");
     expect(result.buffer.length).toBeGreaterThan(0);
diff --git a/src/media/web-media.ts b/src/media/web-media.ts
index f5c9e331476..a232c19260d 100644
--- a/src/media/web-media.ts
+++ b/src/media/web-media.ts
@@ -13,6 +13,7 @@ import {
 } from "@openclaw/media-core/mime";
 import { hasHttpUrlPrefix } from "@openclaw/net-policy/url-protocol";
 import { uniqueValues } from "@openclaw/normalization-core/string-normalization";
+import { resolveCanvasHttpPathToLocalPath } from "../canvas/documents.js";
 import { logVerbose, shouldLogVerbose } from "../globals.js";
 import { formatErrorMessage } from "../infra/errors.js";
 import { FsSafeError, readLocalFileSafely } from "../infra/fs-safe.js";
@@ -879,7 +880,10 @@ async function loadWebMediaInternal(
       throw new LocalMediaAccessError("invalid-file-url", (err as Error).message, { cause: err });
     }
   }
-  mediaUrl = (await resolveHostedPluginMediaUrl(mediaUrl)) ?? mediaUrl;
+  mediaUrl =
+    resolveCanvasHttpPathToLocalPath(mediaUrl) ??
+    (await resolveHostedPluginMediaUrl(mediaUrl)) ??
+    mediaUrl;
   mediaUrl = stripLegacyMediaDirectivePrefix(mediaUrl);
 
   const optimizeAndClampImage = async (
diff --git a/src/plugins/tools.optional.test.ts b/src/plugins/tools.optional.test.ts
index 9d0a357f20c..faab7a5f9a8 100644
--- a/src/plugins/tools.optional.test.ts
+++ b/src/plugins/tools.optional.test.ts
@@ -1974,48 +1974,31 @@ describe("resolvePluginTools optional tools", () => {
   });
 
   it("allows a plugin to register a second tool when one tool shares the plugin id", () => {
-    // Regression: the canvas plugin registers a `canvas` tool (same name as its
-    // plugin id) plus `show_widget`; the id-conflict guard must not treat the
-    // plugin's own earlier tool as a shadowing core name.
     const registry = setRegistry([
       {
-        pluginId: "canvas",
+        pluginId: "demo",
         optional: false,
-        source: "/tmp/canvas.js",
-        names: ["canvas"],
-        factory: () => makeTool("canvas"),
+        source: "/tmp/demo.js",
+        names: ["demo"],
+        factory: () => makeTool("demo"),
       },
       {
-        pluginId: "canvas",
+        pluginId: "demo",
         optional: false,
-        source: "/tmp/canvas.js",
-        names: ["show_widget"],
-        factory: () => makeTool("show_widget"),
+        source: "/tmp/demo.js",
+        names: ["extra_tool"],
+        factory: () => makeTool("extra_tool"),
       },
     ]);
 
     const tools = resolvePluginTools(createResolveToolsParams({}));
 
-    expectResolvedToolNames(tools, ["canvas", "show_widget"]);
+    expectResolvedToolNames(tools, ["demo", "extra_tool"]);
     expect(registry.diagnostics).toHaveLength(0);
   });
 
-  it("filters client-cap tools before resolving contextual duplicate names", () => {
+  it("keeps the Discord-owned show_widget contextual to Discord sessions", () => {
     const registry = setRegistry([
-      {
-        pluginId: "canvas",
-        optional: false,
-        source: "/tmp/canvas.js",
-        names: ["show_widget"],
-        factory: (context) =>
-          (context as { messageChannel?: string }).messageChannel === "discord"
-            ? null
-            : {
-                ...makeTool("show_widget"),
-                description: "canvas implementation",
-                requiredClientCaps: ["inline-widgets"],
-              },
-      },
       {
         pluginId: "discord",
         optional: false,
@@ -2044,9 +2027,7 @@ describe("resolvePluginTools optional tools", () => {
         clientCaps: ["inline-widgets"],
       }),
     );
-    expect(webTools.map((tool) => [tool.name, tool.description])).toEqual([
-      ["show_widget", "canvas implementation"],
-    ]);
+    expect(webTools).toHaveLength(0);
     expect(registry.diagnostics).toHaveLength(0);
   });
 

From 0acece45912de43a7c29638babcb70afce59652c Mon Sep 17 00:00:00 2001
From: Peter Steinberger <peter@steipete.me>
Date: Sat, 18 Jul 2026 14:46:34 +0100
Subject: [PATCH 71/76] feat(chat): rewind and fork a session from a message
 bubble (#110660)

* feat(chat): rewind and fork a session from a message bubble

* docs(web): document chat rewind and fork bubble actions

* fix(chat): lint cleanups, protocol regen, and test splits for rewind/fork CI

* fix(ui): fit chat rewind disabled styles inside the startup CSS budget
---
 .../openclaw/app/gateway/GatewayProtocol.kt   |   2 +
 docs/web/control-ui.md                        |   1 +
 packages/gateway-protocol/src/index.ts        |  14 +
 .../gateway-protocol/src/schema/sessions.ts   |  27 ++
 .../sessions/session-accessor.message-cut.ts  |  20 ++
 ...ession-accessor.sqlite-message-cut.test.ts | 232 +++++++++++++
 .../session-accessor.sqlite-message-cut.ts    | 313 ++++++++++++++++++
 .../sessions/session-accessor.sqlite.ts       |   4 +
 src/config/sessions/session-accessor.ts       |   3 +
 src/config/sessions/session-accessor.types.ts |  24 ++
 .../sessions/session-entry-selection.ts       |  31 ++
 src/gateway/methods/core-descriptors.ts       |   2 +
 src/gateway/server-methods.ts                 |   2 +
 .../server-methods/sessions-rewind.test.ts    | 201 +++++++++++
 src/gateway/server-methods/sessions-rewind.ts | 296 +++++++++++++++++
 src/gateway/server-methods/sessions-shared.ts |  15 +-
 src/gateway/server-methods/sessions.ts        |   2 +
 src/gateway/session-create-service.ts         |  29 +-
 src/plugins/registry-runtime.ts               |   2 +
 ui/src/api/types.ts                           |   5 +
 ui/src/i18n/locales/en.ts                     |   6 +
 ui/src/lib/sessions/index.ts                  |  70 ++++
 ui/src/lib/sessions/message-cut.test.ts       |  93 ++++++
 ui/src/pages/chat/chat-history.test.ts        | 101 +++++-
 ui/src/pages/chat/chat-history.ts             |  46 +++
 .../pages/chat/chat-pane.message-cut.test.ts  | 107 ++++++
 ui/src/pages/chat/chat-pane.ts                |  53 ++-
 ui/src/pages/chat/chat-thread.test.ts         |  15 +
 ui/src/pages/chat/chat-thread.ts              |   4 +
 ui/src/pages/chat/chat-view.test.ts           |  61 ++++
 ui/src/pages/chat/chat-view.ts                |   4 +
 .../chat/components/chat-message.test.ts      |  37 +++
 ui/src/pages/chat/components/chat-message.ts  | 229 ++++++++-----
 ui/src/pages/chat/components/chat-thread.ts   | 104 +++++-
 ui/src/styles/chat/grouped.css                |   6 +
 35 files changed, 2043 insertions(+), 118 deletions(-)
 create mode 100644 src/config/sessions/session-accessor.message-cut.ts
 create mode 100644 src/config/sessions/session-accessor.sqlite-message-cut.test.ts
 create mode 100644 src/config/sessions/session-accessor.sqlite-message-cut.ts
 create mode 100644 src/gateway/server-methods/sessions-rewind.test.ts
 create mode 100644 src/gateway/server-methods/sessions-rewind.ts
 create mode 100644 ui/src/lib/sessions/message-cut.test.ts
 create mode 100644 ui/src/pages/chat/chat-pane.message-cut.test.ts

diff --git a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
index e5a43d3a88e..0a0d9bbc33f 100644
--- a/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/gateway/GatewayProtocol.kt
@@ -303,6 +303,8 @@ enum class GatewayMethod(
   SessionsCompactionGet("sessions.compaction.get"),
   SessionsCompactionBranch("sessions.compaction.branch"),
   SessionsCompactionRestore("sessions.compaction.restore"),
+  SessionsRewind("sessions.rewind"),
+  SessionsFork("sessions.fork"),
   SessionsCreate("sessions.create"),
   SessionsSend("sessions.send"),
   SessionsAbort("sessions.abort"),
diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index f3314dcae9b..144d8866473 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -388,6 +388,7 @@ The macOS app keeps its native link-browser sidebar for links clicked in the das
     - In the macOS app, the OpenClaw mark uses the otherwise-empty native titlebar strip next to the window controls instead of consuming a sidebar row.
     - On desktop widths, chat controls stay on one compact row and collapse while scrolling down the transcript; scrolling up, returning to the top, or reaching the bottom restores the controls.
     - Consecutive duplicate text-only messages render as one bubble with a count badge. Messages that carry images, attachments, tool output, or canvas previews are left uncollapsed.
+    - User-message bubbles carry transcript actions: a hover rewind button (confirm popover with a "Don't ask again" option) plus right-click **Rewind to here** and **Fork from here**. Rewind repoints the session to the state just before that message and returns its text to the composer for edit and resend (`sessions.rewind`, `operator.admin`); fork creates a new session from the active-path prefix before the message, opens it, and seeds its composer with the same text (`sessions.fork`, `operator.write`). Both actions disable with an explanatory tooltip while the agent is working, apply only to persisted user messages, and are rejected for sessions whose conversation is owned by an external agent harness. Rewind moves chat context only — files and other tool side effects are not reverted — and the pre-rewind transcript remains preserved in the append-only session store.
     - When a session's checkout sits on a non-default branch of a GitHub repository, the chat view pins pull request chips above the composer: PR number, repo, branch, diff counts, a CI pill, and draft/merged/closed state, each linking to the PR. The row shows at most two chips — live (open/draft) PRs first — and a "Show more" button reveals collapsed merged/closed history. The CI pill opens a small CI monitoring popover with passed/failed/running/skipped check counts and a link to the PR's checks page. Detection runs server-side through `controlUi.sessionPullRequests`, which reuses the Gateway's `GH_TOKEN`/`GITHUB_TOKEN` when set. When the GitHub API rate limit is hit, chips keep the last known status and show a warning that the status may be out of date; dismissing a chip hides it for that session in the current browser profile. Before any PR exists, the row shows the branch itself — repo, branch name, and the +/− size of the diff against the default-branch merge base (committed and uncommitted work). Once the pushed branch has commits to compare, the row adds a Create PR button that opens GitHub's new-pull-request page; before that, a session with changed files (committed, uncommitted, or untracked) still gets the row without the button. The row hides itself while an open or draft PR exists. The branch row comes from local git only, so it stays available while GitHub is rate limited and carries the same stale-status warning, since "no PR found" cannot be trusted until the limit resets.
     - The session diff panel shows what a session's checkout actually changed: the branch button in the workspace rail or chat title bar opens the detail panel with a per-file diff of branch, uncommitted, and untracked work against the checkout's default-branch merge base — status dot, rename arrow, per-file +/− counts, collapsible files, and "N unmodified lines" markers between hunks. Diffs are computed server-side through the `sessions.diff` Gateway method (`operator.read` scope); binary and oversized files degrade to stats-only entries, and the button only appears when the connected Gateway advertises `sessions.diff`.
     - Every Chat pane has a title bar. Click the session title to rename it; the workspace chip copies the checkout path or branch and can reveal local Gateway workspaces in the host file manager. Remote and exec-node sessions keep copy actions but hide reveal.
diff --git a/packages/gateway-protocol/src/index.ts b/packages/gateway-protocol/src/index.ts
index 4f2814053c5..5d3158d4c95 100644
--- a/packages/gateway-protocol/src/index.ts
+++ b/packages/gateway-protocol/src/index.ts
@@ -364,6 +364,10 @@ import {
   SessionsCompactionGetParamsSchema,
   SessionsCompactionListParamsSchema,
   SessionsCompactionRestoreParamsSchema,
+  SessionsForkParamsSchema,
+  SessionsForkResultSchema,
+  SessionsRewindParamsSchema,
+  SessionsRewindResultSchema,
   SessionFileBrowserEntrySchema,
   SessionFileBrowserResultSchema,
   SessionFileEntrySchema,
@@ -720,6 +724,8 @@ export const validateSessionsCompactionBranchParams = lazyCompile(
 export const validateSessionsCompactionRestoreParams = lazyCompile(
   SessionsCompactionRestoreParamsSchema,
 );
+export const validateSessionsRewindParams = lazyCompile(SessionsRewindParamsSchema);
+export const validateSessionsForkParams = lazyCompile(SessionsForkParamsSchema);
 export const validateSessionsUsageParams = lazyCompile(SessionsUsageParamsSchema);
 export const validateTaskSuggestionsListParams = lazyCompile(TaskSuggestionsListParamsSchema);
 export const validateTaskSuggestionsCreateParams = lazyCompile(TaskSuggestionsCreateParamsSchema);
@@ -1071,6 +1077,10 @@ export {
   SessionsCompactionGetParamsSchema,
   SessionsCompactionBranchParamsSchema,
   SessionsCompactionRestoreParamsSchema,
+  SessionsForkParamsSchema,
+  SessionsForkResultSchema,
+  SessionsRewindParamsSchema,
+  SessionsRewindResultSchema,
   SessionPlacementStateSchema,
   SessionPlacementSchema,
   SessionWorktreeInfoSchema,
@@ -1676,6 +1686,10 @@ export type {
   SessionsReclaimParams,
   SessionsReclaimResult,
   SessionsCreateResult,
+  SessionsForkParams,
+  SessionsForkResult,
+  SessionsRewindParams,
+  SessionsRewindResult,
   SessionsPatchParams,
   SessionsResetParams,
   SessionsDeleteParams,
diff --git a/packages/gateway-protocol/src/schema/sessions.ts b/packages/gateway-protocol/src/schema/sessions.ts
index bdc753883f2..cdab9b4c5fd 100644
--- a/packages/gateway-protocol/src/schema/sessions.ts
+++ b/packages/gateway-protocol/src/schema/sessions.ts
@@ -520,6 +520,29 @@ export const SessionsCompactionRestoreParamsSchema = closedObject({
   checkpointId: NonEmptyString,
 });
 
+/** Repoints a session to the active-path state before one persisted user message. */
+export const SessionsRewindParamsSchema = closedObject({
+  sessionKey: NonEmptyString,
+  agentId: Type.Optional(NonEmptyString),
+  entryId: NonEmptyString,
+});
+
+/** Creates a new session from the active-path state before one persisted user message. */
+export const SessionsForkParamsSchema = closedObject({
+  sessionKey: NonEmptyString,
+  agentId: Type.Optional(NonEmptyString),
+  entryId: NonEmptyString,
+});
+
+export const SessionsRewindResultSchema = closedObject({
+  editorText: Type.Optional(Type.String()),
+});
+
+export const SessionsForkResultSchema = closedObject({
+  sessionKey: NonEmptyString,
+  editorText: Type.Optional(Type.String()),
+});
+
 /** List response for session compaction checkpoints. */
 export const SessionsCompactionListResultSchema = closedObject({
   ok: Type.Literal(true),
@@ -625,6 +648,10 @@ export type SessionsCompactionListResult = Static<typeof SessionsCompactionListR
 export type SessionsCompactionGetResult = Static<typeof SessionsCompactionGetResultSchema>;
 export type SessionsCompactionBranchResult = Static<typeof SessionsCompactionBranchResultSchema>;
 export type SessionsCompactionRestoreResult = Static<typeof SessionsCompactionRestoreResultSchema>;
+export type SessionsRewindParams = Static<typeof SessionsRewindParamsSchema>;
+export type SessionsForkParams = Static<typeof SessionsForkParamsSchema>;
+export type SessionsRewindResult = Static<typeof SessionsRewindResultSchema>;
+export type SessionsForkResult = Static<typeof SessionsForkResultSchema>;
 export type SessionWorktreeInfo = Static<typeof SessionWorktreeInfoSchema>;
 export type SessionsCreateParams = Static<typeof SessionsCreateParamsSchema>;
 export type SessionsCreateResult = Static<typeof SessionsCreateResultSchema>;
diff --git a/src/config/sessions/session-accessor.message-cut.ts b/src/config/sessions/session-accessor.message-cut.ts
new file mode 100644
index 00000000000..4239c2966df
--- /dev/null
+++ b/src/config/sessions/session-accessor.message-cut.ts
@@ -0,0 +1,20 @@
+import {
+  forkSqliteSessionAtMessage,
+  rewindSqliteSessionToMessage,
+} from "./session-accessor.sqlite.js";
+import type {
+  SessionMessageCutMutationParams,
+  SessionMessageCutMutationResult,
+} from "./session-accessor.types.js";
+
+export async function rewindSessionToMessage(
+  params: SessionMessageCutMutationParams,
+): Promise<SessionMessageCutMutationResult> {
+  return await rewindSqliteSessionToMessage(params);
+}
+
+export async function forkSessionAtMessage(
+  params: SessionMessageCutMutationParams & { targetKey: string },
+): Promise<SessionMessageCutMutationResult> {
+  return await forkSqliteSessionAtMessage(params);
+}
diff --git a/src/config/sessions/session-accessor.sqlite-message-cut.test.ts b/src/config/sessions/session-accessor.sqlite-message-cut.test.ts
new file mode 100644
index 00000000000..4b60e4b313f
--- /dev/null
+++ b/src/config/sessions/session-accessor.sqlite-message-cut.test.ts
@@ -0,0 +1,232 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js";
+import { closeOpenClawAgentDatabasesForTest } from "../../state/openclaw-agent-db.js";
+import { closeOpenClawStateDatabaseForTest } from "../../state/openclaw-state-db.js";
+import {
+  appendTranscriptEvent,
+  appendTranscriptMessage,
+  forkSessionAtMessage,
+  loadSessionEntry,
+  loadTranscriptEvents,
+  readSessionTranscriptMessageEventCount,
+  rewindSessionToMessage,
+  upsertSessionEntry,
+} from "./session-accessor.js";
+
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const agentId = "main";
+const sessionKey = "agent:main:message-cut";
+
+afterEach(() => {
+  closeOpenClawAgentDatabasesForTest();
+  closeOpenClawStateDatabaseForTest();
+});
+
+async function createSession() {
+  const stateDir = tempDirs.make("openclaw-message-cut-");
+  const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+  const sessionId = "message-cut-source";
+  const scope = { agentId, env, sessionId, sessionKey };
+  await upsertSessionEntry(scope, {
+    agentHarnessId: "embedded",
+    claudeCliSessionId: "claude-conversation",
+    cliSessionBindings: { "claude-cli": { sessionId: "claude-conversation" } },
+    cliSessionIds: { "claude-cli": "claude-conversation" },
+    compactionCount: 2,
+    contextTokens: 100_000,
+    deliveryContext: { channel: "telegram", to: "chat-123" },
+    lastChannel: "telegram",
+    lastTo: "chat-123",
+    lifecycleRevision: "source-lifecycle-revision",
+    modelOverride: "gpt-5",
+    modelOverrideSource: "user",
+    providerOverride: "openai",
+    sessionId,
+    updatedAt: Date.now(),
+  });
+  for (const event of [
+    { type: "session", id: sessionId, version: 3, timestamp: "2026-07-18T00:00:00.000Z" },
+    {
+      type: "message",
+      id: "user-1",
+      parentId: null,
+      timestamp: "2026-07-18T00:00:01.000Z",
+      message: { role: "user", content: "first prompt" },
+    },
+    {
+      type: "message",
+      id: "assistant-1",
+      parentId: "user-1",
+      timestamp: "2026-07-18T00:00:02.000Z",
+      message: { role: "assistant", content: "first answer" },
+    },
+    {
+      type: "message",
+      id: "user-2",
+      parentId: "assistant-1",
+      timestamp: "2026-07-18T00:00:03.000Z",
+      message: { role: "user", content: [{ type: "text", text: "second prompt" }] },
+    },
+    {
+      type: "message",
+      id: "assistant-2",
+      parentId: "user-2",
+      timestamp: "2026-07-18T00:00:04.000Z",
+      message: { role: "assistant", content: "second answer" },
+    },
+    {
+      type: "message",
+      id: "off-path-user",
+      parentId: "user-1",
+      timestamp: "2026-07-18T00:00:05.000Z",
+      message: { role: "user", content: "inactive prompt" },
+    },
+    {
+      type: "leaf",
+      id: "active-leaf",
+      parentId: "off-path-user",
+      timestamp: "2026-07-18T00:00:06.000Z",
+      targetId: "assistant-2",
+    },
+  ]) {
+    if (event.type === "message") {
+      await appendTranscriptMessage(scope, {
+        eventId: event.id,
+        message: event.message,
+        parentId: event.parentId,
+      });
+    } else {
+      await appendTranscriptEvent(scope, event);
+    }
+  }
+  return { env, scope };
+}
+
+describe("SQLite session message cuts", () => {
+  it("rewinds by repointing the active leaf and returns the editor text", async () => {
+    const { env } = await createSession();
+
+    const result = await rewindSessionToMessage({
+      agentId,
+      env,
+      entryId: "user-2",
+      sessionKey,
+    });
+
+    expect(result).toMatchObject({
+      status: "created",
+      key: sessionKey,
+      editorText: "second prompt",
+    });
+    if (result.status !== "created") {
+      throw new Error("expected rewind result");
+    }
+    expect(
+      readSessionTranscriptMessageEventCount({ agentId, env, sessionId: result.entry.sessionId }),
+    ).toBe(2);
+    expect(loadSessionEntry({ agentId, env, sessionKey })?.sessionId).toBe(result.entry.sessionId);
+    expect(result.entry).toMatchObject({
+      agentHarnessId: undefined,
+      claudeCliSessionId: undefined,
+      cliSessionBindings: undefined,
+      cliSessionIds: undefined,
+      compactionCount: undefined,
+      contextTokens: undefined,
+    });
+    expect(result.entry.deliveryContext).toEqual({ channel: "telegram", to: "chat-123" });
+  });
+
+  it("rewinds the stored row when its canonical key differs", async () => {
+    const { env } = await createSession();
+    const canonicalKey = "agent:main:canonical-message-cut";
+
+    const result = await rewindSessionToMessage({
+      agentId,
+      env,
+      entryId: "user-2",
+      sessionKey: canonicalKey,
+      sessionStoreKey: sessionKey,
+    });
+
+    expect(result).toMatchObject({ status: "created", key: sessionKey });
+    if (result.status !== "created") {
+      throw new Error("expected rewind result");
+    }
+    expect(loadSessionEntry({ agentId, env, sessionKey })?.sessionId).toBe(result.entry.sessionId);
+    expect(loadSessionEntry({ agentId, env, sessionKey: canonicalKey })).toBeUndefined();
+  });
+
+  it("forks an exact active-path prefix without changing the source", async () => {
+    const { env, scope } = await createSession();
+    const canonicalSourceKey = "agent:main:canonical-message-cut-source";
+    const targetKey = "agent:main:dashboard:message-cut-fork";
+
+    const result = await forkSessionAtMessage({
+      agentId,
+      env,
+      entryId: "user-2",
+      sessionKey: canonicalSourceKey,
+      sessionStoreKey: sessionKey,
+      targetKey,
+    });
+
+    expect(result).toMatchObject({
+      status: "created",
+      key: targetKey,
+      editorText: "second prompt",
+    });
+    if (result.status !== "created") {
+      throw new Error("expected fork result");
+    }
+    const forkEvents = await loadTranscriptEvents({
+      agentId,
+      env,
+      sessionId: result.entry.sessionId,
+      sessionKey: targetKey,
+    });
+    expect(
+      forkEvents.flatMap((event) =>
+        event && typeof event === "object" && "id" in event ? [event.id] : [],
+      ),
+    ).toEqual([result.entry.sessionId, "user-1", "assistant-1"]);
+    expect(loadSessionEntry(scope)?.sessionId).toBe(scope.sessionId);
+    expect(result.entry.lifecycleRevision).not.toBe("source-lifecycle-revision");
+    expect(result.entry.cliSessionBindings).toBeUndefined();
+    expect(result.entry.deliveryContext).toBeUndefined();
+    expect(result.entry.lastChannel).toBeUndefined();
+    expect(result.entry.lastTo).toBeUndefined();
+    expect(result.entry.parentSessionKey).toBe(canonicalSourceKey);
+    expect(result.entry).toMatchObject({
+      modelOverride: "gpt-5",
+      modelOverrideSource: "user",
+      providerOverride: "openai",
+    });
+    expect(loadSessionEntry(scope)?.lifecycleRevision).toBe("source-lifecycle-revision");
+  });
+
+  it.each([
+    ["unknown", "missing-entry"],
+    ["assistant-1", "not-user-message"],
+    ["off-path-user", "off-active-path"],
+  ])("rejects %s with %s", async (entryId, status) => {
+    const { env } = await createSession();
+
+    await expect(
+      rewindSessionToMessage({ agentId, env, entryId, sessionKey }),
+    ).resolves.toMatchObject({ status });
+  });
+
+  it("returns a typed error for legacy JSONL transcript storage", async () => {
+    const { env } = await createSession();
+    await upsertSessionEntry(
+      { agentId, env, sessionKey },
+      {
+        sessionFile: "/tmp/legacy-session.jsonl",
+      },
+    );
+
+    await expect(
+      rewindSessionToMessage({ agentId, env, entryId: "user-2", sessionKey }),
+    ).resolves.toMatchObject({ status: "unsupported-storage" });
+  });
+});
diff --git a/src/config/sessions/session-accessor.sqlite-message-cut.ts b/src/config/sessions/session-accessor.sqlite-message-cut.ts
new file mode 100644
index 00000000000..5eb0f68794f
--- /dev/null
+++ b/src/config/sessions/session-accessor.sqlite-message-cut.ts
@@ -0,0 +1,313 @@
+import { randomUUID } from "node:crypto";
+import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
+import {
+  runOpenClawAgentWriteTransaction,
+  type OpenClawAgentDatabase,
+} from "../../state/openclaw-agent-db.js";
+import type { TranscriptEvent } from "./session-accessor.sqlite-contract.js";
+import {
+  collectSessionEntryLookupKeys,
+  readSessionEntryRow,
+  readSqliteSessionIdentitySnapshot,
+  writeSessionEntry,
+} from "./session-accessor.sqlite-entry-store.js";
+import { emitCommittedSessionIdentityDiff } from "./session-accessor.sqlite-identity.js";
+import { loadSqliteTranscriptEventsFromDatabase } from "./session-accessor.sqlite-read.js";
+import {
+  formatSqliteSessionMarkerForScope,
+  normalizeSqliteSessionKey,
+  resolveSqliteScope,
+  runExclusiveSqliteSessionWrite,
+  toDatabaseOptions,
+  type ResolvedSqliteScope,
+} from "./session-accessor.sqlite-scope.js";
+import { appendTranscriptEventsInTransaction } from "./session-accessor.sqlite-transcript-store.js";
+import type {
+  SessionMessageCutMutationParams,
+  SessionMessageCutMutationResult,
+} from "./session-accessor.types.js";
+import { inheritSessionSelection } from "./session-entry-selection.js";
+import { reconcileSessionTranscriptIndexInTransaction } from "./session-transcript-index.js";
+import { parseSqliteSessionFileMarker } from "./sqlite-marker.js";
+import { createSessionTranscriptHeader } from "./transcript-header.js";
+import {
+  scanSessionTranscriptTree,
+  selectSessionTranscriptTreePathNodes,
+} from "./transcript-tree.js";
+import type { SessionEntry } from "./types.js";
+
+type MessageCut = {
+  editorText?: string;
+  parentId: string | null;
+  prefix: TranscriptEvent[];
+};
+
+export async function rewindSqliteSessionToMessage(
+  params: SessionMessageCutMutationParams,
+): Promise<SessionMessageCutMutationResult> {
+  return await mutateSqliteSessionAtMessage(params, "rewind");
+}
+
+export async function forkSqliteSessionAtMessage(
+  params: SessionMessageCutMutationParams & { targetKey: string },
+): Promise<SessionMessageCutMutationResult> {
+  return await mutateSqliteSessionAtMessage(params, "fork");
+}
+
+async function mutateSqliteSessionAtMessage(
+  params: SessionMessageCutMutationParams,
+  mode: "fork" | "rewind",
+): Promise<SessionMessageCutMutationResult> {
+  const canonicalSourceKey = normalizeSqliteSessionKey(params.sessionKey);
+  const sourceKey = normalizeSqliteSessionKey(params.sessionStoreKey ?? params.sessionKey);
+  const targetKey =
+    mode === "rewind"
+      ? sourceKey
+      : normalizeSqliteSessionKey(params.targetKey ?? params.sessionKey);
+  const resolved = resolveSqliteScope({
+    ...(params.agentId ? { agentId: params.agentId } : {}),
+    ...(params.env ? { env: params.env } : {}),
+    sessionKey: sourceKey,
+    ...(params.storePath ? { storePath: params.storePath } : {}),
+  });
+  return await runExclusiveSqliteSessionWrite(resolved, async () => {
+    let result: SessionMessageCutMutationResult = { status: "failed" };
+    let previousIdentity = new Map<string, SessionEntry>();
+    let currentIdentity = new Map<string, SessionEntry>();
+    runOpenClawAgentWriteTransaction((database) => {
+      const identityKeys = uniqueStrings([
+        ...collectSessionEntryLookupKeys(database, sourceKey),
+        ...collectSessionEntryLookupKeys(database, targetKey),
+      ]);
+      previousIdentity = readSqliteSessionIdentitySnapshot(database, identityKeys);
+      result = mutateSqliteSessionAtMessageInTransaction(database, resolved, {
+        entryId: params.entryId,
+        canonicalSourceKey,
+        mode,
+        sourceKey,
+        targetKey,
+      });
+      currentIdentity = readSqliteSessionIdentitySnapshot(database, identityKeys);
+    }, toDatabaseOptions(resolved));
+    emitCommittedSessionIdentityDiff(previousIdentity, currentIdentity);
+    return result;
+  });
+}
+
+function mutateSqliteSessionAtMessageInTransaction(
+  database: OpenClawAgentDatabase,
+  resolved: ResolvedSqliteScope,
+  params: {
+    canonicalSourceKey: string;
+    entryId: string;
+    mode: "fork" | "rewind";
+    sourceKey: string;
+    targetKey: string;
+  },
+): SessionMessageCutMutationResult {
+  const currentEntry = readSessionEntryRow(database, params.sourceKey)?.entry;
+  if (!currentEntry?.sessionId) {
+    return { status: "missing-session" };
+  }
+  if (currentEntry.sessionFile?.trim() && !parseSqliteSessionFileMarker(currentEntry.sessionFile)) {
+    return { status: "unsupported-storage" };
+  }
+  const events = loadSqliteTranscriptEventsFromDatabase(database, currentEntry.sessionId);
+  const cut = resolveMessageCut(events, params.entryId);
+  if ("status" in cut) {
+    return cut;
+  }
+
+  const nextSessionId = randomUUID();
+  const targetScope = {
+    ...resolved,
+    sessionId: nextSessionId,
+    sessionKey: params.targetKey,
+  };
+  const nextSessionFile = formatSqliteSessionMarkerForScope(targetScope);
+  const header = createSessionTranscriptHeader({
+    cwd: readTranscriptHeaderCwd(events),
+    sessionId: nextSessionId,
+  });
+  const nextEvents =
+    params.mode === "fork"
+      ? [header, ...cut.prefix]
+      : [
+          header,
+          ...events.filter((event) => !isSessionHeader(event)),
+          {
+            type: "leaf",
+            id: uniqueEntryId(events),
+            parentId: readLastEventId(events),
+            timestamp: new Date().toISOString(),
+            targetId: cut.parentId,
+          },
+        ];
+  appendTranscriptEventsInTransaction(database, targetScope, nextEvents);
+  if (params.mode === "rewind") {
+    reconcileSessionTranscriptIndexInTransaction(database.db, nextSessionId);
+  }
+
+  // Rotating transcript identity fences stale live managers: later snapshot-replace writes
+  // target the old session and cannot erase this leaf repoint from the active session.
+  const nextEntry = cloneMessageCutSessionEntry({
+    currentEntry,
+    forked: params.mode === "fork",
+    nextSessionFile,
+    nextSessionId,
+    parentSessionKey: params.mode === "fork" ? params.canonicalSourceKey : undefined,
+  });
+  writeSessionEntry(database, params.targetKey, nextEntry);
+  return {
+    status: "created",
+    key: params.targetKey,
+    entry: nextEntry,
+    ...(cut.editorText ? { editorText: cut.editorText } : {}),
+  };
+}
+
+function resolveMessageCut(
+  events: readonly TranscriptEvent[],
+  entryId: string,
+): MessageCut | Exclude<SessionMessageCutMutationResult, { status: "created" }> {
+  const tree = scanSessionTranscriptTree(events);
+  const target = tree.byId.get(entryId);
+  if (!target) {
+    return { status: "missing-entry" };
+  }
+  const record = asRecord(target.entry);
+  const message = asRecord(record?.message);
+  if (record?.type !== "message" || message?.role !== "user") {
+    return { status: "not-user-message" };
+  }
+  const activePath = selectSessionTranscriptTreePathNodes(tree, tree.leafId);
+  const targetIndex = activePath.findIndex((node) => node.id === entryId);
+  if (targetIndex < 0) {
+    return { status: "off-active-path" };
+  }
+  const prefix: TranscriptEvent[] = [];
+  for (const node of activePath.slice(0, targetIndex)) {
+    const entry = asRecord(node.entry);
+    // Spread (not Object.assign) so a parsed own `__proto__` key stays an inert
+    // data property instead of rebinding the copy's prototype.
+    prefix.push(
+      entry && entry.parentId !== node.parentId
+        ? ({ ...entry, parentId: node.parentId } as TranscriptEvent)
+        : node.entry,
+    );
+  }
+  return {
+    editorText: extractEditorText(message.content),
+    parentId: target.parentId,
+    prefix,
+  };
+}
+
+function cloneMessageCutSessionEntry(params: {
+  currentEntry: SessionEntry;
+  forked: boolean;
+  nextSessionFile: string;
+  nextSessionId: string;
+  parentSessionKey?: string;
+}): SessionEntry {
+  const baseEntry = params.forked
+    ? inheritSessionSelection(params.currentEntry)
+    : params.currentEntry;
+  return {
+    ...baseEntry,
+    sessionId: params.nextSessionId,
+    sessionFile: params.nextSessionFile,
+    lifecycleRevision: params.forked ? randomUUID() : params.currentEntry.lifecycleRevision,
+    updatedAt: Date.now(),
+    systemSent: false,
+    abortedLastRun: false,
+    startedAt: undefined,
+    endedAt: undefined,
+    runtimeMs: undefined,
+    status: undefined,
+    inputTokens: undefined,
+    outputTokens: undefined,
+    cacheRead: undefined,
+    cacheWrite: undefined,
+    estimatedCostUsd: undefined,
+    totalTokens: undefined,
+    totalTokensFresh: undefined,
+    // A rotated transcript cannot resume provider/runtime identity from the old tail.
+    // Clear transcript-derived accounting too so the next turn rebuilds canonical state.
+    contextTokens: undefined,
+    contextBudgetStatus: undefined,
+    compactionCount: undefined,
+    compactionCheckpoints: undefined,
+    memoryFlushAt: undefined,
+    memoryFlushCompactionCount: undefined,
+    memoryFlushContextHash: undefined,
+    memoryFlushFailureCount: undefined,
+    memoryFlushLastFailedAt: undefined,
+    memoryFlushLastFailureError: undefined,
+    cliSessionBindings: undefined,
+    cliSessionIds: undefined,
+    claudeCliSessionId: undefined,
+    agentHarnessId: undefined,
+    modelSelectionLocked: undefined,
+    skillsSnapshot: undefined,
+    systemPromptReport: undefined,
+    restartRecoveryRuns: undefined,
+    restartRecoveryForceSafeTools: undefined,
+    abortCutoffMessageSid: undefined,
+    abortCutoffTimestamp: undefined,
+    usageFamilyKey: params.forked ? undefined : params.currentEntry.usageFamilyKey,
+    usageFamilySessionIds: params.forked ? undefined : params.currentEntry.usageFamilySessionIds,
+    ...(params.parentSessionKey ? { parentSessionKey: params.parentSessionKey } : {}),
+  };
+}
+
+function extractEditorText(content: unknown): string | undefined {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+  const text = content
+    .flatMap((block) => {
+      const record = asRecord(block);
+      return record?.type === "text" && typeof record.text === "string" ? [record.text] : [];
+    })
+    .join("");
+  return text || undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function isSessionHeader(event: unknown): boolean {
+  return asRecord(event)?.type === "session";
+}
+
+function readTranscriptHeaderCwd(events: readonly TranscriptEvent[]): string | undefined {
+  const cwd = asRecord(events.find(isSessionHeader))?.cwd;
+  return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+}
+
+function readLastEventId(events: readonly TranscriptEvent[]): string | null {
+  const id = asRecord(events.findLast((event) => !isSessionHeader(event)))?.id;
+  return typeof id === "string" && id.trim() ? id : null;
+}
+
+function uniqueEntryId(events: readonly TranscriptEvent[]): string {
+  const ids = new Set(
+    events.flatMap((event) => {
+      const id = asRecord(event)?.id;
+      return typeof id === "string" ? [id] : [];
+    }),
+  );
+  for (;;) {
+    const id = randomUUID().slice(0, 8);
+    if (!ids.has(id)) {
+      return id;
+    }
+  }
+}
diff --git a/src/config/sessions/session-accessor.sqlite.ts b/src/config/sessions/session-accessor.sqlite.ts
index cd6b736107c..dc9b1634013 100644
--- a/src/config/sessions/session-accessor.sqlite.ts
+++ b/src/config/sessions/session-accessor.sqlite.ts
@@ -37,6 +37,10 @@ export {
   branchSqliteCompactionCheckpointSession,
   restoreSqliteCompactionCheckpointSession,
 } from "./session-accessor.sqlite-checkpoint.js";
+export {
+  forkSqliteSessionAtMessage,
+  rewindSqliteSessionToMessage,
+} from "./session-accessor.sqlite-message-cut.js";
 export {
   appendSqliteExpectedSessionTranscriptTurn,
   appendSqliteTranscriptEvent,
diff --git a/src/config/sessions/session-accessor.ts b/src/config/sessions/session-accessor.ts
index 33365435a50..2ee49f499da 100644
--- a/src/config/sessions/session-accessor.ts
+++ b/src/config/sessions/session-accessor.ts
@@ -39,6 +39,8 @@ export type {
   SessionCompactionCheckpointEntryBuilder,
   SessionCompactionCheckpointForkedTranscript,
   SessionCompactionCheckpointMutationResult,
+  SessionMessageCutMutationParams,
+  SessionMessageCutMutationResult,
   SessionCompactionCheckpointTranscriptForkResult,
   SessionCompactionCheckpointTranscriptForker,
   SessionEntryCandidateAccessScope,
@@ -153,6 +155,7 @@ export {
   rollbackAgentHarnessSessionEntryLifecycle,
   rollbackPluginOwnedSessionEntryLifecycle,
 } from "./session-accessor.lifecycle.js";
+export { forkSessionAtMessage, rewindSessionToMessage } from "./session-accessor.message-cut.js";
 export {
   commitReplySessionInitialization,
   loadReplySessionInitializationSnapshot,
diff --git a/src/config/sessions/session-accessor.types.ts b/src/config/sessions/session-accessor.types.ts
index 3ba9c9d7e28..3165c408384 100644
--- a/src/config/sessions/session-accessor.types.ts
+++ b/src/config/sessions/session-accessor.types.ts
@@ -568,6 +568,30 @@ export type SessionCompactionCheckpointMutationResult =
   | { status: "model-selection-locked" }
   | { status: "failed" };
 
+export type SessionMessageCutMutationResult =
+  | {
+      status: "created";
+      key: string;
+      entry: SessionEntry;
+      editorText?: string;
+    }
+  | { status: "missing-session" }
+  | { status: "missing-entry" }
+  | { status: "not-user-message" }
+  | { status: "off-active-path" }
+  | { status: "unsupported-storage" }
+  | { status: "failed" };
+
+export type SessionMessageCutMutationParams = {
+  agentId?: string;
+  entryId: string;
+  env?: NodeJS.ProcessEnv;
+  sessionKey: string;
+  sessionStoreKey?: string;
+  storePath?: string;
+  targetKey?: string;
+};
+
 export type SessionCompactionCheckpointEntryBuildContext = {
   /** Checkpoint row selected from the current persisted session entry. */
   checkpoint: SessionCompactionCheckpoint;
diff --git a/src/config/sessions/session-entry-selection.ts b/src/config/sessions/session-entry-selection.ts
index 9b1ffeb46e9..de69df44102 100644
--- a/src/config/sessions/session-entry-selection.ts
+++ b/src/config/sessions/session-entry-selection.ts
@@ -10,6 +10,37 @@ type SessionProjectionTarget = {
   primaryKey: string;
 };
 
+/** Carries only user/runtime selection into a new dashboard fork. */
+export function inheritSessionSelection(
+  parentEntry: SessionEntry | undefined,
+): Partial<SessionEntry> {
+  if (!parentEntry) {
+    return {};
+  }
+  return {
+    ...(parentEntry.providerOverride ? { providerOverride: parentEntry.providerOverride } : {}),
+    ...(parentEntry.modelOverride ? { modelOverride: parentEntry.modelOverride } : {}),
+    ...(parentEntry.modelOverrideSource
+      ? { modelOverrideSource: parentEntry.modelOverrideSource }
+      : {}),
+    ...(parentEntry.agentRuntimeOverride
+      ? { agentRuntimeOverride: parentEntry.agentRuntimeOverride }
+      : {}),
+    ...(parentEntry.thinkingLevel ? { thinkingLevel: parentEntry.thinkingLevel } : {}),
+    ...(parentEntry.fastMode !== undefined ? { fastMode: parentEntry.fastMode } : {}),
+    ...(parentEntry.verboseLevel ? { verboseLevel: parentEntry.verboseLevel } : {}),
+    ...(parentEntry.traceLevel ? { traceLevel: parentEntry.traceLevel } : {}),
+    ...(parentEntry.reasoningLevel ? { reasoningLevel: parentEntry.reasoningLevel } : {}),
+    ...(parentEntry.elevatedLevel ? { elevatedLevel: parentEntry.elevatedLevel } : {}),
+    ...(parentEntry.authProfileOverride
+      ? { authProfileOverride: parentEntry.authProfileOverride }
+      : {}),
+    ...(parentEntry.authProfileOverrideSource
+      ? { authProfileOverrideSource: parentEntry.authProfileOverrideSource }
+      : {}),
+  };
+}
+
 /** Normalizes caller aliases while always preserving the canonical key. */
 export function normalizeTargetStoreKeys(target: SessionStoreTarget): string[] {
   const keys = new Set<string>();
diff --git a/src/gateway/methods/core-descriptors.ts b/src/gateway/methods/core-descriptors.ts
index 7f6aa8e85fd..1964d1eda22 100644
--- a/src/gateway/methods/core-descriptors.ts
+++ b/src/gateway/methods/core-descriptors.ts
@@ -196,6 +196,8 @@ const CORE_GATEWAY_METHOD_SPECS: readonly CoreGatewayMethodSpec[] = [
   { name: "sessions.compaction.get", scope: "operator.read" },
   { name: "sessions.compaction.branch", scope: "operator.write" },
   { name: "sessions.compaction.restore", scope: "operator.admin" },
+  { name: "sessions.rewind", scope: "operator.admin" },
+  { name: "sessions.fork", scope: "operator.write" },
   // Params-aware: explicit cwd can point at any host checkout and requires admin.
   { name: "sessions.create", scope: "dynamic", startup: true },
   { name: "sessions.send", scope: "operator.write", startup: true },
diff --git a/src/gateway/server-methods.ts b/src/gateway/server-methods.ts
index 4253bb03269..34ebf9a13fa 100644
--- a/src/gateway/server-methods.ts
+++ b/src/gateway/server-methods.ts
@@ -647,6 +647,8 @@ export const coreGatewayHandlers: GatewayRequestHandlers = {
       "sessions.create",
       "sessions.compaction.branch",
       "sessions.compaction.restore",
+      "sessions.rewind",
+      "sessions.fork",
       "sessions.send",
       "sessions.steer",
       "sessions.abort",
diff --git a/src/gateway/server-methods/sessions-rewind.test.ts b/src/gateway/server-methods/sessions-rewind.test.ts
new file mode 100644
index 00000000000..fd6b613c974
--- /dev/null
+++ b/src/gateway/server-methods/sessions-rewind.test.ts
@@ -0,0 +1,201 @@
+import { expectDefined } from "@openclaw/normalization-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ErrorCodes } from "../../../packages/gateway-protocol/src/index.js";
+import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js";
+import { closeOpenClawAgentDatabasesForTest } from "../../state/openclaw-agent-db.js";
+import { closeOpenClawStateDatabaseForTest } from "../../state/openclaw-state-db.js";
+import type { GatewayRequestContext, RespondFn } from "./types.js";
+
+const mocks = vi.hoisted(() => ({
+  active: false,
+  external: false,
+  queueClear: vi.fn(),
+}));
+
+vi.mock("../../auto-reply/reply/queue/cleanup.js", () => ({
+  clearSessionQueues: mocks.queueClear,
+}));
+
+vi.mock("../../sessions/session-upstream-links.js", () => ({
+  readSessionUpstreamLink: () => (mocks.external ? { upstreamKind: "external" } : undefined),
+}));
+
+vi.mock("./session-active-runs.js", () => {
+  return { hasVisibleActiveSessionRun: () => mocks.active };
+});
+
+import {
+  appendTranscriptEvent,
+  appendTranscriptMessage,
+  upsertSessionEntry,
+} from "../../config/sessions/session-accessor.js";
+import { sessionsHandlers } from "./sessions.js";
+
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+const sessionKey = "agent:main:rewind-handler";
+
+beforeEach(async () => {
+  mocks.active = false;
+  mocks.external = false;
+  mocks.queueClear.mockReset();
+  vi.stubEnv("OPENCLAW_STATE_DIR", tempDirs.make("openclaw-rewind-handler-"));
+  await upsertSessionEntry(
+    { agentId: "main", sessionKey },
+    {
+      sessionId: "rewind-handler-source",
+      updatedAt: Date.now(),
+    },
+  );
+  for (const event of [
+    { type: "session", id: "rewind-handler-source", version: 3 },
+    {
+      type: "message",
+      id: "user-entry",
+      parentId: null,
+      message: { role: "user", content: "edit me" },
+    },
+    {
+      type: "message",
+      id: "assistant-entry",
+      parentId: "user-entry",
+      message: { role: "assistant", content: "answer" },
+    },
+    {
+      type: "message",
+      id: "off-path-entry",
+      parentId: null,
+      message: { role: "user", content: "inactive" },
+    },
+    {
+      type: "leaf",
+      id: "active-leaf",
+      parentId: "off-path-entry",
+      targetId: "assistant-entry",
+    },
+  ]) {
+    const scope = { agentId: "main", sessionId: "rewind-handler-source", sessionKey };
+    if (event.type === "message") {
+      await appendTranscriptMessage(scope, {
+        eventId: event.id,
+        message: event.message,
+        parentId: event.parentId,
+      });
+    } else {
+      await appendTranscriptEvent(scope, event);
+    }
+  }
+});
+
+afterEach(() => {
+  closeOpenClawAgentDatabasesForTest();
+  closeOpenClawStateDatabaseForTest();
+  vi.unstubAllEnvs();
+});
+
+function context(): GatewayRequestContext {
+  return {
+    broadcastToConnIds: vi.fn(),
+    chatAbortControllers: new Map(),
+    getRuntimeConfig: () => ({ agents: { list: [{ id: "main", default: true }] } }),
+    getSessionEventSubscriberConnIds: () => new Set(),
+  } as unknown as GatewayRequestContext;
+}
+
+async function invoke(method: "sessions.fork" | "sessions.rewind", entryId: string) {
+  const respond = vi.fn() as unknown as RespondFn;
+  await expectDefined(
+    sessionsHandlers[method],
+    `${method} handler`,
+  )({
+    req: { id: `${method}-request` } as never,
+    params: { sessionKey, entryId },
+    respond,
+    context: context(),
+    client: null,
+    isWebchatConnect: () => false,
+  });
+  return respond;
+}
+
+describe("session message-cut methods", () => {
+  it("returns editor text for rewind and a new key for fork", async () => {
+    const fork = await invoke("sessions.fork", "user-entry");
+    expect(fork).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({ editorText: "edit me", sessionKey: expect.any(String) }),
+      undefined,
+    );
+
+    const rewind = await invoke("sessions.rewind", "user-entry");
+    expect(rewind).toHaveBeenCalledWith(true, { editorText: "edit me" }, undefined);
+    expect(mocks.queueClear).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["missing", "message entry not found"],
+    ["assistant-entry", "entry is not a user message"],
+    ["off-path-entry", "not on the active path"],
+  ])("returns a typed validation error for %s", async (entryId, message) => {
+    const respond = await invoke("sessions.rewind", entryId);
+    expect(respond).toHaveBeenCalledWith(
+      false,
+      undefined,
+      expect.objectContaining({
+        code: ErrorCodes.INVALID_REQUEST,
+        message: expect.stringContaining(message),
+      }),
+    );
+    expect(mocks.queueClear).not.toHaveBeenCalled();
+  });
+
+  it("rejects externally owned conversations", async () => {
+    mocks.external = true;
+    const respond = await invoke("sessions.rewind", "user-entry");
+
+    expect(respond).toHaveBeenCalledWith(
+      false,
+      undefined,
+      expect.objectContaining({
+        code: ErrorCodes.INVALID_REQUEST,
+        message: expect.stringContaining("external agent harness"),
+      }),
+    );
+  });
+
+  it("returns a typed error for unsupported transcript storage", async () => {
+    await upsertSessionEntry(
+      { agentId: "main", sessionKey },
+      {
+        sessionFile: "/tmp/legacy-session.jsonl",
+      },
+    );
+    const respond = await invoke("sessions.rewind", "user-entry");
+
+    expect(respond).toHaveBeenCalledWith(
+      false,
+      undefined,
+      expect.objectContaining({
+        code: ErrorCodes.INVALID_REQUEST,
+        message: expect.stringContaining("storage does not support rewind"),
+      }),
+    );
+  });
+
+  it.each([
+    ["sessions.fork", "Fork"],
+    ["sessions.rewind", "Rewind"],
+  ] as const)("rejects %s while the source run is active", async (method, label) => {
+    mocks.active = true;
+    const respond = await invoke(method, "user-entry");
+
+    expect(respond).toHaveBeenCalledWith(
+      false,
+      undefined,
+      expect.objectContaining({
+        code: ErrorCodes.UNAVAILABLE,
+        message: `${label} is unavailable while the agent is working.`,
+      }),
+    );
+    expect(mocks.queueClear).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/gateway/server-methods/sessions-rewind.ts b/src/gateway/server-methods/sessions-rewind.ts
new file mode 100644
index 00000000000..1b845906211
--- /dev/null
+++ b/src/gateway/server-methods/sessions-rewind.ts
@@ -0,0 +1,296 @@
+import {
+  ErrorCodes,
+  errorShape,
+  validateSessionsForkParams,
+  validateSessionsRewindParams,
+} from "../../../packages/gateway-protocol/src/index.js";
+import { resolveDefaultAgentId } from "../../agents/agent-scope.js";
+import { clearSessionQueues } from "../../auto-reply/reply/queue/cleanup.js";
+import {
+  forkSessionAtMessage,
+  rewindSessionToMessage,
+  type SessionMessageCutMutationResult,
+} from "../../config/sessions/session-accessor.js";
+import {
+  isCompetingSessionWorkAdmissionActive,
+  runExclusiveSessionLifecycleMutation,
+} from "../../sessions/session-lifecycle-admission.js";
+import { readSessionUpstreamLink } from "../../sessions/session-upstream-links.js";
+import {
+  buildDashboardSessionKey,
+  resolveRequestedSessionAgentId as resolveRequestedGlobalAgentId,
+} from "../session-create-service.js";
+import { asWorkerInferenceControl } from "../worker-environments/inference-control.js";
+import { hasVisibleActiveSessionRun } from "./session-active-runs.js";
+import { emitSessionsChanged } from "./session-change-event.js";
+import {
+  loadAccessorSessionEntryForGatewayTarget,
+  rejectWebchatSessionMutation,
+  resolveSessionWorkerPlacementMutationError,
+  respondSessionWorkerPlacementMutationError,
+} from "./sessions-shared.js";
+import type { GatewayRequestHandlerOptions, GatewayRequestHandlers } from "./types.js";
+import { assertValidParams } from "./validation.js";
+
+type MessageCutAction = "fork" | "rewind";
+
+const EXTERNAL_CONVERSATION_ERROR =
+  "Rewind and fork are unavailable because this session is owned by an external agent harness.";
+
+export const sessionRewindHandlers: GatewayRequestHandlers = {
+  "sessions.rewind": async (options) => {
+    if (
+      !assertValidParams(
+        options.params,
+        validateSessionsRewindParams,
+        "sessions.rewind",
+        options.respond,
+      )
+    ) {
+      return;
+    }
+    await mutateSessionAtMessage(options, "rewind");
+  },
+  "sessions.fork": async (options) => {
+    if (
+      !assertValidParams(
+        options.params,
+        validateSessionsForkParams,
+        "sessions.fork",
+        options.respond,
+      )
+    ) {
+      return;
+    }
+    await mutateSessionAtMessage(options, "fork");
+  },
+};
+
+async function mutateSessionAtMessage(
+  options: GatewayRequestHandlerOptions,
+  action: MessageCutAction,
+): Promise<void> {
+  const { params, respond, context, client, isWebchatConnect } = options;
+  const sessionKey = typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
+  const entryId = typeof params.entryId === "string" ? params.entryId.trim() : "";
+  if (
+    rejectWebchatSessionMutation({
+      action,
+      client,
+      isWebchatConnect,
+      respond,
+    })
+  ) {
+    return;
+  }
+  const cfg = context.getRuntimeConfig();
+  const requestedAgent = resolveRequestedGlobalAgentId(
+    cfg,
+    sessionKey,
+    typeof params.agentId === "string" ? params.agentId : undefined,
+  );
+  if (!requestedAgent.ok) {
+    respond(false, undefined, requestedAgent.error);
+    return;
+  }
+  const initial = loadAccessorSessionEntryForGatewayTarget({
+    key: sessionKey,
+    cfg,
+    agentId: requestedAgent.agentId,
+  });
+  if (!initial.entry?.sessionId) {
+    respond(
+      false,
+      undefined,
+      errorShape(ErrorCodes.INVALID_REQUEST, `session not found: ${sessionKey}`),
+    );
+    return;
+  }
+  const initialSessionId = initial.entry.sessionId;
+  const initialLifecycleRevision = initial.entry.lifecycleRevision;
+  if (readSessionUpstreamLink(initial.canonicalKey, initial.target.agentId)) {
+    respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, EXTERNAL_CONVERSATION_ERROR));
+    return;
+  }
+  const initialPlacementError = resolveSessionWorkerPlacementMutationError({
+    action,
+    context,
+    key: sessionKey,
+    sessionId: initial.entry.sessionId,
+  });
+  if (initialPlacementError) {
+    respondSessionWorkerPlacementMutationError(initialPlacementError, respond);
+    return;
+  }
+
+  const lifecycleIdentities = [
+    sessionKey,
+    initial.canonicalKey,
+    initial.sessionStoreKey,
+    initialSessionId,
+    initialLifecycleRevision,
+  ];
+  let targetStillCurrent = true;
+  let blockedByActiveRun = false;
+  await runExclusiveSessionLifecycleMutation({
+    scope: initial.storePath,
+    identities: [initialSessionId, initialLifecycleRevision],
+    prepare: async () => {
+      const current = loadAccessorSessionEntryForGatewayTarget({
+        key: sessionKey,
+        cfg,
+        agentId: requestedAgent.agentId,
+      });
+      targetStillCurrent =
+        current.entry?.sessionId === initialSessionId &&
+        current.entry.lifecycleRevision === initialLifecycleRevision;
+      if (!targetStillCurrent) {
+        return;
+      }
+      // Fork cannot disturb its source, and rewind must not invalidate queued work on failure.
+      // Reject live work before either transcript mutation instead of interrupting it.
+      blockedByActiveRun =
+        isCompetingSessionWorkAdmissionActive(initial.storePath, lifecycleIdentities) ||
+        (asWorkerInferenceControl(context.workerEnvironmentService)?.hasInferenceForSession(
+          initialSessionId,
+        ) ??
+          false) ||
+        hasVisibleActiveSessionRun({
+          context,
+          requestedKey: sessionKey,
+          canonicalKey: current.canonicalKey,
+          sessionId: initialSessionId,
+          agentId: requestedAgent.agentId,
+          defaultAgentId: resolveDefaultAgentId(cfg),
+        });
+    },
+    run: async () => {
+      if (!targetStillCurrent) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, `Session ${sessionKey} changed; retry ${action}.`),
+        );
+        return;
+      }
+      if (blockedByActiveRun) {
+        respond(
+          false,
+          undefined,
+          errorShape(
+            ErrorCodes.UNAVAILABLE,
+            `${action === "fork" ? "Fork" : "Rewind"} is unavailable while the agent is working.`,
+          ),
+        );
+        return;
+      }
+      const current = loadAccessorSessionEntryForGatewayTarget({
+        key: sessionKey,
+        cfg,
+        agentId: requestedAgent.agentId,
+      });
+      if (
+        current.entry?.sessionId !== initialSessionId ||
+        current.entry.lifecycleRevision !== initialLifecycleRevision
+      ) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, `Session ${sessionKey} changed; retry ${action}.`),
+        );
+        return;
+      }
+      if (readSessionUpstreamLink(current.canonicalKey, current.target.agentId)) {
+        respond(
+          false,
+          undefined,
+          errorShape(ErrorCodes.INVALID_REQUEST, EXTERNAL_CONVERSATION_ERROR),
+        );
+        return;
+      }
+      const placementError = resolveSessionWorkerPlacementMutationError({
+        action,
+        context,
+        key: sessionKey,
+        sessionId: current.entry.sessionId,
+      });
+      if (placementError) {
+        respondSessionWorkerPlacementMutationError(placementError, respond);
+        return;
+      }
+      const targetKey =
+        action === "fork" ? buildDashboardSessionKey(current.target.agentId) : current.canonicalKey;
+      const result = await (action === "fork"
+        ? forkSessionAtMessage({
+            agentId: current.target.agentId,
+            entryId,
+            sessionKey: current.canonicalKey,
+            sessionStoreKey: current.sessionStoreKey,
+            storePath: current.storePath,
+            targetKey,
+          })
+        : rewindSessionToMessage({
+            agentId: current.target.agentId,
+            entryId,
+            sessionKey: current.canonicalKey,
+            sessionStoreKey: current.sessionStoreKey,
+            storePath: current.storePath,
+          }));
+      if (result.status !== "created") {
+        respondMessageCutError(result, action, entryId, respond);
+        return;
+      }
+      if (action === "rewind") {
+        clearSessionQueues(lifecycleIdentities);
+      }
+      respond(
+        true,
+        action === "fork"
+          ? {
+              sessionKey: result.key,
+              ...(result.editorText ? { editorText: result.editorText } : {}),
+            }
+          : result.editorText
+            ? { editorText: result.editorText }
+            : {},
+        undefined,
+      );
+      emitSessionsChanged(context, {
+        sessionKey: action === "fork" ? result.key : current.canonicalKey,
+        ...((action === "fork" ? result.key : current.canonicalKey) === "global" &&
+        requestedAgent.agentId
+          ? { agentId: requestedAgent.agentId }
+          : {}),
+        reason: action,
+      });
+    },
+  });
+}
+
+function respondMessageCutError(
+  result: Exclude<SessionMessageCutMutationResult, { status: "created" }>,
+  action: MessageCutAction,
+  entryId: string,
+  respond: GatewayRequestHandlerOptions["respond"],
+): void {
+  const message =
+    result.status === "missing-session"
+      ? "session not found"
+      : result.status === "missing-entry"
+        ? `message entry not found: ${entryId}`
+        : result.status === "not-user-message"
+          ? `entry is not a user message: ${entryId}`
+          : result.status === "off-active-path"
+            ? `message entry is not on the active path: ${entryId}`
+            : result.status === "unsupported-storage"
+              ? `session transcript storage does not support ${action}`
+              : `failed to ${action} session`;
+  respond(
+    false,
+    undefined,
+    errorShape(
+      result.status === "failed" ? ErrorCodes.UNAVAILABLE : ErrorCodes.INVALID_REQUEST,
+      message,
+    ),
+  );
+}
diff --git a/src/gateway/server-methods/sessions-shared.ts b/src/gateway/server-methods/sessions-shared.ts
index d64bb8c931a..e3e9eaa97d3 100644
--- a/src/gateway/server-methods/sessions-shared.ts
+++ b/src/gateway/server-methods/sessions-shared.ts
@@ -31,7 +31,7 @@ export const sessionLog = createSubsystemLogger("gateway/sessions");
 export class SessionWorkerPlacementMutationError extends Error {
   constructor(
     readonly placementState: SessionPlacement["state"],
-    action: "delete" | "reset" | "restore",
+    action: "delete" | "fork" | "reset" | "restore" | "rewind",
     key: string,
   ) {
     super(`Session ${key} cannot ${action} while cloud worker placement is ${placementState}.`);
@@ -39,7 +39,7 @@ export class SessionWorkerPlacementMutationError extends Error {
 }
 
 export function resolveSessionWorkerPlacementMutationError(params: {
-  action: "delete" | "reset" | "restore";
+  action: "delete" | "fork" | "reset" | "restore" | "rewind";
   context: GatewayRequestContext;
   key: string;
   sessionId: string | undefined;
@@ -278,7 +278,16 @@ export function emitSessionOperation(
 }
 
 export function rejectWebchatSessionMutation(params: {
-  action: "patch" | "delete" | "compact" | "branch" | "restore" | "dispatch" | "reclaim";
+  action:
+    | "patch"
+    | "delete"
+    | "compact"
+    | "branch"
+    | "restore"
+    | "rewind"
+    | "fork"
+    | "dispatch"
+    | "reclaim";
   client: GatewayClient | null;
   isWebchatConnect: (params: GatewayClient["connect"] | null | undefined) => boolean;
   respond: RespondFn;
diff --git a/src/gateway/server-methods/sessions.ts b/src/gateway/server-methods/sessions.ts
index d3e0dcab749..43c12a4a7a0 100644
--- a/src/gateway/server-methods/sessions.ts
+++ b/src/gateway/server-methods/sessions.ts
@@ -11,6 +11,7 @@ import { sessionGroupHandlers } from "./sessions-groups.js";
 import { sessionMessagingHandlers } from "./sessions-messaging.js";
 import { sessionMutationHandlers } from "./sessions-mutations.js";
 import { sessionReadHandlers } from "./sessions-read.js";
+import { sessionRewindHandlers } from "./sessions-rewind.js";
 import { sessionSubscriptionHandlers } from "./sessions-subscriptions.js";
 import type { GatewayRequestHandlers } from "./types.js";
 
@@ -20,6 +21,7 @@ export const sessionsHandlers: GatewayRequestHandlers = {
   ...sessionCreateHandlers,
   ...sessionCheckpointQueryHandlers,
   ...sessionCheckpointHandlers,
+  ...sessionRewindHandlers,
   ...sessionDispatchHandlers,
   ...sessionMessagingHandlers,
   ...sessionAbortHandlers,
diff --git a/src/gateway/session-create-service.ts b/src/gateway/session-create-service.ts
index 6435ed941c3..2f12da6ef49 100644
--- a/src/gateway/session-create-service.ts
+++ b/src/gateway/session-create-service.ts
@@ -28,6 +28,7 @@ import {
   createSessionEntryWithTranscript,
   resolveSessionEntryAccessTarget,
 } from "../config/sessions/session-accessor.js";
+import { inheritSessionSelection } from "../config/sessions/session-entry-selection.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import {
   createInternalHookEvent,
@@ -125,34 +126,6 @@ export function buildDashboardSessionKey(agentId: string): string {
   return `agent:${agentId}:dashboard:${randomUUID()}`;
 }
 
-function inheritSessionSelection(parentEntry: SessionEntry | undefined): Partial<SessionEntry> {
-  if (!parentEntry) {
-    return {};
-  }
-  return {
-    ...(parentEntry.providerOverride ? { providerOverride: parentEntry.providerOverride } : {}),
-    ...(parentEntry.modelOverride ? { modelOverride: parentEntry.modelOverride } : {}),
-    ...(parentEntry.modelOverrideSource
-      ? { modelOverrideSource: parentEntry.modelOverrideSource }
-      : {}),
-    ...(parentEntry.agentRuntimeOverride
-      ? { agentRuntimeOverride: parentEntry.agentRuntimeOverride }
-      : {}),
-    ...(parentEntry.thinkingLevel ? { thinkingLevel: parentEntry.thinkingLevel } : {}),
-    ...(parentEntry.fastMode !== undefined ? { fastMode: parentEntry.fastMode } : {}),
-    ...(parentEntry.verboseLevel ? { verboseLevel: parentEntry.verboseLevel } : {}),
-    ...(parentEntry.traceLevel ? { traceLevel: parentEntry.traceLevel } : {}),
-    ...(parentEntry.reasoningLevel ? { reasoningLevel: parentEntry.reasoningLevel } : {}),
-    ...(parentEntry.elevatedLevel ? { elevatedLevel: parentEntry.elevatedLevel } : {}),
-    ...(parentEntry.authProfileOverride
-      ? { authProfileOverride: parentEntry.authProfileOverride }
-      : {}),
-    ...(parentEntry.authProfileOverrideSource
-      ? { authProfileOverrideSource: parentEntry.authProfileOverrideSource }
-      : {}),
-  };
-}
-
 type CreatedGatewaySession = {
   key: string;
   agentId: string;
diff --git a/src/plugins/registry-runtime.ts b/src/plugins/registry-runtime.ts
index 7642c5cc442..72d505866f6 100644
--- a/src/plugins/registry-runtime.ts
+++ b/src/plugins/registry-runtime.ts
@@ -44,6 +44,8 @@ const PLUGIN_GATEWAY_SESSION_MUTATION_METHODS = new Set([
   "sessions.compact",
   "sessions.compaction.branch",
   "sessions.compaction.restore",
+  "sessions.rewind",
+  "sessions.fork",
   "sessions.create",
   "sessions.delete",
   "sessions.patch",
diff --git a/ui/src/api/types.ts b/ui/src/api/types.ts
index a48cda7bd24..5e31da6aa88 100644
--- a/ui/src/api/types.ts
+++ b/ui/src/api/types.ts
@@ -579,6 +579,11 @@ export type SessionsCompactionRestoreResult = {
   } & Record<string, unknown>;
 };
 
+export type SessionsRewindResult =
+  import("../../../packages/gateway-protocol/src/index.js").SessionsRewindResult;
+export type SessionsForkResult =
+  import("../../../packages/gateway-protocol/src/index.js").SessionsForkResult;
+
 export type SessionsPatchResult = SessionsPatchResultBase<{
   sessionId: string;
   updatedAt?: number;
diff --git a/ui/src/i18n/locales/en.ts b/ui/src/i18n/locales/en.ts
index 7222308f3a1..b0b9594a7a2 100644
--- a/ui/src/i18n/locales/en.ts
+++ b/ui/src/i18n/locales/en.ts
@@ -3674,7 +3674,13 @@ export const en: TranslationMap = {
     messages: {
       activity: "Activity",
       deleteMessage: "Delete message",
+      forkFromHere: "Fork from here",
       openInCanvas: "Open in canvas",
+      rewind: "Rewind",
+      rewindConfirm: "Rewind to before this message?",
+      rewindToHere: "Rewind to here",
+      rewindUnavailable: "Rewind is unavailable while the agent is working",
+      forkUnavailable: "Fork is unavailable while the agent is working",
       unknownDate: "Unknown date",
       voiceNote: "Voice note",
     },
diff --git a/ui/src/lib/sessions/index.ts b/ui/src/lib/sessions/index.ts
index 43fdbe921e9..f35c38c2a87 100644
--- a/ui/src/lib/sessions/index.ts
+++ b/ui/src/lib/sessions/index.ts
@@ -11,8 +11,10 @@ import type {
   SessionsCompactionBranchResult,
   SessionsCompactionListResult,
   SessionsCompactionRestoreResult,
+  SessionsForkResult,
   SessionsListResult,
   SessionsPatchResult,
+  SessionsRewindResult,
   SessionWorkspaceGetResult,
   SessionWorkspaceListResult,
   SessionWorkspaceSetResult,
@@ -229,6 +231,16 @@ export type SessionCapability = {
     checkpointId: string,
     options?: { agentId?: string | null },
   ) => Promise<SessionsCompactionRestoreResult>;
+  rewind: (
+    key: string,
+    entryId: string,
+    options?: { agentId?: string | null },
+  ) => Promise<SessionsRewindResult>;
+  forkAtMessage: (
+    key: string,
+    entryId: string,
+    options?: { agentId?: string | null },
+  ) => Promise<SessionsForkResult>;
   /** Loads the gateway-owned group catalog, coalescing successful connection attempts. */
   groupsLoad: () => Promise<void>;
   /** Replaces the group catalog; stale means the initiating connection retired. */
@@ -518,6 +530,30 @@ function restoreSessionCheckpoint(
   });
 }
 
+function rewindSessionAtMessage(
+  client: SessionRequestClient,
+  key: string,
+  entryId: string,
+  options: { agentId?: string | null } = {},
+): Promise<SessionsRewindResult> {
+  return client.request<SessionsRewindResult>("sessions.rewind", {
+    ...buildSessionRequestParams(key, options.agentId),
+    entryId,
+  });
+}
+
+function forkSessionAtMessage(
+  client: SessionRequestClient,
+  key: string,
+  entryId: string,
+  options: { agentId?: string | null } = {},
+): Promise<SessionsForkResult> {
+  return client.request<SessionsForkResult>("sessions.fork", {
+    ...buildSessionRequestParams(key, options.agentId),
+    entryId,
+  });
+}
+
 function appendSessionResults(
   previous: SessionsListResult,
   page: SessionsListResult,
@@ -1423,6 +1459,38 @@ export function createSessionCapability(gateway: SessionGateway): SessionCapabil
     return result;
   };
 
+  const rewind = async (
+    key: string,
+    entryId: string,
+    options: { agentId?: string | null } = {},
+  ): Promise<SessionsRewindResult> => {
+    const scope = captureConnection();
+    if (!scope) {
+      throw new Error("Session rewind requires an active Gateway connection");
+    }
+    const result = await rewindSessionAtMessage(scope.client, key, entryId, options);
+    if (isCurrentConnection(scope)) {
+      await refreshReplacement(options.agentId ?? state.agentId ?? undefined).catch(() => {});
+    }
+    return result;
+  };
+
+  const forkAtMessage = async (
+    key: string,
+    entryId: string,
+    options: { agentId?: string | null } = {},
+  ): Promise<SessionsForkResult> => {
+    const scope = captureConnection();
+    if (!scope) {
+      throw new Error("Session fork requires an active Gateway connection");
+    }
+    const result = await forkSessionAtMessage(scope.client, key, entryId, options);
+    if (isCurrentConnection(scope)) {
+      await refreshReplacement(options.agentId ?? state.agentId ?? undefined).catch(() => {});
+    }
+    return result;
+  };
+
   const stopGateway = gateway.subscribe((next) => {
     const connectionChanged =
       next.client !== connectionClient || next.connected !== connectionConnected;
@@ -1545,6 +1613,8 @@ export function createSessionCapability(gateway: SessionGateway): SessionCapabil
     listCheckpoints,
     branchCheckpoint,
     restoreCheckpoint,
+    rewind,
+    forkAtMessage,
     groupsLoad,
     groupsPut,
     groupsRename,
diff --git a/ui/src/lib/sessions/message-cut.test.ts b/ui/src/lib/sessions/message-cut.test.ts
new file mode 100644
index 00000000000..1bfbba11098
--- /dev/null
+++ b/ui/src/lib/sessions/message-cut.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it, vi } from "vitest";
+import type { GatewayBrowserClient, GatewayEventFrame, GatewayHelloOk } from "../../api/gateway.ts";
+import { createSessionCapability } from "./index.ts";
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => undefined;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
+function createGatewayHarness(client: GatewayBrowserClient) {
+  let snapshot: {
+    client: GatewayBrowserClient | null;
+    connected: boolean;
+    sessionKey: string;
+    assistantAgentId: string | null;
+    hello: GatewayHelloOk | null;
+  } = {
+    client,
+    connected: true,
+    sessionKey: "agent:main:main",
+    assistantAgentId: "main",
+    hello: null,
+  };
+  const listeners = new Set<(next: typeof snapshot) => void>();
+  const eventListeners = new Set<(event: GatewayEventFrame) => void>();
+  return {
+    gateway: {
+      get snapshot() {
+        return snapshot;
+      },
+      subscribe(listener: (next: typeof snapshot) => void) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+      subscribeEvents(listener: (event: GatewayEventFrame) => void) {
+        eventListeners.add(listener);
+        return () => eventListeners.delete(listener);
+      },
+    },
+    publish: (connected: boolean) => {
+      snapshot = { ...snapshot, connected };
+      for (const listener of listeners) {
+        listener(snapshot);
+      }
+    },
+  };
+}
+
+describe("session capability message cuts", () => {
+  it("returns a committed rewind result after the connection is replaced", async () => {
+    const committed = deferred<{ editorText?: string }>();
+    const request = vi.fn((method: string) => {
+      if (method === "sessions.rewind") {
+        return committed.promise;
+      }
+      throw new Error(`Unexpected request: ${method}`);
+    });
+    const client = { request } as unknown as GatewayBrowserClient;
+    const harness = createGatewayHarness(client);
+    const sessions = createSessionCapability(harness.gateway);
+
+    const pending = sessions.rewind("agent:main:main", "user-entry");
+    harness.publish(false);
+    committed.resolve({ editorText: "edit me" });
+
+    await expect(pending).resolves.toEqual({ editorText: "edit me" });
+    sessions.dispose();
+  });
+
+  it("returns a committed fork result when the replacement refresh fails", async () => {
+    const request = vi.fn(async (method: string) => {
+      if (method === "sessions.fork") {
+        return { sessionKey: "agent:main:dashboard:forked", editorText: "edit me" };
+      }
+      if (method === "sessions.list") {
+        throw new Error("refresh failed");
+      }
+      throw new Error(`Unexpected request: ${method}`);
+    });
+    const client = { request } as unknown as GatewayBrowserClient;
+    const { gateway } = createGatewayHarness(client);
+    const sessions = createSessionCapability(gateway);
+
+    await expect(sessions.forkAtMessage("agent:main:main", "user-entry")).resolves.toEqual({
+      sessionKey: "agent:main:dashboard:forked",
+      editorText: "edit me",
+    });
+    sessions.dispose();
+  });
+});
diff --git a/ui/src/pages/chat/chat-history.test.ts b/ui/src/pages/chat/chat-history.test.ts
index 308cda29904..bf3125ca3c0 100644
--- a/ui/src/pages/chat/chat-history.test.ts
+++ b/ui/src/pages/chat/chat-history.test.ts
@@ -1,7 +1,17 @@
 // @vitest-environment node
 import { describe, expect, it, vi } from "vitest";
 import type { GatewayBrowserClient } from "../../api/gateway.ts";
-import { loadChatHistory, type ChatHistoryResult, type ChatState } from "./chat-history.ts";
+import {
+  loadChatHistory,
+  rewindChatHistory,
+  type ChatHistoryResult,
+  type ChatState,
+} from "./chat-history.ts";
+import {
+  cacheChatSessionSnapshot,
+  readChatMessagesFromCache,
+  type ChatMessageCache,
+} from "./session-message-cache.ts";
 import { handleAgentEvent, type PlanStatus, type ToolStreamEntry } from "./tool-stream.ts";
 
 type TestState = ChatState &
@@ -69,6 +79,95 @@ function activeHistory(
   } satisfies ChatHistoryResult;
 }
 
+describe("rewindChatHistory", () => {
+  it("clears the cached snapshot, refetches, and returns the composer text", async () => {
+    const state = createState({
+      messages: [{ role: "assistant", content: "kept prefix" }],
+    }) as TestState & {
+      chatMessagesBySession: ChatMessageCache;
+      handleChatDraftChange: ReturnType<typeof vi.fn>;
+      sessions: { rewind: ReturnType<typeof vi.fn> };
+    };
+    state.sessionKey = "agent:main:rewind";
+    state.chatMessages = [{ role: "assistant", content: "stale tail" }];
+    state.chatMessagesBySession = new Map();
+    state.handleChatDraftChange = vi.fn((next: string) => {
+      state.chatMessage = next;
+    });
+    state.sessions = {
+      rewind: vi.fn().mockResolvedValue({ editorText: "edit this" }),
+      setModelOverride: vi.fn(),
+    };
+    cacheChatSessionSnapshot(
+      state.chatMessagesBySession,
+      state,
+      { sessionKey: state.sessionKey },
+      {
+        messages: state.chatMessages,
+        pagination: { hasMore: false, completeSnapshot: true },
+        sessionId: "old-session",
+      },
+    );
+
+    const result = await rewindChatHistory(state as never, "user-entry");
+
+    expect(state.sessions.rewind).toHaveBeenCalledWith(
+      state.sessionKey,
+      "user-entry",
+      expect.any(Object),
+    );
+    expect(result).toEqual({ editorText: "edit this" });
+    expect(state.chatMessage).toBe("edit this");
+    expect(state.chatMessages).toEqual([{ role: "assistant", content: "kept prefix" }]);
+    expect(
+      readChatMessagesFromCache(state.chatMessagesBySession, state, {
+        sessionKey: state.sessionKey,
+      }),
+    ).toEqual([{ role: "assistant", content: "kept prefix" }]);
+  });
+
+  it("invalidates the source cache without overwriting a newly selected draft", async () => {
+    const sourceSessionKey = "agent:main:rewind-source";
+    const state = createState({
+      messages: [{ role: "assistant", content: "source prefix" }],
+    }) as TestState & {
+      chatMessagesBySession: ChatMessageCache;
+      handleChatDraftChange: ReturnType<typeof vi.fn>;
+      sessions: { rewind: ReturnType<typeof vi.fn> };
+    };
+    state.sessionKey = sourceSessionKey;
+    state.chatMessagesBySession = new Map();
+    state.handleChatDraftChange = vi.fn();
+    state.sessions = {
+      rewind: vi.fn().mockImplementation(async () => {
+        state.sessionKey = "agent:main:new-selection";
+        return { editorText: "source draft" };
+      }),
+      setModelOverride: vi.fn(),
+    };
+    cacheChatSessionSnapshot(
+      state.chatMessagesBySession,
+      state,
+      { sessionKey: sourceSessionKey },
+      {
+        messages: [{ role: "assistant", content: "stale source tail" }],
+        pagination: { hasMore: false, completeSnapshot: true },
+        sessionId: "old-source-session",
+      },
+    );
+
+    const result = await rewindChatHistory(state as never, "user-entry");
+
+    expect(
+      readChatMessagesFromCache(state.chatMessagesBySession, state, {
+        sessionKey: sourceSessionKey,
+      }),
+    ).toEqual([]);
+    expect(result).toBeNull();
+    expect(state.handleChatDraftChange).not.toHaveBeenCalled();
+  });
+});
+
 describe("chat history plan replay", () => {
   const retainedPlan = {
     runId: "run-retained",
diff --git a/ui/src/pages/chat/chat-history.ts b/ui/src/pages/chat/chat-history.ts
index 1c64083c5eb..40a92f05b93 100644
--- a/ui/src/pages/chat/chat-history.ts
+++ b/ui/src/pages/chat/chat-history.ts
@@ -50,6 +50,7 @@ import {
   resolveStartupRetryDelayMs,
   sleep,
 } from "./chat-history-retry.ts";
+import { persistChatComposerState } from "./composer-persistence.ts";
 import {
   isLocallyOptimisticHistoryMessage,
   messageDisplaySignature,
@@ -794,6 +795,12 @@ type ClearChatHistoryState = ChatState &
 
 type ClearChatHistoryResult = "completed" | "failed" | "uncertain";
 
+type RewindChatHistoryState = ChatState &
+  Parameters<typeof scheduleChatScroll>[0] & {
+    handleChatDraftChange: (next: string) => void;
+    sessions: Pick<SessionCapability, "rewind">;
+  };
+
 function hasAbortableChatSessionRun(state: ClearChatHistoryState): boolean {
   if (state.chatRunId) {
     return true;
@@ -900,6 +907,45 @@ export async function clearChatHistory(
   return "completed";
 }
 
+export async function rewindChatHistory(
+  state: RewindChatHistoryState,
+  entryId: string,
+): Promise<{ editorText?: string } | null> {
+  if (!state.client || !state.connected) {
+    return null;
+  }
+  const sessionKey = state.sessionKey;
+  const agentParams = scopedAgentParamsForSession(state, sessionKey);
+  try {
+    const result = await state.sessions.rewind(sessionKey, entryId, agentParams);
+    const editorText = result.editorText ?? "";
+    if (state.chatMessagesBySession) {
+      clearChatMessagesFromCache(state.chatMessagesBySession, state, {
+        sessionKey,
+        agentId: agentParams.agentId,
+      });
+    }
+    persistChatComposerState(state, sessionKey, {
+      agentId: agentParams.agentId,
+      draft: editorText,
+    });
+    if (!visibleSessionMatches(state, sessionKey, agentParams.agentId)) {
+      return null;
+    }
+    state.chatMessages = [];
+    await loadChatHistory(state);
+    if (!visibleSessionMatches(state, sessionKey, agentParams.agentId)) {
+      return null;
+    }
+    state.handleChatDraftChange(editorText);
+    return result;
+  } catch (error) {
+    setChatError(state, error instanceof Error ? error.message : String(error));
+    scheduleChatScroll(state);
+    return null;
+  }
+}
+
 export async function loadChatHistory(
   state: ChatState,
   opts: LoadChatHistoryOptions = {},
diff --git a/ui/src/pages/chat/chat-pane.message-cut.test.ts b/ui/src/pages/chat/chat-pane.message-cut.test.ts
new file mode 100644
index 00000000000..ec13e703239
--- /dev/null
+++ b/ui/src/pages/chat/chat-pane.message-cut.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from "vitest";
+import type { GatewayBrowserClient } from "../../api/gateway.ts";
+import type { ApplicationContext } from "../../app/context.ts";
+import type { SessionCapability } from "../../lib/sessions/index.ts";
+import "./chat-pane.ts";
+import type { ChatPageHost } from "./chat-state.ts";
+
+type TestChatPane = HTMLElement & {
+  connectedClient: GatewayBrowserClient | null;
+  connectionGeneration: number;
+  context: ApplicationContext;
+  forkFromMessage: (entryId: string) => Promise<void>;
+  onPaneSessionChange?: (paneId: string, sessionKey: string) => void;
+  state: ChatPageHost;
+};
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((nextResolve) => {
+    resolve = nextResolve;
+  });
+  return { promise, resolve };
+}
+
+function createSessionContext(
+  client: GatewayBrowserClient,
+  sessions: SessionCapability,
+): ApplicationContext {
+  return {
+    gateway: {
+      snapshot: {
+        client,
+        connected: true,
+        hello: { features: { methods: [] } },
+      },
+    },
+    agents: { state: { agentsList: null } },
+    sessions,
+  } as unknown as ApplicationContext;
+}
+
+function createTestChatPane(params: { client: GatewayBrowserClient; sessions: SessionCapability }) {
+  const pane = document.createElement("openclaw-chat-pane") as unknown as TestChatPane;
+  Object.defineProperty(pane, "isConnected", {
+    configurable: true,
+    value: true,
+  });
+  const requestUpdate = vi.fn();
+  const state = {
+    agentsList: null,
+    assistantAgentId: null,
+    chatError: null,
+    chatHistoryPagination: { hasMore: false },
+    chatLoading: false,
+    chatMessages: [],
+    chatQueue: [],
+    chatRunId: null,
+    chatSending: false,
+    chatStream: null,
+    client: params.client,
+    connected: true,
+    connectionEpoch: 4,
+    hello: null,
+    lastError: null,
+    requestUpdate,
+    sessionKey: "agent:main:current",
+    sessions: params.sessions,
+    sessionsError: null,
+    sessionsLoading: false,
+    sidebarContent: null,
+    sidebarOpen: false,
+    // Minimal scroll host so scheduleChatScroll is a no-op instead of throwing.
+    chatScrollGeneration: 0,
+    chatScrollCommitCleanup: null,
+    handleChatScroll: vi.fn(),
+    renderLifecycle: { afterCommit: () => () => {}, invalidate: () => {} },
+  } as unknown as ChatPageHost;
+  pane.context = createSessionContext(params.client, params.sessions);
+  pane.state = state;
+  pane.connectedClient = params.client;
+  pane.connectionGeneration = 4;
+  return { pane, state };
+}
+
+describe("chat pane message cuts", () => {
+  it("keeps a newer global agent selection when a message fork finishes late", async () => {
+    const forked = createDeferred<{ sessionKey: string; editorText?: string }>();
+    const sessions = {
+      forkAtMessage: vi.fn(() => forked.promise),
+    } as unknown as SessionCapability;
+    const client = {} as GatewayBrowserClient;
+    const { pane, state } = createTestChatPane({ client, sessions });
+    const navigate = vi.fn();
+    pane.onPaneSessionChange = navigate;
+    state.sessionKey = "global";
+    state.assistantAgentId = "main";
+
+    const pending = pane.forkFromMessage("user-entry");
+    state.assistantAgentId = "work";
+    forked.resolve({ sessionKey: "agent:main:forked", editorText: "edit me" });
+
+    await pending;
+    expect(navigate).not.toHaveBeenCalled();
+    expect(state.sessionKey).toBe("global");
+    expect(state.assistantAgentId).toBe("work");
+  });
+});
diff --git a/ui/src/pages/chat/chat-pane.ts b/ui/src/pages/chat/chat-pane.ts
index d5588ef826b..2ca9c497ff3 100644
--- a/ui/src/pages/chat/chat-pane.ts
+++ b/ui/src/pages/chat/chat-pane.ts
@@ -67,7 +67,11 @@ import {
   parseCatalogSessionKey,
   type CatalogSessionKey,
 } from "../../lib/sessions/catalog-key.ts";
-import { resolveSessionKey, scopedAgentParamsForSession } from "../../lib/sessions/index.ts";
+import {
+  resolveSessionKey,
+  scopedAgentParamsForSession,
+  visibleSessionMatches,
+} from "../../lib/sessions/index.ts";
 import {
   areUiSessionKeysEquivalent,
   buildAgentMainSessionKey,
@@ -87,6 +91,7 @@ import {
   clearChatHistory,
   loadChatHistory,
   loadOlderChatHistoryPage,
+  rewindChatHistory,
   resolveChatHistoryPagination,
   syncSelectedSessionMessageSubscription,
 } from "./chat-history.ts";
@@ -161,6 +166,7 @@ import { WIDGET_PROMPT_EVENT, type WidgetPromptEventDetail } from "./components/
 import {
   CHAT_COMPOSER_DRAFT_STORAGE_ERROR,
   loadChatComposerSnapshot,
+  persistChatComposerState,
   resolveStoredChatOutboxScope,
   storedChatOutboxScopeKey,
 } from "./composer-persistence.ts";
@@ -1308,6 +1314,49 @@ class ChatPane extends OpenClawLightDomElement {
     }
   }
 
+  private async rewindToMessage(entryId: string): Promise<boolean> {
+    const state = this.state;
+    if (!state) {
+      return false;
+    }
+    const result = await rewindChatHistory(state, entryId);
+    if (!result) {
+      state.requestUpdate?.();
+      return false;
+    }
+    state.requestUpdate?.();
+    return true;
+  }
+
+  private async forkFromMessage(entryId: string): Promise<void> {
+    const state = this.state;
+    if (!state) {
+      return;
+    }
+    const sourceKey = state.sessionKey;
+    const agentParams = scopedAgentParamsForSession(state, sourceKey);
+    try {
+      const result = await state.sessions.forkAtMessage(sourceKey, entryId, agentParams);
+      const editorText = result.editorText ?? "";
+      const draftPersisted = persistChatComposerState(state, result.sessionKey, {
+        agentId: parseAgentSessionKey(result.sessionKey)?.agentId,
+        draft: editorText,
+      });
+      if (this.state !== state || !visibleSessionMatches(state, sourceKey, agentParams.agentId)) {
+        return;
+      }
+      this.onPaneSessionChange?.(this.paneId, result.sessionKey);
+      this.switchPaneSession(result.sessionKey);
+      if (!draftPersisted) {
+        state.handleChatDraftChange(editorText);
+      }
+    } catch (error) {
+      state.lastError = error instanceof Error ? error.message : String(error);
+      state.chatError = state.lastError;
+      state.requestUpdate?.();
+    }
+  }
+
   private readonly handleCommandPaletteSlashCommand = (command: string) => {
     const state = this.state;
     if (!state) {
@@ -2541,6 +2590,8 @@ class ChatPane extends OpenClawLightDomElement {
         state.chatReplyTarget = target;
         state.requestUpdate?.();
       },
+      onRewindMessage: (entryId) => this.rewindToMessage(entryId),
+      onForkMessage: (entryId) => this.forkFromMessage(entryId),
       onNewSession: () => void this.createSession(),
       onClearHistory: () => void clearChatHistory(state),
       agentsList: state.agentsList,
diff --git a/ui/src/pages/chat/chat-thread.test.ts b/ui/src/pages/chat/chat-thread.test.ts
index 86f58043c31..807d6c1092f 100644
--- a/ui/src/pages/chat/chat-thread.test.ts
+++ b/ui/src/pages/chat/chat-thread.test.ts
@@ -8,10 +8,25 @@ import {
   coalesceStreamRuns,
   collapseCompletedTurnWork,
   getExpandedToolCards,
+  persistedMessageEntryId,
   resetChatThreadState,
   syncToolCardExpansionState,
 } from "./chat-thread.ts";
 
+describe("persistedMessageEntryId", () => {
+  it("rejects optimistic pending bubbles and accepts transcript identities", () => {
+    expect(
+      persistedMessageEntryId({
+        role: "user",
+        __openclaw: { id: "pending-send:1", kind: "pending-send" },
+      }),
+    ).toBeNull();
+    expect(persistedMessageEntryId({ role: "user", __openclaw: { id: "entry-1", seq: 2 } })).toBe(
+      "entry-1",
+    );
+  });
+});
+
 type CachedChatItemsProps = Parameters<typeof buildCachedChatItems>[0];
 type WorkGroupItem = Extract<
   ReturnType<typeof collapseCompletedTurnWork>[number],
diff --git a/ui/src/pages/chat/chat-thread.ts b/ui/src/pages/chat/chat-thread.ts
index fd4a4431de1..e0c4f7d81c6 100644
--- a/ui/src/pages/chat/chat-thread.ts
+++ b/ui/src/pages/chat/chat-thread.ts
@@ -838,6 +838,10 @@ function sourceMessageId(message: unknown): string | null {
   return id || null;
 }
 
+export function persistedMessageEntryId(message: unknown): string | null {
+  return isPendingSendMessage(message) ? null : sourceMessageId(message);
+}
+
 function transcriptMessageSourceKey(message: unknown): string | null {
   const record = asRecord(message);
   if (!record) {
diff --git a/ui/src/pages/chat/chat-view.test.ts b/ui/src/pages/chat/chat-view.test.ts
index 8f14b7cf21c..0622886ec2d 100644
--- a/ui/src/pages/chat/chat-view.test.ts
+++ b/ui/src/pages/chat/chat-view.test.ts
@@ -5233,6 +5233,67 @@ describe("chat model controls", () => {
 });
 
 describe("right-click Reply", () => {
+  it("adds rewind and fork actions only for persisted user bubbles", () => {
+    const onRewindMessage = vi.fn().mockResolvedValue(true);
+    const onForkMessage = vi.fn();
+    const container = renderChatView({ onRewindMessage, onForkMessage, onSetReply: vi.fn() });
+    const section = container.querySelector<HTMLElement>(".card.chat")!;
+    const group = document.createElement("div");
+    group.className = "chat-group user";
+    const bubble = document.createElement("div");
+    bubble.className = "chat-bubble";
+    bubble.dataset.entryId = "persisted-user";
+    bubble.dataset.messageText = "hello";
+    group.appendChild(bubble);
+    section.querySelector(".chat-thread-inner")!.appendChild(group);
+
+    bubble.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true }));
+
+    const labels = [...document.querySelectorAll(".chat-reply-context-menu button")].map((button) =>
+      button.textContent?.trim(),
+    );
+    expect(labels).toEqual(["Reply", "Rewind to here", "Fork from here"]);
+    document.querySelector<HTMLButtonElement>('[aria-label="Fork from here"]')!.click();
+    expect(onForkMessage).toHaveBeenCalledWith("persisted-user");
+
+    group.className = "chat-group assistant";
+    bubble.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true }));
+    expect(
+      [...document.querySelectorAll(".chat-reply-context-menu button")].map((button) =>
+        button.textContent?.trim(),
+      ),
+    ).toEqual(["Reply"]);
+  });
+
+  it("disables rewind and fork context actions during an active run", () => {
+    const container = renderChatView({
+      canAbort: true,
+      onRewindMessage: vi.fn(),
+      onForkMessage: vi.fn(),
+    });
+    const group = document.createElement("div");
+    group.className = "chat-group user";
+    const bubble = document.createElement("div");
+    bubble.className = "chat-bubble";
+    bubble.dataset.entryId = "persisted-user";
+    group.appendChild(bubble);
+    container.querySelector(".chat-thread-inner")!.appendChild(group);
+
+    bubble.dispatchEvent(new MouseEvent("contextmenu", { bubbles: true, cancelable: true }));
+
+    expect(
+      document.querySelector<HTMLButtonElement>('[aria-label="Rewind to here"]')?.disabled,
+    ).toBe(true);
+    expect(
+      document.querySelector<HTMLButtonElement>('[aria-label="Fork from here"]')?.disabled,
+    ).toBe(true);
+    expect(
+      document
+        .querySelector<HTMLElement>('[aria-label="Rewind to here"]')
+        ?.closest("openclaw-tooltip")?.content,
+    ).toBe("Rewind is unavailable while the agent is working");
+  });
+
   it("opens context menu and calls onSetReply when Reply is selected", () => {
     const onSetReply = vi.fn();
     const container = renderChatView({ onSetReply });
diff --git a/ui/src/pages/chat/chat-view.ts b/ui/src/pages/chat/chat-view.ts
index 20b5f7f4d2c..4c084b4b03f 100644
--- a/ui/src/pages/chat/chat-view.ts
+++ b/ui/src/pages/chat/chat-view.ts
@@ -199,6 +199,8 @@ export type ChatProps = {
   replyTarget?: { messageId: string; text: string; senderLabel?: string | null } | null;
   onClearReply?: () => void;
   onSetReply?: (target: { messageId: string; text: string; senderLabel?: string | null }) => void;
+  onRewindMessage?: (entryId: string) => Promise<boolean> | boolean;
+  onForkMessage?: (entryId: string) => Promise<void> | void;
   sessionWorkspace?: SessionWorkspaceProps;
   backgroundTasks?: BackgroundTasksProps;
   taskSuggestions?: TaskSuggestion[];
@@ -312,6 +314,8 @@ export function renderChat(props: ChatProps) {
       getDraft: props.getDraft,
       onSend: props.onSend,
       onSetReply: props.onSetReply,
+      onRewindMessage: props.onRewindMessage,
+      onForkMessage: props.onForkMessage,
       // Archived/non-composable sessions must not offer selection actions:
       // withholding the callback keeps the popup from rendering at all.
       onSideQuestion: props.canSend ? props.onSideQuestion : undefined,
diff --git a/ui/src/pages/chat/components/chat-message.test.ts b/ui/src/pages/chat/components/chat-message.test.ts
index b8137990f2d..db7d0d91450 100644
--- a/ui/src/pages/chat/components/chat-message.test.ts
+++ b/ui/src/pages/chat/components/chat-message.test.ts
@@ -663,6 +663,43 @@ describe("grouped chat rendering", () => {
     ]);
   });
 
+  it("renders a confirmed rewind action only for user groups", () => {
+    const container = document.createElement("div");
+    const onRewind = vi.fn();
+    localStorageValues.delete("openclaw:skip-rewind-confirm");
+    renderMessageGroups(
+      container,
+      [
+        createMessageGroup({ role: "user", content: "rewind me", timestamp: 1000 }, "user"),
+        createMessageGroup({ role: "assistant", content: "answer", timestamp: 1001 }, "assistant"),
+      ],
+      { onRewind },
+    );
+
+    const rewindButtons = container.querySelectorAll<HTMLButtonElement>(".chat-group-rewind");
+    expect(rewindButtons).toHaveLength(1);
+    rewindButtons[0]!.click();
+    expect(container.querySelector(".chat-delete-confirm__text")?.textContent).toBe(
+      "Rewind to before this message?",
+    );
+    container.querySelector<HTMLButtonElement>(".chat-delete-confirm__yes")!.click();
+    expect(onRewind).toHaveBeenCalledTimes(1);
+  });
+
+  it("disables rewind while the agent is working", () => {
+    const container = document.createElement("div");
+    renderMessageGroups(
+      container,
+      [createMessageGroup({ role: "user", content: "busy", timestamp: 1000 }, "user")],
+      { onRewind: vi.fn(), rewindDisabled: true },
+    );
+
+    const button = container.querySelector<HTMLButtonElement>(".chat-group-rewind");
+    const tooltip = button?.closest("openclaw-tooltip");
+    expect(button?.disabled).toBe(true);
+    expect(tooltip?.content).toBe("Rewind is unavailable while the agent is working");
+  });
+
   it("places the delete confirm below the trigger near the top viewport edge", () => {
     stubDeleteConfirmGeometry({
       trigger: { left: 20, top: 4, width: 24, height: 24 },
diff --git a/ui/src/pages/chat/components/chat-message.ts b/ui/src/pages/chat/components/chat-message.ts
index 27ce735b6d5..638e7be38e2 100644
--- a/ui/src/pages/chat/components/chat-message.ts
+++ b/ui/src/pages/chat/components/chat-message.ts
@@ -56,6 +56,7 @@ import { stripThinkingTags } from "../../../lib/strip-thinking-tags.ts";
 import { detectTextDirection } from "../../../lib/text-direction.ts";
 import { getSafeLocalStorage } from "../../../local-storage.ts";
 import { renderChatAvatar } from "../chat-avatar.ts";
+import { persistedMessageEntryId } from "../chat-thread.ts";
 import type { PlanStatus } from "../tool-stream.ts";
 import { renderChatPlanChecklist } from "./chat-plan-checklist.ts";
 import { renderChatQuestionSummary } from "./chat-question-card.ts";
@@ -787,6 +788,8 @@ type RenderMessageGroupOptions = {
   allowExternalEmbedUrls?: boolean;
   contextWindow?: number | null;
   onDelete?: () => void;
+  onRewind?: () => void;
+  rewindDisabled?: boolean;
 };
 
 type GroupedMessageRenderOptions = Parameters<typeof renderGroupedMessage>[2];
@@ -801,6 +804,7 @@ function buildGroupedMessageRenderOptions(
     isStreaming: group.isStreaming && index === group.messages.length - 1,
     sessionKey: opts.sessionKey,
     agentId: opts.agentId,
+    entryId: persistedMessageEntryId(item.message) ?? undefined,
     onOpenWorkspaceFile: opts.onOpenWorkspaceFile,
     duplicateCount: item.duplicateCount ?? 1,
     showReasoning: opts.showReasoning,
@@ -995,6 +999,9 @@ export function renderMessageGroup(group: MessageGroup, opts: RenderMessageGroup
         })}
         <div class="chat-group-footer">
           <div class="chat-group-footer__meta">
+            ${opts.onRewind && normalizedRole === "user"
+              ? renderRewindButton(opts.onRewind, Boolean(opts.rewindDisabled), "left")
+              : nothing}
             ${opts.onDelete && normalizedRole === "user"
               ? renderDeleteButton(opts.onDelete, "left")
               : nothing}
@@ -1161,7 +1168,8 @@ function renderMessageMeta(timestamp: number, meta: GroupMeta | null) {
   `;
 }
 
-const SKIP_DELETE_CONFIRM_KEY = "openclaw:skipDeleteConfirm";
+const SKIP_DELETE_CONFIRM_PREFERENCE = "openclaw:skipDeleteConfirm";
+const SKIP_REWIND_CONFIRM_PREFERENCE = "openclaw:skip-rewind-confirm";
 const DELETE_CONFIRM_VIEWPORT_MARGIN_PX = 8;
 const DELETE_CONFIRM_TRIGGER_GAP_PX = 6;
 
@@ -1169,9 +1177,9 @@ type DeleteConfirmSide = "left" | "right";
 
 const deleteConfirmDismissers = new WeakMap<Element, () => void>();
 
-function shouldSkipDeleteConfirm(): boolean {
+function shouldSkipActionConfirm(preferenceName: string): boolean {
   try {
-    return getSafeLocalStorage()?.getItem(SKIP_DELETE_CONFIRM_KEY) === "1";
+    return getSafeLocalStorage()?.getItem(preferenceName) === "1";
   } catch {
     return false;
   }
@@ -1244,83 +1252,153 @@ function placeDeleteConfirmPopover(
 }
 
 function renderDeleteButton(onDelete: () => void, side: DeleteConfirmSide) {
-  return html`
-    <span class="chat-delete-wrap">
-      <openclaw-tooltip .content=${t("common.delete")}>
-        <button
-          class="chat-group-delete"
-          aria-label=${t("chat.messages.deleteMessage")}
-          @click=${(e: Event) => {
-            if (shouldSkipDeleteConfirm()) {
-              onDelete();
-              return;
-            }
-            const btn = e.currentTarget as HTMLElement;
-            const wrap = btn.closest(".chat-delete-wrap") as HTMLElement;
-            const existing = wrap?.querySelector(".chat-delete-confirm");
-            if (existing) {
-              dismissDeleteConfirm(existing);
-              return;
-            }
-            const popover = document.createElement("div");
-            popover.className = `chat-delete-confirm chat-delete-confirm--${side}`;
-            popover.innerHTML = `
-            <p class="chat-delete-confirm__text">Delete this message?</p>
-            <label class="chat-delete-confirm__remember">
-              <input type="checkbox" class="chat-delete-confirm__check" />
-              <span>Don't ask again</span>
-            </label>
-            <div class="chat-delete-confirm__actions">
-              <button class="chat-delete-confirm__cancel" type="button">Cancel</button>
-              <button class="chat-delete-confirm__yes" type="button">Delete</button>
-            </div>
-          `;
-            wrap.appendChild(popover);
-            placeDeleteConfirmPopover(btn, popover, side);
+  return renderConfirmedActionButton({
+    action: onDelete,
+    ariaLabel: t("chat.messages.deleteMessage"),
+    buttonClass: "chat-group-delete",
+    confirmLabel: t("common.delete"),
+    confirmText: "Delete this message?",
+    icon: icons.trash ?? icons.x,
+    preferenceName: SKIP_DELETE_CONFIRM_PREFERENCE,
+    side,
+    tooltip: t("common.delete"),
+  });
+}
 
-            const cancel = popover.querySelector(".chat-delete-confirm__cancel")!;
-            const yes = popover.querySelector(".chat-delete-confirm__yes")!;
-            const check = popover.querySelector(".chat-delete-confirm__check") as HTMLInputElement;
+function renderRewindButton(onRewind: () => void, disabled: boolean, side: DeleteConfirmSide) {
+  return renderConfirmedActionButton({
+    action: onRewind,
+    ariaLabel: t("chat.messages.rewind"),
+    buttonClass: "chat-group-rewind",
+    confirmLabel: t("chat.messages.rewind"),
+    confirmText: t("chat.messages.rewindConfirm"),
+    disabled,
+    icon: icons.refresh,
+    preferenceName: SKIP_REWIND_CONFIRM_PREFERENCE,
+    side,
+    tooltip: disabled ? t("chat.messages.rewindUnavailable") : t("chat.messages.rewind"),
+    wrapClass: "chat-rewind-wrap",
+  });
+}
 
-            let dismissed = false;
-            function dismissPopover() {
-              if (dismissed) {
-                return;
-              }
-              dismissed = true;
-              document.removeEventListener("click", closeOnOutside, true);
-              deleteConfirmDismissers.delete(popover);
-              popover.remove();
-            }
-            function closeOnOutside(evt: MouseEvent) {
-              const target = evt.target;
-              if (target instanceof Node && !popover.contains(target) && !btn.contains(target)) {
-                dismissPopover();
-              }
-            }
+type ConfirmedActionParams = {
+  action: () => void;
+  ariaLabel: string;
+  buttonClass?: string;
+  confirmLabel: string;
+  confirmText: string;
+  disabled?: boolean;
+  icon: unknown;
+  preferenceName: string;
+  side: DeleteConfirmSide;
+  tooltip: string;
+  wrapClass?: string;
+};
 
-            deleteConfirmDismissers.set(popover, dismissPopover);
+export function openChatRewindConfirmation(trigger: HTMLElement, action: () => void): void {
+  openConfirmedActionPopover(trigger, {
+    action,
+    confirmLabel: t("chat.messages.rewind"),
+    confirmText: t("chat.messages.rewindConfirm"),
+    preferenceName: SKIP_REWIND_CONFIRM_PREFERENCE,
+    side: "left",
+  });
+}
 
-            cancel.addEventListener("click", dismissPopover);
-            yes.addEventListener("click", () => {
-              if (check.checked) {
-                try {
-                  getSafeLocalStorage()?.setItem(SKIP_DELETE_CONFIRM_KEY, "1");
-                } catch {}
-              }
-              dismissPopover();
-              onDelete();
-            });
+function openConfirmedActionPopover(
+  btn: HTMLElement,
+  params: Pick<
+    ConfirmedActionParams,
+    "action" | "confirmLabel" | "confirmText" | "preferenceName" | "side"
+  >,
+): void {
+  if (shouldSkipActionConfirm(params.preferenceName)) {
+    params.action();
+    return;
+  }
+  const wrap = btn.closest(".chat-delete-wrap") as HTMLElement | null;
+  if (!wrap) {
+    return;
+  }
+  const existing = wrap.querySelector(".chat-delete-confirm");
+  if (existing) {
+    dismissDeleteConfirm(existing);
+    return;
+  }
+  const popover = document.createElement("div");
+  popover.className = `chat-delete-confirm chat-delete-confirm--${params.side}`;
+  popover.innerHTML = `
+    <p class="chat-delete-confirm__text"></p>
+    <label class="chat-delete-confirm__remember">
+      <input type="checkbox" class="chat-delete-confirm__check" />
+      <span>Don't ask again</span>
+    </label>
+    <div class="chat-delete-confirm__actions">
+      <button class="chat-delete-confirm__cancel" type="button">Cancel</button>
+      <button class="chat-delete-confirm__yes" type="button"></button>
+    </div>
+  `;
+  const confirmText = popover.querySelector(".chat-delete-confirm__text");
+  const confirmButton = popover.querySelector(".chat-delete-confirm__yes");
+  if (confirmText) {
+    confirmText.textContent = params.confirmText;
+  }
+  if (confirmButton) {
+    confirmButton.textContent = params.confirmLabel;
+  }
+  wrap.appendChild(popover);
+  placeDeleteConfirmPopover(btn, popover, params.side);
+
+  const cancel = popover.querySelector(".chat-delete-confirm__cancel")!;
+  const yes = popover.querySelector(".chat-delete-confirm__yes")!;
+  const check = popover.querySelector(".chat-delete-confirm__check") as HTMLInputElement;
+  let dismissed = false;
+  function dismissPopover() {
+    if (dismissed) {
+      return;
+    }
+    dismissed = true;
+    document.removeEventListener("click", closeOnOutside, true);
+    deleteConfirmDismissers.delete(popover);
+    popover.remove();
+  }
+  function closeOnOutside(evt: MouseEvent) {
+    const target = evt.target;
+    if (target instanceof Node && !popover.contains(target) && !btn.contains(target)) {
+      dismissPopover();
+    }
+  }
+  deleteConfirmDismissers.set(popover, dismissPopover);
+  cancel.addEventListener("click", dismissPopover);
+  yes.addEventListener("click", () => {
+    if (check.checked) {
+      try {
+        getSafeLocalStorage()?.setItem(params.preferenceName, "1");
+      } catch {}
+    }
+    dismissPopover();
+    params.action();
+  });
+  requestAnimationFrame(() => {
+    if (!dismissed && popover.isConnected) {
+      placeDeleteConfirmPopover(btn, popover, params.side);
+      document.addEventListener("click", closeOnOutside, true);
+    }
+  });
+}
 
-            requestAnimationFrame(() => {
-              if (!dismissed && popover.isConnected) {
-                placeDeleteConfirmPopover(btn, popover, side);
-                document.addEventListener("click", closeOnOutside, true);
-              }
-            });
-          }}
+function renderConfirmedActionButton(params: ConfirmedActionParams) {
+  return html`
+    <span class="chat-delete-wrap ${params.wrapClass ?? ""}">
+      <openclaw-tooltip .content=${params.tooltip}>
+        <button
+          class=${params.buttonClass ?? ""}
+          aria-label=${params.ariaLabel}
+          ?disabled=${params.disabled}
+          @click=${(event: Event) =>
+            openConfirmedActionPopover(event.currentTarget as HTMLElement, params)}
         >
-          ${icons.trash ?? icons.x}
+          ${params.icon}
         </button>
       </openclaw-tooltip>
     </span>
@@ -2242,6 +2320,7 @@ function renderGroupedMessage(
     embedSandboxMode?: EmbedSandboxMode;
     allowExternalEmbedUrls?: boolean;
     onOpenWorkspaceFile?: (target: { path: string; line?: number | null }) => void;
+    entryId?: string;
   },
   onOpenSidebar?: (content: SidebarContent) => void,
 ) {
@@ -2387,6 +2466,7 @@ function renderGroupedMessage(
       <div
         class="${bubbleClasses}"
         data-message-id=${messageKey}
+        data-entry-id=${opts.entryId || nothing}
         data-message-text=${extractedText || nothing}
       >
         ${renderReplyPill(normalizedMessage.replyTarget)}
@@ -2419,6 +2499,7 @@ function renderGroupedMessage(
     <div
       class="${bubbleClasses}"
       data-message-id=${messageKey}
+      data-entry-id=${opts.entryId || nothing}
       data-message-text=${extractedText || nothing}
     >
       ${renderReplyPill(normalizedMessage.replyTarget)}
diff --git a/ui/src/pages/chat/components/chat-thread.ts b/ui/src/pages/chat/components/chat-thread.ts
index fae5d79a9fd..6af26f6e0ae 100644
--- a/ui/src/pages/chat/components/chat-thread.ts
+++ b/ui/src/pages/chat/components/chat-thread.ts
@@ -48,6 +48,7 @@ import {
   collapseCompletedTurnWork,
   deletedChatItemsSignature,
   getExpandedToolCards,
+  persistedMessageEntryId,
   resetChatThreadState,
   stableBooleanMapSignature,
   syncToolCardExpansionState,
@@ -63,6 +64,7 @@ import type { BackgroundTasksProps } from "./chat-background-tasks.ts";
 import { renderChatDivider } from "./chat-divider.ts";
 import {
   getAssistantAttachmentAvailabilityRenderVersion,
+  openChatRewindConfirmation,
   renderMessageGroup,
   renderStreamGroup,
   renderWorkGroupSummary,
@@ -141,6 +143,8 @@ type ChatThreadProps = {
   getDraft?: () => string;
   onSend: () => void;
   onSetReply?: (target: ReplyTarget) => void;
+  onRewindMessage?: (entryId: string) => Promise<boolean> | boolean;
+  onForkMessage?: (entryId: string) => Promise<void> | void;
   onFocusComposer?: () => void;
   /** Sends a detached /btw side question built from the selection popup. */
   onSideQuestion?: (command: string) => void;
@@ -725,6 +729,25 @@ function createReplyContextMenuButton(onClick: () => void): HTMLButtonElement {
   return button;
 }
 
+function createMessageActionContextButton(params: {
+  label: string;
+  disabled: boolean;
+  tooltip: string;
+  onClick: () => void;
+}): { element: HTMLElement; button: HTMLButtonElement } {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.disabled = params.disabled;
+  button.setAttribute("role", "menuitem");
+  button.setAttribute("aria-label", params.label);
+  button.textContent = params.label;
+  button.addEventListener("click", params.onClick);
+  const tooltip = document.createElement("openclaw-tooltip");
+  tooltip.content = params.tooltip;
+  tooltip.append(button);
+  return { element: tooltip, button };
+}
+
 function handleChatThreadSelectionPointerUp(event: PointerEvent, props: ChatThreadProps) {
   if (typeof props.onSideQuestion !== "function") {
     return;
@@ -749,7 +772,7 @@ function handleChatThreadSelectionPointerUp(event: PointerEvent, props: ChatThre
 
 function handleChatContextMenu(event: MouseEvent, props: ChatThreadProps) {
   const bubble = (event.target as HTMLElement).closest(".chat-bubble");
-  if (!bubble || typeof props.onSetReply !== "function") {
+  if (!bubble) {
     return;
   }
   const group = bubble.closest(".chat-group");
@@ -765,13 +788,16 @@ function handleChatContextMenu(event: MouseEvent, props: ChatThreadProps) {
   const senderEl = group.querySelector(".chat-sender-name");
   const senderLabel = senderEl?.textContent?.trim() ?? undefined;
   const text = truncateUtf16Safe((bubble as HTMLElement).dataset.messageText?.trim() ?? "", 500);
-  if (!text) {
+  const entryId = (bubble as HTMLElement).dataset.entryId?.trim() ?? "";
+  const isUserMessage = group.classList.contains("user") && Boolean(entryId);
+  const canReply = Boolean(text && props.onSetReply);
+  const canRewind = isUserMessage && typeof props.onRewindMessage === "function";
+  const canFork = isUserMessage && typeof props.onForkMessage === "function";
+  if (!canReply && !canRewind && !canFork) {
     return;
   }
   event.preventDefault();
   event.stopPropagation();
-  const messageId =
-    (bubble as HTMLElement).dataset.messageId?.trim() || stableReplyMessageId(senderLabel, text);
   removeReplyContextMenu();
   const menu = document.createElement("div");
   menu.className = "chat-reply-context-menu";
@@ -779,12 +805,52 @@ function handleChatContextMenu(event: MouseEvent, props: ChatThreadProps) {
   menu.setAttribute("aria-label", "Message actions");
   menu.style.left = `${event.clientX}px`;
   menu.style.top = `${event.clientY}px`;
-  const button = createReplyContextMenuButton(() => {
-    props.onSetReply?.({ messageId, text, senderLabel });
-    removeReplyContextMenu();
-    props.onFocusComposer?.();
-  });
-  menu.append(button);
+  const focusCandidates: HTMLButtonElement[] = [];
+  if (canReply) {
+    const messageId =
+      (bubble as HTMLElement).dataset.messageId?.trim() || stableReplyMessageId(senderLabel, text);
+    const replyButton = createReplyContextMenuButton(() => {
+      props.onSetReply?.({ messageId, text, senderLabel });
+      removeReplyContextMenu();
+      props.onFocusComposer?.();
+    });
+    menu.append(replyButton);
+    focusCandidates.push(replyButton);
+  }
+  const working = Boolean(props.runActive || props.runWorking);
+  if (canRewind) {
+    const action = createMessageActionContextButton({
+      label: t("chat.messages.rewindToHere"),
+      disabled: working,
+      tooltip: working ? t("chat.messages.rewindUnavailable") : t("chat.messages.rewindToHere"),
+      onClick: () => {
+        openChatRewindConfirmation(action.button, () => {
+          removeReplyContextMenu();
+          void Promise.resolve(props.onRewindMessage?.(entryId)).then((rewound) => {
+            if (rewound) {
+              props.onFocusComposer?.();
+            }
+          });
+        });
+      },
+    });
+    action.element.classList.add("chat-delete-wrap", "chat-rewind-wrap");
+    menu.append(action.element);
+    focusCandidates.push(action.button);
+  }
+  if (canFork) {
+    const action = createMessageActionContextButton({
+      label: t("chat.messages.forkFromHere"),
+      disabled: working,
+      tooltip: working ? t("chat.messages.forkUnavailable") : t("chat.messages.forkFromHere"),
+      onClick: () => {
+        removeReplyContextMenu();
+        void props.onForkMessage?.(entryId);
+      },
+    });
+    menu.append(action.element);
+    focusCandidates.push(action.button);
+  }
   document.body.appendChild(menu);
   activeReplyContextMenu = menu;
   activeReplyContextMenuPaneId = props.paneId;
@@ -800,7 +866,7 @@ function handleChatContextMenu(event: MouseEvent, props: ChatThreadProps) {
   }
   menu.style.left = `${Math.max(0, left)}px`;
   menu.style.top = `${Math.max(0, top)}px`;
-  button.focus();
+  focusCandidates.find((button) => !button.disabled)?.focus();
   requestAnimationFrame(() => {
     if (!menu.isConnected || activeReplyContextMenu !== menu) {
       return;
@@ -1039,6 +1105,11 @@ function renderChatThreadContents(
     if (deleted.has(item.key)) {
       return nothing;
     }
+    const lastMessage = item.messages.at(-1)?.message;
+    const rewindEntryId =
+      item.role.toLowerCase() === "user" && lastMessage
+        ? persistedMessageEntryId(lastMessage)
+        : null;
     return renderMessageGroup(item, {
       onOpenSidebar: props.onOpenSidebar,
       onOpenWorkspaceFile: props.onOpenWorkspaceFile,
@@ -1072,6 +1143,17 @@ function renderChatThreadContents(
         deleted.delete(item.key);
         requestUpdate();
       },
+      onRewind:
+        rewindEntryId && props.onRewindMessage
+          ? () => {
+              void Promise.resolve(props.onRewindMessage?.(rewindEntryId)).then((rewound) => {
+                if (rewound) {
+                  props.onFocusComposer?.();
+                }
+              });
+            }
+          : undefined,
+      rewindDisabled: Boolean(props.runActive || props.runWorking),
     });
   };
   const renderItem = guardChatRenderItems(state, (item) => {
diff --git a/ui/src/styles/chat/grouped.css b/ui/src/styles/chat/grouped.css
index 8088fff4561..8827d522336 100644
--- a/ui/src/styles/chat/grouped.css
+++ b/ui/src/styles/chat/grouped.css
@@ -157,6 +157,12 @@
   pointer-events: auto;
 }
 
+.chat-group:hover .chat-group-footer button:disabled,
+.chat-reply-context-menu button:disabled {
+  opacity: 0.3;
+  pointer-events: none;
+}
+
 .chat-group-footer button:hover,
 .chat-message-actions-row button:hover {
   opacity: 1 !important;

From 05e80917efdf536d9d262787ce490c00894ec7db Mon Sep 17 00:00:00 2001
From: devSejung <sejung5997@gmail.com>
Date: Sat, 18 Jul 2026 22:50:30 +0900
Subject: [PATCH 72/76] docs: record upstream sync head

---
 docs/upstream/status.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/upstream/status.md b/docs/upstream/status.md
index d789e644f97..d807af81c18 100644
--- a/docs/upstream/status.md
+++ b/docs/upstream/status.md
@@ -5,7 +5,7 @@
 - Upstream repository: `https://github.com/openclaw/openclaw.git`
 - Origin repository: `https://github.com/devSejung/platformclaw`
 - Baseline commit: `17c2ce05d8021b969f9e822a34e92535145922d5`
-- Last upstream sync: 2026-07-18 on `sync/upstream-20260718` through upstream commit `5057fd9e597eff5b6eec3669059a751727874ea8`
+- Last upstream sync: 2026-07-18 on `sync/upstream-20260718-refresh` through upstream commit `0acece4591248099a6c58296143adf4d24db3d1e`
 - Initial sync state: local `main`, `origin/main`, and `upstream/main` identical
 
 ## Current Phase

From 2442f3f88d94f9d74009098bf71b3c9618bee0bb Mon Sep 17 00:00:00 2001
From: devSejung <sejung5997@gmail.com>
Date: Sat, 18 Jul 2026 23:05:57 +0900
Subject: [PATCH 73/76] fix(ci): authenticate private checkout fetches

---
 .github/workflows/ci.yml              | 45 +++++++++++++++++++++++++++
 .github/workflows/workflow-sanity.yml | 17 +++++++++-
 2 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9b1eedd3607..e1b47e00463 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -150,8 +150,14 @@ jobs:
           CHECKOUT_EVENT_REF: ${{ github.ref }}
           CHECKOUT_FALLBACK_REF: ${{ github.sha }}
           GITHUB_EVENT_NAME: ${{ github.event_name }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           git init "$GITHUB_WORKSPACE"
           git -C "$GITHUB_WORKSPACE" config gc.auto 0
           git -C "$GITHUB_WORKSPACE" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
@@ -161,6 +167,7 @@ jobs:
             for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
                 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
                 "+${ref}:refs/remotes/origin/checkout" && return 0
               fetch_status="$?"
@@ -184,6 +191,7 @@ jobs:
             for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
                 fetch --no-tags --prune --no-recurse-submodules --depth=2 \
                 --filter=blob:none origin "$sha" && return 0
               if [ "$attempt" = "3" ]; then
@@ -807,8 +815,14 @@ jobs:
           CHECKOUT_REF: ${{ inputs.target_ref || github.sha }}
           CHECKOUT_FALLBACK_REF: ${{ github.sha }}
           GITHUB_EVENT_NAME: ${{ github.event_name }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           git init "$GITHUB_WORKSPACE"
           git -C "$GITHUB_WORKSPACE" config gc.auto 0
           git -C "$GITHUB_WORKSPACE" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
@@ -818,6 +832,7 @@ jobs:
             for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
                 fetch --no-tags --prune --no-recurse-submodules --depth=2 origin \
                 "+${ref}:refs/remotes/origin/checkout" && return 0
               fetch_status="$?"
@@ -970,9 +985,16 @@ jobs:
         env:
           CHECKOUT_REPO: ${{ github.repository }}
           CHECKOUT_SHA: ${{ needs.preflight.outputs.checkout_revision }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
 
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
+
           workdir="$GITHUB_WORKSPACE"
           reset_checkout_dir() {
             mkdir -p "$workdir"
@@ -990,6 +1012,7 @@ jobs:
 
             timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
+              -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
 
@@ -2571,8 +2594,14 @@ jobs:
         env:
           CHECKOUT_REPO: ${{ github.repository }}
           CHECKOUT_SHA: ${{ needs.preflight.outputs.checkout_revision }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           git init "$GITHUB_WORKSPACE"
           git -C "$GITHUB_WORKSPACE" config gc.auto 0
           git -C "$GITHUB_WORKSPACE" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
@@ -2581,6 +2610,7 @@ jobs:
             for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 120s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
                 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
                 "+${CHECKOUT_SHA}:refs/remotes/origin/checkout" && return 0
               fetch_status="$?"
@@ -2639,8 +2669,14 @@ jobs:
         env:
           CHECKOUT_REPO: ${{ github.repository }}
           CHECKOUT_SHA: ${{ needs.preflight.outputs.checkout_revision }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           git init "$GITHUB_WORKSPACE"
           git -C "$GITHUB_WORKSPACE" config gc.auto 0
           git -C "$GITHUB_WORKSPACE" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
@@ -2648,6 +2684,7 @@ jobs:
           fetch_checkout_ref_once() {
             git -C "$GITHUB_WORKSPACE" \
               -c protocol.version=2 \
+              -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/checkout" &
             local fetch_pid="$!"
@@ -3117,9 +3154,16 @@ jobs:
         env:
           CHECKOUT_REPO: ${{ github.repository }}
           CHECKOUT_SHA: ${{ needs.preflight.outputs.checkout_revision }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
 
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
+
           workdir="$GITHUB_WORKSPACE"
           reset_checkout_dir() {
             mkdir -p "$workdir"
@@ -3137,6 +3181,7 @@ jobs:
 
             timeout --signal=TERM --kill-after=10s 120s git -C "$workdir" \
               -c protocol.version=2 \
+              -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
               fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
               "+${CHECKOUT_SHA}:refs/remotes/origin/ci-target" || return 1
 
diff --git a/.github/workflows/workflow-sanity.yml b/.github/workflows/workflow-sanity.yml
index affef8ad795..61a43d29064 100644
--- a/.github/workflows/workflow-sanity.yml
+++ b/.github/workflows/workflow-sanity.yml
@@ -30,8 +30,14 @@ jobs:
         env:
           CHECKOUT_REPO: ${{ github.repository }}
           CHECKOUT_SHA: ${{ github.sha }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           git init "$GITHUB_WORKSPACE"
           git -C "$GITHUB_WORKSPACE" config gc.auto 0
           git -C "$GITHUB_WORKSPACE" remote add origin "https://github.com/${CHECKOUT_REPO}.git"
@@ -40,6 +46,7 @@ jobs:
             for attempt in 1 2 3; do
               timeout --signal=TERM --kill-after=10s 30s git -C "$GITHUB_WORKSPACE" \
                 -c protocol.version=2 \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
                 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin \
                 "+${CHECKOUT_SHA}:refs/remotes/origin/checkout" && return 0
               fetch_status="$?"
@@ -96,8 +103,14 @@ jobs:
         env:
           BASE_REF: ${{ github.event.pull_request.base.ref }}
           BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          CHECKOUT_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
+          if [[ -z "$CHECKOUT_TOKEN" ]]; then
+            echo "checkout token is missing" >&2
+            exit 1
+          fi
+          auth_header="$(printf 'x-access-token:%s' "$CHECKOUT_TOKEN" | base64 | tr -d '\n')"
           trusted_config="$RUNNER_TEMP/pre-commit-base.yaml"
           trusted_zizmor_config="$RUNNER_TEMP/zizmor-base.yml"
 
@@ -106,7 +119,9 @@ jobs:
             local target="$2"
             local fetch_status
             for attempt in 1 2 3; do
-              timeout --signal=TERM --kill-after=10s 30s git fetch --no-tags --depth=1 origin \
+              timeout --signal=TERM --kill-after=10s 30s git \
+                -c "http.extraheader=AUTHORIZATION: basic ${auth_header}" \
+                fetch --no-tags --depth=1 origin \
                 "+${ref}:${target}" && return 0
               fetch_status="$?"
               if [ "$fetch_status" != "124" ] && [ "$fetch_status" != "137" ]; then

From 3e7a0963bf5dbebe13c21eb3b287343c6e6ab034 Mon Sep 17 00:00:00 2001
From: devSejung <sejung5997@gmail.com>
Date: Mon, 20 Jul 2026 17:18:15 +0900
Subject: [PATCH 74/76] chore: refresh plugin sdk api baseline

---
 docs/.generated/plugin-sdk-api-baseline.sha256 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
index 9648715b86e..619a17ada17 100644
--- a/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -170,7 +170,7 @@ bbc06f2bb23d9e4a3445744711f691de9f902270e61c9740fd746f222d10fccb  module/memory-
 fe87e7d794bbbdaed3c834b218a787e98c0e69b26b0fac582b0668b8effab9b4  module/memory-core-host-multimodal
 746e155bb06b398749a6a1bfdc1b435b1ec1941dca3854554a912577731218dd  module/memory-core-host-query
 e2377479799d52d8f67dcccf8f499f28a63948b0c03fa6043fc67e476a22ec0d  module/memory-core-host-runtime-cli
-deb9953dbae4323348197f7aa90de855446d89db6abaac8434104464b16341f5  module/memory-core-host-runtime-core
+813b7f8b864e3e0497970f03a543801ff3f69cda2f80aecb26e947ef0e22534e  module/memory-core-host-runtime-core
 f8eb835f0769eba8324033141ecddb9f45bdb3d3241d2a5959fe8426ba6a2280  module/memory-core-host-runtime-files
 ebbf937b2258487f773b8a6fbd6c648feea96399cae5fbea18ec7d29e027523d  module/memory-core-host-secret
 16bdd82751898ffa98157fd27c86fa0eb9ea415fb8ed703eb4e9b170f0a9501b  module/memory-core-host-status
@@ -254,7 +254,7 @@ f7cf5c4b7be10345ac34e5f88990985f418ab855d4c0f25042b7b8cc933176f2  module/routing
 ff6cca86f54f94f238205f5b122af36666314e0a380f3ec7f0ccb9ed9208df31  module/run-command
 af338ca9fbd0dc5701ad085e17937471953241369a0c961f8894ca7df467b72d  module/runtime
 fcf103d18c1d64ffa9719f1d5a1ca349df3a6125d00c9d54a1b76c195ba8691b  module/runtime-config-snapshot
-0a3bf57216f33847fd556950a63c83ac71baa11a77a5b46a7f60739e482d51bf  module/runtime-doctor
+1392e45b8e8ef50b72a9d012a6abe5a73d00b74b6eccc53c817096dfe7a8f591  module/runtime-doctor
 b6b8edc50ecab8386c9acd8f374a207212b5a99c8f518538bbcf0c458dda3881  module/runtime-env
 841bee5465fd523116f8739eb36f79fd9efc8139dff9d98d32e35002c1614fe7  module/runtime-fetch
 1b223b31f6f78d9eca4a07b92802e59684f24d7a1d040b83856ad165d0dd70fd  module/runtime-group-policy

From a8145bdab738fa131ba98bb30a22972f8b8759ca Mon Sep 17 00:00:00 2001
From: devSejung <sejung5997@gmail.com>
Date: Mon, 20 Jul 2026 17:59:41 +0900
Subject: [PATCH 75/76] ci(platformclaw): allow full sync validation

---
 .github/workflows/platformclaw-ci.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/platformclaw-ci.yml b/.github/workflows/platformclaw-ci.yml
index d83f6bdffd4..e5e341792ce 100644
--- a/.github/workflows/platformclaw-ci.yml
+++ b/.github/workflows/platformclaw-ci.yml
@@ -22,7 +22,7 @@ jobs:
     name: PlatformClaw CI
     if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-24.04
-    timeout-minutes: 45
+    timeout-minutes: 90
     steps:
       - name: Checkout
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6

From 9a5fc441e701ce0c1c40696a74346f7b7719dce2 Mon Sep 17 00:00:00 2001
From: devSejung <sejung5997@gmail.com>
Date: Mon, 20 Jul 2026 20:40:39 +0900
Subject: [PATCH 76/76] fix(platformclaw): pass auth typecheck

---
 .github/workflows/platformclaw-ci.yml               |  7 +++++--
 .../src/browser-auth-service.ts                     | 13 +++++++++----
 .../src/employee-auth-client.test.ts                |  2 +-
 .../src/employee-auth-client.ts                     |  2 +-
 4 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/platformclaw-ci.yml b/.github/workflows/platformclaw-ci.yml
index e5e341792ce..0be7401b967 100644
--- a/.github/workflows/platformclaw-ci.yml
+++ b/.github/workflows/platformclaw-ci.yml
@@ -35,11 +35,14 @@ jobs:
         with:
           install-bun: "false"
 
-      - name: Run changed-surface checks
-        run: pnpm check:changed
+      - name: Typecheck PlatformClaw control plane
+        run: node scripts/run-tsgo.mjs -p packages/platformclaw-control-plane/tsconfig.json --noEmit
 
       - name: Test PlatformClaw control plane
         run: node scripts/run-vitest.mjs packages/platformclaw-control-plane/src
 
       - name: Build PlatformClaw control plane
         run: pnpm --dir packages/platformclaw-control-plane build
+
+      - name: Run changed-surface checks
+        run: pnpm check:changed
diff --git a/packages/platformclaw-control-plane/src/browser-auth-service.ts b/packages/platformclaw-control-plane/src/browser-auth-service.ts
index d827c461bf5..bb6661db6e5 100644
--- a/packages/platformclaw-control-plane/src/browser-auth-service.ts
+++ b/packages/platformclaw-control-plane/src/browser-auth-service.ts
@@ -111,17 +111,22 @@ export class BrowserAuthService {
     }
 
     const sessionAt = (this.options.now ?? Date.now)();
-    const currentSession = params.currentSession
+    const currentSessionToken = params.currentSession?.value;
+    const currentSession = currentSessionToken
       ? await this.options.store.resolveBrowserSession({
-          tokenHash: hashBrowserSessionToken(params.currentSession.value),
+          tokenHash: hashBrowserSessionToken(currentSessionToken),
           resolvedAt: sessionAt,
           touch: true,
         })
       : undefined;
-    if (currentSession?.status === "active" && currentSession.user.id === upserted.user.id) {
+    if (
+      currentSessionToken &&
+      currentSession?.status === "active" &&
+      currentSession.user.id === upserted.user.id
+    ) {
       return {
         status: "authenticated",
-        token: params.currentSession.value,
+        token: currentSessionToken,
         session: currentSession.session,
         user: upserted.user,
         binding,
diff --git a/packages/platformclaw-control-plane/src/employee-auth-client.test.ts b/packages/platformclaw-control-plane/src/employee-auth-client.test.ts
index 299caa609eb..a242ede5685 100644
--- a/packages/platformclaw-control-plane/src/employee-auth-client.test.ts
+++ b/packages/platformclaw-control-plane/src/employee-auth-client.test.ts
@@ -35,7 +35,7 @@ describe("employee auth client config", () => {
 
 describe("HttpEmployeeAuthenticator", () => {
   it("normalizes the full legacy profile while control-plane owns agent routing", async () => {
-    const fetchImpl = vi.fn(
+    const fetchImpl = vi.fn<typeof fetch>(
       async () =>
         new Response(
           JSON.stringify({
diff --git a/packages/platformclaw-control-plane/src/employee-auth-client.ts b/packages/platformclaw-control-plane/src/employee-auth-client.ts
index 364a5762ce5..19faeccc167 100644
--- a/packages/platformclaw-control-plane/src/employee-auth-client.ts
+++ b/packages/platformclaw-control-plane/src/employee-auth-client.ts
@@ -74,7 +74,7 @@ type ExternalAuthSuccess = {
   confluenceSpace?: string;
   notes?: string;
   groups?: string[];
-  attributes?: Record<string, string | string[]>;
+  attributes?: EmployeeDirectoryProfile["attributes"];
 };
 
 type ExternalAuthResponse = ExternalAuthFailure | ExternalAuthSuccess;